actly 1.1.5 → 1.3.0

package/dist/stores/memory.d.ts

@@ -1,79 +1,31 @@
 import type { SyncStateStore } from './base.js';
 export interface InMemoryStoreOptions {
-    /**
-     * Periodically sweep and remove expired entries in the background.
-     *
-     * Disabled by default. The store evicts lazily on `get()` / `has()` access,
-     * which is sufficient for most use cases. Enable `autoCleanup` when the
-     * store is long-lived and accumulates many TTL'd entries that are never
-     * re-read — for example, a server-side cache that receives write-heavy
-     * traffic with low subsequent read rates.
-     */
     autoCleanup?: boolean;
-    /**
-     * Interval between background sweeps in milliseconds.
-     * Defaults to 30 000 (30 seconds). Ignored when `autoCleanup` is false.
-     */
     cleanupIntervalMs?: number;
-    /**
-     * Maximum number of live entries the store will hold.
-     *
-     * When `set()` would exceed this limit, the least-recently-used entry is
-     * evicted before the new one is inserted (LRU semantics). Updates to an
-     * existing key do not trigger eviction.
-     *
-     * Defaults to `Infinity` (unbounded). Set a finite value for long-running
-     * caches with high-cardinality keys to bound memory usage.
-     *
-     * The LRU order is updated on `get()` and `set()` — both move the accessed
-     * key to the most-recent position.
-     */
     maxSize?: number;
+    memoryPressureCleanup?: boolean;
 }
-/**
- * Reference `SyncStateStore` implementation backed by a `Map`.
- *
- * # LRU semantics
- *
- * `Map` iteration order is insertion order, so we implement LRU by
- * `delete` + `set` on every access — the most-recently-touched key ends up
- * at the end of the iteration, and the oldest is `entries.keys().next().value`.
- *
- * # Expiry
- *
- * Lazy on `get()` / `has()`: expired entries are deleted when touched.
- * Background sweep (optional) reclaims entries that are never re-read.
- */
 export declare class InMemoryStore implements SyncStateStore {
     readonly _sync: true;
-    private readonly entries;
+    private static finalizer;
+    private readonly map;
     private readonly maxSize;
+    private head?;
+    private tail?;
     private cleanupTimer;
+    private memoryListener;
     constructor(options?: InMemoryStoreOptions);
     get<T>(key: string): T | undefined;
     set<T>(key: string, value: T, ttlMs?: number): void;
     delete(key: string): void;
     has(key: string): boolean;
     clear(): void;
-    /**
-     * Return the count of live (non-expired) entries.
-     *
-     * Pure query — does NOT touch LRU order. Expired entries discovered during
-     * the scan are evicted opportunistically (they were already invisible to
-     * `get()`, so eviction has no observable effect beyond memory reclamation).
-     *
-     * Two-pass to avoid mutating the Map during iteration (spec-safe).
-     */
     size(): number;
-    /**
-     * Stop the background cleanup timer and release internal state.
-     * Safe to call multiple times — subsequent calls are no-ops.
-     */
     destroy(): void;
-    /**
-     * Sweep all entries and remove those past their expiry time.
-     * Called by the autoCleanup interval; not part of the public contract.
-     */
-    private _sweep;
+    private appendTail;
+    private removeNode;
+    private moveToTail;
+    private sweep;
 }
+export declare function createDefaultStore(): InMemoryStore;
 //# sourceMappingURL=memory.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAwB/C,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,KAAK,EAAG,IAAI,CAAS;IAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,YAAY,CAA4C;gBAEpD,OAAO,GAAE,oBAAyB;IA0B9C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAiBlC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAcnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAYzB,KAAK,IAAI,IAAI;IAIb;;;;;;;;OAQG;IACH,IAAI,IAAI,MAAM;IAiBd;;;OAGG;IACH,OAAO,IAAI,IAAI;IAOf;;;OAGG;IACH,OAAO,CAAC,MAAM;CAUf"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAgC/C,MAAM,WAAW,oBAAoB;IAKnC,WAAW,CAAC,EAAE,OAAO,CAAA;IAGrB,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAU1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAQhB,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC;AAcD,qBAAa,aAAc,YAAW,cAAc;IAClD,QAAQ,CAAC,KAAK,EAAG,IAAI,CAAS;IAS9B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAkE;IAS1F,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,IAAI,CAAC,CAAS;IACtB,OAAO,CAAC,IAAI,CAAC,CAAS;IACtB,OAAO,CAAC,YAAY,CAA4C;IAChE,OAAO,CAAC,cAAc,CAA4C;gBAEtD,OAAO,GAAE,oBAAyB;IAkD9C,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAclC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IA+BnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAOzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAYzB,KAAK,IAAI,IAAI;IAYb,IAAI,IAAI,MAAM;IAUd,OAAO,IAAI,IAAI;IAyBf,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,UAAU;IAelB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,KAAK;CAoBd;AAOD,wBAAgB,kBAAkB,IAAI,aAAa,CAMlD"}

package/dist/stores/memory.js

@@ -1,137 +1,195 @@
+import { LIMITS } from '../utils/limits.js';
 function isUnrefable(t) {
     return typeof t.unref === 'function';
 }
-// ─── Implementation ───────────────────────────────────────────────────────────
-/**
- * Reference `SyncStateStore` implementation backed by a `Map`.
- *
- * # LRU semantics
- *
- * `Map` iteration order is insertion order, so we implement LRU by
- * `delete` + `set` on every access — the most-recently-touched key ends up
- * at the end of the iteration, and the oldest is `entries.keys().next().value`.
- *
- * # Expiry
- *
- * Lazy on `get()` / `has()`: expired entries are deleted when touched.
- * Background sweep (optional) reclaims entries that are never re-read.
- */
 export class InMemoryStore {
     _sync = true;
-    entries = new Map();
+    static finalizer;
+    static {
+        if (typeof FinalizationRegistry === 'function') {
+            InMemoryStore.finalizer = new FinalizationRegistry((timer) => {
+                try {
+                    clearInterval(timer);
+                }
+                catch { }
+            });
+        }
+    }
+    map = new Map();
     maxSize;
+    head;
+    tail;
     cleanupTimer;
+    memoryListener;
     constructor(options = {}) {
-        const { autoCleanup = false, cleanupIntervalMs = 30_000, maxSize = Number.POSITIVE_INFINITY, } = options;
+        const { autoCleanup = false, cleanupIntervalMs = 30_000, maxSize = LIMITS.DEFAULT_STORE_MAX_SIZE, memoryPressureCleanup = false, } = options;
         if (!Number.isFinite(maxSize) || maxSize <= 0) {
-            // Infinity is allowed (unbounded); any other non-positive finite value
-            // is a programmer error.
             if (maxSize !== Number.POSITIVE_INFINITY) {
                 throw new RangeError(`Actly: InMemoryStore maxSize must be a positive finite number or Infinity, got ${maxSize}`);
             }
         }
+        if (maxSize !== Number.POSITIVE_INFINITY && !Number.isInteger(maxSize)) {
+            throw new RangeError(`Actly: InMemoryStore maxSize must be a positive integer or Infinity, got ${maxSize}`);
+        }
         this.maxSize = maxSize;
         if (autoCleanup) {
-            const timer = setInterval(() => this._sweep(), cleanupIntervalMs);
+            const timer = setInterval(() => this.sweep(), cleanupIntervalMs);
             if (isUnrefable(timer))
                 timer.unref();
             this.cleanupTimer = timer;
+            InMemoryStore.finalizer?.register(this, timer, this);
+        }
+        if (memoryPressureCleanup) {
+            const processOn = process.on;
+            if (typeof processOn === 'function') {
+                const memoryListener = () => {
+                    try {
+                        this.sweep();
+                    }
+                    catch { }
+                };
+                processOn.call(process, 'memory', memoryListener);
+                this.memoryListener = memoryListener;
+            }
         }
     }
     get(key) {
-        const entry = this.entries.get(key);
-        if (!entry)
+        const node = this.map.get(key);
+        if (!node)
             return undefined;
-        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
-            this.entries.delete(key);
+        if (node.expiresAt !== null && Date.now() > node.expiresAt) {
+            this.removeNode(node);
+            this.map.delete(key);
             return undefined;
         }
-        // LRU refresh: move to most-recent position.
-        // delete + set is the canonical pattern for reordering a Map.
-        this.entries.delete(key);
-        this.entries.set(key, entry);
-        return entry.value;
+        this.moveToTail(node);
+        return node.value;
     }
     set(key, value, ttlMs) {
-        // Evict if at capacity AND adding a new key (updates don't grow size).
-        if (!this.entries.has(key) && this.entries.size >= this.maxSize) {
-            const oldest = this.entries.keys().next().value;
-            if (oldest !== undefined)
-                this.entries.delete(oldest);
-        }
-        const expiresAt = ttlMs != null && ttlMs > 0 ? Date.now() + ttlMs : null;
-        // delete + set ensures the key is moved to the most-recent position
-        // even on update, keeping LRU order consistent.
-        this.entries.delete(key);
-        this.entries.set(key, { value, expiresAt });
+        const existing = this.map.get(key);
+        const now = Date.now();
+        if (existing) {
+            existing.value = value;
+            existing.expiresAt = ttlMs != null && Number.isFinite(ttlMs) && ttlMs > 0 ? now + ttlMs : null;
+            existing.insertedAt = now;
+            this.moveToTail(existing);
+            return;
+        }
+        while (this.map.size >= this.maxSize && this.head) {
+            const evict = this.head;
+            this.removeNode(evict);
+            this.map.delete(evict.key);
+        }
+        const node = {
+            key,
+            value,
+            expiresAt: ttlMs != null && Number.isFinite(ttlMs) && ttlMs > 0 ? now + ttlMs : null,
+            insertedAt: now,
+        };
+        this.map.set(key, node);
+        this.appendTail(node);
     }
     delete(key) {
-        this.entries.delete(key);
+        const node = this.map.get(key);
+        if (!node)
+            return;
+        this.removeNode(node);
+        this.map.delete(key);
     }
     has(key) {
-        // Inline the expiry check to avoid the LRU side-effect of get().
-        // `has()` should be a pure query, not a touch.
-        const entry = this.entries.get(key);
-        if (!entry)
+        const node = this.map.get(key);
+        if (!node)
             return false;
-        if (entry.expiresAt !== null && Date.now() > entry.expiresAt) {
-            this.entries.delete(key);
+        if (node.expiresAt !== null && Date.now() > node.expiresAt) {
+            this.removeNode(node);
+            this.map.delete(key);
             return false;
         }
         return true;
     }
     clear() {
-        this.entries.clear();
+        this.map.clear();
+        this.head = undefined;
+        this.tail = undefined;
     }
-    /**
-     * Return the count of live (non-expired) entries.
-     *
-     * Pure query — does NOT touch LRU order. Expired entries discovered during
-     * the scan are evicted opportunistically (they were already invisible to
-     * `get()`, so eviction has no observable effect beyond memory reclamation).
-     *
-     * Two-pass to avoid mutating the Map during iteration (spec-safe).
-     */
     size() {
-        const now = Date.now();
-        const expired = [];
-        let count = 0;
-        for (const [key, entry] of this.entries) {
-            if (entry.expiresAt !== null && entry.expiresAt <= now) {
-                expired.push(key);
-            }
-            else {
-                count++;
-            }
-        }
-        for (const key of expired)
-            this.entries.delete(key);
-        return count;
+        return this.map.size;
     }
-    /**
-     * Stop the background cleanup timer and release internal state.
-     * Safe to call multiple times — subsequent calls are no-ops.
-     */
     destroy() {
         if (this.cleanupTimer !== undefined) {
             clearInterval(this.cleanupTimer);
             this.cleanupTimer = undefined;
+            InMemoryStore.finalizer?.unregister(this);
+        }
+        if (this.memoryListener) {
+            const processOff = process.off;
+            if (typeof processOff === 'function') {
+                processOff.call(process, 'memory', this.memoryListener);
+            }
+            this.memoryListener = undefined;
         }
+        this.map.clear();
+        this.head = undefined;
+        this.tail = undefined;
     }
-    /**
-     * Sweep all entries and remove those past their expiry time.
-     * Called by the autoCleanup interval; not part of the public contract.
-     */
-    _sweep() {
-        const now = Date.now();
-        const expired = [];
-        for (const [key, entry] of this.entries) {
-            if (entry.expiresAt !== null && now > entry.expiresAt) {
-                expired.push(key);
+    appendTail(node) {
+        if (this.tail) {
+            this.tail.next = node;
+            node.prev = this.tail;
+            node.next = undefined;
+        }
+        else {
+            this.head = node;
+        }
+        this.tail = node;
+    }
+    removeNode(node) {
+        if (node.prev) {
+            node.prev.next = node.next;
+        }
+        else {
+            this.head = node.next;
+        }
+        if (node.next) {
+            node.next.prev = node.prev;
+        }
+        else {
+            this.tail = node.prev;
+        }
+        node.prev = undefined;
+        node.next = undefined;
+    }
+    moveToTail(node) {
+        if (this.tail === node)
+            return;
+        this.removeNode(node);
+        this.appendTail(node);
+    }
+    sweep() {
+        try {
+            const now = Date.now();
+            const expired = [];
+            for (const [key, node] of this.map) {
+                if (node.expiresAt !== null && now > node.expiresAt) {
+                    expired.push(key);
+                }
             }
+            for (const key of expired) {
+                const node = this.map.get(key);
+                if (node) {
+                    this.removeNode(node);
+                    this.map.delete(key);
+                }
+            }
+        }
+        catch {
         }
-        for (const key of expired)
-            this.entries.delete(key);
     }
 }
-//# sourceMappingURL=memory.js.map
+export function createDefaultStore() {
+    return new InMemoryStore({
+        maxSize: LIMITS.DEFAULT_STORE_MAX_SIZE,
+        autoCleanup: true,
+        cleanupIntervalMs: LIMITS.DEFAULT_STORE_CLEANUP_INTERVAL_MS,
+    });
+}

package/dist/testing/index.cjs

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.waitForObsHook = waitForObsHook;
+exports.isActlyEventType = isActlyEventType;
+function waitForObsHook(hooks, hookName, timeoutMs = 5000) {
+    let resolveFn;
+    let rejectFn;
+    const promise = new Promise((resolve, reject) => {
+        resolveFn = resolve;
+        rejectFn = reject;
+    });
+    let settled = false;
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        settled = true;
+        hooks[hookName] = previousHook;
+        rejectFn(new Error(`Actly: waitForObsHook timed out after ${timeoutMs}ms waiting for "${String(hookName)}".`));
+    }, timeoutMs);
+    const unrefable = timer;
+    if (typeof unrefable.unref === 'function')
+        unrefable.unref();
+    const previousHook = hooks[hookName];
+    const cleanup = () => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        hooks[hookName] = previousHook;
+    };
+    hooks[hookName] = (event) => {
+        if (typeof previousHook === 'function') {
+            try {
+                previousHook(event);
+            }
+            catch { }
+        }
+        if (settled)
+            return;
+        cleanup();
+        resolveFn(event);
+    };
+    return Object.assign(promise, { cancel: cleanup });
+}
+function isActlyEventType(value) {
+    return (value === 'attempt' ||
+        value === 'retry' ||
+        value === 'cache-hit' ||
+        value === 'cache-miss' ||
+        value === 'dedupe-join' ||
+        value === 'timeout' ||
+        value === 'final-success' ||
+        value === 'final-failure' ||
+        value === 'backpressure' ||
+        value === 'watchdog');
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,6 @@
+import type { ObservabilityHooks, ActlyEventType } from '../observability.js';
+export declare function waitForObsHook<K extends keyof ObservabilityHooks>(hooks: ObservabilityHooks, hookName: K, timeoutMs?: number): Promise<Parameters<NonNullable<ObservabilityHooks[K]>>[0]> & {
+    cancel: () => void;
+};
+export declare function isActlyEventType(value: unknown): value is ActlyEventType;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAyB7E,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,kBAAkB,EAC/D,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,CAAC,EACX,SAAS,SAAO,GACf,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,CA+CrF;AAMD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAaxE"}

package/dist/testing/index.js

@@ -0,0 +1,52 @@
+export function waitForObsHook(hooks, hookName, timeoutMs = 5000) {
+    let resolveFn;
+    let rejectFn;
+    const promise = new Promise((resolve, reject) => {
+        resolveFn = resolve;
+        rejectFn = reject;
+    });
+    let settled = false;
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        settled = true;
+        hooks[hookName] = previousHook;
+        rejectFn(new Error(`Actly: waitForObsHook timed out after ${timeoutMs}ms waiting for "${String(hookName)}".`));
+    }, timeoutMs);
+    const unrefable = timer;
+    if (typeof unrefable.unref === 'function')
+        unrefable.unref();
+    const previousHook = hooks[hookName];
+    const cleanup = () => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        hooks[hookName] = previousHook;
+    };
+    hooks[hookName] = (event) => {
+        if (typeof previousHook === 'function') {
+            try {
+                previousHook(event);
+            }
+            catch { }
+        }
+        if (settled)
+            return;
+        cleanup();
+        resolveFn(event);
+    };
+    return Object.assign(promise, { cancel: cleanup });
+}
+export function isActlyEventType(value) {
+    return (value === 'attempt' ||
+        value === 'retry' ||
+        value === 'cache-hit' ||
+        value === 'cache-miss' ||
+        value === 'dedupe-join' ||
+        value === 'timeout' ||
+        value === 'final-success' ||
+        value === 'final-failure' ||
+        value === 'backpressure' ||
+        value === 'watchdog');
+}

package/dist/types/index.cjs

@@ -1,3 +1,2 @@
 "use strict";
-// ─── Public surface ────────────────────────────────────────────────────────────
 Object.defineProperty(exports, "__esModule", { value: true });