@orkestrel/timeout 0.0.8 → 0.0.10

package/README.md

@@ -1,13 +1,14 @@
 # @orkestrel/timeout
 
-A typed, **controllable** `setTimeout` wrapper — a deadline handle that
-exposes an `AbortSignal` which fires on expiry, for racing against work.
-Deliberately small: `start()` arms the deadline, `clear()` cancels it without
-firing, and re-`start()`ing a handle after expiry reuses it for a fresh
-deadline without re-construction. An optional parent `signal` links in without
-inheriting `AbortSignal.any` semantics — a parent abort during the timing
-window _clears_ the timeout (it never expires) rather than firing it. Part of
-the `@orkestrel` line.
+> The time-bound half of the substrate's time-and-cancellation pair: a
+> controllable `setTimeout` wrapper carrying a trace `id` and a deadline `ms`,
+> whose native `AbortSignal` aborts on expiry.
+
+Create a handle with the `createTimeout` function, call `start()` to arm the
+deadline, and hand its signal to the fetch, stream, or queue task the deadline
+bounds; call `clear()` when that work finishes first. Pass a parent signal
+where an outer cancellation must retire the deadline rather than let it expire;
+that link carries no `AbortSignal.any` semantics. Part of the `@orkestrel` line.
 
 ## Install
 
@@ -17,8 +18,8 @@ npm install @orkestrel/timeout
 
 ## Requirements
 
-- Node.js >= 24
-- ESM-only (no CommonJS build)
+- Node.js >= 22.12.0, matching the `engines` field in `package.json`
+- ESM (`import`) and CommonJS (`require`) through the `exports` field
 
 ## Usage
 
@@ -61,7 +62,7 @@ once-read helper that returns a fresh copy without absent optional keys.
 ## Guide
 
 For the full surface — the deadline lifecycle, parent-signal linking, and
-reuse semantics — see [`guides/src/timeout.md`](guides/src/timeout.md).
+reuse semantics — see [`guides/timeout.md`](guides/timeout.md).
 
 ## Package
 

package/dist/src/core/index.cjs

@@ -2,7 +2,7 @@ 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.
+* Names the largest timeout duration the package accepts, `2_147_483_647` milliseconds.
 *
 * @example
 * ```ts
@@ -13,10 +13,11 @@ var MAX_TIMEOUT_MS = 2147483647;
 //#endregion
 //#region src/core/validators.ts
 /**
-* Determine whether a value is an accepted timeout duration.
+* Determines whether a value is an integer in the inclusive range from `0` through
+* `MAX_TIMEOUT_MS`, staying total for every input.
 *
 * @param value - Unknown duration candidate
-* @returns `true` only for an integer in the inclusive timeout range
+* @returns True if the value is an integer in the inclusive timeout range; false otherwise
 *
 * @example
 * ```ts
@@ -25,18 +26,18 @@ var MAX_TIMEOUT_MS = 2147483647;
 * ```
 */
 function isTimeoutDuration(value) {
-	return (0, _orkestrel_contract.isFiniteNumber)(value) && (0, _orkestrel_contract.isInteger)(value) && value >= 0 && value <= 2147483647;
+	return (0, _orkestrel_contract.isInteger)(value) && value >= 0 && value <= 2147483647;
 }
 /**
-* Determine whether a value is a genuine native `AbortSignal`.
+* Determines whether a value is a genuine native `AbortSignal`, staying total for a
+* structural spoof and for a hostile or revoked proxy.
 *
 * @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.
+* The intrinsic `aborted` getter performs the native brand check, and the boundary
+* returns `false` rather than letting a receiver's error escape.
 *
 * @param value - Unknown signal candidate
-* @returns `true` only when the native `AbortSignal` getter accepts the value
+* @returns True if the native `AbortSignal` getter accepts the value; false otherwise
 *
 * @example
 * ```ts
@@ -56,17 +57,17 @@ function isTimeoutSignal(value) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Validate and normalize timeout construction options.
+* Validates once-read timeout construction options and returns a fresh normalized copy
+* omitting absent optional keys.
 *
 * @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
+* Each property is read before any validation runs, and 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`
+* @throws {@link import('@orkestrel/contract').ContractError} Thrown when the
+*   input does not satisfy `TimeoutOptions`
 *
 * @example
 * ```ts
@@ -142,7 +143,8 @@ function validateTimeoutOptions(options) {
 //#endregion
 //#region src/core/Timeout.ts
 /**
-* A controllable deadline whose native `AbortSignal` aborts when it expires.
+* Implements `TimeoutInterface` exactly, as a controllable `setTimeout` wrapper over one
+* owned `AbortController` whose signal aborts when the deadline expires.
 *
 * @remarks
 * `start()` arms or replaces the current deadline. Expiry sets `expired` and
@@ -167,21 +169,26 @@ function validateTimeoutOptions(options) {
 * ```
 */
 var Timeout = class {
-	id;
-	ms;
+	#id;
+	#ms;
 	#parent;
 	#listener;
 	#controller;
 	#handle;
-	#linked = false;
 	constructor(options) {
 		const input = validateTimeoutOptions(options);
-		this.id = input.id === void 0 ? crypto.randomUUID() : input.id;
-		this.ms = input.ms;
+		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 id() {
+		return this.#id;
+	}
+	get ms() {
+		return this.#ms;
+	}
 	get signal() {
 		return this.#controller.signal;
 	}
@@ -196,15 +203,12 @@ var Timeout = class {
 		}
 		this.#detach();
 		if (this.#controller.signal.aborted) this.#controller = new AbortController();
-		if (this.#parent !== void 0) {
-			this.#parent.addEventListener("abort", this.#listener, { once: true });
-			this.#linked = true;
-		}
+		if (this.#parent !== void 0) this.#parent.addEventListener("abort", this.#listener, { once: true });
 		this.#handle = setTimeout(() => {
 			this.#handle = void 0;
 			this.#detach();
 			this.#controller.abort();
-		}, this.ms);
+		}, this.#ms);
 	}
 	clear() {
 		if (this.#handle !== void 0) {
@@ -215,39 +219,43 @@ var Timeout = class {
 		if (this.#controller.signal.aborted) this.#controller = new AbortController();
 	}
 	#detach() {
-		if (this.#linked) {
-			this.#parent?.removeEventListener("abort", this.#listener);
-			this.#linked = false;
-		}
+		this.#parent?.removeEventListener("abort", this.#listener);
 	}
 };
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a controllable deadline whose native signal aborts on expiry.
+* Creates a deadline handle from validated `TimeoutOptions` and returns it as a
+* `TimeoutInterface`.
 *
 * @remarks
 * `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`.
+* timeout's own signal. `start()` returns without arming when the parent
+* `signal` supplied at construction has already aborted, so a handle whose
+* parent aborted never expires again and its `signal` never fires. 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
+* @throws {@link import('@orkestrel/contract').ContractError} Thrown when the
 *   JavaScript input does not satisfy `TimeoutOptions`
 *
-* @example
+* @example Race work against a deadline
 * ```ts
 * import { createTimeout } from '@orkestrel/timeout'
 *
-* const timeout = createTimeout({ ms: 5_000 })
-* timeout.start()
-* try {
-* 	await fetch('/work', { signal: timeout.signal })
-* } finally {
-* 	timeout.clear()
+* async function fetchWithDeadline(url: string, ms: number): Promise<Response> {
+* 	const timeout = createTimeout({ ms })
+* 	timeout.start()
+*
+* 	try {
+* 		return await fetch(url, { signal: timeout.signal })
+* 	} finally {
+* 		timeout.clear() // cancels the still-armed deadline when the fetch won the race
+* 	}
 * }
 * ```
 */

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

@@ -1 +1 @@
-{"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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"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/validators.ts","../../../src/core/helpers.ts","../../../src/core/Timeout.ts","../../../src/core/factories.ts"],"sourcesContent":["/**\n * Names the largest timeout duration the package accepts, `2_147_483_647` 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 { isInteger } from '@orkestrel/contract'\nimport { MAX_TIMEOUT_MS } from './constants.js'\n\n/**\n * Determines whether a value is an integer in the inclusive range from `0` through\n * `MAX_TIMEOUT_MS`, staying total for every input.\n *\n * @param value - Unknown duration candidate\n * @returns True if the value is an integer in the inclusive timeout range; false otherwise\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 isInteger(value) && value >= 0 && value <= MAX_TIMEOUT_MS\n}\n\n/**\n * Determines whether a value is a genuine native `AbortSignal`, staying total for a\n * structural spoof and for a hostile or revoked proxy.\n *\n * @remarks\n * The intrinsic `aborted` getter performs the native brand check, and the boundary\n * returns `false` rather than letting a receiver's error escape.\n *\n * @param value - Unknown signal candidate\n * @returns True if the native `AbortSignal` getter accepts the value; false otherwise\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 * Validates once-read timeout construction options and returns a fresh normalized copy\n * omitting absent optional keys.\n *\n * @remarks\n * Each property is read before any validation runs, and 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} Thrown when the\n *   input 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 * Implements `TimeoutInterface` exactly, as a controllable `setTimeout` wrapper over one\n * owned `AbortController` whose signal aborts when the deadline 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\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 id(): string {\n\t\treturn this.#id\n\t}\n\n\tget ms(): number {\n\t\treturn this.#ms\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}\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\tthis.#parent?.removeEventListener('abort', this.#listener)\n\t}\n}\n","import type { TimeoutInterface, TimeoutOptions } from './types.js'\nimport { Timeout } from './Timeout.js'\n\n/**\n * Creates a deadline handle from validated `TimeoutOptions` and returns it as a\n * `TimeoutInterface`.\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. `start()` returns without arming when the parent\n * `signal` supplied at construction has already aborted, so a handle whose\n * parent aborted never expires again and its `signal` never fires. Omitted\n * `options.id` values generate a random UUID. Malformed or unreadable options\n * use contract code `bound`; invalid `id`, `ms`, and `signal` values use\n * `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} Thrown when the\n *   JavaScript input does not satisfy `TimeoutOptions`\n *\n * @example Race work against a deadline\n * ```ts\n * import { createTimeout } from '@orkestrel/timeout'\n *\n * async function fetchWithDeadline(url: string, ms: number): Promise<Response> {\n * \tconst timeout = createTimeout({ ms })\n * \ttimeout.start()\n *\n * \ttry {\n * \t\treturn await fetch(url, { signal: timeout.signal })\n * \t} finally {\n * \t\ttimeout.clear() // cancels the still-armed deadline when the fetch won the race\n * \t}\n * }\n * ```\n */\nexport function createTimeout(options: TimeoutOptions): TimeoutInterface {\n\treturn new Timeout(options)\n}\n"],"mappings":"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"}

package/dist/src/core/index.d.cts

@@ -1,38 +1,46 @@
 /**
- * Create a controllable deadline whose native signal aborts on expiry.
+ * Creates a deadline handle from validated `TimeoutOptions` and returns it as a
+ * `TimeoutInterface`.
  *
  * @remarks
  * `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`.
+ * timeout's own signal. `start()` returns without arming when the parent
+ * `signal` supplied at construction has already aborted, so a handle whose
+ * parent aborted never expires again and its `signal` never fires. 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
+ * @throws {@link import('@orkestrel/contract').ContractError} Thrown when the
      *   JavaScript input does not satisfy `TimeoutOptions`
      *
-     * @example
+     * @example Race work against a deadline
      * ```ts
      * import { createTimeout } from '@orkestrel/timeout'
      *
-     * const timeout = createTimeout({ ms: 5_000 })
-     * timeout.start()
-     * try {
-     * 	await fetch('/work', { signal: timeout.signal })
-     * } finally {
-     * 	timeout.clear()
+     * async function fetchWithDeadline(url: string, ms: number): Promise<Response> {
+     * 	const timeout = createTimeout({ ms })
+     * 	timeout.start()
+     *
+     * 	try {
+     * 		return await fetch(url, { signal: timeout.signal })
+     * 	} finally {
+     * 		timeout.clear() // cancels the still-armed deadline when the fetch won the race
+     * 	}
      * }
      * ```
      */
  export declare function createTimeout(options: TimeoutOptions): TimeoutInterface;
 
  /**
-  * Determine whether a value is an accepted timeout duration.
+  * Determines whether a value is an integer in the inclusive range from `0` through
+  * `MAX_TIMEOUT_MS`, staying total for every input.
   *
   * @param value - Unknown duration candidate
-  * @returns `true` only for an integer in the inclusive timeout range
+  * @returns True if the value is an integer in the inclusive timeout range; false otherwise
   *
   * @example
   * ```ts
@@ -43,15 +51,15 @@
  export declare function isTimeoutDuration(value: unknown): value is number;
 
  /**
-  * Determine whether a value is a genuine native `AbortSignal`.
+  * Determines whether a value is a genuine native `AbortSignal`, staying total for a
+  * structural spoof and for a hostile or revoked proxy.
   *
   * @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.
+  * The intrinsic `aborted` getter performs the native brand check, and the boundary
+  * returns `false` rather than letting a receiver's error escape.
   *
   * @param value - Unknown signal candidate
-  * @returns `true` only when the native `AbortSignal` getter accepts the value
+  * @returns True if the native `AbortSignal` getter accepts the value; false otherwise
   *
   * @example
   * ```ts
@@ -62,7 +70,7 @@
  export declare function isTimeoutSignal(value: unknown): value is AbortSignal;
 
  /**
-  * Largest timeout duration accepted by the package, in milliseconds.
+  * Names the largest timeout duration the package accepts, `2_147_483_647` milliseconds.
   *
   * @example
   * ```ts
@@ -72,7 +80,8 @@
  export declare const MAX_TIMEOUT_MS = 2147483647;
 
  /**
-  * A controllable deadline whose native `AbortSignal` aborts when it expires.
+  * Implements `TimeoutInterface` exactly, as a controllable `setTimeout` wrapper over one
+  * owned `AbortController` whose signal aborts when the deadline expires.
   *
   * @remarks
   * `start()` arms or replaces the current deadline. Expiry sets `expired` and
@@ -98,9 +107,9 @@
   */
  export declare class Timeout implements TimeoutInterface {
      #private;
-     readonly id: string;
-     readonly ms: number;
      constructor(options: TimeoutOptions);
+     get id(): string;
+     get ms(): number;
      get signal(): AbortSignal;
      get expired(): boolean;
      start(): void;
@@ -108,7 +117,7 @@
  }
 
  /**
-  * A controllable deadline exposing a native `AbortSignal` that aborts on expiry.
+  * Represents a controllable deadline exposing a native `AbortSignal` that aborts on expiry.
   *
   * @example
   * ```ts
@@ -118,22 +127,36 @@
   * ```
   */
  export declare interface TimeoutInterface {
-     /** Trace label supplied at construction or generated as a random UUID. */
+     /** Holds the trace label supplied at construction or generated as a random UUID. */
      readonly id: string;
-     /** Validated integer deadline in milliseconds. */
+     /** Holds the validated integer deadline in milliseconds. */
      readonly ms: number;
-     /** Native signal that aborts once when the current deadline expires. */
+     /**
+      * Holds the native signal that aborts once when the current deadline
+      * expires. A `start()` or `clear()` call after an expiry installs a fresh
+      * signal, so a caller holding an earlier reference keeps the aborted one.
+      */
      readonly signal: AbortSignal;
-     /** Whether the owned signal has aborted, derived directly from that signal. */
+     /** Reports whether the owned signal has aborted, derived directly from that signal. */
      readonly expired: boolean;
      /**
-      * Arm or re-arm the deadline.
+      * Arms or re-arms the deadline for `ms`, installing a fresh `signal` when the
+      * current one has already aborted.
+      *
+      * @remarks
+      * Returns without arming when the parent `signal` supplied at construction
+      * has already aborted, so a handle whose parent aborted never expires again
+      * and its `signal` never fires.
       *
       * @returns Nothing
       */
      start(): void;
      /**
-      * Cancel an armed deadline without aborting its signal and reset expiry state.
+      * Cancels an armed deadline without aborting its `signal`, and resets expiry by
+      * installing a fresh signal when the current one has already aborted.
+      *
+      * @remarks
+      * A signal that never fired keeps its identity.
       *
       * @returns Nothing
       */
@@ -141,7 +164,7 @@
  }
 
  /**
-  * Options for constructing a timeout deadline.
+  * Represents the options `createTimeout` and the `Timeout` constructor accept.
   *
   * @remarks
   * `ms` is an integer from `0` through `2_147_483_647`, inclusive. `id`
@@ -155,26 +178,26 @@
   * ```
   */
  export declare interface TimeoutOptions {
-     /** Trace label for the timeout; omission generates a random UUID. */
+     /** Holds the trace label for the timeout; omission generates a random UUID. */
      readonly id?: string;
-     /** Integer deadline in milliseconds, inclusive from `0` through `2_147_483_647`. */
+     /** Holds the integer deadline in milliseconds, inclusive from `0` through `2_147_483_647`. */
      readonly ms: number;
-     /** Native parent signal whose abort clears an armed timeout. */
+     /** Holds the native parent signal whose abort clears an armed timeout. */
      readonly signal?: AbortSignal;
  }
 
  /**
-  * Validate and normalize timeout construction options.
+  * Validates once-read timeout construction options and returns a fresh normalized copy
+  * omitting absent optional keys.
   *
   * @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
+  * Each property is read before any validation runs, and 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`
+  * @throws {@link import('@orkestrel/contract').ContractError} Thrown when the
+      *   input does not satisfy `TimeoutOptions`
       *
       * @example
       * ```ts

package/dist/src/core/index.d.ts

@@ -1,38 +1,46 @@
 /**
- * Create a controllable deadline whose native signal aborts on expiry.
+ * Creates a deadline handle from validated `TimeoutOptions` and returns it as a
+ * `TimeoutInterface`.
  *
  * @remarks
  * `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`.
+ * timeout's own signal. `start()` returns without arming when the parent
+ * `signal` supplied at construction has already aborted, so a handle whose
+ * parent aborted never expires again and its `signal` never fires. 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
+ * @throws {@link import('@orkestrel/contract').ContractError} Thrown when the
      *   JavaScript input does not satisfy `TimeoutOptions`
      *
-     * @example
+     * @example Race work against a deadline
      * ```ts
      * import { createTimeout } from '@orkestrel/timeout'
      *
-     * const timeout = createTimeout({ ms: 5_000 })
-     * timeout.start()
-     * try {
-     * 	await fetch('/work', { signal: timeout.signal })
-     * } finally {
-     * 	timeout.clear()
+     * async function fetchWithDeadline(url: string, ms: number): Promise<Response> {
+     * 	const timeout = createTimeout({ ms })
+     * 	timeout.start()
+     *
+     * 	try {
+     * 		return await fetch(url, { signal: timeout.signal })
+     * 	} finally {
+     * 		timeout.clear() // cancels the still-armed deadline when the fetch won the race
+     * 	}
      * }
      * ```
      */
  export declare function createTimeout(options: TimeoutOptions): TimeoutInterface;
 
  /**
-  * Determine whether a value is an accepted timeout duration.
+  * Determines whether a value is an integer in the inclusive range from `0` through
+  * `MAX_TIMEOUT_MS`, staying total for every input.
   *
   * @param value - Unknown duration candidate
-  * @returns `true` only for an integer in the inclusive timeout range
+  * @returns True if the value is an integer in the inclusive timeout range; false otherwise
   *
   * @example
   * ```ts
@@ -43,15 +51,15 @@
  export declare function isTimeoutDuration(value: unknown): value is number;
 
  /**
-  * Determine whether a value is a genuine native `AbortSignal`.
+  * Determines whether a value is a genuine native `AbortSignal`, staying total for a
+  * structural spoof and for a hostile or revoked proxy.
   *
   * @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.
+  * The intrinsic `aborted` getter performs the native brand check, and the boundary
+  * returns `false` rather than letting a receiver's error escape.
   *
   * @param value - Unknown signal candidate
-  * @returns `true` only when the native `AbortSignal` getter accepts the value
+  * @returns True if the native `AbortSignal` getter accepts the value; false otherwise
   *
   * @example
   * ```ts
@@ -62,7 +70,7 @@
  export declare function isTimeoutSignal(value: unknown): value is AbortSignal;
 
  /**
-  * Largest timeout duration accepted by the package, in milliseconds.
+  * Names the largest timeout duration the package accepts, `2_147_483_647` milliseconds.
   *
   * @example
   * ```ts
@@ -72,7 +80,8 @@
  export declare const MAX_TIMEOUT_MS = 2147483647;
 
  /**
-  * A controllable deadline whose native `AbortSignal` aborts when it expires.
+  * Implements `TimeoutInterface` exactly, as a controllable `setTimeout` wrapper over one
+  * owned `AbortController` whose signal aborts when the deadline expires.
   *
   * @remarks
   * `start()` arms or replaces the current deadline. Expiry sets `expired` and
@@ -98,9 +107,9 @@
   */
  export declare class Timeout implements TimeoutInterface {
      #private;
-     readonly id: string;
-     readonly ms: number;
      constructor(options: TimeoutOptions);
+     get id(): string;
+     get ms(): number;
      get signal(): AbortSignal;
      get expired(): boolean;
      start(): void;
@@ -108,7 +117,7 @@
  }
 
  /**
-  * A controllable deadline exposing a native `AbortSignal` that aborts on expiry.
+  * Represents a controllable deadline exposing a native `AbortSignal` that aborts on expiry.
   *
   * @example
   * ```ts
@@ -118,22 +127,36 @@
   * ```
   */
  export declare interface TimeoutInterface {
-     /** Trace label supplied at construction or generated as a random UUID. */
+     /** Holds the trace label supplied at construction or generated as a random UUID. */
      readonly id: string;
-     /** Validated integer deadline in milliseconds. */
+     /** Holds the validated integer deadline in milliseconds. */
      readonly ms: number;
-     /** Native signal that aborts once when the current deadline expires. */
+     /**
+      * Holds the native signal that aborts once when the current deadline
+      * expires. A `start()` or `clear()` call after an expiry installs a fresh
+      * signal, so a caller holding an earlier reference keeps the aborted one.
+      */
      readonly signal: AbortSignal;
-     /** Whether the owned signal has aborted, derived directly from that signal. */
+     /** Reports whether the owned signal has aborted, derived directly from that signal. */
      readonly expired: boolean;
      /**
-      * Arm or re-arm the deadline.
+      * Arms or re-arms the deadline for `ms`, installing a fresh `signal` when the
+      * current one has already aborted.
+      *
+      * @remarks
+      * Returns without arming when the parent `signal` supplied at construction
+      * has already aborted, so a handle whose parent aborted never expires again
+      * and its `signal` never fires.
       *
       * @returns Nothing
       */
      start(): void;
      /**
-      * Cancel an armed deadline without aborting its signal and reset expiry state.
+      * Cancels an armed deadline without aborting its `signal`, and resets expiry by
+      * installing a fresh signal when the current one has already aborted.
+      *
+      * @remarks
+      * A signal that never fired keeps its identity.
       *
       * @returns Nothing
       */
@@ -141,7 +164,7 @@
  }
 
  /**
-  * Options for constructing a timeout deadline.
+  * Represents the options `createTimeout` and the `Timeout` constructor accept.
   *
   * @remarks
   * `ms` is an integer from `0` through `2_147_483_647`, inclusive. `id`
@@ -155,26 +178,26 @@
   * ```
   */
  export declare interface TimeoutOptions {
-     /** Trace label for the timeout; omission generates a random UUID. */
+     /** Holds the trace label for the timeout; omission generates a random UUID. */
      readonly id?: string;
-     /** Integer deadline in milliseconds, inclusive from `0` through `2_147_483_647`. */
+     /** Holds the integer deadline in milliseconds, inclusive from `0` through `2_147_483_647`. */
      readonly ms: number;
-     /** Native parent signal whose abort clears an armed timeout. */
+     /** Holds the native parent signal whose abort clears an armed timeout. */
      readonly signal?: AbortSignal;
  }
 
  /**
-  * Validate and normalize timeout construction options.
+  * Validates once-read timeout construction options and returns a fresh normalized copy
+  * omitting absent optional keys.
   *
   * @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
+  * Each property is read before any validation runs, and 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`
+  * @throws {@link import('@orkestrel/contract').ContractError} Thrown when the
+      *   input does not satisfy `TimeoutOptions`
       *
       * @example
       * ```ts

package/dist/src/core/index.js

@@ -1,7 +1,7 @@
-import { ContractError, isFiniteNumber, isInteger, isRecord, isString, preview } from "@orkestrel/contract";
+import { ContractError, isInteger, isRecord, isString, preview } from "@orkestrel/contract";
 //#region src/core/constants.ts
 /**
-* Largest timeout duration accepted by the package, in milliseconds.
+* Names the largest timeout duration the package accepts, `2_147_483_647` milliseconds.
 *
 * @example
 * ```ts
@@ -12,10 +12,11 @@ var MAX_TIMEOUT_MS = 2147483647;
 //#endregion
 //#region src/core/validators.ts
 /**
-* Determine whether a value is an accepted timeout duration.
+* Determines whether a value is an integer in the inclusive range from `0` through
+* `MAX_TIMEOUT_MS`, staying total for every input.
 *
 * @param value - Unknown duration candidate
-* @returns `true` only for an integer in the inclusive timeout range
+* @returns True if the value is an integer in the inclusive timeout range; false otherwise
 *
 * @example
 * ```ts
@@ -24,18 +25,18 @@ var MAX_TIMEOUT_MS = 2147483647;
 * ```
 */
 function isTimeoutDuration(value) {
-	return isFiniteNumber(value) && isInteger(value) && value >= 0 && value <= 2147483647;
+	return isInteger(value) && value >= 0 && value <= 2147483647;
 }
 /**
-* Determine whether a value is a genuine native `AbortSignal`.
+* Determines whether a value is a genuine native `AbortSignal`, staying total for a
+* structural spoof and for a hostile or revoked proxy.
 *
 * @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.
+* The intrinsic `aborted` getter performs the native brand check, and the boundary
+* returns `false` rather than letting a receiver's error escape.
 *
 * @param value - Unknown signal candidate
-* @returns `true` only when the native `AbortSignal` getter accepts the value
+* @returns True if the native `AbortSignal` getter accepts the value; false otherwise
 *
 * @example
 * ```ts
@@ -55,17 +56,17 @@ function isTimeoutSignal(value) {
 //#endregion
 //#region src/core/helpers.ts
 /**
-* Validate and normalize timeout construction options.
+* Validates once-read timeout construction options and returns a fresh normalized copy
+* omitting absent optional keys.
 *
 * @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
+* Each property is read before any validation runs, and 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`
+* @throws {@link import('@orkestrel/contract').ContractError} Thrown when the
+*   input does not satisfy `TimeoutOptions`
 *
 * @example
 * ```ts
@@ -141,7 +142,8 @@ function validateTimeoutOptions(options) {
 //#endregion
 //#region src/core/Timeout.ts
 /**
-* A controllable deadline whose native `AbortSignal` aborts when it expires.
+* Implements `TimeoutInterface` exactly, as a controllable `setTimeout` wrapper over one
+* owned `AbortController` whose signal aborts when the deadline expires.
 *
 * @remarks
 * `start()` arms or replaces the current deadline. Expiry sets `expired` and
@@ -166,21 +168,26 @@ function validateTimeoutOptions(options) {
 * ```
 */
 var Timeout = class {
-	id;
-	ms;
+	#id;
+	#ms;
 	#parent;
 	#listener;
 	#controller;
 	#handle;
-	#linked = false;
 	constructor(options) {
 		const input = validateTimeoutOptions(options);
-		this.id = input.id === void 0 ? crypto.randomUUID() : input.id;
-		this.ms = input.ms;
+		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 id() {
+		return this.#id;
+	}
+	get ms() {
+		return this.#ms;
+	}
 	get signal() {
 		return this.#controller.signal;
 	}
@@ -195,15 +202,12 @@ var Timeout = class {
 		}
 		this.#detach();
 		if (this.#controller.signal.aborted) this.#controller = new AbortController();
-		if (this.#parent !== void 0) {
-			this.#parent.addEventListener("abort", this.#listener, { once: true });
-			this.#linked = true;
-		}
+		if (this.#parent !== void 0) this.#parent.addEventListener("abort", this.#listener, { once: true });
 		this.#handle = setTimeout(() => {
 			this.#handle = void 0;
 			this.#detach();
 			this.#controller.abort();
-		}, this.ms);
+		}, this.#ms);
 	}
 	clear() {
 		if (this.#handle !== void 0) {
@@ -214,39 +218,43 @@ var Timeout = class {
 		if (this.#controller.signal.aborted) this.#controller = new AbortController();
 	}
 	#detach() {
-		if (this.#linked) {
-			this.#parent?.removeEventListener("abort", this.#listener);
-			this.#linked = false;
-		}
+		this.#parent?.removeEventListener("abort", this.#listener);
 	}
 };
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a controllable deadline whose native signal aborts on expiry.
+* Creates a deadline handle from validated `TimeoutOptions` and returns it as a
+* `TimeoutInterface`.
 *
 * @remarks
 * `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`.
+* timeout's own signal. `start()` returns without arming when the parent
+* `signal` supplied at construction has already aborted, so a handle whose
+* parent aborted never expires again and its `signal` never fires. 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
+* @throws {@link import('@orkestrel/contract').ContractError} Thrown when the
 *   JavaScript input does not satisfy `TimeoutOptions`
 *
-* @example
+* @example Race work against a deadline
 * ```ts
 * import { createTimeout } from '@orkestrel/timeout'
 *
-* const timeout = createTimeout({ ms: 5_000 })
-* timeout.start()
-* try {
-* 	await fetch('/work', { signal: timeout.signal })
-* } finally {
-* 	timeout.clear()
+* async function fetchWithDeadline(url: string, ms: number): Promise<Response> {
+* 	const timeout = createTimeout({ ms })
+* 	timeout.start()
+*
+* 	try {
+* 		return await fetch(url, { signal: timeout.signal })
+* 	} finally {
+* 		timeout.clear() // cancels the still-armed deadline when the fetch won the race
+* 	}
 * }
 * ```
 */

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","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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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/validators.ts","../../../src/core/helpers.ts","../../../src/core/Timeout.ts","../../../src/core/factories.ts"],"sourcesContent":["/**\n * Names the largest timeout duration the package accepts, `2_147_483_647` 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 { isInteger } from '@orkestrel/contract'\nimport { MAX_TIMEOUT_MS } from './constants.js'\n\n/**\n * Determines whether a value is an integer in the inclusive range from `0` through\n * `MAX_TIMEOUT_MS`, staying total for every input.\n *\n * @param value - Unknown duration candidate\n * @returns True if the value is an integer in the inclusive timeout range; false otherwise\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 isInteger(value) && value >= 0 && value <= MAX_TIMEOUT_MS\n}\n\n/**\n * Determines whether a value is a genuine native `AbortSignal`, staying total for a\n * structural spoof and for a hostile or revoked proxy.\n *\n * @remarks\n * The intrinsic `aborted` getter performs the native brand check, and the boundary\n * returns `false` rather than letting a receiver's error escape.\n *\n * @param value - Unknown signal candidate\n * @returns True if the native `AbortSignal` getter accepts the value; false otherwise\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 * Validates once-read timeout construction options and returns a fresh normalized copy\n * omitting absent optional keys.\n *\n * @remarks\n * Each property is read before any validation runs, and 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} Thrown when the\n *   input 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 * Implements `TimeoutInterface` exactly, as a controllable `setTimeout` wrapper over one\n * owned `AbortController` whose signal aborts when the deadline 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\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 id(): string {\n\t\treturn this.#id\n\t}\n\n\tget ms(): number {\n\t\treturn this.#ms\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}\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\tthis.#parent?.removeEventListener('abort', this.#listener)\n\t}\n}\n","import type { TimeoutInterface, TimeoutOptions } from './types.js'\nimport { Timeout } from './Timeout.js'\n\n/**\n * Creates a deadline handle from validated `TimeoutOptions` and returns it as a\n * `TimeoutInterface`.\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. `start()` returns without arming when the parent\n * `signal` supplied at construction has already aborted, so a handle whose\n * parent aborted never expires again and its `signal` never fires. Omitted\n * `options.id` values generate a random UUID. Malformed or unreadable options\n * use contract code `bound`; invalid `id`, `ms`, and `signal` values use\n * `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} Thrown when the\n *   JavaScript input does not satisfy `TimeoutOptions`\n *\n * @example Race work against a deadline\n * ```ts\n * import { createTimeout } from '@orkestrel/timeout'\n *\n * async function fetchWithDeadline(url: string, ms: number): Promise<Response> {\n * \tconst timeout = createTimeout({ ms })\n * \ttimeout.start()\n *\n * \ttry {\n * \t\treturn await fetch(url, { signal: timeout.signal })\n * \t} finally {\n * \t\ttimeout.clear() // cancels the still-armed deadline when the fetch won the race\n * \t}\n * }\n * ```\n */\nexport function createTimeout(options: TimeoutOptions): TimeoutInterface {\n\treturn new Timeout(options)\n}\n"],"mappings":";;;;;;;;;;AAQA,IAAa,iBAAiB;;;;;;;;;;;;;;;;ACQ9B,SAAgB,kBAAkB,OAAiC;CAClE,OAAO,UAAU,KAAK,KAAK,SAAS,KAAK,SAAA;AAC1C;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,gBAAgB,OAAsC;CACrE,IAAI;EACH,MAAM,aAAa,OAAO,yBAAyB,YAAY,WAAW,SAAS;EACnF,IAAI,YAAY,QAAQ,KAAA,GAAW,OAAO;EAC1C,OAAO,OAAO,QAAQ,MAAM,WAAW,KAAK,OAAO,CAAC,CAAC,MAAM;CAC5D,QAAQ;EACP,OAAO;CACR;AACD;;;;;;;;;;;;;;;;;;;;;ACtBA,SAAgB,uBAAuB,SAAyC;CAC/E,IAAI,CAAC,SAAS,OAAO,GACpB,MAAM,IAAI,cAAc,2CAA2C;EAClE,MAAM;EACN,SAAS;GACR,MAAM,CAAC,SAAS;GAChB,OAAO;GACP,UAAU,QAAQ,OAAO;EAC1B;CACD,CAAC;CAGF,IAAI;CACJ,IAAI;CACJ,IAAI;CACJ,IAAI;EACH,KAAK,QAAQ;EACb,KAAK,QAAQ;EACb,SAAS,QAAQ;CAClB,SAAS,OAAO;EACf,MAAM,IAAI,cAAc,sCAAsC;GAC7D,MAAM;GACN,SAAS;IACR,MAAM,CAAC,SAAS;IAChB,OAAO;IACP,UAAU,QAAQ,OAAO;GAC1B;GACA;EACD,CAAC;CACF;CAEA,IAAI,OAAO,KAAA,KAAa,CAAC,SAAS,EAAE,GACnC,MAAM,IAAI,cAAc,6CAA6C;EACpE,MAAM;EACN,SAAS;GACR,MAAM,CAAC,WAAW,IAAI;GACtB,OAAO;GACP,UAAU,QAAQ,EAAE;EACrB;CACD,CAAC;CAEF,IAAI,CAAC,kBAAkB,EAAE,GACxB,MAAM,IAAI,cAAc,yDAAyD;EAChF,MAAM;EACN,SAAS;GACR,MAAM,CAAC,WAAW,IAAI;GACtB,OAAO,kBAAkB,eAAe;GACxC,UAAU,QAAQ,EAAE;EACrB;CACD,CAAC;CAEF,IAAI,WAAW,KAAA,KAAa,CAAC,gBAAgB,MAAM,GAClD,MAAM,IAAI,cAAc,6DAA6D;EACpF,MAAM;EACN,SAAS;GACR,MAAM,CAAC,WAAW,QAAQ;GAC1B,OAAO;GACP,UAAU,QAAQ,MAAM;EACzB;CACD,CAAC;CAGF,IAAI,OAAO,KAAA,KAAa,WAAW,KAAA,GAAW,OAAO;EAAE;EAAI;EAAI;CAAO;CACtE,IAAI,OAAO,KAAA,GAAW,OAAO;EAAE;EAAI;CAAG;CACtC,IAAI,WAAW,KAAA,GAAW,OAAO;EAAE;EAAI;CAAO;CAC9C,OAAO,EAAE,GAAG;AACb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC5DA,IAAa,UAAb,MAAiD;CAChD;CACA;CACA;CACA;CACA;CACA;CAEA,YAAY,SAAyB;EACpC,MAAM,QAAQ,uBAAuB,OAAO;EAC5C,KAAK,MAAM,MAAM,OAAO,KAAA,IAAY,OAAO,WAAW,IAAI,MAAM;EAChE,KAAK,MAAM,MAAM;EACjB,KAAK,UAAU,MAAM;EACrB,KAAK,cAAc,IAAI,gBAAgB;EACvC,KAAK,YAAY,KAAK,MAAM,KAAK,IAAI;CACtC;CAEA,IAAI,KAAa;EAChB,OAAO,KAAK;CACb;CAEA,IAAI,KAAa;EAChB,OAAO,KAAK;CACb;CAEA,IAAI,SAAsB;EACzB,OAAO,KAAK,YAAY;CACzB;CAEA,IAAI,UAAmB;EACtB,OAAO,KAAK,YAAY,OAAO;CAChC;CAEA,QAAc;EACb,IAAI,KAAK,SAAS,YAAY,MAAM;EACpC,IAAI,KAAK,YAAY,KAAA,GAAW;GAC/B,aAAa,KAAK,OAAO;GACzB,KAAK,UAAU,KAAA;EAChB;EACA,KAAK,QAAQ;EACb,IAAI,KAAK,YAAY,OAAO,SAAS,KAAK,cAAc,IAAI,gBAAgB;EAC5E,IAAI,KAAK,YAAY,KAAA,GACpB,KAAK,QAAQ,iBAAiB,SAAS,KAAK,WAAW,EAAE,MAAM,KAAK,CAAC;EAEtE,KAAK,UAAU,iBAAiB;GAC/B,KAAK,UAAU,KAAA;GACf,KAAK,QAAQ;GACb,KAAK,YAAY,MAAM;EACxB,GAAG,KAAK,GAAG;CACZ;CAEA,QAAc;EACb,IAAI,KAAK,YAAY,KAAA,GAAW;GAC/B,aAAa,KAAK,OAAO;GACzB,KAAK,UAAU,KAAA;EAChB;EACA,KAAK,QAAQ;EACb,IAAI,KAAK,YAAY,OAAO,SAAS,KAAK,cAAc,IAAI,gBAAgB;CAC7E;CAEA,UAAgB;EACf,KAAK,SAAS,oBAAoB,SAAS,KAAK,SAAS;CAC1D;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACtDA,SAAgB,cAAc,SAA2C;CACxE,OAAO,IAAI,QAAQ,OAAO;AAC3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orkestrel/timeout",
-	"version": "0.0.8",
+	"version": "0.0.10",
 	"description": "A typed, controllable setTimeout wrapper — an AbortSignal deadline with start/clear lifecycle and parent-signal linking. Part of the @orkestrel line.",
 	"keywords": [
 		"abort-signal",
@@ -46,40 +46,43 @@
 		"clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
 		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
 		"scaffold": "scaffold",
-		"lint": "oxlint --config .oxlintrc.json --fix --deny-warnings .",
+		"lint": "oxlint --config .oxlintrc.json --fix .",
 		"check": "tsc --noEmit --project tsconfig.json && npm run check:src",
 		"check:src": "npm run check:src:core",
 		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
 		"format": "oxfmt --config .oxfmtrc.json --write .",
 		"format:check": "oxfmt --config .oxfmtrc.json --check .",
 		"lint:check": "oxlint --config .oxlintrc.json --deny-warnings .",
-		"test": "npm run test:src && npm run test:policy && npm run test:config && npm run test:guides",
+		"test": "npm run test:src && npm run test:policy && npm run test:config && npm run test:setup && npm run test:guides",
 		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
 		"test:src:core": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
 		"test:policy": "vitest run --config vite.config.ts --no-cache --reporter=dot --project policy",
 		"test:config": "vitest run --config vite.config.ts --no-cache --reporter=dot --project config",
-		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
+		"test:guides": "node --experimental-strip-types tests/guides.test.ts",
 		"build": "npm run clean && npm run build:src",
 		"build:src": "npm run build:src:core",
 		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
-		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test"
+		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:distribution -- --mode release",
+		"test:distribution": "vitest run --config vite.config.ts --no-cache --reporter=dot --project distribution",
+		"test:probe": "vitest run --config vite.config.ts --no-cache --reporter=verbose --project probe",
+		"test:bench": "vitest bench --config vite.config.ts --no-cache --project probe",
+		"prepack": "npm run build",
+		"test:setup": "vitest run --config vite.config.ts --no-cache --reporter=dot --project setup"
 	},
 	"dependencies": {
-		"@orkestrel/contract": "^0.0.13"
+		"@orkestrel/contract": "^0.0.17"
 	},
 	"devDependencies": {
 		"@microsoft/api-extractor": "^7.59.0",
-		"@orkestrel/guide": "^0.0.12",
-		"@orkestrel/probe": "^0.0.3",
-		"@orkestrel/scaffold": "^0.0.49",
-		"@orkestrel/test": "^0.0.11",
-		"@types/node": "^26.2.0",
-		"@vitest/browser-playwright": "^4.1.11",
-		"oxfmt": "^0.64.0",
-		"oxlint": "^1.79.0",
+		"@orkestrel/guide": "^0.0.17",
+		"@orkestrel/probe": "^0.0.12",
+		"@orkestrel/scaffold": "^0.0.63",
+		"@orkestrel/test": "^0.0.14",
+		"@types/node": "^26.4.1",
+		"oxfmt": "^0.66.0",
+		"oxlint": "^1.81.0",
 		"typescript": "^6.0.3",
 		"vite": "^8.2.2",
-		"vite-plugin-dts": "^5.0.3",
 		"vitest": "^4.1.11"
 	},
 	"engines": {