actly 1.2.0 → 1.3.0

package/dist/policies/retry.js

@@ -1,122 +1,156 @@
 import { computeDelay } from '../utils/backoff.js';
 import { isAbortError, sleep } from '../utils/abort.js';
+import { safeCall } from '../utils/safeCall.js';
 import { RetryExhaustedError } from '../errors.js';
-// ─── Default predicate ────────────────────────────────────────────────────────
-/**
- * Default `shouldRetry`: retry on any error EXCEPT abort errors.
- *
- * Abort errors indicate the caller or a timeout cancelled the operation —
- * retrying would just abort again on the next attempt, wasting delay budget.
- *
- * User-supplied `shouldRetry` overrides this entirely.
- */
+import { LIMITS } from '../utils/limits.js';
 function defaultShouldRetry(error, _attempt) {
-    return !isAbortError(error);
+    if (isAbortError(error))
+        return false;
+    if (typeof error === 'object' && error !== null) {
+        const code = error.code;
+        if (code === 'ACTLY_TIMEOUT' || code === 'ACTLY_TOTAL_TIMEOUT')
+            return false;
+    }
+    return true;
 }
-// ─── Policy ───────────────────────────────────────────────────────────────────
-/**
- * Retry `fn` up to `opts.attempts` times on retryable errors.
- *
- * Writes the live attempt count into `ctx.meta.attempts` so `act()` can
- * report it in the final `ActResult`.
- *
- * # Signal awareness
- *
- * - Before each attempt, checks `parentSignal.aborted`. If the parent (e.g.
- *   `totalTimeout` or caller) has aborted, throws the parent's reason
- *   immediately — no more attempts.
- * - Sleeps between attempts use `sleep(delay, parentSignal)`. If the parent
- *   aborts mid-delay, the sleep rejects immediately instead of blocking
- *   the loop until the timer would have elapsed.
- *
- * # `shouldRetry` invocation
- *
- * Called after EVERY failure, including the last attempt. This preserves the
- * predicate's contract for observers / metrics that rely on it being called
- * per-attempt. The return value is only consulted when `attempt < max`.
- *
- * # Default predicate
- *
- * If `shouldRetry` is omitted, uses `defaultShouldRetry` which retries on
- * every error EXCEPT abort errors (so timeouts and caller cancellations
- * don't waste retry budget).
- */
 export function retryPolicy(opts) {
     const max = Math.max(1, Math.floor(opts.attempts));
     const shouldRetry = opts.shouldRetry ?? defaultShouldRetry;
+    const shouldRetryResult = opts.shouldRetryResult;
+    const dangerouslyUnref = opts.dangerouslyUnref === true;
+    const sleepOpts = dangerouslyUnref ? { unref: true } : undefined;
+    const backoffFn = opts.backoffFn;
     return (fn, ctx) => async (parentSignal) => {
-        const errors = [];
-        let lastErr;
+        const backoffState = {};
+        let errors;
         let retriedAtLeastOnce = false;
         const obs = ctx.observability;
         for (let attempt = 1; attempt <= max; attempt++) {
-            // Parent (totalTimeout or caller signal) already aborted — bail.
             if (parentSignal.aborted)
                 throw parentSignal.reason;
             ctx.meta.attempts = attempt;
             const attemptStart = Date.now();
             try {
-                // Emit onAttempt before each attempt. (We could emit
-                // after with duration/error, but before lets observers track
-                // in-flight attempts in real time.)
                 if (obs) {
-                    obs.hooks.onAttempt?.({
+                    safeCall(obs.hooks.onAttempt, {
                         type: 'attempt', key: ctx.key, traceId: obs.traceId,
                         timestamp: attemptStart, attempt,
                     });
                 }
-                return await fn(parentSignal);
+                const value = await fn(parentSignal);
+                if (shouldRetryResult) {
+                    let accept;
+                    try {
+                        const raw = shouldRetryResult(value, attempt);
+                        accept = typeof raw === 'boolean' ? raw : true;
+                    }
+                    catch {
+                        return value;
+                    }
+                    if (accept)
+                        return value;
+                    const syntheticError = new Error(`Actly: shouldRetryResult returned false on attempt ${attempt}`);
+                    if (errors === undefined)
+                        errors = [];
+                    if (errors.length < 10) {
+                        errors.push(syntheticError);
+                    }
+                    else {
+                        errors.shift();
+                        errors.push(syntheticError);
+                    }
+                    if (attempt >= max) {
+                        if (obs) {
+                            safeCall(obs.hooks.onRetry, {
+                                type: 'retry', key: ctx.key, traceId: obs.traceId,
+                                timestamp: Date.now(), attempt, delayMs: 0,
+                                error: syntheticError,
+                            });
+                        }
+                        return value;
+                    }
+                    retriedAtLeastOnce = true;
+                    if (parentSignal.aborted)
+                        throw parentSignal.reason;
+                    let rawDelay;
+                    try {
+                        rawDelay = backoffFn
+                            ? backoffFn(attempt, syntheticError, backoffState)
+                            : computeDelay(attempt, opts);
+                    }
+                    catch {
+                        rawDelay = computeDelay(attempt, opts);
+                    }
+                    const safeDelay = Number.isFinite(rawDelay) ? rawDelay : 0;
+                    const delay = Math.min(Math.max(0, safeDelay), LIMITS.MAX_RETRY_DELAY_MS);
+                    if (obs) {
+                        safeCall(obs.hooks.onRetry, {
+                            type: 'retry', key: ctx.key, traceId: obs.traceId,
+                            timestamp: Date.now(), attempt, delayMs: delay,
+                            error: syntheticError,
+                        });
+                    }
+                    if (delay > 0)
+                        await sleep(delay, parentSignal, sleepOpts);
+                    continue;
+                }
+                return value;
             }
             catch (err) {
-                lastErr = err;
-                errors.push(err);
-                // Invoke shouldRetry. If the predicate throws, treat as "don't retry"
-                // and surface the original fn error (not the predicate error).
+                if (errors === undefined)
+                    errors = [];
+                if (errors.length < 10) {
+                    errors.push(err);
+                }
+                else {
+                    errors.shift();
+                    errors.push(err);
+                }
                 let retryable;
                 try {
                     retryable = shouldRetry(err, attempt);
                 }
                 catch {
-                    // Predicate threw — don't retry, surface original error
                     throw err;
                 }
                 if (attempt >= max) {
-                    // Last attempt. If we retried at least once (predicate
-                    // allowed retries), wrap in RetryExhaustedError for context.
                     if (retriedAtLeastOnce) {
                         throw new RetryExhaustedError({
                             key: ctx.key,
                             attempts: attempt,
                             lastError: err,
-                            errors,
+                            errors: errors ?? [],
                         });
                     }
                     throw err;
                 }
-                if (!retryable) {
-                    // Non-retryable error — bail immediately.
+                if (!retryable)
                     throw err;
-                }
-                // Mark that we retried at least once — affects final wrap.
                 retriedAtLeastOnce = true;
-                // Parent aborted mid-attempt — don't sleep, bail.
                 if (parentSignal.aborted)
                     throw parentSignal.reason;
-                const delay = computeDelay(attempt, opts);
-                // Emit onRetry before the delay sleep.
+                let rawDelay;
+                try {
+                    rawDelay = backoffFn
+                        ? backoffFn(attempt, err, backoffState)
+                        : computeDelay(attempt, opts);
+                }
+                catch {
+                    rawDelay = computeDelay(attempt, opts);
+                }
+                const safeDelay = Number.isFinite(rawDelay) ? rawDelay : 0;
+                const delay = Math.min(Math.max(0, safeDelay), LIMITS.MAX_RETRY_DELAY_MS);
                 if (obs) {
-                    obs.hooks.onRetry?.({
+                    safeCall(obs.hooks.onRetry, {
                         type: 'retry', key: ctx.key, traceId: obs.traceId,
                         timestamp: Date.now(), attempt, delayMs: delay, error: err,
                     });
                 }
                 if (delay > 0) {
-                    await sleep(delay, parentSignal);
+                    await sleep(delay, parentSignal, sleepOpts);
                 }
             }
         }
-        // Unreachable: the loop either returns or throws on every iteration.
-        throw lastErr;
+        throw new Error('Actly: retryPolicy reached unreachable state');
     };
 }
-//# sourceMappingURL=retry.js.map

package/dist/policies/timeout.cjs

@@ -4,58 +4,43 @@ exports.TotalTimeoutError = exports.TimeoutError = void 0;
 exports.timeoutPolicy = timeoutPolicy;
 exports.totalTimeoutPolicy = totalTimeoutPolicy;
 const abort_js_1 = require("../utils/abort.js");
+const safeCall_js_1 = require("../utils/safeCall.js");
 const errors_js_1 = require("../errors.js");
 Object.defineProperty(exports, "TimeoutError", { enumerable: true, get: function () { return errors_js_1.TimeoutError; } });
 Object.defineProperty(exports, "TotalTimeoutError", { enumerable: true, get: function () { return errors_js_1.TotalTimeoutError; } });
-// ─── Policy ───────────────────────────────────────────────────────────────────
-/**
- * Build a timeout policy that throws `ErrorCtor` on deadline.
- *
- * # Cancellation contract
- *
- * Each invocation:
- *   1. Creates a fresh `AbortController` for this attempt.
- *   2. Arms a `setTimeout` that aborts the controller with a fresh `ErrorCtor(ms)`.
- *   3. Links the parent signal: if the parent aborts (e.g. `totalTimeout` or
- *      caller cancellation), the child aborts with the parent's reason.
- *   4. Races `fn(childSignal)` against the abort event.
- *
- * The race is critical: it ensures `act()` returns promptly even if `fn`
- * ignores the signal. The underlying `fn` may keep running in the background
- * (resource leak), but the caller is unblocked. This is the best JavaScript
- * can do without cooperation from `fn`.
- *
- * If `fn` cooperates (passes `signal` to `fetch`, `AbortController`, etc.),
- * the underlying work is cancelled properly — no leak.
- *
- * # Error attribution
- *
- * If the per-attempt timer fires, we throw `ErrorCtor(ms)` regardless of
- * what `fn` does. If the parent signal fires first, we throw the parent's
- * reason (could be `TotalTimeoutError`, an `AbortError`, or anything else).
- */
-function makeTimeoutPolicy(opts, ErrorCtor) {
+function makeTimeoutPolicy(opts, errorCtor, kind) {
+    const strategy = opts.strategy ?? 'race';
     return (fn, ctx) => async (parentSignal) => {
         const controller = new AbortController();
-        // Pass key to the error ctor for better debugging context.
-        const timerError = new ErrorCtor(opts.ms, { key: ctx.key });
-        // Arm the per-attempt timer. The error object is allocated once so the
-        // stack trace points here (the policy frame), not at setTimeout's
-        // internal callback.
-        const timer = setTimeout(() => controller.abort(timerError), opts.ms);
-        // NOTE: do NOT `unref()` this timer. The timeout IS the operation
-        // the caller is awaiting. unref'ing would let Node exit the process
-        // while a timeout was pending — silently dropping the operation.
-        // The timer is cleared in the finally block below.
-        // Link parent → child. Capture the unlink function so we can clean
-        // up the listener on success path (contract).
+        const timerError = new errorCtor(opts.ms, { key: ctx.key });
+        const obs = ctx.observability;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (obs) {
+                (0, safeCall_js_1.safeCall)(obs.hooks.onTimeout, {
+                    type: 'timeout', key: ctx.key, traceId: obs.traceId,
+                    timestamp: Date.now(), kind, ms: opts.ms,
+                });
+            }
+            controller.abort(timerError);
+        }, opts.ms);
         const unlink = (0, abort_js_1.linkSignal)(parentSignal, controller);
         try {
-            // Race fn against the abort event. If fn settles first, we get its
-            // result/error. If the signal aborts first, we reject with reason.
-            //
-            // We do NOT use AbortSignal.timeout() here because we need to throw
-            // our own ErrorCtor, not a DOMException named "TimeoutError".
+            if (strategy === 'cooperative') {
+                if (parentSignal.aborted) {
+                    throw parentSignal.reason;
+                }
+                try {
+                    const value = await fn(controller.signal);
+                    return value;
+                }
+                catch (err) {
+                    if (timedOut)
+                        throw timerError;
+                    throw err;
+                }
+            }
             return await new Promise((resolve, reject) => {
                 if (controller.signal.aborted) {
                     reject(controller.signal.reason);
@@ -78,22 +63,9 @@ function makeTimeoutPolicy(opts, ErrorCtor) {
         }
     };
 }
-/**
- * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
- *
- * Place this INSIDE `retryPolicy` (closer to `fn`) so each attempt has its
- * own clock.
- */
 function timeoutPolicy(opts) {
-    return makeTimeoutPolicy(opts, errors_js_1.TimeoutError);
+    return makeTimeoutPolicy(opts, errors_js_1.TimeoutError, 'per-attempt');
 }
-/**
- * Operation-wide timeout. Races the ENTIRE chain (all retry attempts +
- * delays) against a hard budget that does NOT reset.
- *
- * Place this as the OUTERMOST policy so the clock starts before any other
- * policy runs and stops regardless of what the inner chain is doing.
- */
 function totalTimeoutPolicy(opts) {
-    return makeTimeoutPolicy(opts, errors_js_1.TotalTimeoutError);
+    return makeTimeoutPolicy(opts, errors_js_1.TotalTimeoutError, 'total');
 }

package/dist/policies/timeout.d.ts

@@ -1,19 +1,6 @@
 import type { PolicyApplier, TimeoutOptions } from '../types/index.js';
 import { TimeoutError, TotalTimeoutError } from '../errors.js';
 export { TimeoutError, TotalTimeoutError };
-/**
- * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
- *
- * Place this INSIDE `retryPolicy` (closer to `fn`) so each attempt has its
- * own clock.
- */
 export declare function timeoutPolicy<T>(opts: TimeoutOptions): PolicyApplier<T>;
-/**
- * Operation-wide timeout. Races the ENTIRE chain (all retry attempts +
- * delays) against a hard budget that does NOT reset.
- *
- * Place this as the OUTERMOST policy so the clock starts before any other
- * policy runs and stops regardless of what the inner chain is doing.
- */
 export declare function totalTimeoutPolicy<T>(opts: TimeoutOptions): PolicyApplier<T>;
 //# sourceMappingURL=timeout.d.ts.map

package/dist/policies/timeout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAE5F,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAa9D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAyF1C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAE5E"}
+{"version":3,"file":"timeout.d.ts","sourceRoot":"","sources":["../../src/policies/timeout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,aAAa,EAAiB,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAG5F,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAI9D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,CAAA;AAyG1C,wBAAgB,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAEvE;AAMD,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,GAAG,aAAa,CAAC,CAAC,CAAC,CAE5E"}

package/dist/policies/timeout.js

@@ -1,65 +1,40 @@
 import { linkSignal } from '../utils/abort.js';
+import { safeCall } from '../utils/safeCall.js';
 import { TimeoutError, TotalTimeoutError } from '../errors.js';
-// ─── Errors ───────────────────────────────────────────────────────────────────
-//
-// TimeoutError and TotalTimeoutError live in `src/errors.ts` and
-// now extend `ActlyError` (which extends `Error`). Existing `instanceof
-// Error` and `instanceof TimeoutError` checks continue to work; new
-// `instanceof ActlyError` and `.code` field give consumers a stable
-// discriminator for telemetry.
-//
-// Re-exported here for backwards compatibility with code that imports
-// from `'actly/policies/timeout'` (the deep path).
 export { TimeoutError, TotalTimeoutError };
-// ─── Policy ───────────────────────────────────────────────────────────────────
-/**
- * Build a timeout policy that throws `ErrorCtor` on deadline.
- *
- * # Cancellation contract
- *
- * Each invocation:
- *   1. Creates a fresh `AbortController` for this attempt.
- *   2. Arms a `setTimeout` that aborts the controller with a fresh `ErrorCtor(ms)`.
- *   3. Links the parent signal: if the parent aborts (e.g. `totalTimeout` or
- *      caller cancellation), the child aborts with the parent's reason.
- *   4. Races `fn(childSignal)` against the abort event.
- *
- * The race is critical: it ensures `act()` returns promptly even if `fn`
- * ignores the signal. The underlying `fn` may keep running in the background
- * (resource leak), but the caller is unblocked. This is the best JavaScript
- * can do without cooperation from `fn`.
- *
- * If `fn` cooperates (passes `signal` to `fetch`, `AbortController`, etc.),
- * the underlying work is cancelled properly — no leak.
- *
- * # Error attribution
- *
- * If the per-attempt timer fires, we throw `ErrorCtor(ms)` regardless of
- * what `fn` does. If the parent signal fires first, we throw the parent's
- * reason (could be `TotalTimeoutError`, an `AbortError`, or anything else).
- */
-function makeTimeoutPolicy(opts, ErrorCtor) {
+function makeTimeoutPolicy(opts, errorCtor, kind) {
+    const strategy = opts.strategy ?? 'race';
     return (fn, ctx) => async (parentSignal) => {
         const controller = new AbortController();
-        // Pass key to the error ctor for better debugging context.
-        const timerError = new ErrorCtor(opts.ms, { key: ctx.key });
-        // Arm the per-attempt timer. The error object is allocated once so the
-        // stack trace points here (the policy frame), not at setTimeout's
-        // internal callback.
-        const timer = setTimeout(() => controller.abort(timerError), opts.ms);
-        // NOTE: do NOT `unref()` this timer. The timeout IS the operation
-        // the caller is awaiting. unref'ing would let Node exit the process
-        // while a timeout was pending — silently dropping the operation.
-        // The timer is cleared in the finally block below.
-        // Link parent → child. Capture the unlink function so we can clean
-        // up the listener on success path (contract).
+        const timerError = new errorCtor(opts.ms, { key: ctx.key });
+        const obs = ctx.observability;
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            if (obs) {
+                safeCall(obs.hooks.onTimeout, {
+                    type: 'timeout', key: ctx.key, traceId: obs.traceId,
+                    timestamp: Date.now(), kind, ms: opts.ms,
+                });
+            }
+            controller.abort(timerError);
+        }, opts.ms);
         const unlink = linkSignal(parentSignal, controller);
         try {
-            // Race fn against the abort event. If fn settles first, we get its
-            // result/error. If the signal aborts first, we reject with reason.
-            //
-            // We do NOT use AbortSignal.timeout() here because we need to throw
-            // our own ErrorCtor, not a DOMException named "TimeoutError".
+            if (strategy === 'cooperative') {
+                if (parentSignal.aborted) {
+                    throw parentSignal.reason;
+                }
+                try {
+                    const value = await fn(controller.signal);
+                    return value;
+                }
+                catch (err) {
+                    if (timedOut)
+                        throw timerError;
+                    throw err;
+                }
+            }
             return await new Promise((resolve, reject) => {
                 if (controller.signal.aborted) {
                     reject(controller.signal.reason);
@@ -82,23 +57,9 @@ function makeTimeoutPolicy(opts, ErrorCtor) {
         }
     };
 }
-/**
- * Per-attempt timeout. Races `fn` against a deadline that resets on retry.
- *
- * Place this INSIDE `retryPolicy` (closer to `fn`) so each attempt has its
- * own clock.
- */
 export function timeoutPolicy(opts) {
-    return makeTimeoutPolicy(opts, TimeoutError);
+    return makeTimeoutPolicy(opts, TimeoutError, 'per-attempt');
 }
-/**
- * Operation-wide timeout. Races the ENTIRE chain (all retry attempts +
- * delays) against a hard budget that does NOT reset.
- *
- * Place this as the OUTERMOST policy so the clock starts before any other
- * policy runs and stops regardless of what the inner chain is doing.
- */
 export function totalTimeoutPolicy(opts) {
-    return makeTimeoutPolicy(opts, TotalTimeoutError);
+    return makeTimeoutPolicy(opts, TotalTimeoutError, 'total');
 }
-//# sourceMappingURL=timeout.js.map

package/dist/stores/base.cjs

@@ -1,20 +1,10 @@
 "use strict";
-// ─── Store interfaces ─────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSyncStore = isSyncStore;
 exports.isAsyncStore = isAsyncStore;
-// ─── Type guards ──────────────────────────────────────────────────────────────
-/**
- * Narrows `AnyStateStore` to `SyncStateStore` via the `_sync` discriminant.
- * Used by `execute()` and `cachePolicy` to branch between sync and async paths.
- */
 function isSyncStore(store) {
     return store._sync === true;
 }
-/**
- * Narrows `AnyStateStore` to `AsyncStateStore` via the `_sync` discriminant.
- * Provided for symmetry; prefer `isSyncStore` for the common guard pattern.
- */
 function isAsyncStore(store) {
     return store._sync === false;
 }

package/dist/stores/base.d.ts

@@ -1,88 +1,25 @@
-/**
- * Synchronous key-value store. All operations complete in the same tick.
- *
- * # Why synchronous?
- *
- * `dedupePolicy` must read an in-flight Promise from the store and, if absent,
- * write a new one — all within a single synchronous frame. If `get()` were
- * async, two concurrent callers could both observe a miss before either
- * write lands, defeating deduplication entirely. There is no lock primitive
- * in JavaScript that can paper over this: the constraint is structural, not
- * implementation-level.
- *
- * # The `_sync` discriminant
- *
- * `_sync: true` is a runtime tag that lets `execute()` enforce the dedupe
- * constraint for plain-JS callers who bypass TypeScript. It is NOT part of
- * the semantic contract and MUST NOT be used for anything beyond that guard.
- * Implementations must set it as a `readonly` literal (`true as const`).
- *
- * # Lifecycle
- *
- * Implementations that hold background resources (timers, connections) should
- * expose a `destroy()` method as a convention. See `InMemoryStore` for the
- * reference pattern.
- */
 export interface SyncStateStore {
-    /** Runtime discriminant. Must be `true as const`. */
     readonly _sync: true;
     get<T>(key: string): T | undefined;
     set<T>(key: string, value: T, ttlMs?: number): void;
     delete(key: string): void;
     has(key: string): boolean;
-    /**
-     * Remove all entries synchronously.
-     * After `clear()` returns, `size()` returns 0.
-     */
+    deleteIfExists?(key: string): boolean;
     clear(): void;
-    /**
-     * Return the count of live (non-expired) entries.
-     * Side-effect free: does not mutate the store. Implementations MAY evict
-     * expired entries opportunistically during this call, but MUST NOT have
-     * observable side effects beyond internal cleanup.
-     */
     size(): number;
+    destroy?(): void;
 }
-/**
- * Asynchronous key-value store. All operations return Promises.
- *
- * # Policy compatibility
- *
- * Compatible with `cachePolicy` only. Passing an `AsyncStateStore` to a
- * policy chain that includes `dedupePolicy` is a TypeScript error and a
- * runtime error — `execute()` throws at chain-build time. See
- * `SyncStateStore` for why dedupe requires synchronous access.
- *
- * # TTL semantics
- *
- * The store is responsible for honouring `ttlMs`. Actly passes it as a hint.
- * Implementations may delegate to a native TTL mechanism (e.g. Redis EXPIRE).
- *
- * # The `_sync` discriminant
- *
- * `_sync: false` mirrors the discriminant on `SyncStateStore`. Must be set
- * as a `readonly` literal (`false as const`).
- */
 export interface AsyncStateStore {
-    /** Runtime discriminant. Must be `false as const`. */
     readonly _sync: false;
     get<T>(key: string): Promise<T | undefined>;
     set<T>(key: string, value: T, ttlMs?: number): Promise<void>;
     delete(key: string): Promise<void>;
     has(key: string): Promise<boolean>;
-    /** Remove all entries managed by this store. */
+    deleteIfExists?(key: string): Promise<boolean>;
     clear(): Promise<void>;
-    /** Return the count of live (non-expired) entries. */
     size(): Promise<number>;
+    destroy?(): void | Promise<void>;
 }
-/**
- * Narrows `AnyStateStore` to `SyncStateStore` via the `_sync` discriminant.
- * Used by `execute()` and `cachePolicy` to branch between sync and async paths.
- */
 export declare function isSyncStore(store: SyncStateStore | AsyncStateStore): store is SyncStateStore;
-/**
- * Narrows `AnyStateStore` to `AsyncStateStore` via the `_sync` discriminant.
- * Provided for symmetry; prefer `isSyncStore` for the common guard pattern.
- */
 export declare function isAsyncStore(store: SyncStateStore | AsyncStateStore): store is AsyncStateStore;
 //# sourceMappingURL=base.d.ts.map

package/dist/stores/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/stores/base.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;IAEpB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAA;IAClC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAEzB;;;OAGG;IACH,KAAK,IAAI,IAAI,CAAA;IAEb;;;;;OAKG;IACH,IAAI,IAAI,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IAErB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IAC3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAElC,gDAAgD;IAChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAEtB,sDAAsD;IACtD,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAID;;;GAGG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,GAAG,eAAe,GACtC,KAAK,IAAI,cAAc,CAEzB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,GAAG,eAAe,GACtC,KAAK,IAAI,eAAe,CAE1B"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/stores/base.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,cAAc;IAE7B,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;IAEpB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAA;IAClC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IASzB,cAAc,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;IAGrC,KAAK,IAAI,IAAI,CAAA;IAMb,IAAI,IAAI,MAAM,CAAA;IAOd,OAAO,CAAC,IAAI,IAAI,CAAA;CACjB;AAcD,MAAM,WAAW,eAAe;IAE9B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IAErB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAA;IAC3C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5D,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAMlC,cAAc,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAG9C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAGtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;IAMvB,OAAO,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACjC;AAQD,wBAAgB,WAAW,CACzB,KAAK,EAAE,cAAc,GAAG,eAAe,GACtC,KAAK,IAAI,cAAc,CAEzB;AAMD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,cAAc,GAAG,eAAe,GACtC,KAAK,IAAI,eAAe,CAE1B"}

package/dist/stores/base.js

@@ -1,17 +1,6 @@
-// ─── Store interfaces ─────────────────────────────────────────────────────────
-// ─── Type guards ──────────────────────────────────────────────────────────────
-/**
- * Narrows `AnyStateStore` to `SyncStateStore` via the `_sync` discriminant.
- * Used by `execute()` and `cachePolicy` to branch between sync and async paths.
- */
 export function isSyncStore(store) {
     return store._sync === true;
 }
-/**
- * Narrows `AnyStateStore` to `AsyncStateStore` via the `_sync` discriminant.
- * Provided for symmetry; prefer `isSyncStore` for the common guard pattern.
- */
 export function isAsyncStore(store) {
     return store._sync === false;
 }
-//# sourceMappingURL=base.js.map