actly 1.1.5 → 1.3.0

package/dist/utils/safeCall.js

@@ -0,0 +1,25 @@
+const IS_DEV = typeof process !== 'undefined' &&
+    typeof process.env === 'object' &&
+    process.env !== null &&
+    process.env.NODE_ENV !== 'production';
+export function safeCall(fn, ...args) {
+    if (!fn)
+        return;
+    try {
+        const result = fn(...args);
+        if (result !== null && result !== undefined && typeof result.then === 'function') {
+            Promise.resolve(result).catch((err) => {
+                if (IS_DEV) {
+                    console.warn('Actly: async observability hook rejected — error swallowed to protect main path. ' +
+                        'Fix the hook to prevent silent observability loss.', err);
+                }
+            });
+        }
+    }
+    catch (err) {
+        if (IS_DEV) {
+            console.warn('Actly: observability hook threw — error swallowed to protect main path. ' +
+                'Fix the hook to prevent silent observability loss.', err);
+        }
+    }
+}

package/dist/utils/sanitize.cjs

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeErrorMessage = sanitizeErrorMessage;
+exports.sanitizeError = sanitizeError;
+const limits_js_1 = require("./limits.js");
+const errors_js_1 = require("../errors.js");
+const FORBIDDEN_CHARS = /[\x00-\x1f\x7f]/g;
+const HTML_ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#x27;' };
+function sanitizeErrorMessage(msg) {
+    let str;
+    if (msg instanceof Error) {
+        str = String(msg.message ?? '');
+    }
+    else if (typeof msg === 'string') {
+        str = msg;
+    }
+    else {
+        str = String(msg ?? '');
+    }
+    str = str.replace(/[&<>"']/g, (c) => HTML_ENTITIES[c]);
+    str = str.replace(FORBIDDEN_CHARS, '');
+    if (str.length > limits_js_1.LIMITS.MAX_SANITIZED_ERROR_LENGTH) {
+        str = str.slice(0, limits_js_1.LIMITS.MAX_SANITIZED_ERROR_LENGTH - 3) + '...';
+    }
+    return str;
+}
+function sanitizeError(err) {
+    if (err instanceof Error) {
+        const sanitized = new Error(sanitizeErrorMessage(err.message));
+        sanitized.name = err.name;
+        try {
+            sanitized.stack = err.stack;
+        }
+        catch { }
+        if (err instanceof errors_js_1.ActlyError) {
+            const code = err.code;
+            const key = err.key;
+            Object.defineProperty(sanitized, 'code', { value: code, enumerable: true });
+            if (key !== undefined) {
+                Object.defineProperty(sanitized, 'key', { value: key, enumerable: true });
+            }
+        }
+        try {
+            Object.defineProperty(sanitized, 'cause', { value: err, enumerable: false });
+        }
+        catch { }
+        return sanitized;
+    }
+    return sanitizeErrorMessage(err);
+}

package/dist/utils/sanitize.d.ts

@@ -0,0 +1,3 @@
+export declare function sanitizeErrorMessage(msg: unknown): string;
+export declare function sanitizeError(err: unknown): unknown;
+//# sourceMappingURL=sanitize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sanitize.d.ts","sourceRoot":"","sources":["../../src/utils/sanitize.ts"],"names":[],"mappings":"AAQA,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAkBzD;AAQD,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAmBnD"}

package/dist/utils/sanitize.js

@@ -0,0 +1,46 @@
+import { LIMITS } from './limits.js';
+import { ActlyError } from '../errors.js';
+const FORBIDDEN_CHARS = /[\x00-\x1f\x7f]/g;
+const HTML_ENTITIES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#x27;' };
+export function sanitizeErrorMessage(msg) {
+    let str;
+    if (msg instanceof Error) {
+        str = String(msg.message ?? '');
+    }
+    else if (typeof msg === 'string') {
+        str = msg;
+    }
+    else {
+        str = String(msg ?? '');
+    }
+    str = str.replace(/[&<>"']/g, (c) => HTML_ENTITIES[c]);
+    str = str.replace(FORBIDDEN_CHARS, '');
+    if (str.length > LIMITS.MAX_SANITIZED_ERROR_LENGTH) {
+        str = str.slice(0, LIMITS.MAX_SANITIZED_ERROR_LENGTH - 3) + '...';
+    }
+    return str;
+}
+export function sanitizeError(err) {
+    if (err instanceof Error) {
+        const sanitized = new Error(sanitizeErrorMessage(err.message));
+        sanitized.name = err.name;
+        try {
+            sanitized.stack = err.stack;
+        }
+        catch { }
+        if (err instanceof ActlyError) {
+            const code = err.code;
+            const key = err.key;
+            Object.defineProperty(sanitized, 'code', { value: code, enumerable: true });
+            if (key !== undefined) {
+                Object.defineProperty(sanitized, 'key', { value: key, enumerable: true });
+            }
+        }
+        try {
+            Object.defineProperty(sanitized, 'cause', { value: err, enumerable: false });
+        }
+        catch { }
+        return sanitized;
+    }
+    return sanitizeErrorMessage(err);
+}

package/dist/utils/validate.cjs

@@ -6,54 +6,78 @@ 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.
- */
+exports.assertAuditOptions = assertAuditOptions;
+exports.assertCircuitBreakerOptions = assertCircuitBreakerOptions;
+exports.assertBulkheadOptions = assertBulkheadOptions;
+exports.assertRateLimitOptions = assertRateLimitOptions;
+exports.assertHedgeOptions = assertHedgeOptions;
+const limits_js_1 = require("./limits.js");
+const key_js_1 = require("./key.js");
 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)}).`);
-    }
+    (0, key_js_1.sanitizeKey)(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.attempts > limits_js_1.LIMITS.MAX_RETRY_ATTEMPTS) {
+        throw new RangeError(`Actly: retry.attempts ${opts.attempts} exceeds limit ${limits_js_1.LIMITS.MAX_RETRY_ATTEMPTS}. ` +
+            `If you genuinely need more, use an outer supervisor.`);
+    }
     if (opts.delayMs !== undefined) {
-        assertNonNegativeFinite('retry.delayMs', opts.delayMs);
+        assertNonNegativeFinite('retry.delayMs', opts.delayMs, limits_js_1.LIMITS.MAX_RETRY_DELAY_MS);
     }
     if (opts.maxDelay !== undefined) {
-        assertNonNegativeFinite('retry.maxDelay', opts.maxDelay);
+        assertNonNegativeFinite('retry.maxDelay', opts.maxDelay, limits_js_1.LIMITS.MAX_RETRY_DELAY_MS);
+    }
+    if (opts.backoff !== undefined && !BACKOFF_MODES.has(opts.backoff)) {
+        throw new RangeError(`Actly: retry.backoff must be one of ${[...BACKOFF_MODES].map((m) => JSON.stringify(m)).join(' | ')}, ` +
+            `got ${JSON.stringify(opts.backoff)}`);
+    }
+    if (opts.jitter !== undefined && !JITTER_MODES.has(opts.jitter)) {
+        throw new RangeError(`Actly: retry.jitter must be one of ${[...JITTER_MODES].map((m) => JSON.stringify(m)).join(' | ')}, ` +
+            `got ${JSON.stringify(opts.jitter)}`);
     }
     if (opts.shouldRetry !== undefined && typeof opts.shouldRetry !== 'function') {
         throw new TypeError(`Actly: retry.shouldRetry must be a function, got ${typeof opts.shouldRetry}`);
     }
+    if (opts.shouldRetryResult !== undefined && typeof opts.shouldRetryResult !== 'function') {
+        throw new TypeError(`Actly: retry.shouldRetryResult must be a function, got ${typeof opts.shouldRetryResult}`);
+    }
+    if (opts.backoffFn !== undefined && typeof opts.backoffFn !== 'function') {
+        throw new TypeError(`Actly: retry.backoffFn must be a function, got ${typeof opts.backoffFn}`);
+    }
+    if (opts.dangerouslyUnref !== undefined && typeof opts.dangerouslyUnref !== 'boolean') {
+        throw new TypeError(`Actly: retry.dangerouslyUnref must be a boolean, got ${typeof opts.dangerouslyUnref}`);
+    }
 }
 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}`);
     }
+    if (opts.ms > limits_js_1.LIMITS.MAX_TIMEOUT_MS) {
+        throw new RangeError(`Actly: ${field}.ms ${opts.ms} exceeds limit ${limits_js_1.LIMITS.MAX_TIMEOUT_MS}.`);
+    }
+    if (opts.strategy !== undefined && opts.strategy !== 'race' && opts.strategy !== 'cooperative') {
+        throw new RangeError(`Actly: ${field}.strategy must be 'race' or 'cooperative', got ${JSON.stringify(opts.strategy)}`);
+    }
 }
 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}`);
     }
+    if (opts.ttl > limits_js_1.LIMITS.MAX_CACHE_TTL) {
+        throw new RangeError(`Actly: cache.ttl ${opts.ttl} exceeds limit ${limits_js_1.LIMITS.MAX_CACHE_TTL} (~24h).`);
+    }
 }
 function assertDedupeOptions(opts) {
     if (opts.inflightTtl !== undefined) {
-        assertNonNegativeFinite('dedupe.inflightTtl', opts.inflightTtl);
+        if (opts.inflightTtl === Number.POSITIVE_INFINITY)
+            return;
+        if (opts.inflightTtl === 0) {
+            throw new RangeError(`Actly: dedupe.inflightTtl must be > 0 (or Infinity). Got 0 — "immediate expiry" is not a valid configuration; use a small positive number (e.g. 1) instead.`);
+        }
+        assertNonNegativeFinite('dedupe.inflightTtl', opts.inflightTtl, limits_js_1.LIMITS.MAX_INFLIGHT_TTL);
     }
 }
 function assertOptions(options) {
@@ -65,15 +89,128 @@ function assertOptions(options) {
         assertTimeoutOptions(options.totalTimeout, 'totalTimeout');
     if (options.cache)
         assertCacheOptions(options.cache);
-    if (options.dedupe && typeof options.dedupe !== 'boolean') {
+    if (options.dedupe != null && 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}`);
+    if (options.dedupe != null &&
+        typeof options.dedupe !== 'boolean' && typeof options.dedupe !== 'object') {
+        throw new TypeError(`Actly: dedupe must be a boolean, an object, or undefined, got ${typeof options.dedupe}`);
+    }
+    if (options.signal !== undefined && options.signal !== null) {
+        const s = options.signal;
+        if (typeof s !== 'object' ||
+            typeof s.aborted !== 'boolean' ||
+            typeof s.addEventListener !== 'function' ||
+            typeof s.removeEventListener !== 'function') {
+            throw new TypeError(`Actly: signal must be an AbortSignal (object with .aborted boolean, .addEventListener function, and .removeEventListener function), got ${options.signal === null ? 'null' : typeof options.signal}`);
+        }
+    }
+    if (options.circuitBreaker)
+        assertCircuitBreakerOptions(options.circuitBreaker);
+    if (options.bulkhead)
+        assertBulkheadOptions(options.bulkhead);
+    if (options.rateLimit)
+        assertRateLimitOptions(options.rateLimit);
+    if (options.hedge)
+        assertHedgeOptions(options.hedge);
+    if (options.audit)
+        assertAuditOptions(options.audit);
+}
+function assertAuditOptions(opts) {
+    if (typeof opts.log !== 'function') {
+        throw new TypeError(`Actly: audit.log must be a function, got ${opts.log === null ? 'null' : typeof opts.log}`);
+    }
+}
+function assertCircuitBreakerOptions(opts) {
+    if (!Number.isInteger(opts.threshold) || opts.threshold < 1) {
+        throw new RangeError(`Actly: circuitBreaker.threshold must be a positive integer, got ${opts.threshold}`);
+    }
+    if (typeof opts.cooldownMs !== 'number' || !Number.isFinite(opts.cooldownMs) || opts.cooldownMs <= 0) {
+        throw new RangeError(`Actly: circuitBreaker.cooldownMs must be a positive finite number, got ${opts.cooldownMs}`);
+    }
+    if (opts.resetTimeoutMs !== undefined) {
+        if (opts.resetTimeoutMs === Number.POSITIVE_INFINITY)
+            return;
+        assertNonNegativeFinite('circuitBreaker.resetTimeoutMs', opts.resetTimeoutMs, Number.POSITIVE_INFINITY);
+    }
+    if (opts.strategy !== undefined && opts.strategy !== 'consecutive' && opts.strategy !== 'count') {
+        throw new RangeError(`Actly: circuitBreaker.strategy must be 'consecutive' or 'count', got ${JSON.stringify(opts.strategy)}`);
+    }
+    if (opts.countSize !== undefined) {
+        if (!Number.isInteger(opts.countSize) || opts.countSize < 1) {
+            throw new RangeError(`Actly: circuitBreaker.countSize must be a positive integer, got ${opts.countSize}`);
+        }
+        if (opts.countSize > limits_js_1.LIMITS.MAX_CIRCUIT_BREAKER_WINDOW) {
+            throw new RangeError(`Actly: circuitBreaker.countSize ${opts.countSize} exceeds limit ${limits_js_1.LIMITS.MAX_CIRCUIT_BREAKER_WINDOW}.`);
+        }
+    }
+    if (opts.countThreshold !== undefined) {
+        if (!Number.isFinite(opts.countThreshold) || opts.countThreshold < 0 || opts.countThreshold > 1) {
+            throw new RangeError(`Actly: circuitBreaker.countThreshold must be a finite number between 0 and 1, got ${opts.countThreshold}`);
+        }
+    }
+    if (opts.countMinimumCalls !== undefined) {
+        if (!Number.isInteger(opts.countMinimumCalls) || opts.countMinimumCalls < 1) {
+            throw new RangeError(`Actly: circuitBreaker.countMinimumCalls must be a positive integer, got ${opts.countMinimumCalls}`);
+        }
+        if (opts.countMinimumCalls > limits_js_1.LIMITS.MAX_CIRCUIT_BREAKER_WINDOW) {
+            throw new RangeError(`Actly: circuitBreaker.countMinimumCalls ${opts.countMinimumCalls} exceeds limit ${limits_js_1.LIMITS.MAX_CIRCUIT_BREAKER_WINDOW}.`);
+        }
+    }
+}
+function assertBulkheadOptions(opts) {
+    if (!Number.isInteger(opts.maxConcurrent) || opts.maxConcurrent < 1) {
+        throw new RangeError(`Actly: bulkhead.maxConcurrent must be a positive integer, got ${opts.maxConcurrent}`);
+    }
+    if (opts.maxConcurrent > limits_js_1.LIMITS.MAX_BULKHEAD_CONCURRENCY) {
+        throw new RangeError(`Actly: bulkhead.maxConcurrent ${opts.maxConcurrent} exceeds limit ${limits_js_1.LIMITS.MAX_BULKHEAD_CONCURRENCY}.`);
+    }
+    if (opts.queueTimeoutMs !== undefined) {
+        assertNonNegativeFinite('bulkhead.queueTimeoutMs', opts.queueTimeoutMs, Number.POSITIVE_INFINITY);
+    }
+    if (opts.maxQueueSize !== undefined) {
+        if (opts.maxQueueSize !== Number.POSITIVE_INFINITY &&
+            (!Number.isInteger(opts.maxQueueSize) || opts.maxQueueSize < 1)) {
+            throw new RangeError(`Actly: bulkhead.maxQueueSize must be a positive integer or Infinity, got ${opts.maxQueueSize}`);
+        }
+        if (opts.maxQueueSize !== Number.POSITIVE_INFINITY &&
+            opts.maxQueueSize > limits_js_1.LIMITS.MAX_BULKHEAD_QUEUE) {
+            throw new RangeError(`Actly: bulkhead.maxQueueSize ${opts.maxQueueSize} exceeds limit ${limits_js_1.LIMITS.MAX_BULKHEAD_QUEUE}.`);
+        }
     }
 }
-function assertNonNegativeFinite(field, value) {
+function assertRateLimitOptions(opts) {
+    if (!Number.isInteger(opts.maxCalls) || opts.maxCalls < 1) {
+        throw new RangeError(`Actly: rateLimit.maxCalls must be a positive integer, got ${opts.maxCalls}`);
+    }
+    if (opts.maxCalls > limits_js_1.LIMITS.MAX_RATE_LIMIT_CALLS) {
+        throw new RangeError(`Actly: rateLimit.maxCalls ${opts.maxCalls} exceeds limit ${limits_js_1.LIMITS.MAX_RATE_LIMIT_CALLS}.`);
+    }
+    if (typeof opts.windowMs !== 'number' || !Number.isFinite(opts.windowMs) || opts.windowMs <= 0) {
+        throw new RangeError(`Actly: rateLimit.windowMs must be a positive finite number, got ${opts.windowMs}`);
+    }
+}
+function assertHedgeOptions(opts) {
+    if (typeof opts.delayMs !== 'number' || !Number.isFinite(opts.delayMs) || opts.delayMs <= 0) {
+        throw new RangeError(`Actly: hedge.delayMs must be a positive finite number, got ${opts.delayMs}`);
+    }
+    if (opts.delayMs > limits_js_1.LIMITS.MAX_HEDGE_DELAY_MS) {
+        throw new RangeError(`Actly: hedge.delayMs ${opts.delayMs} exceeds limit ${limits_js_1.LIMITS.MAX_HEDGE_DELAY_MS}.`);
+    }
+    if (opts.placement !== undefined && opts.placement !== 'outside-retry' && opts.placement !== 'inside-retry') {
+        throw new RangeError(`Actly: hedge.placement must be 'outside-retry' or 'inside-retry', got ${JSON.stringify(opts.placement)}`);
+    }
+    if (opts.keepLoser !== undefined && typeof opts.keepLoser !== 'boolean') {
+        throw new TypeError(`Actly: hedge.keepLoser must be a boolean, got ${typeof opts.keepLoser}`);
+    }
+}
+function assertNonNegativeFinite(field, value, max) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
         throw new RangeError(`Actly: ${field} must be a non-negative finite number, got ${value}`);
     }
+    if (value > max) {
+        throw new RangeError(`Actly: ${field} ${value} exceeds limit ${max}.`);
+    }
 }
+const BACKOFF_MODES = new Set(['none', 'linear', 'exponential']);
+const JITTER_MODES = new Set(['none', 'full', 'equal', 'decorrelated']);

package/dist/utils/validate.d.ts

@@ -1,15 +1,13 @@
-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.
- */
+import type { ActOptions, AuditOptions, BulkheadOptions, CacheOptions, CircuitBreakerOptions, DedupeOptions, HedgeOptions, RateLimitOptions, RetryOptions, TimeoutOptions } from '../types/index.js';
 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;
+export declare function assertAuditOptions(opts: AuditOptions): void;
+export declare function assertCircuitBreakerOptions(opts: CircuitBreakerOptions): void;
+export declare function assertBulkheadOptions(opts: BulkheadOptions): void;
+export declare function assertRateLimitOptions(opts: RateLimitOptions): void;
+export declare function assertHedgeOptions(opts: HedgeOptions): void;
 //# sourceMappingURL=validate.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACf,MAAM,mBAAmB,CAAA;AAW1B,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAkD3D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAgB9E;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAW3D;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAa7D;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI,CAoCvD;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAM3D;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,qBAAqB,GAAG,IAAI,CAuD7E;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CA4BjE;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAgBnE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAuB3D"}

package/dist/utils/validate.js

@@ -1,51 +1,70 @@
-/**
- * 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.
- */
+import { LIMITS } from './limits.js';
+import { sanitizeKey } from './key.js';
 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)}).`);
-    }
+    sanitizeKey(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.attempts > LIMITS.MAX_RETRY_ATTEMPTS) {
+        throw new RangeError(`Actly: retry.attempts ${opts.attempts} exceeds limit ${LIMITS.MAX_RETRY_ATTEMPTS}. ` +
+            `If you genuinely need more, use an outer supervisor.`);
+    }
     if (opts.delayMs !== undefined) {
-        assertNonNegativeFinite('retry.delayMs', opts.delayMs);
+        assertNonNegativeFinite('retry.delayMs', opts.delayMs, LIMITS.MAX_RETRY_DELAY_MS);
     }
     if (opts.maxDelay !== undefined) {
-        assertNonNegativeFinite('retry.maxDelay', opts.maxDelay);
+        assertNonNegativeFinite('retry.maxDelay', opts.maxDelay, LIMITS.MAX_RETRY_DELAY_MS);
+    }
+    if (opts.backoff !== undefined && !BACKOFF_MODES.has(opts.backoff)) {
+        throw new RangeError(`Actly: retry.backoff must be one of ${[...BACKOFF_MODES].map((m) => JSON.stringify(m)).join(' | ')}, ` +
+            `got ${JSON.stringify(opts.backoff)}`);
+    }
+    if (opts.jitter !== undefined && !JITTER_MODES.has(opts.jitter)) {
+        throw new RangeError(`Actly: retry.jitter must be one of ${[...JITTER_MODES].map((m) => JSON.stringify(m)).join(' | ')}, ` +
+            `got ${JSON.stringify(opts.jitter)}`);
     }
     if (opts.shouldRetry !== undefined && typeof opts.shouldRetry !== 'function') {
         throw new TypeError(`Actly: retry.shouldRetry must be a function, got ${typeof opts.shouldRetry}`);
     }
+    if (opts.shouldRetryResult !== undefined && typeof opts.shouldRetryResult !== 'function') {
+        throw new TypeError(`Actly: retry.shouldRetryResult must be a function, got ${typeof opts.shouldRetryResult}`);
+    }
+    if (opts.backoffFn !== undefined && typeof opts.backoffFn !== 'function') {
+        throw new TypeError(`Actly: retry.backoffFn must be a function, got ${typeof opts.backoffFn}`);
+    }
+    if (opts.dangerouslyUnref !== undefined && typeof opts.dangerouslyUnref !== 'boolean') {
+        throw new TypeError(`Actly: retry.dangerouslyUnref must be a boolean, got ${typeof opts.dangerouslyUnref}`);
+    }
 }
 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}`);
     }
+    if (opts.ms > LIMITS.MAX_TIMEOUT_MS) {
+        throw new RangeError(`Actly: ${field}.ms ${opts.ms} exceeds limit ${LIMITS.MAX_TIMEOUT_MS}.`);
+    }
+    if (opts.strategy !== undefined && opts.strategy !== 'race' && opts.strategy !== 'cooperative') {
+        throw new RangeError(`Actly: ${field}.strategy must be 'race' or 'cooperative', got ${JSON.stringify(opts.strategy)}`);
+    }
 }
 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}`);
     }
+    if (opts.ttl > LIMITS.MAX_CACHE_TTL) {
+        throw new RangeError(`Actly: cache.ttl ${opts.ttl} exceeds limit ${LIMITS.MAX_CACHE_TTL} (~24h).`);
+    }
 }
 export function assertDedupeOptions(opts) {
     if (opts.inflightTtl !== undefined) {
-        assertNonNegativeFinite('dedupe.inflightTtl', opts.inflightTtl);
+        if (opts.inflightTtl === Number.POSITIVE_INFINITY)
+            return;
+        if (opts.inflightTtl === 0) {
+            throw new RangeError(`Actly: dedupe.inflightTtl must be > 0 (or Infinity). Got 0 — "immediate expiry" is not a valid configuration; use a small positive number (e.g. 1) instead.`);
+        }
+        assertNonNegativeFinite('dedupe.inflightTtl', opts.inflightTtl, LIMITS.MAX_INFLIGHT_TTL);
     }
 }
 export function assertOptions(options) {
@@ -57,16 +76,128 @@ export function assertOptions(options) {
         assertTimeoutOptions(options.totalTimeout, 'totalTimeout');
     if (options.cache)
         assertCacheOptions(options.cache);
-    if (options.dedupe && typeof options.dedupe !== 'boolean') {
+    if (options.dedupe != null && 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}`);
+    if (options.dedupe != null &&
+        typeof options.dedupe !== 'boolean' && typeof options.dedupe !== 'object') {
+        throw new TypeError(`Actly: dedupe must be a boolean, an object, or undefined, got ${typeof options.dedupe}`);
+    }
+    if (options.signal !== undefined && options.signal !== null) {
+        const s = options.signal;
+        if (typeof s !== 'object' ||
+            typeof s.aborted !== 'boolean' ||
+            typeof s.addEventListener !== 'function' ||
+            typeof s.removeEventListener !== 'function') {
+            throw new TypeError(`Actly: signal must be an AbortSignal (object with .aborted boolean, .addEventListener function, and .removeEventListener function), got ${options.signal === null ? 'null' : typeof options.signal}`);
+        }
+    }
+    if (options.circuitBreaker)
+        assertCircuitBreakerOptions(options.circuitBreaker);
+    if (options.bulkhead)
+        assertBulkheadOptions(options.bulkhead);
+    if (options.rateLimit)
+        assertRateLimitOptions(options.rateLimit);
+    if (options.hedge)
+        assertHedgeOptions(options.hedge);
+    if (options.audit)
+        assertAuditOptions(options.audit);
+}
+export function assertAuditOptions(opts) {
+    if (typeof opts.log !== 'function') {
+        throw new TypeError(`Actly: audit.log must be a function, got ${opts.log === null ? 'null' : typeof opts.log}`);
+    }
+}
+export function assertCircuitBreakerOptions(opts) {
+    if (!Number.isInteger(opts.threshold) || opts.threshold < 1) {
+        throw new RangeError(`Actly: circuitBreaker.threshold must be a positive integer, got ${opts.threshold}`);
+    }
+    if (typeof opts.cooldownMs !== 'number' || !Number.isFinite(opts.cooldownMs) || opts.cooldownMs <= 0) {
+        throw new RangeError(`Actly: circuitBreaker.cooldownMs must be a positive finite number, got ${opts.cooldownMs}`);
+    }
+    if (opts.resetTimeoutMs !== undefined) {
+        if (opts.resetTimeoutMs === Number.POSITIVE_INFINITY)
+            return;
+        assertNonNegativeFinite('circuitBreaker.resetTimeoutMs', opts.resetTimeoutMs, Number.POSITIVE_INFINITY);
+    }
+    if (opts.strategy !== undefined && opts.strategy !== 'consecutive' && opts.strategy !== 'count') {
+        throw new RangeError(`Actly: circuitBreaker.strategy must be 'consecutive' or 'count', got ${JSON.stringify(opts.strategy)}`);
+    }
+    if (opts.countSize !== undefined) {
+        if (!Number.isInteger(opts.countSize) || opts.countSize < 1) {
+            throw new RangeError(`Actly: circuitBreaker.countSize must be a positive integer, got ${opts.countSize}`);
+        }
+        if (opts.countSize > LIMITS.MAX_CIRCUIT_BREAKER_WINDOW) {
+            throw new RangeError(`Actly: circuitBreaker.countSize ${opts.countSize} exceeds limit ${LIMITS.MAX_CIRCUIT_BREAKER_WINDOW}.`);
+        }
+    }
+    if (opts.countThreshold !== undefined) {
+        if (!Number.isFinite(opts.countThreshold) || opts.countThreshold < 0 || opts.countThreshold > 1) {
+            throw new RangeError(`Actly: circuitBreaker.countThreshold must be a finite number between 0 and 1, got ${opts.countThreshold}`);
+        }
+    }
+    if (opts.countMinimumCalls !== undefined) {
+        if (!Number.isInteger(opts.countMinimumCalls) || opts.countMinimumCalls < 1) {
+            throw new RangeError(`Actly: circuitBreaker.countMinimumCalls must be a positive integer, got ${opts.countMinimumCalls}`);
+        }
+        if (opts.countMinimumCalls > LIMITS.MAX_CIRCUIT_BREAKER_WINDOW) {
+            throw new RangeError(`Actly: circuitBreaker.countMinimumCalls ${opts.countMinimumCalls} exceeds limit ${LIMITS.MAX_CIRCUIT_BREAKER_WINDOW}.`);
+        }
+    }
+}
+export function assertBulkheadOptions(opts) {
+    if (!Number.isInteger(opts.maxConcurrent) || opts.maxConcurrent < 1) {
+        throw new RangeError(`Actly: bulkhead.maxConcurrent must be a positive integer, got ${opts.maxConcurrent}`);
+    }
+    if (opts.maxConcurrent > LIMITS.MAX_BULKHEAD_CONCURRENCY) {
+        throw new RangeError(`Actly: bulkhead.maxConcurrent ${opts.maxConcurrent} exceeds limit ${LIMITS.MAX_BULKHEAD_CONCURRENCY}.`);
+    }
+    if (opts.queueTimeoutMs !== undefined) {
+        assertNonNegativeFinite('bulkhead.queueTimeoutMs', opts.queueTimeoutMs, Number.POSITIVE_INFINITY);
+    }
+    if (opts.maxQueueSize !== undefined) {
+        if (opts.maxQueueSize !== Number.POSITIVE_INFINITY &&
+            (!Number.isInteger(opts.maxQueueSize) || opts.maxQueueSize < 1)) {
+            throw new RangeError(`Actly: bulkhead.maxQueueSize must be a positive integer or Infinity, got ${opts.maxQueueSize}`);
+        }
+        if (opts.maxQueueSize !== Number.POSITIVE_INFINITY &&
+            opts.maxQueueSize > LIMITS.MAX_BULKHEAD_QUEUE) {
+            throw new RangeError(`Actly: bulkhead.maxQueueSize ${opts.maxQueueSize} exceeds limit ${LIMITS.MAX_BULKHEAD_QUEUE}.`);
+        }
     }
 }
-function assertNonNegativeFinite(field, value) {
+export function assertRateLimitOptions(opts) {
+    if (!Number.isInteger(opts.maxCalls) || opts.maxCalls < 1) {
+        throw new RangeError(`Actly: rateLimit.maxCalls must be a positive integer, got ${opts.maxCalls}`);
+    }
+    if (opts.maxCalls > LIMITS.MAX_RATE_LIMIT_CALLS) {
+        throw new RangeError(`Actly: rateLimit.maxCalls ${opts.maxCalls} exceeds limit ${LIMITS.MAX_RATE_LIMIT_CALLS}.`);
+    }
+    if (typeof opts.windowMs !== 'number' || !Number.isFinite(opts.windowMs) || opts.windowMs <= 0) {
+        throw new RangeError(`Actly: rateLimit.windowMs must be a positive finite number, got ${opts.windowMs}`);
+    }
+}
+export function assertHedgeOptions(opts) {
+    if (typeof opts.delayMs !== 'number' || !Number.isFinite(opts.delayMs) || opts.delayMs <= 0) {
+        throw new RangeError(`Actly: hedge.delayMs must be a positive finite number, got ${opts.delayMs}`);
+    }
+    if (opts.delayMs > LIMITS.MAX_HEDGE_DELAY_MS) {
+        throw new RangeError(`Actly: hedge.delayMs ${opts.delayMs} exceeds limit ${LIMITS.MAX_HEDGE_DELAY_MS}.`);
+    }
+    if (opts.placement !== undefined && opts.placement !== 'outside-retry' && opts.placement !== 'inside-retry') {
+        throw new RangeError(`Actly: hedge.placement must be 'outside-retry' or 'inside-retry', got ${JSON.stringify(opts.placement)}`);
+    }
+    if (opts.keepLoser !== undefined && typeof opts.keepLoser !== 'boolean') {
+        throw new TypeError(`Actly: hedge.keepLoser must be a boolean, got ${typeof opts.keepLoser}`);
+    }
+}
+function assertNonNegativeFinite(field, value, max) {
     if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
         throw new RangeError(`Actly: ${field} must be a non-negative finite number, got ${value}`);
     }
+    if (value > max) {
+        throw new RangeError(`Actly: ${field} ${value} exceeds limit ${max}.`);
+    }
 }
-//# sourceMappingURL=validate.js.map
+const BACKOFF_MODES = new Set(['none', 'linear', 'exponential']);
+const JITTER_MODES = new Set(['none', 'full', 'equal', 'decorrelated']);