@orkestrel/timeout 0.0.3 → 0.0.5

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

@@ -1,106 +1,186 @@
 /**
- * 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.
+ * `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 - `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}
- *
- * @example
- * ```ts
- * import { createTimeout } from '@src/core'
- *
- * 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
- * ```
- */
-export declare function createTimeout(options: TimeoutOptions): TimeoutInterface;
+ * @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 '@orkestrel/timeout'
+     *
+     * const timeout = createTimeout({ ms: 5_000 })
+     * timeout.start()
+     * try {
+     * 	await fetch('/work', { signal: timeout.signal })
+     * } finally {
+     * 	timeout.clear()
+     * }
+     * ```
+     */
+ export declare function createTimeout(options: TimeoutOptions): TimeoutInterface;
 
-/**
- * A deadline handle — a controllable `setTimeout` wrapper that exposes an
- * `AbortSignal` which fires when the timeout expires, for racing against work.
- *
- * @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.
- *
- * @example
- * ```ts
- * const timeout = new Timeout({ ms: 5_000 })
- * timeout.start()
- * timeout.signal.addEventListener('abort', () => giveUp(), { once: true })
- * timeout.clear() // cancels the deadline before it fires
- * ```
- */
-export declare class Timeout implements TimeoutInterface {
-    #private;
-    readonly id: string;
-    readonly ms: number;
-    constructor(options: TimeoutOptions);
-    get signal(): AbortSignal;
-    get expired(): boolean;
-    start(): void;
-    clear(): void;
-}
+ /**
+  * 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
+  * ```
+  */
+ export declare function isTimeoutDuration(value: unknown): value is number;
 
-/**
- * A deadline handle — a controllable `setTimeout` wrapper that exposes an
- * `AbortSignal` which fires when the timeout expires, for racing against work.
- */
-export declare interface TimeoutInterface {
-    readonly id: string;
-    readonly ms: number;
-    readonly signal: AbortSignal;
-    readonly expired: boolean;
-    start(): void;
-    clear(): void;
-}
+ /**
+  * 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
+  * ```
+  */
+ export declare function isTimeoutSignal(value: unknown): value is AbortSignal;
 
-/** Options for `createTimeout`. */
-export declare interface TimeoutOptions {
-    readonly id?: string;
-    /**
-     * The deadline in milliseconds — must be a non-negative finite number.
-     *
-     * @remarks
-     * Passed straight to the host `setTimeout`, which clamps a negative or `NaN`
-     * value to roughly `0` (firing on the next macrotask) rather than throwing.
-     */
-    readonly ms: number;
-    /** A parent signal — clears the timeout (so it never expires) if this aborts. */
-    readonly signal?: AbortSignal;
-}
+ /**
+  * Largest timeout duration accepted by the package, in milliseconds.
+  *
+  * @example
+  * ```ts
+  * createTimeout({ ms: MAX_TIMEOUT_MS })
+  * ```
+  */
+ export declare const MAX_TIMEOUT_MS = 2147483647;
+
+ /**
+  * A controllable deadline whose native `AbortSignal` aborts when it expires.
+  *
+  * @remarks
+  * `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()
+  * ```
+  */
+ export declare class Timeout implements TimeoutInterface {
+     #private;
+     readonly id: string;
+     readonly ms: number;
+     constructor(options: TimeoutOptions);
+     get signal(): AbortSignal;
+     get expired(): boolean;
+     start(): void;
+     clear(): void;
+ }
+
+ /**
+  * A controllable deadline exposing a native `AbortSignal` that aborts on expiry.
+  *
+  * @example
+  * ```ts
+  * const timeout: TimeoutInterface = createTimeout({ ms: 5_000 })
+  * timeout.start()
+  * timeout.clear()
+  * ```
+  */
+ export declare interface TimeoutInterface {
+     /** Trace label supplied at construction or generated as a random UUID. */
+     readonly id: string;
+     /** Validated integer deadline in milliseconds. */
+     readonly ms: number;
+     /** Native signal that aborts once when the current deadline expires. */
+     readonly signal: AbortSignal;
+     /** Whether the owned signal has aborted, derived directly from that signal. */
+     readonly expired: boolean;
+     /**
+      * Arm or re-arm the deadline.
+      *
+      * @returns Nothing
+      */
+     start(): void;
+     /**
+      * Cancel an armed deadline without aborting its signal and reset expiry state.
+      *
+      * @returns Nothing
+      */
+     clear(): void;
+ }
+
+ /**
+  * Options for constructing a timeout deadline.
+  *
+  * @remarks
+  * `ms` is an integer from `0` through `2_147_483_647`, inclusive. `id`
+  * defaults to a random UUID when omitted, and `signal` is an optional native
+  * parent signal whose abort clears an armed timeout without aborting the
+  * timeout's own signal.
+  *
+  * @example
+  * ```ts
+  * const options: TimeoutOptions = { id: 'request', ms: 5_000 }
+  * ```
+  */
+ export declare interface TimeoutOptions {
+     /** 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`. */
+     readonly ms: number;
+     /** Native parent signal whose abort clears an armed timeout. */
+     readonly signal?: AbortSignal;
+ }
+
+ /**
+  * 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 })
+      * ```
+      */
+  export declare function validateTimeoutOptions(options: TimeoutOptions): TimeoutOptions;
 
-export { }
+  export { }

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

@@ -1,106 +1,186 @@
 /**
- * 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.
+ * `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 - `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}
- *
- * @example
- * ```ts
- * import { createTimeout } from '@src/core'
- *
- * 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
- * ```
- */
-export declare function createTimeout(options: TimeoutOptions): TimeoutInterface;
+ * @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 '@orkestrel/timeout'
+     *
+     * const timeout = createTimeout({ ms: 5_000 })
+     * timeout.start()
+     * try {
+     * 	await fetch('/work', { signal: timeout.signal })
+     * } finally {
+     * 	timeout.clear()
+     * }
+     * ```
+     */
+ export declare function createTimeout(options: TimeoutOptions): TimeoutInterface;
 
-/**
- * A deadline handle — a controllable `setTimeout` wrapper that exposes an
- * `AbortSignal` which fires when the timeout expires, for racing against work.
- *
- * @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.
- *
- * @example
- * ```ts
- * const timeout = new Timeout({ ms: 5_000 })
- * timeout.start()
- * timeout.signal.addEventListener('abort', () => giveUp(), { once: true })
- * timeout.clear() // cancels the deadline before it fires
- * ```
- */
-export declare class Timeout implements TimeoutInterface {
-    #private;
-    readonly id: string;
-    readonly ms: number;
-    constructor(options: TimeoutOptions);
-    get signal(): AbortSignal;
-    get expired(): boolean;
-    start(): void;
-    clear(): void;
-}
+ /**
+  * 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
+  * ```
+  */
+ export declare function isTimeoutDuration(value: unknown): value is number;
 
-/**
- * A deadline handle — a controllable `setTimeout` wrapper that exposes an
- * `AbortSignal` which fires when the timeout expires, for racing against work.
- */
-export declare interface TimeoutInterface {
-    readonly id: string;
-    readonly ms: number;
-    readonly signal: AbortSignal;
-    readonly expired: boolean;
-    start(): void;
-    clear(): void;
-}
+ /**
+  * 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
+  * ```
+  */
+ export declare function isTimeoutSignal(value: unknown): value is AbortSignal;
 
-/** Options for `createTimeout`. */
-export declare interface TimeoutOptions {
-    readonly id?: string;
-    /**
-     * The deadline in milliseconds — must be a non-negative finite number.
-     *
-     * @remarks
-     * Passed straight to the host `setTimeout`, which clamps a negative or `NaN`
-     * value to roughly `0` (firing on the next macrotask) rather than throwing.
-     */
-    readonly ms: number;
-    /** A parent signal — clears the timeout (so it never expires) if this aborts. */
-    readonly signal?: AbortSignal;
-}
+ /**
+  * Largest timeout duration accepted by the package, in milliseconds.
+  *
+  * @example
+  * ```ts
+  * createTimeout({ ms: MAX_TIMEOUT_MS })
+  * ```
+  */
+ export declare const MAX_TIMEOUT_MS = 2147483647;
+
+ /**
+  * A controllable deadline whose native `AbortSignal` aborts when it expires.
+  *
+  * @remarks
+  * `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()
+  * ```
+  */
+ export declare class Timeout implements TimeoutInterface {
+     #private;
+     readonly id: string;
+     readonly ms: number;
+     constructor(options: TimeoutOptions);
+     get signal(): AbortSignal;
+     get expired(): boolean;
+     start(): void;
+     clear(): void;
+ }
+
+ /**
+  * A controllable deadline exposing a native `AbortSignal` that aborts on expiry.
+  *
+  * @example
+  * ```ts
+  * const timeout: TimeoutInterface = createTimeout({ ms: 5_000 })
+  * timeout.start()
+  * timeout.clear()
+  * ```
+  */
+ export declare interface TimeoutInterface {
+     /** Trace label supplied at construction or generated as a random UUID. */
+     readonly id: string;
+     /** Validated integer deadline in milliseconds. */
+     readonly ms: number;
+     /** Native signal that aborts once when the current deadline expires. */
+     readonly signal: AbortSignal;
+     /** Whether the owned signal has aborted, derived directly from that signal. */
+     readonly expired: boolean;
+     /**
+      * Arm or re-arm the deadline.
+      *
+      * @returns Nothing
+      */
+     start(): void;
+     /**
+      * Cancel an armed deadline without aborting its signal and reset expiry state.
+      *
+      * @returns Nothing
+      */
+     clear(): void;
+ }
+
+ /**
+  * Options for constructing a timeout deadline.
+  *
+  * @remarks
+  * `ms` is an integer from `0` through `2_147_483_647`, inclusive. `id`
+  * defaults to a random UUID when omitted, and `signal` is an optional native
+  * parent signal whose abort clears an armed timeout without aborting the
+  * timeout's own signal.
+  *
+  * @example
+  * ```ts
+  * const options: TimeoutOptions = { id: 'request', ms: 5_000 }
+  * ```
+  */
+ export declare interface TimeoutOptions {
+     /** 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`. */
+     readonly ms: number;
+     /** Native parent signal whose abort clears an armed timeout. */
+     readonly signal?: AbortSignal;
+ }
+
+ /**
+  * 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 })
+      * ```
+      */
+  export declare function validateTimeoutOptions(options: TimeoutOptions): TimeoutOptions;
 
-export { }
+  export { }