actor-ts 0.9.0 → 0.10.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;AAK7C,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;CAgEjC"}

package/dist/cluster/sharding/ShardedDaemonProcess.js

@@ -4,6 +4,7 @@ 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';
 const WAKEUP = { t: 'sharded-daemon.wakeup' };
 /**
  * Starts exactly N named daemon actors spread across the cluster.  Built on
@@ -17,18 +18,20 @@ 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 settings = options;
         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-${settings.name}`)
+            .withEntityProps(Props.create(() => new DaemonHost(settings.behaviorFor)))
+            .withExtractEntityId((env) => String(env.index))
+            .withExtractEntityMessage((env) => env.body)
+            .withNumShards(settings.numDaemons)
+            .withRememberEntities(true)
+            .withAllocationStrategy(new LeastShardAllocationStrategy());
+        if (settings.role !== undefined)
+            startOptions.withRole(settings.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 = () => {

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

@@ -1 +1 @@
-{"version":3,"file":"ShardedDaemonProcess.js","sourceRoot":"","sources":["../../../src/cluster/sharding/ShardedDaemonProcess.ts"],"names":[],"mappings":"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"}
+{"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,51 @@
+import type { Props } from '../../Props.js';
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/** Plain settings-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;
+}
+/**
+ * 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;AAE9D,iFAAiF;AACjF,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;;;;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,35 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.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);
+    }
+}
+/** 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;AAwB9D;;;;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;AAUD,0HAA0H;AAC1H,MAAM,CAAC,MAAM,2BAA2B,GAAG,kCAAkC,CAAC"}

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

@@ -0,0 +1,84 @@
+import type { Props } from '../../Props.js';
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/**
+ * Plain settings-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<TMsg> {
+    readonly typeName: string;
+    readonly entityProps: Props<TMsg>;
+    readonly extractEntityId: (message: TMsg) => string;
+    readonly extractEntityMessage?: (message: TMsg) => 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 settings 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<TMsg, S extends ShardingOptionsType<TMsg> = ShardingOptionsType<TMsg>> extends OptionsBuilder<S> {
+    /** Start a fresh builder.  Equivalent to `new ShardingOptionsBuilder<TMsg>()`. */
+    static create<TMsg>(): ShardingOptionsBuilder<TMsg>;
+    /** Logical name of the sharded type. */
+    withTypeName(typeName: string): this;
+    /** Props used to spawn each entity instance. */
+    withEntityProps(entityProps: Props<TMsg>): this;
+    /** Derive the stable entity id from an incoming message. */
+    withExtractEntityId(extractEntityId: (message: TMsg) => string): this;
+    /** Unwrap the payload actually delivered to the entity.  Default: identity. */
+    withExtractEntityMessage(extractEntityMessage: (message: TMsg) => 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;
+}
+/**
+ * Accepted input for a sharded-region-configurable API: the fluent
+ * {@link ShardingOptionsBuilder} OR a plain {@link ShardingOptionsType} object.
+ */
+export type ShardingOptions<TMsg, S extends ShardingOptionsType<TMsg> = ShardingOptionsType<TMsg>> = ShardingOptionsBuilder<TMsg, 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;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB,CAAC,IAAI;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,IAAI,KAAK,MAAM,CAAC;IACpD,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,OAAO,EAAE,IAAI,KAAK,OAAO,CAAC;IAC3D,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,IAAI,EACJ,CAAC,SAAS,mBAAmB,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAC/D,SAAQ,cAAc,CAAC,CAAC,CAAC;IACzB,kFAAkF;IAClF,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,sBAAsB,CAAC,IAAI,CAAC;IAInD,wCAAwC;IACxC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIpC,gDAAgD;IAChD,eAAe,CAAC,WAAW,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI;IAI/C,4DAA4D;IAC5D,mBAAmB,CAAC,eAAe,EAAE,CAAC,OAAO,EAAE,IAAI,KAAK,MAAM,GAAG,IAAI;IAIrE,+EAA+E;IAC/E,wBAAwB,CAAC,oBAAoB,EAAE,CAAC,OAAO,EAAE,IAAI,KAAK,OAAO,GAAG,IAAI;IAIhF,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;;;GAGG;AACH,MAAM,MAAM,eAAe,CACzB,IAAI,EACJ,CAAC,SAAS,mBAAmB,CAAC,IAAI,CAAC,GAAG,mBAAmB,CAAC,IAAI,CAAC,IAC7D,sBAAsB,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;AACxC,kGAAkG;AAClG,eAAO,MAAM,eAAe,+BAAyB,CAAC"}

package/dist/cluster/sharding/ShardingOptions.js

@@ -0,0 +1,62 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.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 settings 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<TMsg>()`. */
+    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);
+    }
+}
+/** 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":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAyC9D;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,sBAGX,SAAQ,cAAiB;IACzB,kFAAkF;IAClF,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,sBAAsB,EAAQ,CAAC;IAC5C,CAAC;IAED,wCAAwC;IACxC,YAAY,CAAC,QAAgB;QAC3B,OAAO,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,gDAAgD;IAChD,eAAe,CAAC,WAAwB;QACtC,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;IAED,4DAA4D;IAC5D,mBAAmB,CAAC,eAA0C;QAC5D,OAAO,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IACtD,CAAC;IAED,+EAA+E;IAC/E,wBAAwB,CAAC,oBAAgD;QACvE,OAAO,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,oBAAoB,CAAC,CAAC;IAChE,CAAC;IAED,gEAAgE;IAChE,aAAa,CAAC,SAAiB;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,wEAAwE;IACxE,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,uEAAuE;IACvE,SAAS,CAAC,KAAK,GAAG,IAAI;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,6EAA6E;IAC7E,oBAAoB,CAAC,gBAAgB,GAAG,IAAI;QAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;IACxD,CAAC;IAED,oEAAoE;IACpE,qBAAqB,CAAC,iBAAyB;QAC7C,OAAO,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC;IAC1D,CAAC;IAED,kGAAkG;IAClG,eAAe,CAAC,WAAmB;QACjC,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;CACF;AAUD,kGAAkG;AAClG,MAAM,CAAC,MAAM,eAAe,GAAG,sBAAsB,CAAC"}

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

@@ -0,0 +1,98 @@
+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 } from './ShardingOptions.js';
+import type { ShardingOptionsType } from './ShardingOptions.js';
+/**
+ * Plain settings-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<TMsg> extends ShardingOptionsType<TMsg> {
+    /** 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<TMsg> extends ShardingOptionsBuilder<TMsg, StartShardingOptionsType<TMsg>> {
+    /** Start a fresh builder.  Equivalent to `new StartShardingOptionsBuilder<TMsg>()`. */
+    static create<TMsg>(): StartShardingOptionsBuilder<TMsg>;
+    /** 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;
+}
+/**
+ * Accepted input for {@link ClusterSharding.start}: the fluent
+ * {@link StartShardingOptionsBuilder} OR a plain (partial)
+ * {@link StartShardingOptionsType} object.
+ */
+export type StartShardingOptions<TMsg> = StartShardingOptionsBuilder<TMsg> | Partial<StartShardingOptionsType<TMsg>>;
+/** 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,MAAM,sBAAsB,CAAC;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB,CAAC,IAAI,CAAE,SAAQ,mBAAmB,CAAC,IAAI,CAAC;IAC/E,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,IAAI,CAAE,SAAQ,sBAAsB,CAAC,IAAI,EAAE,wBAAwB,CAAC,IAAI,CAAC,CAAC;IACjH,uFAAuF;IACvF,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,2BAA2B,CAAC,IAAI,CAAC;IAIxD,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;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,IAAI,IACjC,2BAA2B,CAAC,IAAI,CAAC,GACjC,OAAO,CAAC,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5C,4GAA4G;AAC5G,eAAO,MAAM,oBAAoB,oCAA8B,CAAC"}

package/dist/cluster/sharding/StartShardingOptions.js

@@ -0,0 +1,52 @@
+import { ShardingOptionsBuilder } from './ShardingOptions.js';
+/**
+ * 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 class StartShardingOptionsBuilder extends ShardingOptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new StartShardingOptionsBuilder<TMsg>()`. */
+    static create() {
+        return new StartShardingOptionsBuilder();
+    }
+    /** Strategy the coordinator uses to allocate and rebalance shards. */
+    withAllocationStrategy(allocationStrategy) {
+        return this.set('allocationStrategy', allocationStrategy);
+    }
+    /** Gap between coordinator-driven rebalance passes. */
+    withRebalanceIntervalMs(rebalanceIntervalMs) {
+        return this.set('rebalanceIntervalMs', rebalanceIntervalMs);
+    }
+    /** Time to wait for HandOffComplete before force-reallocating. */
+    withHandOffTimeoutMs(handOffTimeoutMs) {
+        return this.set('handOffTimeoutMs', handOffTimeoutMs);
+    }
+    /** Optional split-brain protection for the coordinator (a {@link Lease}). */
+    withLease(lease) {
+        return this.set('lease', lease);
+    }
+    /** Retry interval for `lease.acquire()` after a failed attempt.  Default: 5 s. */
+    withAcquireRetryIntervalMs(acquireRetryIntervalMs) {
+        return this.set('acquireRetryIntervalMs', acquireRetryIntervalMs);
+    }
+    /**
+     * Persistence backend for the entity registry (only when `rememberEntities`).
+     * Pass `null` to keep the registry in-memory only (opt out of persistence).
+     */
+    withRememberEntitiesStore(rememberEntitiesStore) {
+        return this.set('rememberEntitiesStore', rememberEntitiesStore);
+    }
+    /** Persistence backend for the coordinator's allocation state. */
+    withCoordinatorStateStore(coordinatorStateStore) {
+        return this.set('coordinatorStateStore', coordinatorStateStore);
+    }
+}
+/** Value alias so `StartShardingOptions.create()` / `new StartShardingOptions()` resolve to the builder. */
+export const StartShardingOptions = StartShardingOptionsBuilder;
+//# sourceMappingURL=StartShardingOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StartShardingOptions.js","sourceRoot":"","sources":["../../../src/cluster/sharding/StartShardingOptions.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAuD9D;;;;;;;;;;GAUG;AACH,MAAM,OAAO,2BAAkC,SAAQ,sBAA4D;IACjH,uFAAuF;IACvF,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,2BAA2B,EAAQ,CAAC;IACjD,CAAC;IAED,sEAAsE;IACtE,sBAAsB,CAAC,kBAAsC;QAC3D,OAAO,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;IAC5D,CAAC;IAED,uDAAuD;IACvD,uBAAuB,CAAC,mBAA2B;QACjD,OAAO,IAAI,CAAC,GAAG,CAAC,qBAAqB,EAAE,mBAAmB,CAAC,CAAC;IAC9D,CAAC;IAED,kEAAkE;IAClE,oBAAoB,CAAC,gBAAwB;QAC3C,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;IACxD,CAAC;IAED,6EAA6E;IAC7E,SAAS,CAAC,KAAY;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,kFAAkF;IAClF,0BAA0B,CAAC,sBAA8B;QACvD,OAAO,IAAI,CAAC,GAAG,CAAC,wBAAwB,EAAE,sBAAsB,CAAC,CAAC;IACpE,CAAC;IAED;;;OAGG;IACH,yBAAyB,CAAC,qBAAmD;QAC3E,OAAO,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;IAClE,CAAC;IAED,kEAAkE;IAClE,yBAAyB,CAAC,qBAA4C;QACpE,OAAO,IAAI,CAAC,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;IAClE,CAAC;CACF;AAUD,4GAA4G;AAC5G,MAAM,CAAC,MAAM,oBAAoB,GAAG,2BAA2B,CAAC"}

package/dist/cluster/singleton/ClusterSingleton.d.ts

@@ -1,38 +1,10 @@
 import type { ActorRef } from '../../ActorRef.js';
 import type { ActorSystem } from '../../ActorSystem.js';
-import type { Lease } from '../../coordination/Lease.js';
 import { type ExtensionId } from '../../Extension.js';
-import { Props } from '../../Props.js';
 import type { Cluster } from '../Cluster.js';
 import { type Option } from '../../util/Option.js';
+import type { StartSingletonOptions } from './StartSingletonOptions.js';
 import { ClusterSingletonProxy } from './ClusterSingletonProxy.js';
-export interface StartSingletonSettings<T> {
-    /** Logical name for this singleton — used in the manager/child actor path. */
-    readonly typeName: string;
-    /** Props used to construct the singleton on the leader. */
-    readonly props: Props<T>;
-    /** If set, only nodes carrying this role tag will host the singleton. */
-    readonly role?: string;
-    /**
-     * Optional split-brain protection.  When provided, the elected
-     * leader's manager calls `lease.acquire()` before spawning the
-     * singleton — so a partition that produces two oldest views still
-     * only ever spawns the singleton on the side that holds the lease.
-     * The manager subscribes to `lease.onLost(reason)` and stops the
-     * child if ownership is revoked mid-flight.
-     *
-     * Without a lease the manager keeps its current sync behaviour:
-     * spawn the moment cluster gossip says we're leader, no external
-     * arbitration.
-     */
-    readonly lease?: Lease;
-    /**
-     * How often to retry `lease.acquire()` after a failed attempt
-     * (another holder owns it, transient backend error, etc.).
-     * Default: `5_000` ms.  Ignored if no lease is provided.
-     */
-    readonly acquireRetryIntervalMs?: number;
-}
 export interface SingletonHandle<T> {
     /** Location-transparent ActorRef — tell here, the leader's instance receives. */
     readonly proxy: ClusterSingletonProxy<T>;
@@ -51,7 +23,7 @@ export declare class ClusterSingleton {
     private readonly system;
     private handles;
     constructor(system: ActorSystem);
-    start<T>(cluster: Cluster, settings: StartSingletonSettings<T>): SingletonHandle<T>;
+    start<T>(cluster: Cluster, options: StartSingletonOptions<T>): SingletonHandle<T>;
     /** Look up a previously-started singleton by typeName. */
     get<T>(typeName: string): Option<SingletonHandle<T>>;
 }

package/dist/cluster/singleton/ClusterSingleton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterSingleton.d.ts","sourceRoot":"","sources":["../../../src/cluster/singleton/ClusterSingleton.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACzD,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAMjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,yCAAyC;IACzC,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAEf,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,OAAO,CAAC,OAAO,CAA+C;gBACjC,MAAM,EAAE,WAAW;IAEhD,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;IA2CnF,0DAA0D;IAC1D,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAGrD;AAED,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,gBAAgB,CAG5D,CAAC"}
+{"version":3,"file":"ClusterSingleton.d.ts","sourceRoot":"","sources":["../../../src/cluster/singleton/ClusterSingleton.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAOjE,OAAO,KAAK,EAAE,qBAAqB,EAA6B,MAAM,4BAA4B,CAAC;AACnG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACzC,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;IAC3B,yCAAyC;IACzC,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAEf,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,OAAO,CAAC,OAAO,CAA+C;gBACjC,MAAM,EAAE,WAAW;IAEhD,KAAK,CAAC,CAAC,EACL,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAChC,eAAe,CAAC,CAAC,CAAC;IA8CrB,0DAA0D;IAC1D,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAGrD;AAED,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,gBAAgB,CAG5D,CAAC"}