actor-ts 0.9.0

package/dist/pattern/CircuitBreaker.js

@@ -0,0 +1,110 @@
+export class CircuitBreakerOpenError extends Error {
+    constructor(message = 'circuit breaker is open') {
+        super(message);
+        this.name = 'CircuitBreakerOpenError';
+    }
+}
+export class CircuitBreakerTimeoutError extends Error {
+    constructor(ms) {
+        super(`call timed out after ${ms}ms`);
+        this.name = 'CircuitBreakerTimeoutError';
+    }
+}
+/**
+ * Three-state circuit breaker.  Wraps calls that might fail — when enough
+ * fail in a row the breaker "opens" and refuses further calls for a
+ * timeout window.  The first call after the timeout probes the upstream
+ * ("half-open"); if it succeeds, the breaker closes and normal operation
+ * resumes.
+ *
+ * Not tied to actors — works with any `() => Promise<T>` factory.  For
+ * actor-based usage, wrap `ask(target, msg, timeout)` in the factory.
+ */
+export class CircuitBreaker {
+    settings;
+    _state = 'closed';
+    failureCount = 0;
+    nextProbeAt = 0;
+    listeners = new Set();
+    constructor(settings) {
+        this.settings = settings;
+        if (settings.maxFailures < 1) {
+            throw new Error('CircuitBreaker: maxFailures must be >= 1');
+        }
+        if (settings.resetTimeoutMs < 0) {
+            throw new Error('CircuitBreaker: resetTimeoutMs must be >= 0');
+        }
+    }
+    get state() { return this._state; }
+    /** Call `factory` under breaker supervision.  Throws `CircuitBreakerOpenError` when open. */
+    async call(factory) {
+        this.maybeTransitionToHalfOpen();
+        if (this._state === 'open')
+            throw new CircuitBreakerOpenError();
+        const promise = this.settings.callTimeoutMs && this.settings.callTimeoutMs > 0
+            ? this.applyTimeout(factory(), this.settings.callTimeoutMs)
+            : factory();
+        try {
+            const value = await promise;
+            this.onSuccess();
+            return value;
+        }
+        catch (err) {
+            const asErr = err instanceof Error ? err : new Error(String(err));
+            const isFailure = this.settings.isFailure?.(asErr) ?? true;
+            if (isFailure)
+                this.onFailure();
+            throw asErr;
+        }
+    }
+    /** Observe state transitions — useful for logging/metrics. */
+    onStateChange(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Force the breaker into a specific state (mostly for tests / admin). */
+    setState(next) {
+        if (this._state === next)
+            return;
+        this._state = next;
+        this.failureCount = 0;
+        if (next === 'open')
+            this.nextProbeAt = Date.now() + this.settings.resetTimeoutMs;
+        for (const l of this.listeners) {
+            try {
+                l(next);
+            }
+            catch { /* ignore */ }
+        }
+    }
+    onSuccess() {
+        if (this._state === 'half-open') {
+            this.setState('closed');
+            return;
+        }
+        this.failureCount = 0;
+    }
+    onFailure() {
+        if (this._state === 'half-open') {
+            this.setState('open');
+            return;
+        }
+        this.failureCount++;
+        if (this.failureCount >= this.settings.maxFailures) {
+            this.setState('open');
+        }
+    }
+    maybeTransitionToHalfOpen() {
+        if (this._state !== 'open')
+            return;
+        if (Date.now() >= this.nextProbeAt)
+            this.setState('half-open');
+    }
+    applyTimeout(p, ms) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => reject(new CircuitBreakerTimeoutError(ms)), ms);
+            p.then((v) => { clearTimeout(timer); resolve(v); }, (e) => { clearTimeout(timer); reject(e); });
+        });
+    }
+}
+//# sourceMappingURL=CircuitBreaker.js.map

package/dist/pattern/CircuitBreaker.js.map

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

package/dist/pattern/Status.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Historical location of the `Success` / `Failure` marker classes used
+ * by `pipeTo`.  They have since been unified with the richer `Try<T>`
+ * implementation in `src/util/Try.ts` — this module just re-exports so
+ * legacy import paths (`import { Success, Failure } from '…/pattern'`)
+ * keep working.
+ *
+ * `Failure` from `Try<T>` still has `.cause` as a back-compat getter,
+ * so existing pipeTo consumers that wrote `msg.cause.message` don't
+ * need to change.
+ */
+export { Success, Failure } from '../util/Try.js';
+//# sourceMappingURL=Status.d.ts.map

package/dist/pattern/Status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Status.d.ts","sourceRoot":"","sources":["../../src/pattern/Status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/pattern/Status.js

@@ -0,0 +1,13 @@
+/**
+ * Historical location of the `Success` / `Failure` marker classes used
+ * by `pipeTo`.  They have since been unified with the richer `Try<T>`
+ * implementation in `src/util/Try.ts` — this module just re-exports so
+ * legacy import paths (`import { Success, Failure } from '…/pattern'`)
+ * keep working.
+ *
+ * `Failure` from `Try<T>` still has `.cause` as a back-compat getter,
+ * so existing pipeTo consumers that wrote `msg.cause.message` don't
+ * need to change.
+ */
+export { Success, Failure } from '../util/Try.js';
+//# sourceMappingURL=Status.js.map

package/dist/pattern/Status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Status.js","sourceRoot":"","sources":["../../src/pattern/Status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/pattern/after.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Wait for `delayMs`, then execute `factory()` and return its eventual
+ * value.  The delay is cancellable via the returned Promise's `.cancel()`
+ * method — useful for building retry/timeout helpers.
+ *
+ * `factory` is called once after the delay; if you need to re-evaluate on
+ * each retry, pass a function that returns a fresh Promise each time.
+ */
+export interface CancellablePromise<T> extends Promise<T> {
+    cancel(): void;
+}
+export declare function after<T>(delayMs: number, factory: () => Promise<T>): CancellablePromise<T>;
+//# sourceMappingURL=after.d.ts.map

package/dist/pattern/after.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"after.d.ts","sourceRoot":"","sources":["../../src/pattern/after.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,CAAE,SAAQ,OAAO,CAAC,CAAC,CAAC;IACvD,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAqB1F"}

package/dist/pattern/after.js

@@ -0,0 +1,26 @@
+export function after(delayMs, factory) {
+    let timer = null;
+    let cancelled = false;
+    let rejectOuter = null;
+    const wrapped = new Promise((resolve, reject) => {
+        rejectOuter = reject;
+        timer = setTimeout(() => {
+            timer = null;
+            if (cancelled)
+                return;
+            factory().then(resolve, reject);
+        }, delayMs);
+    });
+    wrapped.cancel = () => {
+        if (cancelled)
+            return;
+        cancelled = true;
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        rejectOuter?.(new Error('after: cancelled'));
+    };
+    return wrapped;
+}
+//# sourceMappingURL=after.js.map

package/dist/pattern/after.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"after.js","sourceRoot":"","sources":["../../src/pattern/after.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,KAAK,CAAI,OAAe,EAAE,OAAyB;IACjE,IAAI,KAAK,GAAyC,IAAI,CAAC;IACvD,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,WAAW,GAAkC,IAAI,CAAC;IAEtD,MAAM,OAAO,GAAG,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACjD,WAAW,GAAG,MAAM,CAAC;QACrB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,KAAK,GAAG,IAAI,CAAC;YACb,IAAI,SAAS;gBAAE,OAAO;YACtB,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAClC,CAAC,EAAE,OAAO,CAAC,CAAC;IACd,CAAC,CAA0B,CAAC;IAE5B,OAAO,CAAC,MAAM,GAAG,GAAS,EAAE;QAC1B,IAAI,SAAS;YAAE,OAAO;QACtB,SAAS,GAAG,IAAI,CAAC;QACjB,IAAI,KAAK,EAAE,CAAC;YAAC,YAAY,CAAC,KAAK,CAAC,CAAC;YAAC,KAAK,GAAG,IAAI,CAAC;QAAC,CAAC;QACjD,WAAW,EAAE,CAAC,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC;IACF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/pattern/index.d.ts

@@ -0,0 +1,14 @@
+export { CircuitBreaker, CircuitBreakerOpenError, CircuitBreakerTimeoutError, } from './CircuitBreaker.js';
+export type { CircuitBreakerSettings, CircuitState } from './CircuitBreaker.js';
+export { pipeTo } from './pipeTo.js';
+export type { PipeToOptions } from './pipeTo.js';
+export { after } from './after.js';
+export type { CancellablePromise } from './after.js';
+export { retry } from './retry.js';
+export type { RetryOptions } from './retry.js';
+export { Success, Failure } from './Status.js';
+export { exponentialBackoff, linearBackoff } from './BackoffPolicy.js';
+export type { BackoffPolicy, ExponentialBackoffOptions, LinearBackoffOptions, } from './BackoffPolicy.js';
+export { BackoffSupervisor } from './BackoffSupervisor.js';
+export type { BackoffOptions, ResetCounter, ForwardStrategy, } from './BackoffSupervisor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/pattern/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pattern/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACvE,YAAY,EACV,aAAa,EACb,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EACV,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,MAAM,wBAAwB,CAAC"}

package/dist/pattern/index.js

@@ -0,0 +1,8 @@
+export { CircuitBreaker, CircuitBreakerOpenError, CircuitBreakerTimeoutError, } from './CircuitBreaker.js';
+export { pipeTo } from './pipeTo.js';
+export { after } from './after.js';
+export { retry } from './retry.js';
+export { Success, Failure } from './Status.js';
+export { exponentialBackoff, linearBackoff } from './BackoffPolicy.js';
+export { BackoffSupervisor } from './BackoffSupervisor.js';
+//# sourceMappingURL=index.js.map

package/dist/pattern/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pattern/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/pattern/pipeTo.d.ts

@@ -0,0 +1,20 @@
+import type { ActorRef } from '../ActorRef.js';
+export interface PipeToOptions {
+    /** ActorRef attributed as the sender on the tell; optional. */
+    readonly sender?: ActorRef | null;
+    /**
+     * When true (default), wraps the value in `Success` and the error in
+     * `Failure` before telling.  Set to false to forward the raw value on
+     * success and drop errors.
+     */
+    readonly wrap?: boolean;
+}
+/**
+ * Route the eventual result of `promise` into an actor's mailbox.  On
+ * fulfilment the value (or `Success<T>`) lands as a message.  On rejection
+ * `Failure(error)` is delivered so the actor can react.
+ *
+ * Returns the same promise so callers can chain further logic if needed.
+ */
+export declare function pipeTo<T>(promise: Promise<T>, recipient: ActorRef, options?: PipeToOptions): Promise<T>;
+//# sourceMappingURL=pipeTo.d.ts.map

package/dist/pattern/pipeTo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeTo.d.ts","sourceRoot":"","sources":["../../src/pattern/pipeTo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAG/C,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,QAAQ,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,CAAC,CAAC,CAeZ"}

package/dist/pattern/pipeTo.js

@@ -0,0 +1,22 @@
+import { Failure, Success } from './Status.js';
+/**
+ * Route the eventual result of `promise` into an actor's mailbox.  On
+ * fulfilment the value (or `Success<T>`) lands as a message.  On rejection
+ * `Failure(error)` is delivered so the actor can react.
+ *
+ * Returns the same promise so callers can chain further logic if needed.
+ */
+export function pipeTo(promise, recipient, options = {}) {
+    const wrap = options.wrap ?? true;
+    const sender = options.sender ?? null;
+    promise.then((v) => {
+        recipient.tell(wrap ? new Success(v) : v, sender);
+    }, (err) => {
+        if (wrap) {
+            recipient.tell(new Failure(err instanceof Error ? err : new Error(String(err))), sender);
+        }
+        // When !wrap, rejections are silently dropped — the caller opted out.
+    });
+    return promise;
+}
+//# sourceMappingURL=pipeTo.js.map

package/dist/pattern/pipeTo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeTo.js","sourceRoot":"","sources":["../../src/pattern/pipeTo.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAa/C;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CACpB,OAAmB,EACnB,SAAmB,EACnB,UAAyB,EAAE;IAE3B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACtC,OAAO,CAAC,IAAI,CACV,CAAC,CAAC,EAAE,EAAE;QACJ,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAW,EAAE,MAAM,CAAC,CAAC;IAC/D,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;QACf,IAAI,IAAI,EAAE,CAAC;YACT,SAAS,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAU,EAAE,MAAM,CAAC,CAAC;QACpG,CAAC;QACD,sEAAsE;IACxE,CAAC,CACF,CAAC;IACF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/pattern/retry.d.ts

@@ -0,0 +1,24 @@
+export interface RetryOptions {
+    /** Total attempts including the initial call.  Must be >= 1. */
+    readonly attempts: number;
+    /** Base delay between retries, in ms. */
+    readonly delayMs?: number;
+    /** Exponential-backoff multiplier applied to `delayMs` (default 1 — no backoff). */
+    readonly factor?: number;
+    /** Upper bound for any individual retry delay. */
+    readonly maxDelayMs?: number;
+    /**
+     * Predicate that decides whether a specific error is retryable.  Return
+     * false to short-circuit with the final error.  Defaults to "retry any".
+     */
+    readonly shouldRetry?: (err: Error, attempt: number) => boolean;
+    /** Called after each failed attempt; useful for logging/metrics. */
+    readonly onAttempt?: (err: Error, attempt: number) => void;
+}
+/**
+ * Invoke `factory` up to `options.attempts` times with configurable
+ * exponential backoff.  Returns the first successful result.  Propagates
+ * the final error if every attempt fails or `shouldRetry` vetoes a retry.
+ */
+export declare function retry<T>(factory: () => Promise<T>, options: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/pattern/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/pattern/retry.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAChE,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5D;AAED;;;;GAIG;AACH,wBAAsB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,CAAC,CA2B3F"}

package/dist/pattern/retry.js

@@ -0,0 +1,35 @@
+/**
+ * Invoke `factory` up to `options.attempts` times with configurable
+ * exponential backoff.  Returns the first successful result.  Propagates
+ * the final error if every attempt fails or `shouldRetry` vetoes a retry.
+ */
+export async function retry(factory, options) {
+    const max = options.attempts;
+    if (max < 1)
+        throw new Error(`retry: attempts must be >= 1 (got ${max})`);
+    const base = options.delayMs ?? 0;
+    const factor = options.factor ?? 1;
+    const maxDelay = options.maxDelayMs ?? Number.POSITIVE_INFINITY;
+    const shouldRetry = options.shouldRetry ?? (() => true);
+    let lastError;
+    for (let attempt = 1; attempt <= max; attempt++) {
+        try {
+            return await factory();
+        }
+        catch (err) {
+            lastError = err;
+            const asErr = err instanceof Error ? err : new Error(String(err));
+            options.onAttempt?.(asErr, attempt);
+            if (attempt >= max || !shouldRetry(asErr, attempt)) {
+                throw asErr;
+            }
+            const delay = Math.min(base * Math.pow(factor, attempt - 1), maxDelay);
+            if (delay > 0) {
+                await new Promise(r => setTimeout(r, delay));
+            }
+        }
+    }
+    // Unreachable, but TS can't prove it.
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+//# sourceMappingURL=retry.js.map

package/dist/pattern/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/pattern/retry.ts"],"names":[],"mappings":"AAkBA;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CAAI,OAAyB,EAAE,OAAqB;IAC7E,MAAM,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC7B,IAAI,GAAG,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,GAAG,GAAG,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC;IAClC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,IAAI,MAAM,CAAC,iBAAiB,CAAC;IAChE,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,GAAY,EAAE,CAAC,IAAI,CAAC,CAAC;IAEjE,IAAI,SAAkB,CAAC;IACvB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC;QAChD,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,EAAE,CAAC;QACzB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,SAAS,GAAG,GAAG,CAAC;YAChB,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAClE,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACpC,IAAI,OAAO,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;gBACnD,MAAM,KAAK,CAAC;YACd,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;YACvE,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;IACD,sCAAsC;IACtC,MAAM,SAAS,YAAY,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC;AAC9E,CAAC"}

package/dist/persistence/DurableStateActor.d.ts

@@ -0,0 +1,62 @@
+import { Actor } from '../Actor.js';
+import { type DurableStateRecord, type DurableStateStore } from './DurableStateStore.js';
+import type { CompressionConfig, EncryptionConfig } from './PersistenceOptions.js';
+import type { StateAdapter } from './migration/Adapter.js';
+export interface DurableStateSettings<S> {
+    readonly persistenceId: string;
+    readonly store: DurableStateStore;
+    /** Factory invoked when no record exists yet. */
+    readonly emptyState: () => S;
+}
+/**
+ * Base class for actors that persist a single state value per
+ * `persistenceId` instead of an event log.  State is loaded on startup
+ * (or an `emptyState` snapshot is used) and persisted after each
+ * mutation via `persist(newState)`.
+ *
+ * User code overrides `onCommand` with the command handler and calls
+ * `this.state` to read, `this.persist(next)` to write.  Writes are
+ * optimistic — concurrent writers receive `DurableStateConcurrencyError`.
+ */
+export declare abstract class DurableStateActor<Cmd, S> extends Actor<Cmd> {
+    readonly settings: DurableStateSettings<S>;
+    private _record;
+    private _persisting;
+    constructor(settings: DurableStateSettings<S>);
+    /** Current state snapshot — safe to read inside a handler. */
+    protected get state(): S;
+    protected get revision(): number;
+    /**
+     * Optional state adapter for schema evolution.  When defined, the
+     * persisted state is wrapped in a `{ _v, _t, _e }` envelope on
+     * `persist()` and unwrapped (with up-casting through the adapter) in
+     * `preStart()`.  Strict on read: a non-envelope state with adapter
+     * present throws `MigrationError`.  See `src/persistence/migration/`.
+     */
+    protected stateAdapter(): StateAdapter<S> | undefined;
+    /**
+     * Per-actor compression — overrides the plugin default.  Stores that
+     * don't compress ignore it.  Default `undefined` defers to the plugin.
+     */
+    protected compression(): CompressionConfig | undefined;
+    /**
+     * Per-actor encryption — overrides the plugin default.  Used on both
+     * the write path (encrypt) and the read path (decrypt).  Default
+     * `undefined` defers to the plugin.
+     */
+    protected encryption(): EncryptionConfig | undefined;
+    preStart(): Promise<void>;
+    onReceive(cmd: Cmd): Promise<void>;
+    /** User handler — invoked once `preStart` has loaded the record. */
+    abstract onCommand(cmd: Cmd): void | Promise<void>;
+    /** Persist the new state atomically; rejects on concurrency conflict. */
+    protected persist(next: S): Promise<DurableStateRecord<S>>;
+    /** Delete the underlying record and reset to emptyState in memory. */
+    protected deleteRecord(): Promise<void>;
+    /**
+     * Build per-call `PersistenceOptions` from this actor's hooks.
+     * Returns `undefined` when neither hook is set.
+     */
+    private persistenceOptions;
+}
+//# sourceMappingURL=DurableStateActor.d.ts.map

package/dist/persistence/DurableStateActor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurableStateActor.d.ts","sourceRoot":"","sources":["../../src/persistence/DurableStateActor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAG3D,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAClC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,8BAAsB,iBAAiB,CAAC,GAAG,EAAE,CAAC,CAAE,SAAQ,KAAK,CAAC,GAAG,CAAC;aAIpC,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAH7D,OAAO,CAAC,OAAO,CAAsC;IACrD,OAAO,CAAC,WAAW,CAA8B;gBAErB,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC;IAE7D,8DAA8D;IAC9D,SAAS,KAAK,KAAK,IAAI,CAAC,CAMvB;IAED,SAAS,KAAK,QAAQ,IAAI,MAAM,CAE/B;IAED;;;;;;OAMG;IACH,SAAS,CAAC,YAAY,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS;IAErD;;;OAGG;IACH,SAAS,CAAC,WAAW,IAAI,iBAAiB,GAAG,SAAS;IAEtD;;;;OAIG;IACH,SAAS,CAAC,UAAU,IAAI,gBAAgB,GAAG,SAAS;IAErC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBzB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD,yEAAyE;cACzD,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAgChE,sEAAsE;cACtD,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7C;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAM3B"}

package/dist/persistence/DurableStateActor.js

@@ -0,0 +1,120 @@
+import { Actor } from '../Actor.js';
+import { DurableStateConcurrencyError, } from './DurableStateStore.js';
+import { decodeState, encodeState } from './migration/Envelope.js';
+/**
+ * Base class for actors that persist a single state value per
+ * `persistenceId` instead of an event log.  State is loaded on startup
+ * (or an `emptyState` snapshot is used) and persisted after each
+ * mutation via `persist(newState)`.
+ *
+ * User code overrides `onCommand` with the command handler and calls
+ * `this.state` to read, `this.persist(next)` to write.  Writes are
+ * optimistic — concurrent writers receive `DurableStateConcurrencyError`.
+ */
+export class DurableStateActor extends Actor {
+    settings;
+    _record = null;
+    _persisting = null;
+    constructor(settings) {
+        super();
+        this.settings = settings;
+    }
+    /** Current state snapshot — safe to read inside a handler. */
+    get state() {
+        if (!this._record) {
+            // emptyState served as the first value before any persist() completed.
+            return this.settings.emptyState();
+        }
+        return this._record.state;
+    }
+    get revision() {
+        return this._record?.revision ?? 0;
+    }
+    /**
+     * Optional state adapter for schema evolution.  When defined, the
+     * persisted state is wrapped in a `{ _v, _t, _e }` envelope on
+     * `persist()` and unwrapped (with up-casting through the adapter) in
+     * `preStart()`.  Strict on read: a non-envelope state with adapter
+     * present throws `MigrationError`.  See `src/persistence/migration/`.
+     */
+    stateAdapter() { return undefined; }
+    /**
+     * Per-actor compression — overrides the plugin default.  Stores that
+     * don't compress ignore it.  Default `undefined` defers to the plugin.
+     */
+    compression() { return undefined; }
+    /**
+     * Per-actor encryption — overrides the plugin default.  Used on both
+     * the write path (encrypt) and the read path (decrypt).  Default
+     * `undefined` defers to the plugin.
+     */
+    encryption() { return undefined; }
+    async preStart() {
+        const adapter = this.stateAdapter();
+        const loaded = await this.settings.store.load(this.settings.persistenceId, this.persistenceOptions());
+        const opt = loaded.toNullable();
+        if (!opt) {
+            this._record = null;
+            return;
+        }
+        const decoded = decodeState(opt.state, adapter);
+        this._record = {
+            persistenceId: opt.persistenceId,
+            revision: opt.revision,
+            state: decoded,
+            timestamp: opt.timestamp,
+        };
+    }
+    async onReceive(cmd) {
+        if (this._persisting)
+            await this._persisting;
+        await this.onCommand(cmd);
+    }
+    /** Persist the new state atomically; rejects on concurrency conflict. */
+    async persist(next) {
+        const expected = this.revision;
+        const adapter = this.stateAdapter();
+        const wire = adapter ? encodeState(next, adapter) : next;
+        // Store sees an envelope (or raw value when no adapter).  We re-stamp
+        // the local record with the original `next` so callers see the
+        // current-version domain shape.
+        const p = this.settings.store.upsert(this.settings.persistenceId, expected, wire, this.persistenceOptions());
+        this._persisting = p.then(() => undefined, () => undefined);
+        try {
+            const record = await p;
+            const local = {
+                persistenceId: record.persistenceId,
+                revision: record.revision,
+                state: next,
+                timestamp: record.timestamp,
+            };
+            this._record = local;
+            return local;
+        }
+        catch (err) {
+            if (err instanceof DurableStateConcurrencyError)
+                throw err;
+            throw err;
+        }
+        finally {
+            this._persisting = null;
+        }
+    }
+    /** Delete the underlying record and reset to emptyState in memory. */
+    async deleteRecord() {
+        await this.settings.store.delete(this.settings.persistenceId);
+        this._record = null;
+    }
+    /**
+     * Build per-call `PersistenceOptions` from this actor's hooks.
+     * Returns `undefined` when neither hook is set.
+     */
+    persistenceOptions() {
+        const compression = this.compression();
+        const encryption = this.encryption();
+        if (!compression && !encryption)
+            return undefined;
+        return { compression, encryption };
+    }
+}
+//# sourceMappingURL=DurableStateActor.js.map

package/dist/persistence/DurableStateActor.js.map

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

package/dist/persistence/DurableStateStore.d.ts

@@ -0,0 +1,43 @@
+import type { Option } from '../util/Option.js';
+import type { PersistenceOptions } from './PersistenceOptions.js';
+/**
+ * Storage contract for Durable State — the "event-free" cousin of Event
+ * Sourcing.  Instead of appending events that are replayed, a Durable State
+ * actor overwrites a single snapshot per persistence id.  This trades off
+ * the audit log for simpler implementation and faster recovery.
+ *
+ * Revision is a monotonic counter used for optimistic concurrency: writes
+ * must pass the expected previous revision or they fail.
+ */
+export interface DurableStateRecord<S> {
+    readonly persistenceId: string;
+    readonly revision: number;
+    readonly state: S;
+    readonly timestamp: number;
+}
+export declare class DurableStateConcurrencyError extends Error {
+    readonly persistenceId: string;
+    readonly expected: number;
+    readonly actual: number;
+    constructor(persistenceId: string, expected: number, actual: number);
+}
+export interface DurableStateStore {
+    /**
+     * Upsert the state for `persistenceId`.  `expectedRevision` must match the
+     * current stored revision (0 when no record exists yet).  Throws
+     * `DurableStateConcurrencyError` on conflict.  Optional `options`
+     * carry per-call preferences from the caller (e.g. compression /
+     * encryption set on the actor); stores that cannot honour them
+     * silently ignore the field.
+     */
+    upsert<S>(persistenceId: string, expectedRevision: number, state: S, options?: PersistenceOptions): Promise<DurableStateRecord<S>>;
+    /**
+     * Load the latest record for `persistenceId`, or None if none exists.
+     * `options.encryption` is required when client-side encryption was
+     * used at write time.
+     */
+    load<S>(persistenceId: string, options?: PersistenceOptions): Promise<Option<DurableStateRecord<S>>>;
+    /** Remove the record entirely.  Idempotent. */
+    delete(persistenceId: string): Promise<void>;
+}
+//# sourceMappingURL=DurableStateStore.d.ts.map

package/dist/persistence/DurableStateStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurableStateStore.d.ts","sourceRoot":"","sources":["../../src/persistence/DurableStateStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qBAAa,4BAA6B,SAAQ,KAAK;aAEnC,aAAa,EAAE,MAAM;aACrB,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBAFd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAKjC;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,EACN,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;IAElC;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAErG,+CAA+C;IAC/C,MAAM,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C"}

package/dist/persistence/DurableStateStore.js

@@ -0,0 +1,13 @@
+export class DurableStateConcurrencyError extends Error {
+    persistenceId;
+    expected;
+    actual;
+    constructor(persistenceId, expected, actual) {
+        super(`durable-state concurrency conflict on ${persistenceId}: expected rev=${expected} but was ${actual}`);
+        this.persistenceId = persistenceId;
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'DurableStateConcurrencyError';
+    }
+}
+//# sourceMappingURL=DurableStateStore.js.map

package/dist/persistence/DurableStateStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DurableStateStore.js","sourceRoot":"","sources":["../../src/persistence/DurableStateStore.ts"],"names":[],"mappings":"AAmBA,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAEnC;IACA;IACA;IAHlB,YACkB,aAAqB,EACrB,QAAgB,EAChB,MAAc;QAE9B,KAAK,CAAC,yCAAyC,aAAa,kBAAkB,QAAQ,YAAY,MAAM,EAAE,CAAC,CAAC;QAJ5F,kBAAa,GAAb,aAAa,CAAQ;QACrB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAG9B,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;IAC7C,CAAC;CACF"}