@orkestrel/timeout 0.0.4 → 0.0.6

package/README.md

@@ -39,15 +39,24 @@ timeout.clear() // work finished first — cancel the deadline
 ```
 
 `createTimeout(options)` (or `new Timeout(options)`) returns a
-`TimeoutInterface`. `options.ms` is the deadline in milliseconds (a
-non-negative finite number — the host `setTimeout` clamps a negative, `NaN`,
-or over-2^31-1 value rather than throwing); an optional `options.id` labels the
-handle for tracing (defaults to a random UUID); an optional `options.signal`
-links a parent `AbortSignal` whose abort clears the timeout while a timer is
-armed. `start()` arms the deadline: on expiry `expired` flips `true` and
-`signal` fires. `clear()` cancels a pending expiry without firing `signal` and
-resets `expired` back to `false`. The handle is a pure functional primitive —
-no `Emitter`, no events.
+`TimeoutInterface`. `options.ms` must be an integer from `0` through
+`MAX_TIMEOUT_MS` (`2_147_483_647`), inclusive; invalid values throw a coded
+`ContractError` before any timer lifecycle begins. Zero is intentionally a
+next-turn deadline. An optional string `options.id` labels the handle for
+tracing and defaults to a random UUID. An optional `options.signal` must be a
+genuine native `AbortSignal`; its abort clears an armed timeout without
+expiring it, aborting the timeout's own signal, or forwarding its reason.
+`start()` arms or replaces the deadline. On expiry `expired` flips `true` and
+the native `signal` aborts once. `clear()` cancels without aborting, resets
+`expired`, and remains safe to call while idle. `isTimeoutDuration` and
+`isTimeoutSignal` provide total validators for dynamic inputs.
+
+Malformed or unreadable options throw with contract code `bound`. Invalid
+defined `id`, `ms`, and `signal` values use `literal`, `range`, and `placement`,
+respectively, with safe path, limit, and received-value context. `expired`
+derives directly from the owned signal's `aborted` state.
+`validateTimeoutOptions` exposes the same strict construction boundary as a
+once-read helper that returns a fresh copy without absent optional keys.
 
 ## Guide
 

package/dist/src/core/index.cjs

@@ -1,33 +1,169 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_contract = require("@orkestrel/contract");
+//#region src/core/constants.ts
+/**
+* Largest timeout duration accepted by the package, in milliseconds.
+*
+* @example
+* ```ts
+* createTimeout({ ms: MAX_TIMEOUT_MS })
+* ```
+*/
+var MAX_TIMEOUT_MS = 2147483647;
+//#endregion
+//#region src/core/validators.ts
+/**
+* Determine whether a value is an accepted timeout duration.
+*
+* @param value - Unknown duration candidate
+* @returns `true` only for an integer in the inclusive timeout range
+*
+* @example
+* ```ts
+* isTimeoutDuration(0) // true
+* isTimeoutDuration(1.5) // false
+* ```
+*/
+function isTimeoutDuration(value) {
+	return (0, _orkestrel_contract.isFiniteNumber)(value) && (0, _orkestrel_contract.isInteger)(value) && value >= 0 && value <= 2147483647;
+}
+/**
+* Determine whether a value is a genuine native `AbortSignal`.
+*
+* @remarks
+* The intrinsic `aborted` getter performs the native brand check. The boundary
+* contains revoked proxies and hostile receivers, returning `false` instead of
+* allowing their errors to escape.
+*
+* @param value - Unknown signal candidate
+* @returns `true` only when the native `AbortSignal` getter accepts the value
+*
+* @example
+* ```ts
+* isTimeoutSignal(new AbortController().signal) // true
+* isTimeoutSignal({ aborted: false }) // false
+* ```
+*/
+function isTimeoutSignal(value) {
+	try {
+		const descriptor = Object.getOwnPropertyDescriptor(AbortSignal.prototype, "aborted");
+		if (descriptor?.get === void 0) return false;
+		return typeof Reflect.apply(descriptor.get, value, []) === "boolean";
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/core/helpers.ts
+/**
+* Validate and normalize timeout construction options.
+*
+* @remarks
+* Each property is read exactly once before validation. The returned object is
+* a fresh copy and omits absent optional properties. No timer, controller, or
+* listener lifecycle begins at this boundary.
+*
+* @param options - Potentially untrusted timeout options
+* @returns A fresh validated `TimeoutOptions` object
+* @throws {@link import('@orkestrel/contract').ContractError} When the input
+*   does not satisfy `TimeoutOptions`
+*
+* @example
+* ```ts
+* const options = validateTimeoutOptions({ ms: 5_000 })
+* ```
+*/
+function validateTimeoutOptions(options) {
+	if (!(0, _orkestrel_contract.isRecord)(options)) throw new _orkestrel_contract.ContractError("Timeout: options must be a plain record", {
+		code: "bound",
+		context: {
+			path: ["options"],
+			limit: "plain record",
+			received: (0, _orkestrel_contract.preview)(options)
+		}
+	});
+	let id;
+	let ms;
+	let signal;
+	try {
+		id = options.id;
+		ms = options.ms;
+		signal = options.signal;
+	} catch (cause) {
+		throw new _orkestrel_contract.ContractError("Timeout: options could not be read", {
+			code: "bound",
+			context: {
+				path: ["options"],
+				limit: "readable plain record",
+				received: (0, _orkestrel_contract.preview)(options)
+			},
+			cause
+		});
+	}
+	if (id !== void 0 && !(0, _orkestrel_contract.isString)(id)) throw new _orkestrel_contract.ContractError("Timeout: id must be a string when defined", {
+		code: "literal",
+		context: {
+			path: ["options", "id"],
+			limit: "string or undefined",
+			received: (0, _orkestrel_contract.preview)(id)
+		}
+	});
+	if (!isTimeoutDuration(ms)) throw new _orkestrel_contract.ContractError("Timeout: ms must be an integer in the supported range", {
+		code: "range",
+		context: {
+			path: ["options", "ms"],
+			limit: `integer in [0, ${MAX_TIMEOUT_MS}]`,
+			received: (0, _orkestrel_contract.preview)(ms)
+		}
+	});
+	if (signal !== void 0 && !isTimeoutSignal(signal)) throw new _orkestrel_contract.ContractError("Timeout: signal must be a native AbortSignal when defined", {
+		code: "placement",
+		context: {
+			path: ["options", "signal"],
+			limit: "native AbortSignal or undefined",
+			received: (0, _orkestrel_contract.preview)(signal)
+		}
+	});
+	if (id !== void 0 && signal !== void 0) return {
+		id,
+		ms,
+		signal
+	};
+	if (id !== void 0) return {
+		id,
+		ms
+	};
+	if (signal !== void 0) return {
+		ms,
+		signal
+	};
+	return { ms };
+}
+//#endregion
 //#region src/core/Timeout.ts
 /**
-* A deadline handle — a controllable `setTimeout` wrapper that exposes an
-* `AbortSignal` which fires when the timeout expires, for racing against work.
+* A controllable deadline whose native `AbortSignal` aborts when it expires.
 *
 * @remarks
-* - **Deadline signal.** `start()` arms a `setTimeout` for `ms`; on expiry it
-*   flips `expired` and aborts the controller, firing `signal`. Race `signal`
-*   against work to bound how long it may run.
-* - **Controllable.** `clear()` cancels a pending expiry WITHOUT firing `signal`,
-*   and resets `expired` back to `false` (the §10 reset) — a cleared timeout
-*   reports `expired === false` and a non-aborted `signal`.
-* - **Reusable.** Re-`start()` after an expiry swaps in a fresh controller and
-*   resets `expired`, so `signal` / `expired` reflect the new run — the handle is
-*   reusable across deadlines without re-construction.
-* - **Parent linking.** A parent `signal` does NOT expire this timeout — it
-*   CLEARS it: the parent listener is attached only while a timer is armed (added
-*   on `start()`, removed on expiry or `clear()`), so a parent abort during the
-*   timing window cancels the pending expiry and a later `start()` is a no-op once
-*   the parent has aborted. An idle handle holds no parent listener.
-* - **Event-free.** A pure functional primitive — no Emitter, no events.
+* `start()` arms or replaces the current deadline. Expiry sets `expired` and
+* aborts the current signal once. `clear()` cancels without aborting and resets
+* `expired`. Starting or clearing after expiry installs a fresh signal. A parent
+* abort deliberately clears the timeout without aborting its signal; once the
+* parent has aborted, later starts are inert.
+*
+* Construction validates the complete JavaScript boundary before creating an
+* `AbortController`. A malformed or unreadable options record throws a
+* `bound`-coded {@link import('@orkestrel/contract').ContractError}; an invalid
+* `id`, `ms`, or `signal` uses `literal`, `range`, or `placement`, respectively.
 *
 * @example
 * ```ts
+* import { Timeout } from '@orkestrel/timeout'
+*
 * const timeout = new Timeout({ ms: 5_000 })
 * timeout.start()
 * timeout.signal.addEventListener('abort', () => giveUp(), { once: true })
-* timeout.clear() // cancels the deadline before it fires
+* timeout.clear()
 * ```
 */
 var Timeout = class {
@@ -35,21 +171,22 @@ var Timeout = class {
 	ms;
 	#parent;
 	#listener;
-	#controller = new AbortController();
+	#controller;
 	#handle;
 	#linked = false;
-	#expired = false;
 	constructor(options) {
-		this.id = (0, _orkestrel_contract.isString)(options.id) ? options.id : crypto.randomUUID();
-		this.ms = options.ms;
-		this.#parent = options.signal;
+		const input = validateTimeoutOptions(options);
+		this.id = input.id === void 0 ? crypto.randomUUID() : input.id;
+		this.ms = input.ms;
+		this.#parent = input.signal;
+		this.#controller = new AbortController();
 		this.#listener = this.clear.bind(this);
 	}
 	get signal() {
 		return this.#controller.signal;
 	}
 	get expired() {
-		return this.#expired;
+		return this.#controller.signal.aborted;
 	}
 	start() {
 		if (this.#parent?.aborted === true) return;
@@ -58,7 +195,6 @@ var Timeout = class {
 			this.#handle = void 0;
 		}
 		this.#detach();
-		this.#expired = false;
 		if (this.#controller.signal.aborted) this.#controller = new AbortController();
 		if (this.#parent !== void 0) {
 			this.#parent.addEventListener("abort", this.#listener, { once: true });
@@ -66,9 +202,8 @@ var Timeout = class {
 		}
 		this.#handle = setTimeout(() => {
 			this.#handle = void 0;
-			this.#expired = true;
-			this.#controller.abort();
 			this.#detach();
+			this.#controller.abort();
 		}, this.ms);
 	}
 	clear() {
@@ -77,7 +212,6 @@ var Timeout = class {
 			this.#handle = void 0;
 		}
 		this.#detach();
-		this.#expired = false;
 		if (this.#controller.signal.aborted) this.#controller = new AbortController();
 	}
 	#detach() {
@@ -90,45 +224,42 @@ var Timeout = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a deadline handle — a controllable `setTimeout` wrapper that exposes an
-* `AbortSignal` which fires when the timeout expires, for racing against work.
+* Create a controllable deadline whose native signal aborts on expiry.
 *
 * @remarks
-* Call `start()` to arm the deadline for `ms` milliseconds; on expiry the handle's
-* `signal` fires and `expired` flips `true`. Call `clear()` to cancel a pending
-* deadline without firing. When `options.signal` is given, a parent abort CLEARS
-* the timeout (it never expires) rather than firing it. Pass `options.id` to label
-* the handle for tracing, or let it default to a random UUID. `ms` must be a
-* non-negative finite number; the host `setTimeout` clamps a negative or `NaN`
-* value to roughly `0` (firing on the next macrotask) rather than throwing.
-*
-* @param options - `ms` (the deadline in milliseconds, a non-negative finite
-*   number), an optional `id` (a trace label; defaults to a random UUID), and an
-*   optional parent `signal` whose abort clears the timeout
-* @returns A working {@link TimeoutInterface}
+* `options.ms` must be an integer from `0` through `2_147_483_647`, inclusive.
+* A parent `options.signal` clears an armed timeout without aborting the
+* timeout's own signal. Omitted `options.id` values generate a random UUID.
+* Malformed or unreadable options use contract code `bound`; invalid `id`,
+* `ms`, and `signal` values use `literal`, `range`, and `placement`.
+*
+* @param options - Validated deadline, optional trace label, and optional native parent signal
+* @returns A reusable timeout handle
+* @throws {@link import('@orkestrel/contract').ContractError} When the
+*   JavaScript input does not satisfy `TimeoutOptions`
 *
 * @example
 * ```ts
-* import { createTimeout } from '@src/core'
+* import { createTimeout } from '@orkestrel/timeout'
 *
 * const timeout = createTimeout({ ms: 5_000 })
 * timeout.start()
-* const result = await Promise.race([
-* 	work(),
-* 	new Promise((_, reject) =>
-* 		timeout.signal.addEventListener('abort', () => reject(new Error('timed out')), {
-* 			once: true,
-* 		}),
-* 	),
-* ])
-* timeout.clear() // work finished first — cancel the deadline
+* try {
+* 	await fetch('/work', { signal: timeout.signal })
+* } finally {
+* 	timeout.clear()
+* }
 * ```
 */
 function createTimeout(options) {
 	return new Timeout(options);
 }
 //#endregion
+exports.MAX_TIMEOUT_MS = MAX_TIMEOUT_MS;
 exports.Timeout = Timeout;
 exports.createTimeout = createTimeout;
+exports.isTimeoutDuration = isTimeoutDuration;
+exports.isTimeoutSignal = isTimeoutSignal;
+exports.validateTimeoutOptions = validateTimeoutOptions;
 
 //# sourceMappingURL=index.cjs.map

package/dist/src/core/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["#parent","#listener","#controller","#expired","#handle","#detach","#linked"],"sources":["../../../src/core/Timeout.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { TimeoutInterface, TimeoutOptions } from './types.js'\nimport { isString } from '@orkestrel/contract'\n\n/**\n * A deadline handle — a controllable `setTimeout` wrapper that exposes an\n * `AbortSignal` which fires when the timeout expires, for racing against work.\n *\n * @remarks\n * - **Deadline signal.** `start()` arms a `setTimeout` for `ms`; on expiry it\n *   flips `expired` and aborts the controller, firing `signal`. Race `signal`\n *   against work to bound how long it may run.\n * - **Controllable.** `clear()` cancels a pending expiry WITHOUT firing `signal`,\n *   and resets `expired` back to `false` (the §10 reset) — a cleared timeout\n *   reports `expired === false` and a non-aborted `signal`.\n * - **Reusable.** Re-`start()` after an expiry swaps in a fresh controller and\n *   resets `expired`, so `signal` / `expired` reflect the new run — the handle is\n *   reusable across deadlines without re-construction.\n * - **Parent linking.** A parent `signal` does NOT expire this timeout — it\n *   CLEARS it: the parent listener is attached only while a timer is armed (added\n *   on `start()`, removed on expiry or `clear()`), so a parent abort during the\n *   timing window cancels the pending expiry and a later `start()` is a no-op once\n *   the parent has aborted. An idle handle holds no parent listener.\n * - **Event-free.** A pure functional primitive — no Emitter, no events.\n *\n * @example\n * ```ts\n * const timeout = new Timeout({ ms: 5_000 })\n * timeout.start()\n * timeout.signal.addEventListener('abort', () => giveUp(), { once: true })\n * timeout.clear() // cancels the deadline before it fires\n * ```\n */\nexport class Timeout implements TimeoutInterface {\n\treadonly id: string\n\treadonly ms: number\n\treadonly #parent: AbortSignal | undefined\n\treadonly #listener: () => void\n\t#controller = new AbortController()\n\t#handle: ReturnType<typeof setTimeout> | undefined\n\t#linked = false\n\t#expired = false\n\n\tconstructor(options: TimeoutOptions) {\n\t\t// Construction is the defensive JS boundary — validate here so the\n\t\t// start()/clear() hot paths stay dependency-free.\n\t\tthis.id = isString(options.id) ? options.id : crypto.randomUUID()\n\t\tthis.ms = options.ms\n\t\tthis.#parent = options.signal\n\t\tthis.#listener = this.clear.bind(this)\n\t}\n\n\tget signal(): AbortSignal {\n\t\treturn this.#controller.signal\n\t}\n\n\tget expired(): boolean {\n\t\treturn this.#expired\n\t}\n\n\tstart(): void {\n\t\t// Once the parent has aborted, the deadline must never fire.\n\t\tif (this.#parent?.aborted === true) return\n\t\t// Re-arm cleanly: drop any pending timer + parent listener from a prior run.\n\t\tif (this.#handle !== undefined) {\n\t\t\tclearTimeout(this.#handle)\n\t\t\tthis.#handle = undefined\n\t\t}\n\t\tthis.#detach()\n\t\tthis.#expired = false\n\t\t// Swap in a fresh controller only when the current one has already fired, so a\n\t\t// re-armed run gets a clean `signal` while a listener attached before the FIRST\n\t\t// `start()` (on the construction-time signal) survives to fire on expiry.\n\t\tif (this.#controller.signal.aborted) this.#controller = new AbortController()\n\t\t// Link the parent only for the lifetime of this timer — a parent abort CLEARS\n\t\t// the timeout (so it never expires); the listener is removed when the timer settles.\n\t\tif (this.#parent !== undefined) {\n\t\t\tthis.#parent.addEventListener('abort', this.#listener, { once: true })\n\t\t\tthis.#linked = true\n\t\t}\n\t\tthis.#handle = setTimeout(() => {\n\t\t\tthis.#handle = undefined\n\t\t\tthis.#expired = true\n\t\t\tthis.#controller.abort()\n\t\t\t// The timer fired — drop the parent listener so a later parent abort can no\n\t\t\t// longer reach `clear()` and un-expire this legitimate expiry.\n\t\t\tthis.#detach()\n\t\t}, this.ms)\n\t}\n\n\tclear(): void {\n\t\tif (this.#handle !== undefined) {\n\t\t\tclearTimeout(this.#handle)\n\t\t\tthis.#handle = undefined\n\t\t}\n\t\tthis.#detach()\n\t\tthis.#expired = false\n\t\t// If the controller had already fired, swap a fresh one so a cleared timeout\n\t\t// reports `expired === false` AND a non-aborted `signal`, consistently.\n\t\tif (this.#controller.signal.aborted) this.#controller = new AbortController()\n\t}\n\n\t// Remove the parent-abort listener if one is currently attached.\n\t#detach(): void {\n\t\tif (this.#linked) {\n\t\t\tthis.#parent?.removeEventListener('abort', this.#listener)\n\t\t\tthis.#linked = false\n\t\t}\n\t}\n}\n","import type { TimeoutInterface, TimeoutOptions } from './types.js'\nimport { Timeout } from './Timeout.js'\n\n/**\n * Create a deadline handle — a controllable `setTimeout` wrapper that exposes an\n * `AbortSignal` which fires when the timeout expires, for racing against work.\n *\n * @remarks\n * Call `start()` to arm the deadline for `ms` milliseconds; on expiry the handle's\n * `signal` fires and `expired` flips `true`. Call `clear()` to cancel a pending\n * deadline without firing. When `options.signal` is given, a parent abort CLEARS\n * the timeout (it never expires) rather than firing it. Pass `options.id` to label\n * the handle for tracing, or let it default to a random UUID. `ms` must be a\n * non-negative finite number; the host `setTimeout` clamps a negative or `NaN`\n * value to roughly `0` (firing on the next macrotask) rather than throwing.\n *\n * @param options - `ms` (the deadline in milliseconds, a non-negative finite\n *   number), an optional `id` (a trace label; defaults to a random UUID), and an\n *   optional parent `signal` whose abort clears the timeout\n * @returns A working {@link TimeoutInterface}\n *\n * @example\n * ```ts\n * import { createTimeout } from '@src/core'\n *\n * const timeout = createTimeout({ ms: 5_000 })\n * timeout.start()\n * const result = await Promise.race([\n * \twork(),\n * \tnew Promise((_, reject) =>\n * \t\ttimeout.signal.addEventListener('abort', () => reject(new Error('timed out')), {\n * \t\t\tonce: true,\n * \t\t}),\n * \t),\n * ])\n * timeout.clear() // work finished first — cancel the deadline\n * ```\n */\nexport function createTimeout(options: TimeoutOptions): TimeoutInterface {\n\treturn new Timeout(options)\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAa,UAAb,MAAiD;CAChD;CACA;CACA;CACA;CACA,cAAc,IAAI,gBAAgB;CAClC;CACA,UAAU;CACV,WAAW;CAEX,YAAY,SAAyB;EAGpC,KAAK,MAAA,GAAA,oBAAA,SAAA,CAAc,QAAQ,EAAE,IAAI,QAAQ,KAAK,OAAO,WAAW;EAChE,KAAK,KAAK,QAAQ;EAClB,KAAKA,UAAU,QAAQ;EACvB,KAAKC,YAAY,KAAK,MAAM,KAAK,IAAI;CACtC;CAEA,IAAI,SAAsB;EACzB,OAAO,KAAKC,YAAY;CACzB;CAEA,IAAI,UAAmB;EACtB,OAAO,KAAKC;CACb;CAEA,QAAc;EAEb,IAAI,KAAKH,SAAS,YAAY,MAAM;EAEpC,IAAI,KAAKI,YAAY,KAAA,GAAW;GAC/B,aAAa,KAAKA,OAAO;GACzB,KAAKA,UAAU,KAAA;EAChB;EACA,KAAKC,QAAQ;EACb,KAAKF,WAAW;EAIhB,IAAI,KAAKD,YAAY,OAAO,SAAS,KAAKA,cAAc,IAAI,gBAAgB;EAG5E,IAAI,KAAKF,YAAY,KAAA,GAAW;GAC/B,KAAKA,QAAQ,iBAAiB,SAAS,KAAKC,WAAW,EAAE,MAAM,KAAK,CAAC;GACrE,KAAKK,UAAU;EAChB;EACA,KAAKF,UAAU,iBAAiB;GAC/B,KAAKA,UAAU,KAAA;GACf,KAAKD,WAAW;GAChB,KAAKD,YAAY,MAAM;GAGvB,KAAKG,QAAQ;EACd,GAAG,KAAK,EAAE;CACX;CAEA,QAAc;EACb,IAAI,KAAKD,YAAY,KAAA,GAAW;GAC/B,aAAa,KAAKA,OAAO;GACzB,KAAKA,UAAU,KAAA;EAChB;EACA,KAAKC,QAAQ;EACb,KAAKF,WAAW;EAGhB,IAAI,KAAKD,YAAY,OAAO,SAAS,KAAKA,cAAc,IAAI,gBAAgB;CAC7E;CAGA,UAAgB;EACf,IAAI,KAAKI,SAAS;GACjB,KAAKN,SAAS,oBAAoB,SAAS,KAAKC,SAAS;GACzD,KAAKK,UAAU;EAChB;CACD;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACtEA,SAAgB,cAAc,SAA2C;CACxE,OAAO,IAAI,QAAQ,OAAO;AAC3B"}
+{"version":3,"file":"index.cjs","names":["#parent","#listener","#controller","#handle","#detach","#linked"],"sources":["../../../src/core/constants.ts","../../../src/core/validators.ts","../../../src/core/helpers.ts","../../../src/core/Timeout.ts","../../../src/core/factories.ts"],"sourcesContent":["/**\n * Largest timeout duration accepted by the package, in milliseconds.\n *\n * @example\n * ```ts\n * createTimeout({ ms: MAX_TIMEOUT_MS })\n * ```\n */\nexport const MAX_TIMEOUT_MS = 2_147_483_647\n","import { isFiniteNumber, isInteger } from '@orkestrel/contract'\nimport { MAX_TIMEOUT_MS } from './constants.js'\n\n/**\n * Determine whether a value is an accepted timeout duration.\n *\n * @param value - Unknown duration candidate\n * @returns `true` only for an integer in the inclusive timeout range\n *\n * @example\n * ```ts\n * isTimeoutDuration(0) // true\n * isTimeoutDuration(1.5) // false\n * ```\n */\nexport function isTimeoutDuration(value: unknown): value is number {\n\treturn isFiniteNumber(value) && isInteger(value) && value >= 0 && value <= MAX_TIMEOUT_MS\n}\n\n/**\n * Determine whether a value is a genuine native `AbortSignal`.\n *\n * @remarks\n * The intrinsic `aborted` getter performs the native brand check. The boundary\n * contains revoked proxies and hostile receivers, returning `false` instead of\n * allowing their errors to escape.\n *\n * @param value - Unknown signal candidate\n * @returns `true` only when the native `AbortSignal` getter accepts the value\n *\n * @example\n * ```ts\n * isTimeoutSignal(new AbortController().signal) // true\n * isTimeoutSignal({ aborted: false }) // false\n * ```\n */\nexport function isTimeoutSignal(value: unknown): value is AbortSignal {\n\ttry {\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(AbortSignal.prototype, 'aborted')\n\t\tif (descriptor?.get === undefined) return false\n\t\treturn typeof Reflect.apply(descriptor.get, value, []) === 'boolean'\n\t} catch {\n\t\treturn false\n\t}\n}\n","import type { TimeoutOptions } from './types.js'\nimport { ContractError, isRecord, isString, preview } from '@orkestrel/contract'\nimport { MAX_TIMEOUT_MS } from './constants.js'\nimport { isTimeoutDuration, isTimeoutSignal } from './validators.js'\n\n/**\n * Validate and normalize timeout construction options.\n *\n * @remarks\n * Each property is read exactly once before validation. The returned object is\n * a fresh copy and omits absent optional properties. No timer, controller, or\n * listener lifecycle begins at this boundary.\n *\n * @param options - Potentially untrusted timeout options\n * @returns A fresh validated `TimeoutOptions` object\n * @throws {@link import('@orkestrel/contract').ContractError} When the input\n *   does not satisfy `TimeoutOptions`\n *\n * @example\n * ```ts\n * const options = validateTimeoutOptions({ ms: 5_000 })\n * ```\n */\nexport function validateTimeoutOptions(options: TimeoutOptions): TimeoutOptions {\n\tif (!isRecord(options)) {\n\t\tthrow new ContractError('Timeout: options must be a plain record', {\n\t\t\tcode: 'bound',\n\t\t\tcontext: {\n\t\t\t\tpath: ['options'],\n\t\t\t\tlimit: 'plain record',\n\t\t\t\treceived: preview(options),\n\t\t\t},\n\t\t})\n\t}\n\n\tlet id: TimeoutOptions['id']\n\tlet ms: TimeoutOptions['ms']\n\tlet signal: TimeoutOptions['signal']\n\ttry {\n\t\tid = options.id\n\t\tms = options.ms\n\t\tsignal = options.signal\n\t} catch (cause) {\n\t\tthrow new ContractError('Timeout: options could not be read', {\n\t\t\tcode: 'bound',\n\t\t\tcontext: {\n\t\t\t\tpath: ['options'],\n\t\t\t\tlimit: 'readable plain record',\n\t\t\t\treceived: preview(options),\n\t\t\t},\n\t\t\tcause,\n\t\t})\n\t}\n\n\tif (id !== undefined && !isString(id)) {\n\t\tthrow new ContractError('Timeout: id must be a string when defined', {\n\t\t\tcode: 'literal',\n\t\t\tcontext: {\n\t\t\t\tpath: ['options', 'id'],\n\t\t\t\tlimit: 'string or undefined',\n\t\t\t\treceived: preview(id),\n\t\t\t},\n\t\t})\n\t}\n\tif (!isTimeoutDuration(ms)) {\n\t\tthrow new ContractError('Timeout: ms must be an integer in the supported range', {\n\t\t\tcode: 'range',\n\t\t\tcontext: {\n\t\t\t\tpath: ['options', 'ms'],\n\t\t\t\tlimit: `integer in [0, ${MAX_TIMEOUT_MS}]`,\n\t\t\t\treceived: preview(ms),\n\t\t\t},\n\t\t})\n\t}\n\tif (signal !== undefined && !isTimeoutSignal(signal)) {\n\t\tthrow new ContractError('Timeout: signal must be a native AbortSignal when defined', {\n\t\t\tcode: 'placement',\n\t\t\tcontext: {\n\t\t\t\tpath: ['options', 'signal'],\n\t\t\t\tlimit: 'native AbortSignal or undefined',\n\t\t\t\treceived: preview(signal),\n\t\t\t},\n\t\t})\n\t}\n\n\tif (id !== undefined && signal !== undefined) return { id, ms, signal }\n\tif (id !== undefined) return { id, ms }\n\tif (signal !== undefined) return { ms, signal }\n\treturn { ms }\n}\n","import type { TimeoutInterface, TimeoutOptions } from './types.js'\nimport { validateTimeoutOptions } from './helpers.js'\n\n/**\n * A controllable deadline whose native `AbortSignal` aborts when it expires.\n *\n * @remarks\n * `start()` arms or replaces the current deadline. Expiry sets `expired` and\n * aborts the current signal once. `clear()` cancels without aborting and resets\n * `expired`. Starting or clearing after expiry installs a fresh signal. A parent\n * abort deliberately clears the timeout without aborting its signal; once the\n * parent has aborted, later starts are inert.\n *\n * Construction validates the complete JavaScript boundary before creating an\n * `AbortController`. A malformed or unreadable options record throws a\n * `bound`-coded {@link import('@orkestrel/contract').ContractError}; an invalid\n * `id`, `ms`, or `signal` uses `literal`, `range`, or `placement`, respectively.\n *\n * @example\n * ```ts\n * import { Timeout } from '@orkestrel/timeout'\n *\n * const timeout = new Timeout({ ms: 5_000 })\n * timeout.start()\n * timeout.signal.addEventListener('abort', () => giveUp(), { once: true })\n * timeout.clear()\n * ```\n */\nexport class Timeout implements TimeoutInterface {\n\treadonly id: string\n\treadonly ms: number\n\treadonly #parent: AbortSignal | undefined\n\treadonly #listener: () => void\n\t#controller: AbortController\n\t#handle: ReturnType<typeof setTimeout> | undefined\n\t#linked = false\n\n\tconstructor(options: TimeoutOptions) {\n\t\tconst input = validateTimeoutOptions(options)\n\t\tthis.id = input.id === undefined ? crypto.randomUUID() : input.id\n\t\tthis.ms = input.ms\n\t\tthis.#parent = input.signal\n\t\tthis.#controller = new AbortController()\n\t\tthis.#listener = this.clear.bind(this)\n\t}\n\n\tget signal(): AbortSignal {\n\t\treturn this.#controller.signal\n\t}\n\n\tget expired(): boolean {\n\t\treturn this.#controller.signal.aborted\n\t}\n\n\tstart(): void {\n\t\tif (this.#parent?.aborted === true) return\n\t\tif (this.#handle !== undefined) {\n\t\t\tclearTimeout(this.#handle)\n\t\t\tthis.#handle = undefined\n\t\t}\n\t\tthis.#detach()\n\t\tif (this.#controller.signal.aborted) this.#controller = new AbortController()\n\t\tif (this.#parent !== undefined) {\n\t\t\tthis.#parent.addEventListener('abort', this.#listener, { once: true })\n\t\t\tthis.#linked = true\n\t\t}\n\t\tthis.#handle = setTimeout(() => {\n\t\t\tthis.#handle = undefined\n\t\t\tthis.#detach()\n\t\t\tthis.#controller.abort()\n\t\t}, this.ms)\n\t}\n\n\tclear(): void {\n\t\tif (this.#handle !== undefined) {\n\t\t\tclearTimeout(this.#handle)\n\t\t\tthis.#handle = undefined\n\t\t}\n\t\tthis.#detach()\n\t\tif (this.#controller.signal.aborted) this.#controller = new AbortController()\n\t}\n\n\t#detach(): void {\n\t\tif (this.#linked) {\n\t\t\tthis.#parent?.removeEventListener('abort', this.#listener)\n\t\t\tthis.#linked = false\n\t\t}\n\t}\n}\n","import type { TimeoutInterface, TimeoutOptions } from './types.js'\nimport { Timeout } from './Timeout.js'\n\n/**\n * Create a controllable deadline whose native signal aborts on expiry.\n *\n * @remarks\n * `options.ms` must be an integer from `0` through `2_147_483_647`, inclusive.\n * A parent `options.signal` clears an armed timeout without aborting the\n * timeout's own signal. Omitted `options.id` values generate a random UUID.\n * Malformed or unreadable options use contract code `bound`; invalid `id`,\n * `ms`, and `signal` values use `literal`, `range`, and `placement`.\n *\n * @param options - Validated deadline, optional trace label, and optional native parent signal\n * @returns A reusable timeout handle\n * @throws {@link import('@orkestrel/contract').ContractError} When the\n *   JavaScript input does not satisfy `TimeoutOptions`\n *\n * @example\n * ```ts\n * import { createTimeout } from '@orkestrel/timeout'\n *\n * const timeout = createTimeout({ ms: 5_000 })\n * timeout.start()\n * try {\n * \tawait fetch('/work', { signal: timeout.signal })\n * } finally {\n * \ttimeout.clear()\n * }\n * ```\n */\nexport function createTimeout(options: TimeoutOptions): TimeoutInterface {\n\treturn new Timeout(options)\n}\n"],"mappings":"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"}