actor-ts 0.9.1 → 0.11.0

package/dist/cluster/sharding/ShardedDaemonProcess.d.ts

@@ -1,7 +1,7 @@
 import type { ActorRef } from '../../ActorRef.js';
 import type { ActorSystem } from '../../ActorSystem.js';
-import { Props } from '../../Props.js';
 import type { Cluster } from '../Cluster.js';
+import type { ShardedDaemonProcessOptions } from './ShardedDaemonProcessOptions.js';
 /** Envelope the sharded region routes to daemon #index. */
 interface DaemonEnvelope<T> {
     readonly index: number;
@@ -11,26 +11,6 @@ interface DaemonEnvelope<T> {
 interface Wakeup {
     readonly t: 'sharded-daemon.wakeup';
 }
-export interface ShardedDaemonProcessSettings<T> {
-    /** Logical name used for the shard type; must be unique per daemon set. */
-    readonly name: string;
-    /** Total number of daemons to keep running cluster-wide. */
-    readonly numDaemons: number;
-    /** Props factory — gets the daemon's stable index (0..numDaemons-1). */
-    readonly behaviorFor: (daemonIndex: number) => Props<T>;
-    /** Optional role — only members carrying the role host daemons. */
-    readonly role?: string;
-    /**
-     * Period (ms) at which a "liveness ping" wakes every daemon index even
-     * when no cluster topology event has fired.  Acts as a safety net for
-     * the event-driven path (`LeaderChanged` / `MemberRemoved`) — if a wake
-     * was missed (e.g. brief partition right at the failover moment), the
-     * heartbeat ensures the daemons still get re-materialized.
-     *
-     * Default: `30_000` (30 s).  Set to `0` to disable.
-     */
-    readonly livenessIntervalMs?: number;
-}
 export interface ShardedDaemonProcessHandle<T> {
     /**
      * Sharded region ref.  Messages sent here must carry a `{index, body}`
@@ -58,7 +38,7 @@ export interface ShardedDaemonProcessHandle<T> {
  * machinery to materialize it on the node the coordinator chose.
  */
 export declare class ShardedDaemonProcess {
-    static init<T>(system: ActorSystem, cluster: Cluster, settings: ShardedDaemonProcessSettings<T>): ShardedDaemonProcessHandle<T>;
+    static init<T>(system: ActorSystem, cluster: Cluster, options: ShardedDaemonProcessOptions<T>): ShardedDaemonProcessHandle<T>;
 }
 export {};
 //# sourceMappingURL=ShardedDaemonProcess.d.ts.map

package/dist/cluster/sharding/ShardedDaemonProcess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShardedDaemonProcess.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardedDaemonProcess.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAK7C,2DAA2D;AAC3D,UAAU,cAAc,CAAC,CAAC;IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;CAAE;AAElF,sEAAsE;AACtE,UAAU,MAAM;IAAG,QAAQ,CAAC,CAAC,EAAE,uBAAuB,CAAC;CAAE;AAGzD,MAAM,WAAW,4BAA4B,CAAC,CAAC;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC;IACxD,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7C,wCAAwC;IACxC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAEtC;;;;OAIG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IAC/B,MAAM,CAAC,IAAI,CAAC,CAAC,EACX,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,4BAA4B,CAAC,CAAC,CAAC,GACxC,0BAA0B,CAAC,CAAC,CAAC;CA+DjC"}
+{"version":3,"file":"ShardedDaemonProcess.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardedDaemonProcess.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAM7C,OAAO,KAAK,EAAE,2BAA2B,EAAmC,MAAM,kCAAkC,CAAC;AAErH,2DAA2D;AAC3D,UAAU,cAAc,CAAC,CAAC;IAAI,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;CAAE;AAElF,sEAAsE;AACtE,UAAU,MAAM;IAAG,QAAQ,CAAC,CAAC,EAAE,uBAAuB,CAAC;CAAE;AAGzD,MAAM,WAAW,0BAA0B,CAAC,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAE7C,wCAAwC;IACxC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAEtC;;;;OAIG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IAC/B,MAAM,CAAC,IAAI,CAAC,CAAC,EACX,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,GACtC,0BAA0B,CAAC,CAAC,CAAC;CAiEjC"}

package/dist/cluster/sharding/ShardedDaemonProcess.js

@@ -4,6 +4,8 @@ import { Props } from '../../Props.js';
 import { LeaderChanged, MemberRemoved } from '../ClusterEvents.js';
 import { LeastShardAllocationStrategy } from './AllocationStrategy.js';
 import { ClusterSharding } from './ClusterSharding.js';
+import { StartShardingOptions } from './StartShardingOptions.js';
+import { ShardedDaemonProcessOptionsValidator } from './ShardedDaemonProcessOptions.js';
 const WAKEUP = { t: 'sharded-daemon.wakeup' };
 /**
  * Starts exactly N named daemon actors spread across the cluster.  Built on
@@ -17,22 +19,25 @@ const WAKEUP = { t: 'sharded-daemon.wakeup' };
  * machinery to materialize it on the node the coordinator chose.
  */
 export class ShardedDaemonProcess {
-    static init(system, cluster, settings) {
+    static init(system, cluster, options) {
+        const resolvedOptions = options;
+        new ShardedDaemonProcessOptionsValidator().validate(resolvedOptions);
         const sharding = ClusterSharding.get(system, cluster);
-        const region = sharding.start({
-            typeName: `daemon-${settings.name}`,
-            entityProps: Props.create(() => new DaemonHost(settings.behaviorFor)),
-            extractEntityId: (env) => String(env.index),
-            extractEntityMessage: (env) => env.body,
-            numShards: settings.numDaemons,
-            role: settings.role,
-            rememberEntities: true,
-            allocationStrategy: new LeastShardAllocationStrategy(),
-        });
+        const startOptions = StartShardingOptions.create()
+            .withTypeName(`daemon-${resolvedOptions.name}`)
+            .withEntityProps(Props.create(() => new DaemonHost(resolvedOptions.behaviorFor)))
+            .withExtractEntityId((env) => String(env.index))
+            .withExtractEntityMessage((env) => env.body)
+            .withNumShards(resolvedOptions.numDaemons)
+            .withRememberEntities(true)
+            .withAllocationStrategy(new LeastShardAllocationStrategy());
+        if (resolvedOptions.role !== undefined)
+            startOptions.withRole(resolvedOptions.role);
+        const region = sharding.start(startOptions);
         // Wake every daemon so the coordinator allocates a shard and the host
         // actor's preStart runs.  Afterwards rememberEntities keeps them alive.
         const wakeAll = () => {
-            for (let i = 0; i < settings.numDaemons; i++) {
+            for (let i = 0; i < resolvedOptions.numDaemons; i++) {
                 region.tell({ index: i, body: WAKEUP });
             }
         };
@@ -49,7 +54,7 @@ export class ShardedDaemonProcess {
         // Periodic liveness backstop — fires even when no cluster events do,
         // so any wake-up that got lost in transit (rare, but possible during
         // brief partition + heal cycles) gets retried.
-        const livenessIntervalMs = settings.livenessIntervalMs ?? 30_000;
+        const livenessIntervalMs = resolvedOptions.livenessIntervalMs ?? 30_000;
         let livenessTimer = null;
         if (livenessIntervalMs > 0) {
             livenessTimer = system.scheduler.scheduleAtFixedRateFn(livenessIntervalMs, livenessIntervalMs, wakeAll);
@@ -98,8 +103,8 @@ class DaemonHost extends Actor {
 function indexFromEntityName(name) {
     // Names are set by ShardRegion as `entity-<entityId>` where entityId is
     // the stringified daemon index (see extractEntityId above).
-    const m = name.match(/^entity-(\d+)$/);
-    return m ? parseInt(m[1], 10) : 0;
+    const match = name.match(/^entity-(\d+)$/);
+    return match ? parseInt(match[1], 10) : 0;
 }
 function isWakeup(x) {
     return !!x && typeof x === 'object' && x.t === 'sharded-daemon.wakeup';

package/dist/cluster/sharding/ShardedDaemonProcess.js.map

@@ -1 +1 @@
-{"version":3,"file":"ShardedDaemonProcess.js","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardedDaemonProcess.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAGvC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,4BAA4B,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAOvD,MAAM,MAAM,GAAW,EAAE,CAAC,EAAE,uBAAuB,EAAE,CAAC;AAyCtD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,oBAAoB;IAC/B,MAAM,CAAC,IAAI,CACT,MAAmB,EACnB,OAAgB,EAChB,QAAyC;QAEzC,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAEtD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAoB;YAC/C,QAAQ,EAAE,UAAU,QAAQ,CAAC,IAAI,EAAE;YACnC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,UAAU,CAAI,QAAQ,CAAC,WAAW,CAAwC,CAAC;YAC/G,eAAe,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;YAC3C,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI;YACvC,SAAS,EAAE,QAAQ,CAAC,UAAU;YAC9B,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,gBAAgB,EAAE,IAAI;YACtB,kBAAkB,EAAE,IAAI,4BAA4B,EAAE;SACvD,CAAC,CAAC;QAEH,sEAAsE;QACtE,wEAAwE;QACxE,MAAM,OAAO,GAAG,GAAS,EAAE;YACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7C,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC,CAAC;QACF,cAAc,CAAC,OAAO,CAAC,CAAC;QAExB,mEAAmE;QACnE,sEAAsE;QACtE,iEAAiE;QACjE,qEAAqE;QACrE,uEAAuE;QACvE,kDAAkD;QAClD,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,EAAE,CAC5C,KAAK,CAAC,GAAG,CAAC;aACP,IAAI,CACH,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,EACjE,GAAG,EAAE,GAAG,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CACpC;aACA,SAAS,CAAC,GAAG,EAAE,GAA8C,CAAC,CAAC,CACnE,CAAC;QAEF,qEAAqE;QACrE,qEAAqE;QACrE,+CAA+C;QAC/C,MAAM,kBAAkB,GAAG,QAAQ,CAAC,kBAAkB,IAAI,MAAM,CAAC;QACjE,IAAI,aAAa,GAAuB,IAAI,CAAC;QAC7C,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;YAC3B,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,qBAAqB,CACpD,kBAAkB,EAAE,kBAAkB,EAAE,OAAO,CAChD,CAAC;QACJ,CAAC;QAED,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,OAAO;YACL,MAAM;YACN,IAAI,CAAC,KAAa,EAAE,OAAU;gBAC5B,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;YACxC,CAAC;YACD,IAAI;gBACF,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,aAAa,EAAE,MAAM,EAAE,CAAC;gBACxB,WAAW,EAAE,CAAC;YAChB,CAAC;SACF,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAc,SAAQ,KAAwB;IAGrB;IAFrB,KAAK,GAAuB,IAAI,CAAC;IAEzC,YAA6B,WAAoC;QAAI,KAAK,EAAE,CAAC;QAAhD,gBAAW,GAAX,WAAW,CAAyB;IAAa,CAAC;IAEtE,QAAQ;QACf,MAAM,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACnD,CAAC;IAEQ,SAAS,CAAC,GAAmC;QACpD,wEAAwE;QACxE,wEAAwE;QACxE,IAAI,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,+BAA+B;QAC1D,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAQ,CAAC,CAAC;IAC7B,CAAC;CACF;AAED,SAAS,mBAAmB,CAAC,IAAY;IACvC,wEAAwE;IACxE,4DAA4D;IAC5D,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACvC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAK,CAAoB,CAAC,CAAC,KAAK,uBAAuB,CAAC;AAC7F,CAAC"}
+{"version":3,"file":"ShardedDaemonProcess.js","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardedDaemonProcess.ts"],"names":[],"mappings":"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"}

package/dist/cluster/sharding/ShardedDaemonProcessOptions.d.ts

@@ -0,0 +1,57 @@
+import type { Props } from '../../Props.js';
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/** Plain options-object shape consumed by {@link ShardedDaemonProcess.init}. */
+export interface ShardedDaemonProcessOptionsType<T> {
+    /** Logical name used for the shard type; must be unique per daemon set. */
+    readonly name: string;
+    /** Total number of daemons to keep running cluster-wide. */
+    readonly numDaemons: number;
+    /** Props factory — gets the daemon's stable index (0..numDaemons-1). */
+    readonly behaviorFor: (daemonIndex: number) => Props<T>;
+    /** Optional role — only members carrying the role host daemons. */
+    readonly role?: string;
+    /**
+     * Period (ms) at which a "liveness ping" wakes every daemon index even
+     * when no cluster topology event has fired.  Acts as a safety net for
+     * the event-driven path (`LeaderChanged` / `MemberRemoved`) — if a wake
+     * was missed (e.g. brief partition right at the failover moment), the
+     * heartbeat ensures the daemons still get re-materialized.
+     *
+     * Default: `30_000` (30 s).  Set to `0` to disable.
+     */
+    readonly livenessIntervalMs?: number;
+}
+/**
+ * Fluent builder for {@link ShardedDaemonProcessOptionsType}.  The
+ * `behaviorFor` factory is a whole-object field passed via a single
+ * `withBehaviorFor(fn)`.
+ */
+export declare class ShardedDaemonProcessOptionsBuilder<T> extends OptionsBuilder<ShardedDaemonProcessOptionsType<T>> {
+    /** Start a fresh builder.  Equivalent to `new ShardedDaemonProcessOptionsBuilder<T>()`. */
+    static create<T>(): ShardedDaemonProcessOptionsBuilder<T>;
+    /** Logical name used for the shard type; must be unique per daemon set. */
+    withName(name: string): this;
+    /** Total number of daemons to keep running cluster-wide. */
+    withNumDaemons(numDaemons: number): this;
+    /** Props factory — gets the daemon's stable index (0..numDaemons-1). */
+    withBehaviorFor(behaviorFor: (daemonIndex: number) => Props<T>): this;
+    /** Only members carrying this role host daemons. */
+    withRole(role: string): this;
+    /** Period (ms) for the liveness ping that re-materializes daemons.  Default: 30 s; `0` disables. */
+    withLivenessIntervalMs(livenessIntervalMs: number): this;
+}
+/** Validates resolved {@link ShardedDaemonProcessOptionsType} settings. */
+export declare class ShardedDaemonProcessOptionsValidator<T> extends OptionsValidator<ShardedDaemonProcessOptionsType<T>> {
+    constructor();
+    protected rules(_s: Partial<ShardedDaemonProcessOptionsType<T>>): void;
+}
+/**
+ * Accepted input for {@link ShardedDaemonProcess.init}: the fluent
+ * {@link ShardedDaemonProcessOptionsBuilder} OR a plain (partial)
+ * {@link ShardedDaemonProcessOptionsType} object.
+ */
+export type ShardedDaemonProcessOptions<T> = ShardedDaemonProcessOptionsBuilder<T> | Partial<ShardedDaemonProcessOptionsType<T>>;
+/** Value alias so `ShardedDaemonProcessOptions.create()` / `new ShardedDaemonProcessOptions()` resolve to the builder. */
+export declare const ShardedDaemonProcessOptions: typeof ShardedDaemonProcessOptionsBuilder;
+//# sourceMappingURL=ShardedDaemonProcessOptions.d.ts.map

package/dist/cluster/sharding/ShardedDaemonProcessOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShardedDaemonProcessOptions.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardedDaemonProcessOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,gFAAgF;AAChF,MAAM,WAAW,+BAA+B,CAAC,CAAC;IAChD,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC;IACxD,mEAAmE;IACnE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED;;;;GAIG;AACH,qBAAa,kCAAkC,CAAC,CAAC,CAAE,SAAQ,cAAc,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC;IAC3G,2FAA2F;IAC3F,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,kCAAkC,CAAC,CAAC,CAAC;IAIzD,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5B,4DAA4D;IAC5D,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAIxC,wEAAwE;IACxE,eAAe,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI;IAIrE,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5B,oGAAoG;IACpG,sBAAsB,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI;CAGzD;AAED,2EAA2E;AAC3E,qBAAa,oCAAoC,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC;;IAI/G,SAAS,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI;CAKvE;AAED;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,CAAC,CAAC,IACrC,kCAAkC,CAAC,CAAC,CAAC,GACrC,OAAO,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,0HAA0H;AAC1H,eAAO,MAAM,2BAA2B,2CAAqC,CAAC"}

package/dist/cluster/sharding/ShardedDaemonProcessOptions.js

@@ -0,0 +1,47 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/**
+ * Fluent builder for {@link ShardedDaemonProcessOptionsType}.  The
+ * `behaviorFor` factory is a whole-object field passed via a single
+ * `withBehaviorFor(fn)`.
+ */
+export class ShardedDaemonProcessOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new ShardedDaemonProcessOptionsBuilder<T>()`. */
+    static create() {
+        return new ShardedDaemonProcessOptionsBuilder();
+    }
+    /** Logical name used for the shard type; must be unique per daemon set. */
+    withName(name) {
+        return this.set('name', name);
+    }
+    /** Total number of daemons to keep running cluster-wide. */
+    withNumDaemons(numDaemons) {
+        return this.set('numDaemons', numDaemons);
+    }
+    /** Props factory — gets the daemon's stable index (0..numDaemons-1). */
+    withBehaviorFor(behaviorFor) {
+        return this.set('behaviorFor', behaviorFor);
+    }
+    /** Only members carrying this role host daemons. */
+    withRole(role) {
+        return this.set('role', role);
+    }
+    /** Period (ms) for the liveness ping that re-materializes daemons.  Default: 30 s; `0` disables. */
+    withLivenessIntervalMs(livenessIntervalMs) {
+        return this.set('livenessIntervalMs', livenessIntervalMs);
+    }
+}
+/** Validates resolved {@link ShardedDaemonProcessOptionsType} settings. */
+export class ShardedDaemonProcessOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('ShardedDaemonProcessOptions');
+    }
+    rules(_s) {
+        this.nonEmptyString('name');
+        this.positiveInt('numDaemons');
+        this.nonNegativeInt('livenessIntervalMs'); // 0 disables the liveness ping
+    }
+}
+/** Value alias so `ShardedDaemonProcessOptions.create()` / `new ShardedDaemonProcessOptions()` resolve to the builder. */
+export const ShardedDaemonProcessOptions = ShardedDaemonProcessOptionsBuilder;
+//# sourceMappingURL=ShardedDaemonProcessOptions.js.map

package/dist/cluster/sharding/ShardedDaemonProcessOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShardedDaemonProcessOptions.js","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardedDaemonProcessOptions.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAwBlE;;;;GAIG;AACH,MAAM,OAAO,kCAAsC,SAAQ,cAAkD;IAC3G,2FAA2F;IAC3F,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,kCAAkC,EAAK,CAAC;IACrD,CAAC;IAED,2EAA2E;IAC3E,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,4DAA4D;IAC5D,cAAc,CAAC,UAAkB;QAC/B,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;IAED,wEAAwE;IACxE,eAAe,CAAC,WAA8C;QAC5D,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;IAED,oDAAoD;IACpD,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,oGAAoG;IACpG,sBAAsB,CAAC,kBAA0B;QAC/C,OAAO,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;IAC5D,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,OAAO,oCAAwC,SAAQ,gBAAoD;IAC/G;QACE,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACvC,CAAC;IACS,KAAK,CAAC,EAA+C;QAC7D,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;QAC/B,IAAI,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC,CAAC,+BAA+B;IAC5E,CAAC;CACF;AAUD,0HAA0H;AAC1H,MAAM,CAAC,MAAM,2BAA2B,GAAG,kCAAkC,CAAC"}

package/dist/cluster/sharding/ShardingOptions.d.ts

@@ -0,0 +1,95 @@
+import type { Props } from '../../Props.js';
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/**
+ * Plain options-object shape for a sharded region.  Consumed by
+ * {@link ShardRegion.settingsToConfig} and extended by
+ * {@link StartShardingOptionsType} — the coordinator-side superset that
+ * {@link ClusterSharding.start} accepts.
+ */
+export interface ShardingOptionsType<TMessage> {
+    readonly typeName: string;
+    readonly entityProps: Props<TMessage>;
+    readonly extractEntityId: (message: TMessage) => string;
+    readonly extractEntityMessage?: (message: TMessage) => unknown;
+    readonly numShards?: number;
+    /** Members must carry this role to be candidates for hosting shards. */
+    readonly role?: string;
+    /** Run as a proxy — route messages but never host entities locally. */
+    readonly proxy?: boolean;
+    /** Track entity lifecycle so entities can be re-created on the new owner. */
+    readonly rememberEntities?: boolean;
+    /** Notify the region after an entity has been idle this many ms.  */
+    readonly passivationIdleMs?: number;
+    /**
+     * Cap the number of locally-hosted entities (#82).  When the region
+     * is about to spawn a new entity and the existing count is already
+     * `maxEntities`, the entity with the oldest `lastActivity` is
+     * passivated — same code path users invoke manually via
+     * {@link Passivate}.  Useful for unbounded entity sets (per-user
+     * sessions, IoT devices, …) where a memory cap per node matters
+     * more than keeping every cold entity resident.
+     *
+     * Default: `0` (no cap).  Eviction runs only when `> 0`.
+     *
+     * Note: passivation is asynchronous, so during the brief window
+     * between "stop the LRU" and "Terminated arrives" the region may
+     * hold `maxEntities + 1` entities; the cap is a steady-state
+     * upper bound rather than a strict instantaneous one.
+     */
+    readonly maxEntities?: number;
+}
+/**
+ * Fluent builder for {@link ShardingOptionsType}.  Base of the builder
+ * inheritance chain: {@link StartShardingOptionsBuilder} (in
+ * `StartShardingOptions`) extends this and adds the coordinator-side
+ * fields.  Each concrete `withX` records exactly one field so unset
+ * fields fall through to HOCON / built-in defaults when the options are
+ * normalised by {@link ShardRegion.settingsToConfig}.
+ *
+ * The whole-object fields — `entityProps` (a {@link Props}), and the
+ * `extractEntityId` / `extractEntityMessage` extractors — are passed
+ * as-is via a single `withX(value)`; no nested builders.
+ */
+export declare class ShardingOptionsBuilder<TMessage, S extends ShardingOptionsType<TMessage> = ShardingOptionsType<TMessage>> extends OptionsBuilder<S> {
+    /** Start a fresh builder.  Equivalent to `new ShardingOptionsBuilder<TMessage>()`. */
+    static create<TMessage>(): ShardingOptionsBuilder<TMessage>;
+    /** Logical name of the sharded type. */
+    withTypeName(typeName: string): this;
+    /** Props used to spawn each entity instance. */
+    withEntityProps(entityProps: Props<TMessage>): this;
+    /** Derive the stable entity id from an incoming message. */
+    withExtractEntityId(extractEntityId: (message: TMessage) => string): this;
+    /** Unwrap the payload actually delivered to the entity.  Default: identity. */
+    withExtractEntityMessage(extractEntityMessage: (message: TMessage) => unknown): this;
+    /** Number of shards to spread entities across.  Default: 64. */
+    withNumShards(numShards: number): this;
+    /** Members must carry this role to be candidates for hosting shards. */
+    withRole(role: string): this;
+    /** Run as a proxy — route messages but never host entities locally. */
+    withProxy(proxy?: boolean): this;
+    /** Track entity lifecycle so entities can be re-created on the new owner. */
+    withRememberEntities(rememberEntities?: boolean): this;
+    /** Notify the region after an entity has been idle this many ms. */
+    withPassivationIdleMs(passivationIdleMs: number): this;
+    /** Cap the number of locally-hosted entities; LRU-passivate on overflow.  Default: 0 (no cap). */
+    withMaxEntities(maxEntities: number): this;
+}
+/**
+ * Validates resolved sharding settings.  Generic so
+ * {@link StartShardingOptionsValidator} can extend it via {@link commonRules};
+ * only present values are checked (unset fields fall through to defaults).
+ */
+export declare class ShardingOptionsValidator<TMessage, S extends ShardingOptionsType<TMessage> = ShardingOptionsType<TMessage>> extends OptionsValidator<S> {
+    constructor(optionsName?: string);
+    protected rules(s: Partial<S>): void;
+    protected commonRules(s: Partial<S>): void;
+}
+/**
+ * Accepted input for a sharded-region-configurable API: the fluent
+ * {@link ShardingOptionsBuilder} OR a plain {@link ShardingOptionsType} object.
+ */
+export type ShardingOptions<TMessage, S extends ShardingOptionsType<TMessage> = ShardingOptionsType<TMessage>> = ShardingOptionsBuilder<TMessage, S> | S;
+/** Value alias so `ShardingOptions.create()` / `new ShardingOptions()` resolve to the builder. */
+export declare const ShardingOptions: typeof ShardingOptionsBuilder;
+//# sourceMappingURL=ShardingOptions.d.ts.map

package/dist/cluster/sharding/ShardingOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShardingOptions.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardingOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,QAAQ;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,CAAC;IACxD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC,qEAAqE;IACrE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAsB,CACjC,QAAQ,EACR,CAAC,SAAS,mBAAmB,CAAC,QAAQ,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CACvE,SAAQ,cAAc,CAAC,CAAC,CAAC;IACzB,sFAAsF;IACtF,MAAM,CAAC,MAAM,CAAC,QAAQ,KAAK,sBAAsB,CAAC,QAAQ,CAAC;IAI3D,wCAAwC;IACxC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIpC,gDAAgD;IAChD,eAAe,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,IAAI;IAInD,4DAA4D;IAC5D,mBAAmB,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,MAAM,GAAG,IAAI;IAIzE,+EAA+E;IAC/E,wBAAwB,CAAC,oBAAoB,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,GAAG,IAAI;IAIpF,gEAAgE;IAChE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAItC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5B,uEAAuE;IACvE,SAAS,CAAC,KAAK,UAAO,GAAG,IAAI;IAI7B,6EAA6E;IAC7E,oBAAoB,CAAC,gBAAgB,UAAO,GAAG,IAAI;IAInD,oEAAoE;IACpE,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IAItD,kGAAkG;IAClG,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;CAG3C;AAED;;;;GAIG;AACH,qBAAa,wBAAwB,CACnC,QAAQ,EACR,CAAC,SAAS,mBAAmB,CAAC,QAAQ,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CACvE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;gBACf,WAAW,SAAoB;IAG3C,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAGpC,SAAS,CAAC,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;CAkB3C;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,CACzB,QAAQ,EACR,CAAC,SAAS,mBAAmB,CAAC,QAAQ,CAAC,GAAG,mBAAmB,CAAC,QAAQ,CAAC,IACrE,sBAAsB,CAAC,QAAQ,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;AAC5C,kGAAkG;AAClG,eAAO,MAAM,eAAe,+BAAyB,CAAC"}

package/dist/cluster/sharding/ShardingOptions.js

@@ -0,0 +1,92 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import { OptionsValidator } from '../../util/OptionsValidator.js';
+/**
+ * Fluent builder for {@link ShardingOptionsType}.  Base of the builder
+ * inheritance chain: {@link StartShardingOptionsBuilder} (in
+ * `StartShardingOptions`) extends this and adds the coordinator-side
+ * fields.  Each concrete `withX` records exactly one field so unset
+ * fields fall through to HOCON / built-in defaults when the options are
+ * normalised by {@link ShardRegion.settingsToConfig}.
+ *
+ * The whole-object fields — `entityProps` (a {@link Props}), and the
+ * `extractEntityId` / `extractEntityMessage` extractors — are passed
+ * as-is via a single `withX(value)`; no nested builders.
+ */
+export class ShardingOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new ShardingOptionsBuilder<TMessage>()`. */
+    static create() {
+        return new ShardingOptionsBuilder();
+    }
+    /** Logical name of the sharded type. */
+    withTypeName(typeName) {
+        return this.set('typeName', typeName);
+    }
+    /** Props used to spawn each entity instance. */
+    withEntityProps(entityProps) {
+        return this.set('entityProps', entityProps);
+    }
+    /** Derive the stable entity id from an incoming message. */
+    withExtractEntityId(extractEntityId) {
+        return this.set('extractEntityId', extractEntityId);
+    }
+    /** Unwrap the payload actually delivered to the entity.  Default: identity. */
+    withExtractEntityMessage(extractEntityMessage) {
+        return this.set('extractEntityMessage', extractEntityMessage);
+    }
+    /** Number of shards to spread entities across.  Default: 64. */
+    withNumShards(numShards) {
+        return this.set('numShards', numShards);
+    }
+    /** Members must carry this role to be candidates for hosting shards. */
+    withRole(role) {
+        return this.set('role', role);
+    }
+    /** Run as a proxy — route messages but never host entities locally. */
+    withProxy(proxy = true) {
+        return this.set('proxy', proxy);
+    }
+    /** Track entity lifecycle so entities can be re-created on the new owner. */
+    withRememberEntities(rememberEntities = true) {
+        return this.set('rememberEntities', rememberEntities);
+    }
+    /** Notify the region after an entity has been idle this many ms. */
+    withPassivationIdleMs(passivationIdleMs) {
+        return this.set('passivationIdleMs', passivationIdleMs);
+    }
+    /** Cap the number of locally-hosted entities; LRU-passivate on overflow.  Default: 0 (no cap). */
+    withMaxEntities(maxEntities) {
+        return this.set('maxEntities', maxEntities);
+    }
+}
+/**
+ * Validates resolved sharding settings.  Generic so
+ * {@link StartShardingOptionsValidator} can extend it via {@link commonRules};
+ * only present values are checked (unset fields fall through to defaults).
+ */
+export class ShardingOptionsValidator extends OptionsValidator {
+    constructor(optionsName = 'ShardingOptions') {
+        super(optionsName);
+    }
+    rules(s) {
+        this.commonRules(s);
+    }
+    commonRules(s) {
+        const opts = s;
+        if (opts.typeName !== undefined && (typeof opts.typeName !== 'string' || opts.typeName.length === 0)) {
+            this.fail('typeName', 'must be a non-empty string', opts.typeName);
+        }
+        if (opts.numShards !== undefined && (!Number.isInteger(opts.numShards) || opts.numShards < 1)) {
+            this.fail('numShards', 'must be an integer >= 1', opts.numShards);
+        }
+        if (opts.passivationIdleMs !== undefined &&
+            (typeof opts.passivationIdleMs !== 'number' || !Number.isFinite(opts.passivationIdleMs) || opts.passivationIdleMs < 0)) {
+            this.fail('passivationIdleMs', 'must be a non-negative finite number', opts.passivationIdleMs);
+        }
+        if (opts.maxEntities !== undefined && (!Number.isInteger(opts.maxEntities) || opts.maxEntities < 0)) {
+            this.fail('maxEntities', 'must be an integer >= 0', opts.maxEntities);
+        }
+    }
+}
+/** Value alias so `ShardingOptions.create()` / `new ShardingOptions()` resolve to the builder. */
+export const ShardingOptions = ShardingOptionsBuilder;
+//# sourceMappingURL=ShardingOptions.js.map

package/dist/cluster/sharding/ShardingOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ShardingOptions.js","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardingOptions.ts"],"names":[],"mappings":"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"}

package/dist/cluster/sharding/ShardingProtocol.d.ts

@@ -2,7 +2,7 @@ import type { NodeAddressData } from '../NodeAddress.js';
 /**
  * Message types exchanged between ShardRegions and the ShardCoordinator.
  * They travel as plain actor messages (delivered locally or over the wire
- * as EnvelopeMsg.body) so the discriminator is a string `$t` property.
+ * as EnvelopeMessage.body) so the discriminator is a string `$t` property.
  */
 export interface RegisterRegion {
     readonly $t: 'sharding.Register';
@@ -11,8 +11,8 @@ export interface RegisterRegion {
     readonly proxy: boolean;
     readonly hostedShards: number[];
 }
-export interface RegisterAck {
-    readonly $t: 'sharding.RegisterAck';
+export interface RegisterAcknowledgment {
+    readonly $t: 'sharding.RegisterAcknowledgment';
     readonly coordinator: string;
 }
 export interface GetShardHome {
@@ -31,8 +31,8 @@ export interface BeginHandOff {
     readonly $t: 'sharding.BeginHandOff';
     readonly shardId: number;
 }
-export interface BeginHandOffAck {
-    readonly $t: 'sharding.BeginHandOffAck';
+export interface BeginHandOffAcknowledgment {
+    readonly $t: 'sharding.BeginHandOffAcknowledgment';
     readonly shardId: number;
 }
 export interface HandOff {
@@ -87,6 +87,6 @@ export interface ShardReply {
     readonly correlationId: number;
     readonly message: unknown;
 }
-export type ShardingMessage = RegisterRegion | RegisterAck | GetShardHome | ShardHome | BeginHandOff | BeginHandOffAck | HandOff | HandOffComplete | RegionTerminated | EntityStarted | EntityStopped | RememberedEntities | ShardEnvelope | ShardReply;
+export type ShardingMessage = RegisterRegion | RegisterAcknowledgment | GetShardHome | ShardHome | BeginHandOff | BeginHandOffAcknowledgment | HandOff | HandOffComplete | RegionTerminated | EntityStarted | EntityStopped | RememberedEntities | ShardEnvelope | ShardReply;
 export declare function isShardingMessage(msg: unknown): msg is ShardingMessage;
 //# sourceMappingURL=ShardingProtocol.d.ts.map

package/dist/cluster/sharding/ShardingProtocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShardingProtocol.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardingProtocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ShardingProtocol.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardingProtocol.ts"],"names":[],"mappings":"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"}

package/dist/cluster/sharding/StartShardingOptions.d.ts

@@ -0,0 +1,106 @@
+import type { Lease } from '../../coordination/Lease.js';
+import type { AllocationStrategy } from './AllocationStrategy.js';
+import type { CoordinatorStateStore } from './CoordinatorState.js';
+import type { RememberEntitiesStore } from './RememberEntitiesStore.js';
+import { ShardingOptionsBuilder, ShardingOptionsValidator } from './ShardingOptions.js';
+import type { ShardingOptionsType } from './ShardingOptions.js';
+/**
+ * Plain options-object shape accepted by {@link ClusterSharding.start} —
+ * the region-side {@link ShardingOptionsType} plus the coordinator-side
+ * fields (allocation, rebalance, lease, persistence backends).
+ */
+export interface StartShardingOptionsType<TMessage> extends ShardingOptionsType<TMessage> {
+    /** Strategy the coordinator uses to allocate and rebalance shards. */
+    readonly allocationStrategy?: AllocationStrategy;
+    /** Gap between coordinator-driven rebalance passes. */
+    readonly rebalanceIntervalMs?: number;
+    /** Time to wait for HandOffComplete before force-reallocating. */
+    readonly handOffTimeoutMs?: number;
+    /**
+     * Optional split-brain protection for the coordinator.  When set,
+     * the elected leader's coordinator must hold the lease before it
+     * processes shard messages — under a network partition that
+     * produces two leader views, only the side that successfully
+     * acquires the lease ever issues `AllocateShard` / `HandOff`
+     * directives.  See `ShardCoordinatorOptionsType.lease`.
+     */
+    readonly lease?: Lease;
+    /** Retry interval for `lease.acquire()` after a failed attempt.  Default: 5 s. */
+    readonly acquireRetryIntervalMs?: number;
+    /**
+     * Optional persistence backend for the entity registry — relevant
+     * only when `rememberEntities: true`.  When omitted (and
+     * `rememberEntities: true`), the default
+     * `JournalRememberEntitiesStore` is auto-instantiated using the
+     * Journal from the system's `PersistenceExtension`, so a full
+     * cluster cold-start no longer loses the registry.  Set to a
+     * custom impl to plug in a separate store.
+     *
+     * Pass `null` to opt out of persistence entirely (registry stays
+     * in-memory only — the v1 behaviour).
+     */
+    readonly rememberEntitiesStore?: RememberEntitiesStore | null;
+    /**
+     * Optional persistence backend for the coordinator's allocation
+     * state (`regions` + `shardHome`).  When set, a new leader
+     * elected after the previous leader's failure can seed its
+     * coordinator from the snapshot instead of running
+     * `tryAllocate` from scratch — saves a brief reallocation storm
+     * at thousands-of-shards scale.
+     *
+     * Unlike `rememberEntitiesStore`, ClusterSharding does NOT
+     * auto-instantiate this — the user must explicitly pass a store
+     * (typically `new DistributedDataCoordinatorStateStore(dd, ...)`).
+     * Without it, the v1 rebuild-from-Register behaviour is preserved.
+     */
+    readonly coordinatorStateStore?: CoordinatorStateStore;
+}
+/**
+ * Fluent builder for {@link StartShardingOptionsType} — the argument to
+ * {@link ClusterSharding.start}.  Extends {@link ShardingOptionsBuilder} so it
+ * carries every region-side `withX` (typeName, entityProps, extractors,
+ * numShards, role, proxy, rememberEntities, …) and adds the
+ * coordinator-side fields on top.
+ *
+ * The polymorphic fields are passed whole via a single `withX(value)`:
+ * `allocationStrategy` ({@link AllocationStrategy}), `lease`
+ * ({@link Lease}), `rememberEntitiesStore`, and `coordinatorStateStore`.
+ */
+export declare class StartShardingOptionsBuilder<TMessage> extends ShardingOptionsBuilder<TMessage, StartShardingOptionsType<TMessage>> {
+    /** Start a fresh builder.  Equivalent to `new StartShardingOptionsBuilder<TMessage>()`. */
+    static create<TMessage>(): StartShardingOptionsBuilder<TMessage>;
+    /** Strategy the coordinator uses to allocate and rebalance shards. */
+    withAllocationStrategy(allocationStrategy: AllocationStrategy): this;
+    /** Gap between coordinator-driven rebalance passes. */
+    withRebalanceIntervalMs(rebalanceIntervalMs: number): this;
+    /** Time to wait for HandOffComplete before force-reallocating. */
+    withHandOffTimeoutMs(handOffTimeoutMs: number): this;
+    /** Optional split-brain protection for the coordinator (a {@link Lease}). */
+    withLease(lease: Lease): this;
+    /** Retry interval for `lease.acquire()` after a failed attempt.  Default: 5 s. */
+    withAcquireRetryIntervalMs(acquireRetryIntervalMs: number): this;
+    /**
+     * Persistence backend for the entity registry (only when `rememberEntities`).
+     * Pass `null` to keep the registry in-memory only (opt out of persistence).
+     */
+    withRememberEntitiesStore(rememberEntitiesStore: RememberEntitiesStore | null): this;
+    /** Persistence backend for the coordinator's allocation state. */
+    withCoordinatorStateStore(coordinatorStateStore: CoordinatorStateStore): this;
+}
+/**
+ * Validates resolved {@link StartShardingOptionsType} settings — the region-side
+ * {@link ShardingOptionsValidator} rules plus the coordinator-side intervals.
+ */
+export declare class StartShardingOptionsValidator<TMessage> extends ShardingOptionsValidator<TMessage, StartShardingOptionsType<TMessage>> {
+    constructor();
+    protected rules(s: Partial<StartShardingOptionsType<TMessage>>): void;
+}
+/**
+ * Accepted input for {@link ClusterSharding.start}: the fluent
+ * {@link StartShardingOptionsBuilder} OR a plain (partial)
+ * {@link StartShardingOptionsType} object.
+ */
+export type StartShardingOptions<TMessage> = StartShardingOptionsBuilder<TMessage> | Partial<StartShardingOptionsType<TMessage>>;
+/** Value alias so `StartShardingOptions.create()` / `new StartShardingOptions()` resolve to the builder. */
+export declare const StartShardingOptions: typeof StartShardingOptionsBuilder;
+//# sourceMappingURL=StartShardingOptions.d.ts.map

package/dist/cluster/sharding/StartShardingOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StartShardingOptions.d.ts","sourceRoot":"","sources":["../../../src/cluster/sharding/StartShardingOptions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB,CAAC,QAAQ,CAAE,SAAQ,mBAAmB,CAAC,QAAQ,CAAC;IACvF,sEAAsE;IACtE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;IACjD,uDAAuD;IACvD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,kFAAkF;IAClF,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC9D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;CACxD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,2BAA2B,CAAC,QAAQ,CAAE,SAAQ,sBAAsB,CAAC,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAC7H,2FAA2F;IAC3F,MAAM,CAAC,MAAM,CAAC,QAAQ,KAAK,2BAA2B,CAAC,QAAQ,CAAC;IAIhE,sEAAsE;IACtE,sBAAsB,CAAC,kBAAkB,EAAE,kBAAkB,GAAG,IAAI;IAIpE,uDAAuD;IACvD,uBAAuB,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI;IAI1D,kEAAkE;IAClE,oBAAoB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAIpD,6EAA6E;IAC7E,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAI7B,kFAAkF;IAClF,0BAA0B,CAAC,sBAAsB,EAAE,MAAM,GAAG,IAAI;IAIhE;;;OAGG;IACH,yBAAyB,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,IAAI,GAAG,IAAI;IAIpF,kEAAkE;IAClE,yBAAyB,CAAC,qBAAqB,EAAE,qBAAqB,GAAG,IAAI;CAG9E;AAED;;;GAGG;AACH,qBAAa,6BAA6B,CAAC,QAAQ,CACjD,SAAQ,wBAAwB,CAAC,QAAQ,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;;cAI3D,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI;CAM/E;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,QAAQ,IACrC,2BAA2B,CAAC,QAAQ,CAAC,GACrC,OAAO,CAAC,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChD,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,oCAA8B,CAAC"}