From 2e3dccaa97b060b0be6f90051e7f9404d1008166 Mon Sep 17 00:00:00 2001
From: lauckhart <greg@lauckhart.com>
Date: Fri, 8 Nov 2024 14:19:39 -0800
Subject: [PATCH] More descriptive "with" functions (#1379)

Includes MutableEndpointType.withBehaviors and ClusterBehavior.withFeatures

The existing "with" now is a shortcut alias.

Co-authored-by: Ingo Fischer <github@fischer-ka.de>
---
 .../src/behavior/cluster/ClusterBehavior.ts   | 44 +++++++++++++++++--
 .../node/src/endpoint/type/MutableEndpoint.ts | 12 +++++
 2 files changed, 52 insertions(+), 4 deletions(-)

diff --git a/packages/node/src/behavior/cluster/ClusterBehavior.ts b/packages/node/src/behavior/cluster/ClusterBehavior.ts
index c48650177e..3efa5eb50e 100644
--- a/packages/node/src/behavior/cluster/ClusterBehavior.ts
+++ b/packages/node/src/behavior/cluster/ClusterBehavior.ts
@@ -106,7 +106,7 @@ export class ClusterBehavior extends Behavior {
     /**
      * Create a new behavior with different cluster features.
      */
-    static with<
+    static withFeatures<
         This extends ClusterBehavior.Type,
         const FeaturesT extends ClusterComposer.FeatureSelection<This["cluster"]>,
     >(this: This, ...features: FeaturesT) {
@@ -117,6 +117,16 @@ export class ClusterBehavior extends Behavior {
         return this.for(newCluster);
     }
 
+    /**
+     * Alias for {@link withFeatures}.
+     */
+    static with<
+        This extends ClusterBehavior.Type,
+        const FeaturesT extends ClusterComposer.FeatureSelection<This["cluster"]>,
+    >(this: This, ...features: FeaturesT) {
+        return this.withFeatures<This, FeaturesT>(...features);
+    }
+
     /**
      * Create a new behavior with modified cluster elements.
      */
@@ -231,21 +241,44 @@ export namespace ClusterBehavior {
         // Prior to TS 5.4 could do this.  Sadly typing no longer carries through on these...  This["cluster"] reverts
         // to ClusterType).  So we have to define the long way.
         //
-        // This also means intellisense doesn't work unless we copy comments here (or move here and cast ClusterBehavior
-        // to ClusterBehavior.Type).
-        //
         // - for: typeof ClusterBehavior.for;
         // - with: typeof ClusterBehavior.with;
         // - alter: typeof ClusterBehavior.alter;
         // - set: typeof ClusterBehavior.set;
         // - enable: typeof ClusterBehavior.enable;
+        //
+        // This also means intellisense doesn't work unless we copy comments here (or move here and cast ClusterBehavior
+        // to ClusterBehavior.Type).  Currently we do the former.
 
+        /**
+         * Create a new behavior for a specific {@link ClusterType}.
+         *
+         * If you invoke directly on {@link ClusterBehavior} you will receive a new implementation that reports all commands
+         * as unimplemented.
+         *
+         * If you invoke on an existing subclass, you will receive a new implementation with the cluster in the subclass
+         * replaced.  You should generally only do this with a {@link ClusterType} with the same ID.
+         */
         for<This extends ClusterBehavior.Type, const ClusterT extends ClusterType>(
             this: This,
             cluster: ClusterT,
             schema?: Schema,
         ): ClusterBehavior.Type<ClusterT, This>;
 
+        /**
+         * Create a new behavior with different cluster features.
+         */
+        withFeatures<
+            This extends ClusterBehavior.Type,
+            const FeaturesT extends ClusterComposer.FeatureSelection<This["cluster"]>,
+        >(
+            this: This,
+            ...features: FeaturesT
+        ): ClusterBehavior.Type<ClusterComposer.WithFeatures<This["cluster"], FeaturesT>, This>;
+
+        /**
+         * Alias for {@link withFeatures}.
+         */
         with<
             This extends ClusterBehavior.Type,
             const FeaturesT extends ClusterComposer.FeatureSelection<This["cluster"]>,
@@ -254,6 +287,9 @@ export namespace ClusterBehavior {
             ...features: FeaturesT
         ): ClusterBehavior.Type<ClusterComposer.WithFeatures<This["cluster"], FeaturesT>, This>;
 
+        /**
+         * Create a new behavior with modified cluster elements.
+         */
         alter<
             This extends ClusterBehavior.Type,
             const AlterationsT extends ElementModifier.Alterations<This["cluster"]>,
diff --git a/packages/node/src/endpoint/type/MutableEndpoint.ts b/packages/node/src/endpoint/type/MutableEndpoint.ts
index 0014c119c9..6696b22b00 100644
--- a/packages/node/src/endpoint/type/MutableEndpoint.ts
+++ b/packages/node/src/endpoint/type/MutableEndpoint.ts
@@ -25,6 +25,11 @@ export interface MutableEndpoint extends EndpointType {
     /**
      * Define an endpoint like this one with additional and/or replacement server behaviors.
      */
+    withBehaviors(...behaviors: SupportedBehaviors.List): MutableEndpoint;
+
+    /**
+     * Alias for {@link withBehaviors}.
+     */
     with(...behaviors: SupportedBehaviors.List): MutableEndpoint;
 }
 
@@ -96,6 +101,13 @@ export namespace MutableEndpoint {
         /**
          * Define an endpoint like this one with additional and/or replacement server behaviors.
          */
+        withBehaviors<const BL extends SupportedBehaviors.List>(
+            ...behaviors: BL
+        ): With<B, SupportedBehaviors.With<SB, BL>>;
+
+        /**
+         * Alias for {@link withBehaviors}.
+         */
         with<const BL extends SupportedBehaviors.List>(...behaviors: BL): With<B, SupportedBehaviors.With<SB, BL>>;
     };
 }