@orkestrel/test 0.0.7 → 0.0.9

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

@@ -27,10 +27,23 @@ export declare function collectStream<T>(stream: ReadableStream<T>): Promise<rea
 /**
  * Creates values that make common object readers throw or violate their assumptions.
  *
- * @returns A frozen array whose six values are fresh on every call.
- * @remarks Every member makes a naive reader throw. A total guard survives every member without
- * throwing. Whether it accepts or refuses one is that guard's own contract. Membership may grow in
- * a release, so test the whole returned set in a loop and include the index in each failure.
+ * @returns A frozen array whose values are fresh on every call.
+ * @remarks Every member makes a naive read throw or violates a naive structural assumption. A total
+ * guard survives every member without throwing. Whether it accepts or refuses one is that guard's
+ * own contract. Membership may grow in a release, so test the whole returned set in a loop and
+ * include the index in each failure.
+ *
+ * - The self-referential record makes JSON record serialization throw.
+ * - The revoked object proxy makes reflective object access throw.
+ * - The property proxy makes a named property read throw.
+ * - The key proxy makes key enumeration throw.
+ * - The prototype proxy makes a prototype read throw.
+ * - The null-prototype record breaks a direct `hasOwnProperty` call.
+ * - The array-target proxy passes an array check and makes an index read throw.
+ * - The self-referential array makes JSON collection serialization throw.
+ * - The sparse array violates the assumption that every index is enumerable.
+ * - The hidden-key record violates the assumption that every own key is enumerable.
+ * - The named getter makes its property read throw.
  * @example
  * ```ts
  * import { expect } from 'vitest'
@@ -65,7 +78,43 @@ export declare function createHostileValues(): readonly unknown[];
  * @typeParam TArgs - The argument tuple to record.
  * @returns A recorder whose handler appends calls in order.
  */
-export declare function createRecorder<TArgs extends readonly unknown[]>(): RecorderInterface<TArgs>;
+export declare function createRecorder<TArgs extends readonly unknown[] = readonly unknown[]>(): RecorderInterface<TArgs>;
+
+/**
+ * Creates event recorders and subscribes them to the source.
+ *
+ * @typeParam TMap - The source's event names and delivered argument tuples.
+ * @typeParam TName - The requested event names.
+ * @param source - The source to subscribe to.
+ * @param events - The events to record.
+ * @returns A map from each requested event name to its recorder.
+ * @throws Thrown when a listed event has no recorder, which a well-formed events array cannot
+ * produce.
+ * @remarks A duplicate event name installs a fresh recorder for every occurrence. The returned map
+ * keeps the recorder installed for the last occurrence. `TName` derives from the array's element
+ * type. An array declared with a wider union than its contents widens `TName` beyond the listed
+ * events. The omitted key reads `undefined` at runtime under a non-optional type, and the guard
+ * reports `true` because it checks the listed events. Pass a literal array or a tuple.
+ */
+export declare function createRecorders<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(source: EventSourceInterface<TMap>, events: readonly TName[]): RecorderMap<TMap, TName>;
+
+/**
+ * Creates a monotonically numbered resource factory with creation and destruction records.
+ *
+ * @returns A resource factory whose recorders retain every affected id in order.
+ */
+export declare function createResourceFactory(): ResourceFactoryInterface;
+
+/**
+ * Creates a real abort controller whose signal reports its live abort listeners.
+ *
+ * @returns The controller, its instrumented signal, and the current listener tally.
+ * @remarks Instrumentation is installed on the created signal instance. A one-shot listener leaves
+ * the tally when it fires, and removal accepts the original listener supplied by the caller. A
+ * listener scoped by another signal leaves when that signal aborts. An already-aborted scope
+ * installs and records nothing.
+ */
+export declare function createSignal(): SignalInterface;
 
 /**
  * Creates a teardown list that runs registered handlers newest-first.
@@ -74,6 +123,88 @@ export declare function createRecorder<TArgs extends readonly unknown[]>(): Reco
  */
 export declare function createTeardown(): TeardownInterface;
 
+/**
+ * Decodes newline-delimited JSON values.
+ *
+ * @param text - The JSON Lines text to decode.
+ * @returns The decoded values in physical-line order.
+ * @throws An `Error` naming the malformed physical line, with the native `SyntaxError` as its
+ * `cause`.
+ */
+export declare function decodeJSONLines(text: string): readonly unknown[];
+
+/**
+ * Subscribes handlers to a typed event source.
+ *
+ * @typeParam TMap - The event names and argument tuples the source delivers.
+ */
+export declare interface EventSourceInterface<TMap extends Record<string, readonly unknown[]>> {
+    /**
+     * Subscribes a handler to an event.
+     *
+     * @param event - The event to subscribe to.
+     * @param handler - The handler that receives each delivery.
+     */
+    on<K extends keyof TMap>(event: K, handler: (...args: TMap[K]) => void): void;
+}
+
+/**
+ * Subscribes a listener to one event source.
+ *
+ * @typeParam TArgs - The argument tuple the event delivers.
+ * @param listener - The listener that receives each delivery.
+ * @returns The cleanup that removes the listener, or `void` when the source needs none.
+ */
+export declare type EventSubscriber<TArgs extends readonly unknown[]> = (listener: (...args: TArgs) => void) => (() => void) | void;
+
+/**
+ * Normalizes headers into a frozen plain record.
+ *
+ * @param init - The platform header initializer to normalize.
+ * @returns A frozen record of normalized header names and values.
+ * @remarks Normalization follows the host `Headers` implementation, including lowercased names and
+ * combined values.
+ */
+export declare function flattenHeaders(init: HeadersSource): Readonly<Record<string, string>>;
+
+/**
+ * Any value the host `Headers` constructor accepts.
+ *
+ * @remarks Derived from the host constructor rather than named from a single library, so the type
+ * resolves in every project against that project's own `Headers` declaration. The record,
+ * entries-array, and `Headers` forms all satisfy it.
+ */
+export declare type HeadersSource = NonNullable<ConstructorParameters<typeof Headers>[0]>;
+
+/**
+ * Invokes an unknown method through an explicit unchecked result contract.
+ *
+ * @typeParam T - The result type claimed by the caller.
+ * @param target - The value used as the method's `this` argument.
+ * @param method - The unknown method to invoke.
+ * @param args - The arguments to pass.
+ * @returns The method's result under the caller's claimed type.
+ * @throws A `TypeError` when `method` is not callable.
+ * @remarks The caller owns the claim that the returned value has type `T`. The contained `any`
+ * bridges the unchecked runtime result to that caller-owned claim.
+ */
+export declare function invokeUnchecked<T>(target: unknown, method: unknown, args: readonly unknown[]): T;
+
+/**
+ * Checks whether a value contains a recorder for every listed event.
+ *
+ * @typeParam TMap - The source's event names and delivered argument tuples.
+ * @typeParam TName - The event names represented in the map.
+ * @param value - The value to inspect.
+ * @param events - The events the completed map must contain.
+ * @returns True if every listed event has a structurally valid recorder; false otherwise.
+ * @remarks Per-key tuple precision is the predicate's claim. The factory proves that claim by
+ * wiring each recorder to exactly the event where it stores that recorder. A direct caller must
+ * establish the same pairing before it relies on the narrowing. This guard takes the listed events
+ * through a reference parameter rather than using the canonical single-value guard form.
+ */
+export declare function isRecorderMapComplete<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(value: unknown, events: readonly TName[]): value is RecorderMap<TMap, TName>;
+
 /**
  * The JSON-safe projection of a type: every member JSON preserves, mapped to itself, and every
  * member it does not, mapped to `never`.
@@ -112,6 +243,19 @@ export declare type JSONValue = string | number | boolean | null | readonly JSON
     readonly [key: string]: JSONValue;
 };
 
+/**
+ * Reads a property from an unknown object or function.
+ *
+ * @typeParam T - The property type claimed by the caller.
+ * @param target - The unknown value to read.
+ * @param key - The property key to read.
+ * @returns The property value under the caller's claimed type.
+ * @throws A `TypeError` when `target` is neither an object nor a function.
+ * @remarks The caller owns the claim that the returned value has type `T`. The contained `any`
+ * bridges the unchecked runtime result to that caller-owned claim.
+ */
+export declare function readProperty<T>(target: unknown, key: PropertyKey): T;
+
 /**
  * Records every call made to its handler.
  *
@@ -128,6 +272,16 @@ export declare interface RecorderInterface<TArgs extends readonly unknown[]> {
     clear(): void;
 }
 
+/**
+ * Maps event names to recorders for their delivered argument tuples.
+ *
+ * @typeParam TMap - The event names and argument tuples the source delivers.
+ * @typeParam TName - The event names represented in the map.
+ */
+export declare type RecorderMap<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap> = {
+    readonly [K in TName]: RecorderInterface<TMap[K]>;
+};
+
 /**
  * Requires a value to be present.
  *
@@ -147,6 +301,49 @@ export declare function requireValue<T>(value: T | null | undefined, message?: s
  */
 export declare function resolveRoot(meta: ImportMeta): URL;
 
+/** A numbered resource factory with records of every creation and destruction. */
+export declare interface ResourceFactoryInterface {
+    /** The ids returned by `create`, in order. */
+    readonly created: RecorderInterface<readonly [id: number]>;
+    /** The ids passed to `destroy`, in order. */
+    readonly destroyed: RecorderInterface<readonly [id: number]>;
+    /**
+     * Creates a numbered resource.
+     *
+     * @returns The next monotonically increasing id.
+     */
+    create(): number;
+    /**
+     * Destroys a numbered resource.
+     *
+     * @param id - The resource id to destroy.
+     */
+    destroy(id: number): void;
+}
+
+/** Configures a bounded retry. */
+export declare interface RetryOptions extends WaitOptions {
+    /** The maximum number of producer calls. When omitted, only the time budget bounds the retry. */
+    readonly attempts?: number;
+}
+
+/**
+ * Repeats a producer until one produced value satisfies a predicate.
+ *
+ * @typeParam T - The produced value type.
+ * @param description - The operation described in an exhaustion error.
+ * @param produce - The synchronous or asynchronous operation to repeat.
+ * @param satisfied - The predicate that accepts a produced value.
+ * @param options - The time, attempt, and abort bounds.
+ * @returns The first produced value the predicate accepts.
+ * @throws The predicate's thrown value, the abort reason, or an `Error` when a bound is invalid or
+ * the retry exhausts its budget or attempts.
+ * @remarks A producer throw counts as an unsatisfied attempt. The last producer error becomes the
+ * exhaustion error's `cause`. Default budget: `1000` milliseconds. Default interval: `10`
+ * milliseconds.
+ */
+export declare function retryUntil<T>(description: string, produce: () => T | Promise<T>, satisfied: (value: T) => boolean, options?: RetryOptions): Promise<T>;
+
 /**
  * Copies a JSON value through serialization and parsing.
  *
@@ -159,6 +356,16 @@ export declare function resolveRoot(meta: ImportMeta): URL;
  */
 export declare function roundTripJSON<T>(value: T & JSONSafe<T>): T;
 
+/** A real abort signal and controller instrumented with its live abort-listener tally. */
+export declare interface SignalInterface {
+    /** The controller that owns the signal. */
+    readonly controller: AbortController;
+    /** The instrumented signal. */
+    readonly signal: AbortSignal;
+    /** The live abort-listener tally. */
+    readonly count: number;
+}
+
 /** The work one teardown entry performs when the list is destroyed. */
 export declare type TeardownHandler = () => void | Promise<void>;
 
@@ -185,6 +392,30 @@ export declare interface TeardownInterface {
     destroy(): Promise<void>;
 }
 
+/**
+ * Waits until an abort signal is aborted.
+ *
+ * @param signal - The signal to observe.
+ * @returns A promise that resolves when the signal is aborted.
+ * @remarks An already-aborted signal resolves immediately. Otherwise the wait parks on a one-shot
+ * abort listener without a timer or polling.
+ */
+export declare function waitForAbort(signal: AbortSignal): Promise<void>;
+
+/**
+ * Waits until a condition holds within an elapsed-time budget.
+ *
+ * @param description - The condition described in a timeout error.
+ * @param condition - The synchronous or asynchronous condition to read.
+ * @param options - The time bounds and abort signal.
+ * @returns A promise that resolves when the condition first returns `true`.
+ * @throws The condition's thrown value, the abort reason, or an `Error` when a bound is invalid or
+ * the condition does not hold within the budget.
+ * @remarks The first read is immediate. Default budget: `1000` milliseconds. Default interval: `10`
+ * milliseconds.
+ */
+export declare function waitForCondition(description: string, condition: () => boolean | Promise<boolean>, options?: WaitOptions): Promise<void>;
+
 /**
  * Waits for a host timer to elapse.
  *
@@ -193,4 +424,35 @@ export declare interface TeardownInterface {
  */
 export declare function waitForDelay(ms?: number): Promise<void>;
 
+/**
+ * Waits for the first delivery from an event subscription.
+ *
+ * @typeParam TArgs - The delivered argument tuple.
+ * @param subscribe - The function that installs the event listener and may return its cleanup.
+ * @param description - The event described in a timeout error.
+ * @param options - The time bounds and abort signal.
+ * @returns The first delivered argument tuple.
+ * @throws The subscription's thrown value, the abort reason, or an `Error` when a bound is invalid
+ * or the event is not delivered within the budget.
+ * @remarks Default budget: `1000` milliseconds. The interval is validated for consistency with the
+ * wait family but is not used because this helper parks on the event.
+ */
+export declare function waitForEvent<TArgs extends readonly unknown[]>(subscribe: EventSubscriber<TArgs>, description: string, options?: WaitOptions): Promise<TArgs>;
+
+/**
+ * Configures a bounded asynchronous wait.
+ *
+ * @remarks
+ * A default belongs to the function that reads these bounds rather than to the shape, because the
+ * consumers do not agree on one. Each states its own numbers in its `@remarks`.
+ */
+export declare interface WaitOptions {
+    /** The elapsed-time limit in milliseconds. */
+    readonly budget?: number;
+    /** The delay between readings in milliseconds. */
+    readonly interval?: number;
+    /** The signal that aborts the wait. */
+    readonly signal?: AbortSignal;
+}
+
 export { }

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

@@ -27,10 +27,23 @@ export declare function collectStream<T>(stream: ReadableStream<T>): Promise<rea
 /**
  * Creates values that make common object readers throw or violate their assumptions.
  *
- * @returns A frozen array whose six values are fresh on every call.
- * @remarks Every member makes a naive reader throw. A total guard survives every member without
- * throwing. Whether it accepts or refuses one is that guard's own contract. Membership may grow in
- * a release, so test the whole returned set in a loop and include the index in each failure.
+ * @returns A frozen array whose values are fresh on every call.
+ * @remarks Every member makes a naive read throw or violates a naive structural assumption. A total
+ * guard survives every member without throwing. Whether it accepts or refuses one is that guard's
+ * own contract. Membership may grow in a release, so test the whole returned set in a loop and
+ * include the index in each failure.
+ *
+ * - The self-referential record makes JSON record serialization throw.
+ * - The revoked object proxy makes reflective object access throw.
+ * - The property proxy makes a named property read throw.
+ * - The key proxy makes key enumeration throw.
+ * - The prototype proxy makes a prototype read throw.
+ * - The null-prototype record breaks a direct `hasOwnProperty` call.
+ * - The array-target proxy passes an array check and makes an index read throw.
+ * - The self-referential array makes JSON collection serialization throw.
+ * - The sparse array violates the assumption that every index is enumerable.
+ * - The hidden-key record violates the assumption that every own key is enumerable.
+ * - The named getter makes its property read throw.
  * @example
  * ```ts
  * import { expect } from 'vitest'
@@ -65,7 +78,43 @@ export declare function createHostileValues(): readonly unknown[];
  * @typeParam TArgs - The argument tuple to record.
  * @returns A recorder whose handler appends calls in order.
  */
-export declare function createRecorder<TArgs extends readonly unknown[]>(): RecorderInterface<TArgs>;
+export declare function createRecorder<TArgs extends readonly unknown[] = readonly unknown[]>(): RecorderInterface<TArgs>;
+
+/**
+ * Creates event recorders and subscribes them to the source.
+ *
+ * @typeParam TMap - The source's event names and delivered argument tuples.
+ * @typeParam TName - The requested event names.
+ * @param source - The source to subscribe to.
+ * @param events - The events to record.
+ * @returns A map from each requested event name to its recorder.
+ * @throws Thrown when a listed event has no recorder, which a well-formed events array cannot
+ * produce.
+ * @remarks A duplicate event name installs a fresh recorder for every occurrence. The returned map
+ * keeps the recorder installed for the last occurrence. `TName` derives from the array's element
+ * type. An array declared with a wider union than its contents widens `TName` beyond the listed
+ * events. The omitted key reads `undefined` at runtime under a non-optional type, and the guard
+ * reports `true` because it checks the listed events. Pass a literal array or a tuple.
+ */
+export declare function createRecorders<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(source: EventSourceInterface<TMap>, events: readonly TName[]): RecorderMap<TMap, TName>;
+
+/**
+ * Creates a monotonically numbered resource factory with creation and destruction records.
+ *
+ * @returns A resource factory whose recorders retain every affected id in order.
+ */
+export declare function createResourceFactory(): ResourceFactoryInterface;
+
+/**
+ * Creates a real abort controller whose signal reports its live abort listeners.
+ *
+ * @returns The controller, its instrumented signal, and the current listener tally.
+ * @remarks Instrumentation is installed on the created signal instance. A one-shot listener leaves
+ * the tally when it fires, and removal accepts the original listener supplied by the caller. A
+ * listener scoped by another signal leaves when that signal aborts. An already-aborted scope
+ * installs and records nothing.
+ */
+export declare function createSignal(): SignalInterface;
 
 /**
  * Creates a teardown list that runs registered handlers newest-first.
@@ -74,6 +123,88 @@ export declare function createRecorder<TArgs extends readonly unknown[]>(): Reco
  */
 export declare function createTeardown(): TeardownInterface;
 
+/**
+ * Decodes newline-delimited JSON values.
+ *
+ * @param text - The JSON Lines text to decode.
+ * @returns The decoded values in physical-line order.
+ * @throws An `Error` naming the malformed physical line, with the native `SyntaxError` as its
+ * `cause`.
+ */
+export declare function decodeJSONLines(text: string): readonly unknown[];
+
+/**
+ * Subscribes handlers to a typed event source.
+ *
+ * @typeParam TMap - The event names and argument tuples the source delivers.
+ */
+export declare interface EventSourceInterface<TMap extends Record<string, readonly unknown[]>> {
+    /**
+     * Subscribes a handler to an event.
+     *
+     * @param event - The event to subscribe to.
+     * @param handler - The handler that receives each delivery.
+     */
+    on<K extends keyof TMap>(event: K, handler: (...args: TMap[K]) => void): void;
+}
+
+/**
+ * Subscribes a listener to one event source.
+ *
+ * @typeParam TArgs - The argument tuple the event delivers.
+ * @param listener - The listener that receives each delivery.
+ * @returns The cleanup that removes the listener, or `void` when the source needs none.
+ */
+export declare type EventSubscriber<TArgs extends readonly unknown[]> = (listener: (...args: TArgs) => void) => (() => void) | void;
+
+/**
+ * Normalizes headers into a frozen plain record.
+ *
+ * @param init - The platform header initializer to normalize.
+ * @returns A frozen record of normalized header names and values.
+ * @remarks Normalization follows the host `Headers` implementation, including lowercased names and
+ * combined values.
+ */
+export declare function flattenHeaders(init: HeadersSource): Readonly<Record<string, string>>;
+
+/**
+ * Any value the host `Headers` constructor accepts.
+ *
+ * @remarks Derived from the host constructor rather than named from a single library, so the type
+ * resolves in every project against that project's own `Headers` declaration. The record,
+ * entries-array, and `Headers` forms all satisfy it.
+ */
+export declare type HeadersSource = NonNullable<ConstructorParameters<typeof Headers>[0]>;
+
+/**
+ * Invokes an unknown method through an explicit unchecked result contract.
+ *
+ * @typeParam T - The result type claimed by the caller.
+ * @param target - The value used as the method's `this` argument.
+ * @param method - The unknown method to invoke.
+ * @param args - The arguments to pass.
+ * @returns The method's result under the caller's claimed type.
+ * @throws A `TypeError` when `method` is not callable.
+ * @remarks The caller owns the claim that the returned value has type `T`. The contained `any`
+ * bridges the unchecked runtime result to that caller-owned claim.
+ */
+export declare function invokeUnchecked<T>(target: unknown, method: unknown, args: readonly unknown[]): T;
+
+/**
+ * Checks whether a value contains a recorder for every listed event.
+ *
+ * @typeParam TMap - The source's event names and delivered argument tuples.
+ * @typeParam TName - The event names represented in the map.
+ * @param value - The value to inspect.
+ * @param events - The events the completed map must contain.
+ * @returns True if every listed event has a structurally valid recorder; false otherwise.
+ * @remarks Per-key tuple precision is the predicate's claim. The factory proves that claim by
+ * wiring each recorder to exactly the event where it stores that recorder. A direct caller must
+ * establish the same pairing before it relies on the narrowing. This guard takes the listed events
+ * through a reference parameter rather than using the canonical single-value guard form.
+ */
+export declare function isRecorderMapComplete<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap>(value: unknown, events: readonly TName[]): value is RecorderMap<TMap, TName>;
+
 /**
  * The JSON-safe projection of a type: every member JSON preserves, mapped to itself, and every
  * member it does not, mapped to `never`.
@@ -112,6 +243,19 @@ export declare type JSONValue = string | number | boolean | null | readonly JSON
     readonly [key: string]: JSONValue;
 };
 
+/**
+ * Reads a property from an unknown object or function.
+ *
+ * @typeParam T - The property type claimed by the caller.
+ * @param target - The unknown value to read.
+ * @param key - The property key to read.
+ * @returns The property value under the caller's claimed type.
+ * @throws A `TypeError` when `target` is neither an object nor a function.
+ * @remarks The caller owns the claim that the returned value has type `T`. The contained `any`
+ * bridges the unchecked runtime result to that caller-owned claim.
+ */
+export declare function readProperty<T>(target: unknown, key: PropertyKey): T;
+
 /**
  * Records every call made to its handler.
  *
@@ -128,6 +272,16 @@ export declare interface RecorderInterface<TArgs extends readonly unknown[]> {
     clear(): void;
 }
 
+/**
+ * Maps event names to recorders for their delivered argument tuples.
+ *
+ * @typeParam TMap - The event names and argument tuples the source delivers.
+ * @typeParam TName - The event names represented in the map.
+ */
+export declare type RecorderMap<TMap extends Record<string, readonly unknown[]>, TName extends keyof TMap> = {
+    readonly [K in TName]: RecorderInterface<TMap[K]>;
+};
+
 /**
  * Requires a value to be present.
  *
@@ -147,6 +301,49 @@ export declare function requireValue<T>(value: T | null | undefined, message?: s
  */
 export declare function resolveRoot(meta: ImportMeta): URL;
 
+/** A numbered resource factory with records of every creation and destruction. */
+export declare interface ResourceFactoryInterface {
+    /** The ids returned by `create`, in order. */
+    readonly created: RecorderInterface<readonly [id: number]>;
+    /** The ids passed to `destroy`, in order. */
+    readonly destroyed: RecorderInterface<readonly [id: number]>;
+    /**
+     * Creates a numbered resource.
+     *
+     * @returns The next monotonically increasing id.
+     */
+    create(): number;
+    /**
+     * Destroys a numbered resource.
+     *
+     * @param id - The resource id to destroy.
+     */
+    destroy(id: number): void;
+}
+
+/** Configures a bounded retry. */
+export declare interface RetryOptions extends WaitOptions {
+    /** The maximum number of producer calls. When omitted, only the time budget bounds the retry. */
+    readonly attempts?: number;
+}
+
+/**
+ * Repeats a producer until one produced value satisfies a predicate.
+ *
+ * @typeParam T - The produced value type.
+ * @param description - The operation described in an exhaustion error.
+ * @param produce - The synchronous or asynchronous operation to repeat.
+ * @param satisfied - The predicate that accepts a produced value.
+ * @param options - The time, attempt, and abort bounds.
+ * @returns The first produced value the predicate accepts.
+ * @throws The predicate's thrown value, the abort reason, or an `Error` when a bound is invalid or
+ * the retry exhausts its budget or attempts.
+ * @remarks A producer throw counts as an unsatisfied attempt. The last producer error becomes the
+ * exhaustion error's `cause`. Default budget: `1000` milliseconds. Default interval: `10`
+ * milliseconds.
+ */
+export declare function retryUntil<T>(description: string, produce: () => T | Promise<T>, satisfied: (value: T) => boolean, options?: RetryOptions): Promise<T>;
+
 /**
  * Copies a JSON value through serialization and parsing.
  *
@@ -159,6 +356,16 @@ export declare function resolveRoot(meta: ImportMeta): URL;
  */
 export declare function roundTripJSON<T>(value: T & JSONSafe<T>): T;
 
+/** A real abort signal and controller instrumented with its live abort-listener tally. */
+export declare interface SignalInterface {
+    /** The controller that owns the signal. */
+    readonly controller: AbortController;
+    /** The instrumented signal. */
+    readonly signal: AbortSignal;
+    /** The live abort-listener tally. */
+    readonly count: number;
+}
+
 /** The work one teardown entry performs when the list is destroyed. */
 export declare type TeardownHandler = () => void | Promise<void>;
 
@@ -185,6 +392,30 @@ export declare interface TeardownInterface {
     destroy(): Promise<void>;
 }
 
+/**
+ * Waits until an abort signal is aborted.
+ *
+ * @param signal - The signal to observe.
+ * @returns A promise that resolves when the signal is aborted.
+ * @remarks An already-aborted signal resolves immediately. Otherwise the wait parks on a one-shot
+ * abort listener without a timer or polling.
+ */
+export declare function waitForAbort(signal: AbortSignal): Promise<void>;
+
+/**
+ * Waits until a condition holds within an elapsed-time budget.
+ *
+ * @param description - The condition described in a timeout error.
+ * @param condition - The synchronous or asynchronous condition to read.
+ * @param options - The time bounds and abort signal.
+ * @returns A promise that resolves when the condition first returns `true`.
+ * @throws The condition's thrown value, the abort reason, or an `Error` when a bound is invalid or
+ * the condition does not hold within the budget.
+ * @remarks The first read is immediate. Default budget: `1000` milliseconds. Default interval: `10`
+ * milliseconds.
+ */
+export declare function waitForCondition(description: string, condition: () => boolean | Promise<boolean>, options?: WaitOptions): Promise<void>;
+
 /**
  * Waits for a host timer to elapse.
  *
@@ -193,4 +424,35 @@ export declare interface TeardownInterface {
  */
 export declare function waitForDelay(ms?: number): Promise<void>;
 
+/**
+ * Waits for the first delivery from an event subscription.
+ *
+ * @typeParam TArgs - The delivered argument tuple.
+ * @param subscribe - The function that installs the event listener and may return its cleanup.
+ * @param description - The event described in a timeout error.
+ * @param options - The time bounds and abort signal.
+ * @returns The first delivered argument tuple.
+ * @throws The subscription's thrown value, the abort reason, or an `Error` when a bound is invalid
+ * or the event is not delivered within the budget.
+ * @remarks Default budget: `1000` milliseconds. The interval is validated for consistency with the
+ * wait family but is not used because this helper parks on the event.
+ */
+export declare function waitForEvent<TArgs extends readonly unknown[]>(subscribe: EventSubscriber<TArgs>, description: string, options?: WaitOptions): Promise<TArgs>;
+
+/**
+ * Configures a bounded asynchronous wait.
+ *
+ * @remarks
+ * A default belongs to the function that reads these bounds rather than to the shape, because the
+ * consumers do not agree on one. Each states its own numbers in its `@remarks`.
+ */
+export declare interface WaitOptions {
+    /** The elapsed-time limit in milliseconds. */
+    readonly budget?: number;
+    /** The delay between readings in milliseconds. */
+    readonly interval?: number;
+    /** The signal that aborts the wait. */
+    readonly signal?: AbortSignal;
+}
+
 export { }