@orkestrel/process 0.0.9 → 0.0.10

package/dist/src/server/index.js

@@ -8,6 +8,42 @@ import { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_DRAIN, PROCESS_EVIDENCE,
 import { createInterface } from "node:readline";
 import { Emitter } from "@orkestrel/emitter";
 import { StringDecoder } from "node:string_decoder";
+//#region src/server/cloners.ts
+/**
+* Takes one owned frozen snapshot of a caller's command.
+*
+* @remarks
+* Every public entry point snapshots before it validates, so the object validated is the object
+* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
+* command whose `file` changes between reads would otherwise validate one executable and spawn
+* another. The argument vector and the environment record are copied and frozen, so a caller
+* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
+* becoming an explicit `undefined`.
+*
+* @param command - The caller's command, whose properties may be getters
+* @returns A frozen command carrying the values read at this instant
+*
+* @example
+* ```ts
+* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
+* ```
+*/
+function snapshotCommand(command) {
+	const file = command.file;
+	const argumentsList = Object.freeze([...command.arguments]);
+	const sourceEnvironment = command.environment;
+	const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
+	const input = command.input;
+	const isolated = command.isolated;
+	return Object.freeze({
+		file,
+		arguments: argumentsList,
+		...environment === void 0 ? {} : { environment },
+		...input === void 0 ? {} : { input },
+		...isolated === void 0 ? {} : { isolated }
+	});
+}
+//#endregion
 //#region src/server/helpers.ts
 /**
 * Trims a buffer to at most `limit` trailing bytes without splitting a UTF-8 sequence.
@@ -106,40 +142,6 @@ function captureChunk(chunk, room) {
 	return Buffer.from(chunk.subarray(0, room));
 }
 /**
-* Takes one owned frozen snapshot of a caller's command.
-*
-* @remarks
-* Every public entry point snapshots before it validates, so the object validated is the object
-* spawned. Each property is read exactly once, because reading one runs the caller's own getter: a
-* command whose `file` changes between reads would otherwise validate one executable and spawn
-* another. The argument vector and the environment record are copied and frozen, so a caller
-* mutating either after the call cannot reach the spawn. An absent optional stays absent rather than
-* becoming an explicit `undefined`.
-*
-* @param command - The caller's command, whose properties may be getters
-* @returns A frozen command carrying the values read at this instant
-*
-* @example
-* ```ts
-* snapshotCommand({ file: 'git', arguments: ['status'] }) // { file: 'git', arguments: ['status'] }
-* ```
-*/
-function snapshotCommand(command) {
-	const file = command.file;
-	const argumentsList = Object.freeze([...command.arguments]);
-	const sourceEnvironment = command.environment;
-	const environment = sourceEnvironment === void 0 ? void 0 : Object.freeze({ ...sourceEnvironment });
-	const input = command.input;
-	const isolated = command.isolated;
-	return Object.freeze({
-		file,
-		arguments: argumentsList,
-		...environment === void 0 ? {} : { environment },
-		...input === void 0 ? {} : { input },
-		...isolated === void 0 ? {} : { isolated }
-	});
-}
-/**
 * Renders one command into its diagnostic command line.
 *
 * @param command - The executable and its argument vector
@@ -256,7 +258,7 @@ function mergeEnvironment(isolated, base, override) {
 * command. An unreadable or malformed path reports `false` rather than throwing.
 *
 * @param target - The absolute or relative path to inspect
-* @returns True when the path resolves to a regular file; false otherwise
+* @returns True if the path resolves to a regular file; false otherwise
 *
 * @example
 * ```ts
@@ -529,7 +531,7 @@ function validateWorkspace(workspace) {
 * initiated against a pid the host may have reused.
 *
 * @param child - The child boundary
-* @returns True when the process has exited; false while it is live
+* @returns True if the process has exited; false otherwise
 *
 * @example
 * ```ts
@@ -585,7 +587,7 @@ function killProcess(child, signal) {
 *
 * @param pid - The root process id of the tree to end
 * @param timeout - The milliseconds the utility is given before it is killed
-* @returns True when the utility reported success; false when it failed, was unavailable, or was cut off
+* @returns True if the utility reported success; false otherwise (it failed, was unavailable, or was cut off)
 *
 * @example
 * ```ts
@@ -636,7 +638,7 @@ function waitForExit(child, timeout) {
 *
 * @param child - The child boundary
 * @param timeout - The milliseconds to wait before giving up
-* @returns True when the host close arrived inside the deadline; false otherwise
+* @returns True if the host close arrived inside the deadline; false otherwise
 *
 * @example
 * ```ts
@@ -671,7 +673,7 @@ function waitForClose(child, timeout) {
 * @param child - The child boundary
 * @param grace - The cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL`
 * @param confirm - The milliseconds the native exit is awaited after the final kill
-* @returns True when the native exit was observed; false when `confirm` elapsed without it
+* @returns True if the native exit was observed; false otherwise (`confirm` elapsed without it)
 *
 * @example
 * ```ts
@@ -1029,7 +1031,7 @@ function detach(command, options) {
 	child.unref();
 }
 //#endregion
-//#region src/server/Supervisor.ts
+//#region src/server/processes/Supervisor.ts
 /**
 * Supervises one child process and reports each lifecycle moment to the face composing it.
 *
@@ -1058,6 +1060,25 @@ function detach(command, options) {
 * termination completes. `relieve` is optional because a face that never pauses the child's output
 * holds no backpressure to release, and a face with nothing to do there would otherwise declare an
 * empty method to say so.
+*
+* @example
+* ```ts
+* import { Supervisor } from '@orkestrel/process/server'
+*
+* const engine = new Supervisor(
+* 	{ command: { file: 'node', arguments: ['--version'] }, workspace: process.cwd() },
+* 	{
+* 		chunk: () => undefined,
+* 		fault: () => undefined,
+* 		close: () => undefined,
+* 		terminal: () => undefined,
+* 		teardown: () => undefined,
+* 	},
+* )
+* const exit = await engine.exit
+* exit.code // 0
+* await engine.destroy()
+* ```
 */
 var Supervisor = class {
 	#chunk;
@@ -1087,7 +1108,7 @@ var Supervisor = class {
 	#termination;
 	#destruction;
 	/**
-	* Spawn one child process and begin standard-error capture.
+	* Spawns one child process and begins standard-error capture.
 	*
 	* @remarks
 	* The face's callbacks are captured before anything is read or spawned, so the first moment the
@@ -1164,36 +1185,36 @@ var Supervisor = class {
 			if (signal.aborted) this.stop();
 		}
 	}
-	/** The child's standard-output stream, for the composing face to attach its own consumer to. */
+	/** Holds the child's standard-output stream, for the composing face to attach its own consumer to. */
 	get stdout() {
 		return this.#child.stdout;
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#child.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#child.exitCode;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#child.signalCode;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#tail.toString("utf8");
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#settled;
 	}
-	/** True after termination began, including after the terminal moment. */
+	/** Reports whether termination began, including after the terminal moment. */
 	get stopping() {
 		return this.#stopping;
 	}
 	/**
-	* The child's own ending, awaited without the terminal moment's drain window.
+	* Settles at the child's own ending, awaited without the terminal moment's drain window.
 	*
 	* @remarks
 	* Never rejects, and resolves no value: `code` and `signal` carry the terminal facts as soon as
@@ -1203,7 +1224,7 @@ var Supervisor = class {
 	get ending() {
 		return this.#ending.promise;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#exit.promise;
 	}
@@ -1220,7 +1241,30 @@ var Supervisor = class {
 	* discard.
 	*
 	* @param bytes - The payload to write, already framed by the caller
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
+	*
+	* @example
+	* ```ts
+	* import { Supervisor } from '@orkestrel/process/server'
+	*
+	* const engine = new Supervisor(
+	* 	{
+	* 		command: { file: 'node', arguments: ['-e', 'process.stdin.pipe(process.stdout)'] },
+	* 		workspace: process.cwd(),
+	* 		writable: true,
+	* 	},
+	* 	{
+	* 		chunk: () => undefined,
+	* 		fault: () => undefined,
+	* 		close: () => undefined,
+	* 		terminal: () => undefined,
+	* 		teardown: () => undefined,
+	* 	},
+	* )
+	* const accepted = await engine.deliver(new TextEncoder().encode('ping\n'))
+	* accepted // true
+	* await engine.destroy()
+	* ```
 	*/
 	deliver(bytes) {
 		const stdin = this.#child.stdin;
@@ -1271,7 +1315,7 @@ var Supervisor = class {
 	* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
 	* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		if (this.#termination !== void 0) return this.#termination;
@@ -1399,7 +1443,7 @@ var Supervisor = class {
 	}
 };
 //#endregion
-//#region src/server/Process.ts
+//#region src/server/processes/Process.ts
 /**
 * Supervises one child while keeping every observation channel aligned at termination.
 *
@@ -1446,7 +1490,7 @@ var Process = class {
 	#truncated = false;
 	#ended = false;
 	/**
-	* Spawn one child process and begin stream capture.
+	* Spawns one child process and begins stream capture.
 	*
 	* @param options - Command, workspace, termination, capture, stdin, and observation settings
 	* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
@@ -1501,48 +1545,48 @@ var Process = class {
 		this.#reader.on("line", this.#push.bind(this));
 		this.#reader.once("close", this.#finish.bind(this));
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#engine.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#engine.code;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#engine.signal;
 	}
-	/** The typed lifecycle observation surface. */
+	/** Holds the typed lifecycle observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
+	/** Yields the captured stdout lines, in arrival order, ending after queued lines at the terminal moment. */
 	get lines() {
 		return this.#lines;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#engine.evidence;
 	}
-	/** True when the `lines` stream omitted output after a retention bound was reached. */
+	/** Reports whether the `lines` stream omitted output after a retention bound was reached. */
 	get truncated() {
 		return this.#truncated;
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#engine.settled;
 	}
-	/** True after termination began, including after the terminal moment. */
+	/** Reports whether termination began, including after the terminal moment. */
 	get stopping() {
 		return this.#engine.stopping;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#engine.exit;
 	}
 	/**
-	* Write one line to the open standard-input channel.
+	* Writes one line to the open standard-input channel.
 	*
 	* @remarks
 	* Never rejects. `true` means the host accepted the bytes without reporting a fault; it does not
@@ -1556,7 +1600,7 @@ var Process = class {
 	* for bytes the package is about to discard.
 	*
 	* @param text - The line text without its trailing newline
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
 	*/
 	send(text) {
 		return this.#engine.deliver(Buffer.from(`${text}\n`, "utf8"));
@@ -1570,7 +1614,7 @@ var Process = class {
 	* and settles `exit` when they remain open. A cutoff reached before the native exit reports the
 	* `code` and `signal` the host had recorded by then, which is `null` for a child still running.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		return this.#engine.stop();
@@ -1688,9 +1732,9 @@ var Process = class {
 	}
 };
 //#endregion
-//#region src/server/ProcessManager.ts
+//#region src/server/processes/ProcessManager.ts
 /**
-* A keyed registry of live supervised child processes.
+* Represents a keyed registry of live supervised child processes.
 *
 * @remarks
 * A child launched under an id joins the registry and emits `launch`; when it settles it removes
@@ -1726,7 +1770,7 @@ var ProcessManager = class {
 	#destroying = false;
 	#ending;
 	/**
-	* Construct a process registry.
+	* Constructs a process registry.
 	*
 	* @param options - Initial fleet-level observation hooks and listener-error handling
 	*/
@@ -1738,16 +1782,16 @@ var ProcessManager = class {
 			...error === void 0 ? {} : { error }
 		});
 	}
-	/** The typed fleet-level observation surface. */
+	/** Holds the typed fleet-level observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The number of live children. */
+	/** Counts the live children. */
 	get count() {
 		return this.#children.size;
 	}
 	/**
-	* The live child under `id`, or `undefined` when none is.
+	* Returns the live child under `id`, or `undefined` when none is.
 	*
 	* @param id - The registry key
 	* @returns The child, or `undefined`
@@ -1756,7 +1800,7 @@ var ProcessManager = class {
 		return this.#children.get(id);
 	}
 	/**
-	* A snapshot of every live child.
+	* Returns a snapshot of every live child.
 	*
 	* @returns The live children in launch order
 	*/
@@ -1764,7 +1808,7 @@ var ProcessManager = class {
 		return [...this.#children.values()];
 	}
 	/**
-	* Spawn and register one child under `id`.
+	* Spawns and registers one child under `id`.
 	*
 	* @remarks
 	* {@link Process} reads every option before it spawns, so a caller's own option getter runs while
@@ -1802,7 +1846,7 @@ var ProcessManager = class {
 		return this.#stopMany(target);
 	}
 	/**
-	* Stop every child, then destroy the registry emitter last.
+	* Stops every child, then destroys the registry emitter last.
 	*
 	* @remarks
 	* Always resolves, and refuses a later `launch` with a {@link createProtocolError}. Each child is
@@ -1855,7 +1899,7 @@ var ProcessManager = class {
 	}
 };
 //#endregion
-//#region src/server/Session.ts
+//#region src/server/processes/Session.ts
 /**
 * Supervises one child and publishes its standard output as raw bytes.
 *
@@ -1892,7 +1936,7 @@ var Session = class {
 	#engine;
 	#output;
 	/**
-	* Spawn one child process and begin byte capture.
+	* Spawns one child process and begins byte capture.
 	*
 	* @param options - Command, workspace, termination, evidence, stdin, and observation settings
 	* @throws A {@link ProcessError} coded `invalid` when an option or command string is malformed
@@ -1930,39 +1974,39 @@ var Session = class {
 		});
 		this.#engine.stdout.on("data", this.#output);
 	}
-	/** The host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
+	/** Holds the host process id, fixed when construction returns, or `undefined` when the spawn produced none. */
 	get pid() {
 		return this.#engine.pid;
 	}
-	/** The exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
+	/** Holds the exit code the host recorded, or `null` while the child has not exited and when a signal ended it. */
 	get code() {
 		return this.#engine.code;
 	}
-	/** The terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
+	/** Holds the terminating signal name the host recorded, or `null` while the child has not exited and when it exited on its own. */
 	get signal() {
 		return this.#engine.signal;
 	}
-	/** The typed lifecycle observation surface. */
+	/** Holds the typed lifecycle observation surface. */
 	get emitter() {
 		return this.#emitter;
 	}
-	/** The decoded byte-bounded stderr tail, frozen at the terminal moment. */
+	/** Holds the decoded byte-bounded stderr tail, frozen at the terminal moment. */
 	get evidence() {
 		return this.#engine.evidence;
 	}
-	/** True after the terminal moment arrived and `exit` settled. */
+	/** Reports whether the terminal moment arrived and `exit` settled. */
 	get settled() {
 		return this.#engine.settled;
 	}
-	/** True after termination began, including after the terminal moment. `end` never turns it true. */
+	/** Reports whether termination began, including after the terminal moment. `end` never turns it true. */
 	get stopping() {
 		return this.#engine.stopping;
 	}
-	/** The child's own ending, awaited without the terminal moment's drain window. */
+	/** Settles at the child's own ending, awaited without the terminal moment's drain window. */
 	get ending() {
 		return this.#engine.ending;
 	}
-	/** The terminal child state, observed once after stream close or the drain cutoff. */
+	/** Settles with the terminal child state, observed once after stream close or the drain cutoff. */
 	get exit() {
 		return this.#engine.exit;
 	}
@@ -1976,7 +2020,7 @@ var Session = class {
 	* returned promise settles.
 	*
 	* @param bytes - The payload to write, already framed by the caller
-	* @returns True when the host accepted the bytes without reporting a fault; false when the channel was closed, destroyed, ended, failed, or remained unconfirmed through `delivery`
+	* @returns True if the host accepted the bytes without reporting a fault; false otherwise (the channel was closed, destroyed, ended, failed, or the write remained unconfirmed through `delivery`)
 	*/
 	write(bytes) {
 		return this.#engine.deliver(bytes);
@@ -2000,7 +2044,7 @@ var Session = class {
 	* @remarks
 	* Never rejects, and every call shares one termination bounded by `grace` and `drain`.
 	*
-	* @returns True when the child's native exit was observed; false when the confirmation deadline elapsed without it
+	* @returns True if the child's native exit was observed; false otherwise (the confirmation deadline elapsed without it)
 	*/
 	stop() {
 		return this.#engine.stop();
@@ -2092,6 +2136,6 @@ function createProcessManager(options) {
 	return new ProcessManager(options);
 }
 //#endregion
-export { Process, ProcessManager, Session, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, captureChunk, createProcess, createProcessManager, createSession, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
+export { Process, ProcessManager, Session, Supervisor, buildExecutableCandidates, buildExecuteResult, buildPlatformSpawn, buildSpawn, captureChunk, createProcess, createProcessManager, createSession, detach, execute, executeSync, formatCommand, isExited, isFile, killProcess, killTree, mergeEnvironment, mergePlatformEnvironment, quoteArgument, readPlatformVariable, readVariable, resolveExecutable, snapshotCommand, stopChild, trimHead, trimTail, validateBytes, validateCommand, validateEnvironment, validateText, validateTimer, validateWorkspace, waitForClose, waitForExit };
 
 //# sourceMappingURL=index.js.map