actly 1.1.0 → 1.1.5

package/dist/utils/backoff.d.ts

@@ -0,0 +1,14 @@
+import type { RetryOptions } from '../types/index.js';
+/**
+ * Compute the delay before the next retry attempt, applying backoff, cap, and
+ * jitter in that order.
+ *
+ * Order matters:
+ *  1. `backoff` grows the base delay geometrically/linearly.
+ *  2. `maxDelay` caps the result (prevents exponential blowup).
+ *  3. `jitter` randomises within `[0, delay]` (prevents thundering herd).
+ *
+ * Returns 0 if `delayMs` is 0 or undefined — skipping the sleep entirely.
+ */
+export declare function computeDelay(attempt: number, opts: RetryOptions): number;
+//# sourceMappingURL=backoff.d.ts.map

package/dist/utils/backoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.d.ts","sourceRoot":"","sources":["../../src/utils/backoff.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,MAAM,CAyBxE"}

package/dist/utils/backoff.js

@@ -0,0 +1,41 @@
+/**
+ * Compute the delay before the next retry attempt, applying backoff, cap, and
+ * jitter in that order.
+ *
+ * Order matters:
+ *  1. `backoff` grows the base delay geometrically/linearly.
+ *  2. `maxDelay` caps the result (prevents exponential blowup).
+ *  3. `jitter` randomises within `[0, delay]` (prevents thundering herd).
+ *
+ * Returns 0 if `delayMs` is 0 or undefined — skipping the sleep entirely.
+ */
+export function computeDelay(attempt, opts) {
+    const base = opts.delayMs ?? 0;
+    if (base === 0)
+        return 0;
+    // Step 1: backoff
+    let delay;
+    switch (opts.backoff ?? 'none') {
+        case 'linear':
+            delay = base * attempt;
+            break;
+        case 'exponential':
+            delay = base * 2 ** (attempt - 1);
+            break;
+        default: delay = base;
+    }
+    // Step 2: cap (guard against Infinity and NaN before Math.min)
+    const max = opts.maxDelay ?? Number.POSITIVE_INFINITY;
+    if (!Number.isFinite(delay))
+        delay = max;
+    delay = Math.min(delay, max);
+    // Step 3: jitter
+    switch (opts.jitter ?? 'full') {
+        case 'none': return delay;
+        case 'full': return Math.random() * delay;
+        case 'equal': return delay / 2 + Math.random() * delay / 2;
+        case 'decorrelated': return base + Math.random() * (delay - base);
+        default: return delay;
+    }
+}
+//# sourceMappingURL=backoff.js.map

package/dist/utils/backoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backoff.js","sourceRoot":"","sources":["../../src/utils/backoff.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,IAAkB;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAA;IAC9B,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAExB,kBAAkB;IAClB,IAAI,KAAa,CAAA;IACjB,QAAQ,IAAI,CAAC,OAAO,IAAI,MAAM,EAAE,CAAC;QAC/B,KAAK,QAAQ;YAAO,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC;YAAC,MAAK;QACjD,KAAK,aAAa;YAAE,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;YAAC,MAAK;QAC5D,OAAO,CAAC,CAAY,KAAK,GAAG,IAAI,CAAA;IAClC,CAAC;IAED,+DAA+D;IAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,iBAAiB,CAAA;IACrD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,KAAK,GAAG,GAAG,CAAA;IACxC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IAE5B,iBAAiB;IACjB,QAAQ,IAAI,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;QAC9B,KAAK,MAAM,CAAC,CAAS,OAAO,KAAK,CAAA;QACjC,KAAK,MAAM,CAAC,CAAS,OAAO,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,CAAA;QACjD,KAAK,OAAO,CAAC,CAAQ,OAAO,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC,CAAA;QACjE,KAAK,cAAc,CAAC,CAAC,OAAO,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,CAAA;QACjE,OAAO,CAAC,CAAa,OAAO,KAAK,CAAA;IACnC,CAAC;AACH,CAAC"}

package/dist/utils/validate.cjs

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertKey = assertKey;
+exports.assertRetryOptions = assertRetryOptions;
+exports.assertTimeoutOptions = assertTimeoutOptions;
+exports.assertCacheOptions = assertCacheOptions;
+exports.assertDedupeOptions = assertDedupeOptions;
+exports.assertOptions = assertOptions;
+/**
+ * Validate user-facing option shapes. Throws `RangeError` / `TypeError` on
+ * invalid input — these are programmer errors, not runtime failures, so
+ * throwing (rather than returning an `ActFailure`) is the right call.
+ *
+ * Called once at the top of `act()` so policies can assume well-formed input.
+ */
+function assertKey(key) {
+    if (typeof key !== 'string') {
+        throw new TypeError(`Actly: key must be a string, got ${typeof key}`);
+    }
+    if (key.length === 0) {
+        throw new RangeError("Actly: key must be non-empty. An empty key collapses every caller " +
+            "onto the same dedupe/cache slot — almost certainly a bug.");
+    }
+    // Reject reserved internal prefixes so user keys cannot collide with
+    // dedupe/cache namespace prefixes.
+    if (key.startsWith('dedupe:') || key.startsWith('cache:') || key.startsWith('__inflight:')) {
+        throw new RangeError(`Actly: key must not start with reserved prefix "dedupe:", "cache:", or "__inflight:" (got ${JSON.stringify(key)}).`);
+    }
+}
+function assertRetryOptions(opts) {
+    if (!Number.isInteger(opts.attempts) || opts.attempts < 1) {
+        throw new RangeError(`Actly: retry.attempts must be a positive integer, got ${opts.attempts}`);
+    }
+    if (opts.delayMs !== undefined) {
+        assertNonNegativeFinite('retry.delayMs', opts.delayMs);
+    }
+    if (opts.maxDelay !== undefined) {
+        assertNonNegativeFinite('retry.maxDelay', opts.maxDelay);
+    }
+    if (opts.shouldRetry !== undefined && typeof opts.shouldRetry !== 'function') {
+        throw new TypeError(`Actly: retry.shouldRetry must be a function, got ${typeof opts.shouldRetry}`);
+    }
+}
+function assertTimeoutOptions(opts, field) {
+    if (typeof opts.ms !== 'number' || !Number.isFinite(opts.ms) || opts.ms <= 0) {
+        throw new RangeError(`Actly: ${field}.ms must be a positive finite number, got ${opts.ms}`);
+    }
+}
+function assertCacheOptions(opts) {
+    if (typeof opts.ttl !== 'number' || !Number.isFinite(opts.ttl) || opts.ttl <= 0) {
+        throw new RangeError(`Actly: cache.ttl must be a positive finite number, got ${opts.ttl}`);
+    }
+}
+function assertDedupeOptions(opts) {
+    if (opts.inflightTtl !== undefined) {
+        assertNonNegativeFinite('dedupe.inflightTtl', opts.inflightTtl);
+    }
+}
+function assertOptions(options) {
+    if (options.retry)
+        assertRetryOptions(options.retry);
+    if (options.timeout)
+        assertTimeoutOptions(options.timeout, 'timeout');
+    if (options.totalTimeout)
+        assertTimeoutOptions(options.totalTimeout, 'totalTimeout');
+    if (options.cache)
+        assertCacheOptions(options.cache);
+    if (options.dedupe && typeof options.dedupe !== 'boolean') {
+        assertDedupeOptions(options.dedupe);
+    }
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+        throw new TypeError(`Actly: signal must be an AbortSignal, got ${options.signal === null ? 'null' : typeof options.signal}`);
+    }
+}
+function assertNonNegativeFinite(field, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new RangeError(`Actly: ${field} must be a non-negative finite number, got ${value}`);
+    }
+}

package/dist/utils/validate.d.ts

@@ -0,0 +1,15 @@
+import type { ActOptions, CacheOptions, DedupeOptions, RetryOptions, TimeoutOptions } from '../types/index.js';
+/**
+ * Validate user-facing option shapes. Throws `RangeError` / `TypeError` on
+ * invalid input — these are programmer errors, not runtime failures, so
+ * throwing (rather than returning an `ActFailure`) is the right call.
+ *
+ * Called once at the top of `act()` so policies can assume well-formed input.
+ */
+export declare function assertKey(key: string): void;
+export declare function assertRetryOptions(opts: RetryOptions): void;
+export declare function assertTimeoutOptions(opts: TimeoutOptions, field: string): void;
+export declare function assertCacheOptions(opts: CacheOptions): void;
+export declare function assertDedupeOptions(opts: DedupeOptions): void;
+export declare function assertOptions(options: ActOptions): void;
+//# sourceMappingURL=validate.d.ts.map

package/dist/utils/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAA;AAE1B;;;;;;GAMG;AAEH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAiB3C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAiB3D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAM9E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAM3D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAI7D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAavD"}

package/dist/utils/validate.js

@@ -0,0 +1,72 @@
+/**
+ * Validate user-facing option shapes. Throws `RangeError` / `TypeError` on
+ * invalid input — these are programmer errors, not runtime failures, so
+ * throwing (rather than returning an `ActFailure`) is the right call.
+ *
+ * Called once at the top of `act()` so policies can assume well-formed input.
+ */
+export function assertKey(key) {
+    if (typeof key !== 'string') {
+        throw new TypeError(`Actly: key must be a string, got ${typeof key}`);
+    }
+    if (key.length === 0) {
+        throw new RangeError("Actly: key must be non-empty. An empty key collapses every caller " +
+            "onto the same dedupe/cache slot — almost certainly a bug.");
+    }
+    // Reject reserved internal prefixes so user keys cannot collide with
+    // dedupe/cache namespace prefixes.
+    if (key.startsWith('dedupe:') || key.startsWith('cache:') || key.startsWith('__inflight:')) {
+        throw new RangeError(`Actly: key must not start with reserved prefix "dedupe:", "cache:", or "__inflight:" (got ${JSON.stringify(key)}).`);
+    }
+}
+export function assertRetryOptions(opts) {
+    if (!Number.isInteger(opts.attempts) || opts.attempts < 1) {
+        throw new RangeError(`Actly: retry.attempts must be a positive integer, got ${opts.attempts}`);
+    }
+    if (opts.delayMs !== undefined) {
+        assertNonNegativeFinite('retry.delayMs', opts.delayMs);
+    }
+    if (opts.maxDelay !== undefined) {
+        assertNonNegativeFinite('retry.maxDelay', opts.maxDelay);
+    }
+    if (opts.shouldRetry !== undefined && typeof opts.shouldRetry !== 'function') {
+        throw new TypeError(`Actly: retry.shouldRetry must be a function, got ${typeof opts.shouldRetry}`);
+    }
+}
+export function assertTimeoutOptions(opts, field) {
+    if (typeof opts.ms !== 'number' || !Number.isFinite(opts.ms) || opts.ms <= 0) {
+        throw new RangeError(`Actly: ${field}.ms must be a positive finite number, got ${opts.ms}`);
+    }
+}
+export function assertCacheOptions(opts) {
+    if (typeof opts.ttl !== 'number' || !Number.isFinite(opts.ttl) || opts.ttl <= 0) {
+        throw new RangeError(`Actly: cache.ttl must be a positive finite number, got ${opts.ttl}`);
+    }
+}
+export function assertDedupeOptions(opts) {
+    if (opts.inflightTtl !== undefined) {
+        assertNonNegativeFinite('dedupe.inflightTtl', opts.inflightTtl);
+    }
+}
+export function assertOptions(options) {
+    if (options.retry)
+        assertRetryOptions(options.retry);
+    if (options.timeout)
+        assertTimeoutOptions(options.timeout, 'timeout');
+    if (options.totalTimeout)
+        assertTimeoutOptions(options.totalTimeout, 'totalTimeout');
+    if (options.cache)
+        assertCacheOptions(options.cache);
+    if (options.dedupe && typeof options.dedupe !== 'boolean') {
+        assertDedupeOptions(options.dedupe);
+    }
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal)) {
+        throw new TypeError(`Actly: signal must be an AbortSignal, got ${options.signal === null ? 'null' : typeof options.signal}`);
+    }
+}
+function assertNonNegativeFinite(field, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw new RangeError(`Actly: ${field} must be a non-negative finite number, got ${value}`);
+    }
+}
+//# sourceMappingURL=validate.js.map

package/dist/utils/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AAEH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,SAAS,CAAC,oCAAoC,OAAO,GAAG,EAAE,CAAC,CAAA;IACvE,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,UAAU,CAClB,oEAAoE;YACpE,2DAA2D,CAC5D,CAAA;IACH,CAAC;IACD,qEAAqE;IACrE,mCAAmC;IACnC,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC3F,MAAM,IAAI,UAAU,CAClB,6FAA6F,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CACrH,CAAA;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAkB;IACnD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,UAAU,CAClB,yDAAyD,IAAI,CAAC,QAAQ,EAAE,CACzE,CAAA;IACH,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,uBAAuB,CAAC,eAAe,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;IACxD,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChC,uBAAuB,CAAC,gBAAgB,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC1D,CAAC;IACD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QAC7E,MAAM,IAAI,SAAS,CACjB,oDAAoD,OAAO,IAAI,CAAC,WAAW,EAAE,CAC9E,CAAA;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,IAAoB,EAAE,KAAa;IACtE,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,UAAU,CAClB,UAAU,KAAK,6CAA6C,IAAI,CAAC,EAAE,EAAE,CACtE,CAAA;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAkB;IACnD,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,UAAU,CAClB,0DAA0D,IAAI,CAAC,GAAG,EAAE,CACrE,CAAA;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,IAAmB;IACrD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACnC,uBAAuB,CAAC,oBAAoB,EAAE,IAAI,CAAC,WAAW,CAAC,CAAA;IACjE,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAmB;IAC/C,IAAI,OAAO,CAAC,KAAK;QAAM,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACxD,IAAI,OAAO,CAAC,OAAO;QAAI,oBAAoB,CAAC,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;IACvE,IAAI,OAAO,CAAC,YAAY;QAAE,oBAAoB,CAAC,OAAO,CAAC,YAAY,EAAE,cAAc,CAAC,CAAA;IACpF,IAAI,OAAO,CAAC,KAAK;QAAM,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACxD,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1D,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACrC,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,OAAO,CAAC,MAAM,YAAY,WAAW,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,SAAS,CACjB,6CAA6C,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,MAAM,EAAE,CACxG,CAAA;IACH,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,KAAa,EAAE,KAAa;IAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,UAAU,CAClB,UAAU,KAAK,8CAA8C,KAAK,EAAE,CACrE,CAAA;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "actly",
-  "version": "1.1.0",
-  "description": "A reliability primitive for executing async actions safely.",
+  "version": "1.1.5",
+  "description": "A reliability primitive for executing async actions safely — with proper AbortSignal cancellation, single-flight cache, LRU store, and jittered backoff.",
   "keywords": [
     "reliability",
     "retry",
     "timeout",
     "dedupe",
     "cache",
-    "async"
+    "async",
+    "backoff",
+    "abort",
+    "single-flight",
+    "resilience",
+    "jitter"
   ],
   "license": "MIT",
   "type": "module",
@@ -17,9 +22,9 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     }
   },
   "files": [
@@ -27,42 +32,19 @@
     "README.md",
     "LICENSE"
   ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
   "scripts": {
     "build": "tsc --project tsconfig.build.json && tsc --project tsconfig.cjs.json && node scripts/postbuild.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "jest"
-  },
-  "jest": {
-    "preset": "ts-jest/presets/default-esm",
-    "testEnvironment": "node",
-    "extensionsToTreatAsEsm": [
-      ".ts"
-    ],
-    "moduleNameMapper": {
-      "^(\\.{1,2}/.*)\\.js$": "$1"
-    },
-    "transform": {
-      "^.+\\.tsx?$": [
-        "ts-jest",
-        {
-          "useESM": true,
-          "tsconfig": {
-            "module": "ESNext",
-            "moduleResolution": "bundler"
-          }
-        }
-      ]
-    },
-    "testMatch": [
-      "**/src/__tests__/**/*.test.ts"
-    ],
-    "clearMocks": true,
-    "restoreMocks": true
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.0",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.4.0",
-    "typescript": "^5.4.0"
+    "@types/node": "^18.19.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0"
   }
 }