@orkestrel/test 0.0.11 → 0.0.13

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

@@ -1,11 +1,13 @@
 import { Server } from 'node:net';
 import { Socket } from 'node:net';
+import { Stats } from 'node:fs';
 import { WaitOptions } from '@orkestrel/test';
 
-/** A name-keyed cookie store a test drives one origin with, filled from real responses. */
+/** Holds a name-keyed cookie store a test drives one origin with, filled from real responses. */
 export declare interface CookieJarInterface {
     /**
-     * The `Cookie` request header naming every stored cookie, or `undefined` while the jar holds none.
+     * Reports the `Cookie` request header naming every stored cookie, or `undefined` while the jar
+     * holds none.
      */
     readonly header: string | undefined;
     /**
@@ -68,8 +70,8 @@ export declare function createLoopback(server: Server): Promise<LoopbackInterfac
  * @returns The scratch directory and its file operations.
  * @throws When the parent is missing, a symbolic link, or not a directory; when the prefix contains
  * `/` or `\`; or when allocation or seeding fails.
- * @remarks The parent defaults to the host temporary directory. The prefix defaults to
- * `orkestrel-test-`. Seed keys use root-relative paths.
+ * @remarks Default parent: the host temporary directory. Default prefix: `orkestrel-test-`. Seed
+ * keys use root-relative paths.
  */
 export declare function createScratch(options?: ScratchOptions): ScratchInterface;
 
@@ -100,13 +102,14 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
  */
 export declare function destroyScratch(scratch: ScratchInterface, options?: WaitOptions): Promise<void>;
 
-/** Options for reading a source inventory. */
+/** Configures a source inventory read. */
 export declare interface InventoryOptions {
-    /** The file extensions to include, each written with its leading dot. */
+    /** Lists the file extensions to include, each written with its leading dot. */
     readonly extensions?: readonly string[];
     /**
-     * The root-relative path keys to exclude. A key excludes itself and every key below it, matched
-     * on whole segments, so `excluded` drops `excluded/file.ts` and keeps `excluded-other/file.ts`.
+     * Lists the root-relative path keys to exclude. A key excludes itself and every key below it,
+     * matched on whole segments, so `excluded` drops `excluded/file.ts` and keeps
+     * `excluded-other/file.ts`.
      */
     readonly exclude?: readonly string[];
 }
@@ -116,7 +119,7 @@ export declare interface InventoryOptions {
  *
  * @param key - The root-relative key to test.
  * @param exclusions - The normalized root-relative exclusion keys.
- * @returns Whether an exclusion names the key or one of its ancestors.
+ * @returns True if an exclusion names the key or one of its ancestors; false otherwise.
  */
 export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
 
@@ -139,14 +142,14 @@ export declare function isExcluded(key: string, exclusions: readonly string[]):
  */
 export declare function isRunning(pid: number): boolean;
 
-/** A server a test owns, listening on an ephemeral loopback port until the test releases it. */
+/** Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. */
 export declare interface LoopbackInterface {
     /**
-     * The `http` origin for the assigned port, without a trailing slash. A TLS server answers on the
-     * same port under `https`.
+     * Names the `http` origin for the assigned port, without a trailing slash. A TLS server answers
+     * on the same port under `https`.
      */
     readonly url: string;
-    /** The ephemeral port the host assigned. */
+    /** Holds the ephemeral port the host assigned. */
     readonly port: number;
     /**
      * Drops every live connection on a server that carries `closeAllConnections`, stops listening, and
@@ -162,13 +165,33 @@ export declare interface LoopbackInterface {
  *
  * @param current - The identity read from the path now.
  * @param allocation - The identity recorded when the directory was allocated.
- * @returns Whether the device, the index node, and the creation time all match.
+ * @returns True if the device, the index node, and the creation time all match; false otherwise.
  * @remarks All three fields are compared because none of them alone identifies an allocation. A
  * device is shared by every directory on one filesystem, an index node is reused once its directory
  * is removed, and a creation time repeats within the host's timestamp resolution.
  */
 export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
 
+/**
+ * Reads the `code` an unknown thrown value carries.
+ *
+ * @param error - The thrown value to read.
+ * @returns The string `code` the value carries, or `undefined` when it carries none.
+ * @remarks The read is contained on its own terms: a value that is not an object, one carrying no
+ * `code`, and one carrying a `code` that is not a string all answer `undefined`. A null-prototype
+ * object is read the same way, because the key is tested with `in` rather than through
+ * `hasOwnProperty`.
+ */
+export declare function readErrorCode(error: unknown): string | undefined;
+
+/**
+ * Reads the identity of one allocated directory off a host status.
+ *
+ * @param status - The status read from the directory's path.
+ * @returns The device, index node, and creation time that together name the allocation.
+ */
+export declare function readIdentity(status: Stats): ScratchIdentity;
+
 /**
  * Reads files from selected targets below a root directory.
  *
@@ -185,17 +208,17 @@ export declare function matchesIdentity(current: ScratchIdentity, allocation: Sc
 export declare function readInventory(root: URL | string, targets: readonly string[], options?: InventoryOptions): Readonly<Record<string, string>>;
 
 /**
- * The attempts `removeTree` makes before rethrowing a retryable removal error.
+ * Caps the attempts `removeTree` makes before rethrowing a retryable removal error.
  */
 export declare const REMOVE_TREE_MAX_ATTEMPTS = 10;
 
 /**
- * The synchronous delay, in milliseconds, `removeTree` waits between attempts.
+ * Names the synchronous delay, in milliseconds, `removeTree` waits between attempts.
  */
 export declare const REMOVE_TREE_RETRY_DELAY_MS = 100;
 
 /**
- * The error codes `removeTree` retries; every other code rethrows immediately.
+ * Names the error codes `removeTree` retries; every other code rethrows immediately.
  */
 export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
 
@@ -248,6 +271,20 @@ export declare function removeTree(path: string): void;
  */
 export declare function requestUpgrade(port: number, options?: UpgradeOptions): Promise<UpgradeResult>;
 
+/**
+ * Resolves a target that stays below a root directory, refusing an escape.
+ *
+ * @param root - The absolute root directory.
+ * @param target - The relative or absolute target to resolve.
+ * @returns The absolute target below the root.
+ * @throws An `Error` reading `Path outside scratch directory: <target>` when the target escapes the
+ * root.
+ * @remarks This is {@link resolveContained} with the refusal every contained scratch operation makes
+ * of an escape, so the check and its one message are stated once. Read `resolveContained` where an
+ * escape is an answer rather than a refusal.
+ */
+export declare function requireContained(root: string, target: string): string;
+
 /**
  * Resolves a target that stays below a root directory.
  *
@@ -257,19 +294,19 @@ export declare function requestUpgrade(port: number, options?: UpgradeOptions):
  */
 export declare function resolveContained(root: string, target: string): string | undefined;
 
-/** The fields that together identify one allocated directory on its host. */
+/** Represents the fields that together identify one allocated directory on its host. */
 export declare interface ScratchIdentity {
-    /** The identifier of the device holding the directory. */
+    /** Holds the identifier of the device holding the directory. */
     readonly device: number;
-    /** The number of the directory's index node on that device. */
+    /** Holds the number of the directory's index node on that device. */
     readonly inode: number;
-    /** The directory's creation time in milliseconds. */
+    /** Holds the directory's creation time in milliseconds. */
     readonly birth: number;
 }
 
-/** A temporary directory a test owns, writes into, reads back, and removes when it is done. */
+/** Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. */
 export declare interface ScratchInterface {
-    /** The absolute path of the allocated directory. */
+    /** Holds the absolute path of the allocated directory. */
     readonly path: string;
     /**
      * Writes a file, creating each parent directory that does not exist.
@@ -296,15 +333,16 @@ export declare interface ScratchInterface {
      * Reports whether a path exists without following its final symbolic link.
      *
      * @param target - A relative or absolute path contained by the scratch directory.
-     * @returns True when the entry exists, including a symbolic link whose target is missing.
+     * @returns True if the entry exists, including a symbolic link whose target is
+     * missing; false otherwise.
      * @throws When the path escapes the scratch directory or its root is a symbolic link or file.
      */
     has(target: string): boolean;
     /**
      * Lists the names directly inside a directory in sorted order.
      *
-     * @param target - A relative or absolute directory path contained by the scratch directory. The
-     * scratch root is used when omitted.
+     * @param target - A relative or absolute directory path contained by the scratch directory.
+     * Default: the scratch root.
      * @returns The sorted entry names, without their parent paths.
      * @throws When the path escapes the scratch directory, the target is missing or is not a
      * directory, or the scratch root is a symbolic link or file.
@@ -353,23 +391,23 @@ export declare interface ScratchInterface {
     destroy(): void;
 }
 
-/** Options for allocating a scratch directory. */
+/** Configures a scratch directory allocation. */
 export declare interface ScratchOptions {
     /**
-     * The existing directory in which to create the allocation. Defaults to the host temporary
+     * Names the existing directory in which to create the allocation. Defaults to the host temporary
      * directory. Allocation throws when this path is missing, a symbolic link, or not a directory.
      */
     readonly parent?: string;
     /**
-     * The name fragment that starts the generated directory name. Allocation throws when this value
-     * contains `/` or `\`. Both are refused on every host, so the rule does not vary by host. A
+     * Holds the name fragment that starts the generated directory name. Allocation throws when this
+     * value contains `/` or `\`. Both are refused on every host, so the rule does not vary by host. A
      * fragment carrying no separator is one path segment and cannot steer the allocation, so
      * `release-0..2-` allocates.
      */
     readonly prefix?: string;
     /**
-     * Files to write on allocation, keyed by path below the scratch directory. Allocation removes its
-     * directory and rethrows when a key escapes or the host refuses a write.
+     * Holds the files to write on allocation, keyed by path below the scratch directory. Allocation
+     * removes its directory and rethrows when a key escapes or the host refuses a write.
      */
     readonly files?: Readonly<Record<string, string>>;
 }
@@ -449,23 +487,23 @@ export declare function supportsFileLinks(): boolean;
 export declare function supportsMode(): boolean;
 
 /**
- * Options for driving a client upgrade request.
+ * Configures a client upgrade request.
  *
  * @remarks The time bounds and abort signal bound the wait for the server's answer, so a server
  * that accepts the connection and never answers ends the call rather than parking it.
  */
 export declare interface UpgradeOptions extends WaitOptions {
-    /** The request path, written with its leading slash. Defaults to `/`. */
+    /** Names the request path, written with its leading slash. Defaults to `/`. */
     readonly path?: string;
     /**
-     * The subprotocol tokens the request offers. They are sent as one comma-separated
+     * Lists the subprotocol tokens the request offers. They are sent as one comma-separated
      * `Sec-WebSocket-Protocol` field, and an empty or omitted list sends no field at all.
      */
     readonly protocols?: readonly string[];
 }
 
 /**
- * What one server did with a client upgrade request.
+ * Represents what one server did with a client upgrade request.
  *
  * @remarks `claimed` is the discriminant. The claimed arm carries `protocol`, the subprotocol the
  * server selected, which is `undefined` when it selected none; a claimed upgrade produced no plain

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

@@ -1,11 +1,13 @@
 import { Server } from 'node:net';
 import { Socket } from 'node:net';
+import { Stats } from 'node:fs';
 import { WaitOptions } from '@orkestrel/test';
 
-/** A name-keyed cookie store a test drives one origin with, filled from real responses. */
+/** Holds a name-keyed cookie store a test drives one origin with, filled from real responses. */
 export declare interface CookieJarInterface {
     /**
-     * The `Cookie` request header naming every stored cookie, or `undefined` while the jar holds none.
+     * Reports the `Cookie` request header naming every stored cookie, or `undefined` while the jar
+     * holds none.
      */
     readonly header: string | undefined;
     /**
@@ -68,8 +70,8 @@ export declare function createLoopback(server: Server): Promise<LoopbackInterfac
  * @returns The scratch directory and its file operations.
  * @throws When the parent is missing, a symbolic link, or not a directory; when the prefix contains
  * `/` or `\`; or when allocation or seeding fails.
- * @remarks The parent defaults to the host temporary directory. The prefix defaults to
- * `orkestrel-test-`. Seed keys use root-relative paths.
+ * @remarks Default parent: the host temporary directory. Default prefix: `orkestrel-test-`. Seed
+ * keys use root-relative paths.
  */
 export declare function createScratch(options?: ScratchOptions): ScratchInterface;
 
@@ -100,13 +102,14 @@ export declare function createScratch(options?: ScratchOptions): ScratchInterfac
  */
 export declare function destroyScratch(scratch: ScratchInterface, options?: WaitOptions): Promise<void>;
 
-/** Options for reading a source inventory. */
+/** Configures a source inventory read. */
 export declare interface InventoryOptions {
-    /** The file extensions to include, each written with its leading dot. */
+    /** Lists the file extensions to include, each written with its leading dot. */
     readonly extensions?: readonly string[];
     /**
-     * The root-relative path keys to exclude. A key excludes itself and every key below it, matched
-     * on whole segments, so `excluded` drops `excluded/file.ts` and keeps `excluded-other/file.ts`.
+     * Lists the root-relative path keys to exclude. A key excludes itself and every key below it,
+     * matched on whole segments, so `excluded` drops `excluded/file.ts` and keeps
+     * `excluded-other/file.ts`.
      */
     readonly exclude?: readonly string[];
 }
@@ -116,7 +119,7 @@ export declare interface InventoryOptions {
  *
  * @param key - The root-relative key to test.
  * @param exclusions - The normalized root-relative exclusion keys.
- * @returns Whether an exclusion names the key or one of its ancestors.
+ * @returns True if an exclusion names the key or one of its ancestors; false otherwise.
  */
 export declare function isExcluded(key: string, exclusions: readonly string[]): boolean;
 
@@ -139,14 +142,14 @@ export declare function isExcluded(key: string, exclusions: readonly string[]):
  */
 export declare function isRunning(pid: number): boolean;
 
-/** A server a test owns, listening on an ephemeral loopback port until the test releases it. */
+/** Holds a server a test owns, listening on an ephemeral loopback port until the test releases it. */
 export declare interface LoopbackInterface {
     /**
-     * The `http` origin for the assigned port, without a trailing slash. A TLS server answers on the
-     * same port under `https`.
+     * Names the `http` origin for the assigned port, without a trailing slash. A TLS server answers
+     * on the same port under `https`.
      */
     readonly url: string;
-    /** The ephemeral port the host assigned. */
+    /** Holds the ephemeral port the host assigned. */
     readonly port: number;
     /**
      * Drops every live connection on a server that carries `closeAllConnections`, stops listening, and
@@ -162,13 +165,33 @@ export declare interface LoopbackInterface {
  *
  * @param current - The identity read from the path now.
  * @param allocation - The identity recorded when the directory was allocated.
- * @returns Whether the device, the index node, and the creation time all match.
+ * @returns True if the device, the index node, and the creation time all match; false otherwise.
  * @remarks All three fields are compared because none of them alone identifies an allocation. A
  * device is shared by every directory on one filesystem, an index node is reused once its directory
  * is removed, and a creation time repeats within the host's timestamp resolution.
  */
 export declare function matchesIdentity(current: ScratchIdentity, allocation: ScratchIdentity): boolean;
 
+/**
+ * Reads the `code` an unknown thrown value carries.
+ *
+ * @param error - The thrown value to read.
+ * @returns The string `code` the value carries, or `undefined` when it carries none.
+ * @remarks The read is contained on its own terms: a value that is not an object, one carrying no
+ * `code`, and one carrying a `code` that is not a string all answer `undefined`. A null-prototype
+ * object is read the same way, because the key is tested with `in` rather than through
+ * `hasOwnProperty`.
+ */
+export declare function readErrorCode(error: unknown): string | undefined;
+
+/**
+ * Reads the identity of one allocated directory off a host status.
+ *
+ * @param status - The status read from the directory's path.
+ * @returns The device, index node, and creation time that together name the allocation.
+ */
+export declare function readIdentity(status: Stats): ScratchIdentity;
+
 /**
  * Reads files from selected targets below a root directory.
  *
@@ -185,17 +208,17 @@ export declare function matchesIdentity(current: ScratchIdentity, allocation: Sc
 export declare function readInventory(root: URL | string, targets: readonly string[], options?: InventoryOptions): Readonly<Record<string, string>>;
 
 /**
- * The attempts `removeTree` makes before rethrowing a retryable removal error.
+ * Caps the attempts `removeTree` makes before rethrowing a retryable removal error.
  */
 export declare const REMOVE_TREE_MAX_ATTEMPTS = 10;
 
 /**
- * The synchronous delay, in milliseconds, `removeTree` waits between attempts.
+ * Names the synchronous delay, in milliseconds, `removeTree` waits between attempts.
  */
 export declare const REMOVE_TREE_RETRY_DELAY_MS = 100;
 
 /**
- * The error codes `removeTree` retries; every other code rethrows immediately.
+ * Names the error codes `removeTree` retries; every other code rethrows immediately.
  */
 export declare const REMOVE_TREE_RETRYABLE_CODES: readonly string[];
 
@@ -248,6 +271,20 @@ export declare function removeTree(path: string): void;
  */
 export declare function requestUpgrade(port: number, options?: UpgradeOptions): Promise<UpgradeResult>;
 
+/**
+ * Resolves a target that stays below a root directory, refusing an escape.
+ *
+ * @param root - The absolute root directory.
+ * @param target - The relative or absolute target to resolve.
+ * @returns The absolute target below the root.
+ * @throws An `Error` reading `Path outside scratch directory: <target>` when the target escapes the
+ * root.
+ * @remarks This is {@link resolveContained} with the refusal every contained scratch operation makes
+ * of an escape, so the check and its one message are stated once. Read `resolveContained` where an
+ * escape is an answer rather than a refusal.
+ */
+export declare function requireContained(root: string, target: string): string;
+
 /**
  * Resolves a target that stays below a root directory.
  *
@@ -257,19 +294,19 @@ export declare function requestUpgrade(port: number, options?: UpgradeOptions):
  */
 export declare function resolveContained(root: string, target: string): string | undefined;
 
-/** The fields that together identify one allocated directory on its host. */
+/** Represents the fields that together identify one allocated directory on its host. */
 export declare interface ScratchIdentity {
-    /** The identifier of the device holding the directory. */
+    /** Holds the identifier of the device holding the directory. */
     readonly device: number;
-    /** The number of the directory's index node on that device. */
+    /** Holds the number of the directory's index node on that device. */
     readonly inode: number;
-    /** The directory's creation time in milliseconds. */
+    /** Holds the directory's creation time in milliseconds. */
     readonly birth: number;
 }
 
-/** A temporary directory a test owns, writes into, reads back, and removes when it is done. */
+/** Holds a temporary directory a test owns, writes into, reads back, and removes when it is done. */
 export declare interface ScratchInterface {
-    /** The absolute path of the allocated directory. */
+    /** Holds the absolute path of the allocated directory. */
     readonly path: string;
     /**
      * Writes a file, creating each parent directory that does not exist.
@@ -296,15 +333,16 @@ export declare interface ScratchInterface {
      * Reports whether a path exists without following its final symbolic link.
      *
      * @param target - A relative or absolute path contained by the scratch directory.
-     * @returns True when the entry exists, including a symbolic link whose target is missing.
+     * @returns True if the entry exists, including a symbolic link whose target is
+     * missing; false otherwise.
      * @throws When the path escapes the scratch directory or its root is a symbolic link or file.
      */
     has(target: string): boolean;
     /**
      * Lists the names directly inside a directory in sorted order.
      *
-     * @param target - A relative or absolute directory path contained by the scratch directory. The
-     * scratch root is used when omitted.
+     * @param target - A relative or absolute directory path contained by the scratch directory.
+     * Default: the scratch root.
      * @returns The sorted entry names, without their parent paths.
      * @throws When the path escapes the scratch directory, the target is missing or is not a
      * directory, or the scratch root is a symbolic link or file.
@@ -353,23 +391,23 @@ export declare interface ScratchInterface {
     destroy(): void;
 }
 
-/** Options for allocating a scratch directory. */
+/** Configures a scratch directory allocation. */
 export declare interface ScratchOptions {
     /**
-     * The existing directory in which to create the allocation. Defaults to the host temporary
+     * Names the existing directory in which to create the allocation. Defaults to the host temporary
      * directory. Allocation throws when this path is missing, a symbolic link, or not a directory.
      */
     readonly parent?: string;
     /**
-     * The name fragment that starts the generated directory name. Allocation throws when this value
-     * contains `/` or `\`. Both are refused on every host, so the rule does not vary by host. A
+     * Holds the name fragment that starts the generated directory name. Allocation throws when this
+     * value contains `/` or `\`. Both are refused on every host, so the rule does not vary by host. A
      * fragment carrying no separator is one path segment and cannot steer the allocation, so
      * `release-0..2-` allocates.
      */
     readonly prefix?: string;
     /**
-     * Files to write on allocation, keyed by path below the scratch directory. Allocation removes its
-     * directory and rethrows when a key escapes or the host refuses a write.
+     * Holds the files to write on allocation, keyed by path below the scratch directory. Allocation
+     * removes its directory and rethrows when a key escapes or the host refuses a write.
      */
     readonly files?: Readonly<Record<string, string>>;
 }
@@ -449,23 +487,23 @@ export declare function supportsFileLinks(): boolean;
 export declare function supportsMode(): boolean;
 
 /**
- * Options for driving a client upgrade request.
+ * Configures a client upgrade request.
  *
  * @remarks The time bounds and abort signal bound the wait for the server's answer, so a server
  * that accepts the connection and never answers ends the call rather than parking it.
  */
 export declare interface UpgradeOptions extends WaitOptions {
-    /** The request path, written with its leading slash. Defaults to `/`. */
+    /** Names the request path, written with its leading slash. Defaults to `/`. */
     readonly path?: string;
     /**
-     * The subprotocol tokens the request offers. They are sent as one comma-separated
+     * Lists the subprotocol tokens the request offers. They are sent as one comma-separated
      * `Sec-WebSocket-Protocol` field, and an empty or omitted list sends no field at all.
      */
     readonly protocols?: readonly string[];
 }
 
 /**
- * What one server did with a client upgrade request.
+ * Represents what one server did with a client upgrade request.
  *
  * @remarks `claimed` is the discriminant. The claimed arm carries `protocol`, the subprotocol the
  * server selected, which is `undefined` when it selected none; a claimed upgrade produced no plain