@orkestrel/process 0.0.2 → 0.0.4

package/dist/src/core/index.js

@@ -1,11 +1,27 @@
-import { holds } from "@orkestrel/contract";
+import { holds, isError } from "@orkestrel/contract";
 //#region src/core/constants.ts
-/** The default cooperative window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
+/** The default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */
 var PROCESS_GRACE = 5e3;
+/** The window in milliseconds a termination waits for the child's native exit after the final kill. */
+var PROCESS_CONFIRMATION = 5e3;
 /** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */
 var PROCESS_EVIDENCE = 2048;
+/** The default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */
+var PROCESS_BACKLOG = 10485760;
 /** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */
 var PROCESS_OUTPUT = 10485760;
+/** The largest timer delay in milliseconds the host schedules without truncating it to one. */
+var PROCESS_TIMER = 2147483647;
+/** The executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
+var PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+/** The machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
+var PROCESS_ERROR_CODES = Object.freeze([
+	"spawn",
+	"timeout",
+	"duplicate",
+	"protocol",
+	"invalid"
+]);
 //#endregion
 //#region src/core/errors.ts
 /** A child-process failure with a stable machine-readable category. */
@@ -24,6 +40,7 @@ var ProcessError = class extends Error {
 	constructor(message, options) {
 		const cause = options.cause;
 		super(message, cause === void 0 ? void 0 : { cause });
+		Object.defineProperty(this, Symbol.for("@orkestrel/process.error"), { value: true });
 		this.code = options.code;
 		if (options.context !== void 0) this.context = options.context;
 		if (options.result !== void 0) this.result = options.result;
@@ -32,6 +49,13 @@ var ProcessError = class extends Error {
 /**
 * Checks whether an unknown value is a {@link ProcessError}.
 *
+* @remarks
+* Recognition combines a global own-property brand with the native `Error` base, the subclass
+* prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is
+* recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy
+* earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a
+* plain or property-only lookalike.
+*
 * @param value - The value to inspect
 * @returns True only for a `ProcessError` instance; false otherwise
 *
@@ -42,7 +66,14 @@ var ProcessError = class extends Error {
 * ```
 */
 function isProcessError(value) {
-	return holds(() => value instanceof ProcessError);
+	if (!isError(value)) return false;
+	return holds(() => {
+		if (Object.getPrototypeOf(value) === Error.prototype) return false;
+		if (value.name !== "ProcessError" || !("code" in value)) return false;
+		if (Object.getOwnPropertyDescriptor(value, Symbol.for("@orkestrel/process.error"))?.value !== true) return false;
+		const code = value.code;
+		return PROCESS_ERROR_CODES.some((declared) => declared === code);
+	});
 }
 /**
 * Creates the failure raised when a manager launch reuses a live id.
@@ -57,16 +88,55 @@ function createDuplicateError(id) {
 	});
 }
 /**
+* Creates the failure raised when a launch is attempted on a registry that is being destroyed.
+*
+* @param id - The id the refused launch asked for
+* @returns A typed protocol failure
+*/
+function createProtocolError(id) {
+	return new ProcessError(`Process '${id}' cannot launch: the registry is destroyed`, {
+		code: "protocol",
+		context: { id }
+	});
+}
+/**
+* Creates the failure raised when a public input is refused before anything is spawned.
+*
+* @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`
+* @param value - The rejected value, carried as `context.value`
+* @returns A typed validation failure
+*
+* @example
+* ```ts
+* createInvalidError("option 'grace'", -1).code // 'invalid'
+* ```
+*/
+function createInvalidError(subject, value) {
+	return new ProcessError(`Invalid ${subject}`, {
+		code: "invalid",
+		context: { value }
+	});
+}
+/**
 * Creates the failure raised when a run does not complete successfully and rejection is requested.
 *
+* @remarks
+* The category is `timeout` only when the run's own timeout elapsed; every other failure,
+* including an abort and an output overflow, is a `spawn` failure carrying its
+* {@link ExecuteResult}.
+*
 * @param result - The buffered run outcome that failed
-* @param cause - The underlying spawn error, when one ended the run
-* @returns A typed run failure carrying its {@link RunResult}
+* @param cause - The underlying host fault, when one ended the run
+* @returns A typed run failure carrying its {@link ExecuteResult}
 */
-function createRunError(result, cause) {
-	const reason = result.timedOut ? "timed out" : result.signal !== null ? `was killed by ${result.signal}` : `exited with code ${String(result.code)}`;
+function createExecuteError(result, cause) {
+	let reason = `exited with code ${String(result.code)}`;
+	if (result.signal !== null) reason = `was killed by ${result.signal}`;
+	if (result.truncated) reason = "exceeded its output limit";
+	if (result.aborted) reason = "was aborted";
+	if (result.expired) reason = "timed out";
 	return new ProcessError(`Command '${result.command}' ${reason}`, {
-		code: result.timedOut ? "timeout" : "spawn",
+		code: result.expired ? "timeout" : "spawn",
 		context: {
 			command: result.command,
 			code: result.code,
@@ -77,6 +147,6 @@ function createRunError(result, cause) {
 	});
 }
 //#endregion
-export { PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, ProcessError, createDuplicateError, createRunError, isProcessError };
+export { PROCESS_BACKLOG, PROCESS_CONFIRMATION, PROCESS_ERROR_CODES, PROCESS_EVIDENCE, PROCESS_GRACE, PROCESS_OUTPUT, PROCESS_PATHEXT, PROCESS_TIMER, ProcessError, createDuplicateError, createExecuteError, createInvalidError, createProtocolError, isProcessError };
 
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** The default cooperative window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */\nexport const PROCESS_OUTPUT = 10_485_760\n","import { holds } from '@orkestrel/contract'\nimport type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tRunResult,\n} from './types.js'\n\n/** A child-process failure with a stable machine-readable category. */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** The buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: RunResult\n\n\t/**\n\t * Create a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @param value - The value to inspect\n * @returns True only for a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\treturn holds(() => value instanceof ProcessError)\n}\n\n/**\n * Creates the failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @param result - The buffered run outcome that failed\n * @param cause - The underlying spawn error, when one ended the run\n * @returns A typed run failure carrying its {@link RunResult}\n */\nexport function createRunError(result: RunResult, cause?: unknown): ProcessError {\n\tconst reason = result.timedOut\n\t\t? 'timed out'\n\t\t: result.signal !== null\n\t\t\t? `was killed by ${result.signal}`\n\t\t\t: `exited with code ${String(result.code)}`\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.timedOut ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\t...(cause === undefined ? {} : { cause }),\n\t\tresult,\n\t})\n}\n"],"mappings":";;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,mBAAmB;;AAGhC,IAAa,iBAAiB;;;;ACE9B,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;AAcA,SAAgB,eAAe,OAAuC;CACrE,OAAO,YAAY,iBAAiB,YAAY;AACjD;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;AASA,SAAgB,eAAe,QAAmB,OAA+B;CAChF,MAAM,SAAS,OAAO,WACnB,cACA,OAAO,WAAW,OACjB,iBAAiB,OAAO,WACxB,oBAAoB,OAAO,OAAO,IAAI;CAC1C,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,WAAW,YAAY;EACpC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;EACvC;CACD,CAAC;AACF"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts"],"sourcesContent":["/** The default cooperative POSIX window in milliseconds between `SIGTERM` and `SIGKILL` during termination. */\nexport const PROCESS_GRACE = 5_000\n\n/** The window in milliseconds a termination waits for the child's native exit after the final kill. */\nexport const PROCESS_CONFIRMATION = 5_000\n\n/** The default maximum retained stderr tail in bytes for a supervised {@link ProcessInterface}. */\nexport const PROCESS_EVIDENCE = 2_048\n\n/** The default soft high-water mark in bytes for a supervised {@link ProcessInterface} line backlog. */\nexport const PROCESS_BACKLOG = 10_485_760\n\n/** The default maximum captured bytes for a one-shot run's stdout and stderr, each. */\nexport const PROCESS_OUTPUT = 10_485_760\n\n/** The largest timer delay in milliseconds the host schedules without truncating it to one. */\nexport const PROCESS_TIMER = 2_147_483_647\n\n/** The executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */\nexport const PROCESS_PATHEXT = '.COM;.EXE;.BAT;.CMD'\n\n/** The machine-readable failure categories a {@link ProcessError} carries, in declaration order. */\nexport const PROCESS_ERROR_CODES = Object.freeze([\n\t'spawn',\n\t'timeout',\n\t'duplicate',\n\t'protocol',\n\t'invalid',\n] as const)\n","import type {\n\tProcessErrorCode,\n\tProcessErrorContext,\n\tProcessErrorOptions,\n\tExecuteResult,\n} from './types.js'\nimport { holds, isError } from '@orkestrel/contract'\nimport { PROCESS_ERROR_CODES } from './constants.js'\n\n/** A child-process failure with a stable machine-readable category. */\nexport class ProcessError extends Error {\n\toverride readonly name = 'ProcessError'\n\treadonly code: ProcessErrorCode\n\treadonly context?: ProcessErrorContext\n\t/** The buffered run outcome, present when a one-shot run produced the failure. */\n\treadonly result?: ExecuteResult\n\n\t/**\n\t * Create a process error.\n\t *\n\t * @param message - Human-readable failure description\n\t * @param options - Machine-readable category, optional context, optional cause, and optional run result\n\t */\n\tconstructor(message: string, options: ProcessErrorOptions) {\n\t\tconst cause = options.cause\n\t\tsuper(message, cause === undefined ? undefined : { cause })\n\t\tObject.defineProperty(this, Symbol.for('@orkestrel/process.error'), { value: true })\n\t\tthis.code = options.code\n\t\tif (options.context !== undefined) this.context = options.context\n\t\tif (options.result !== undefined) this.result = options.result\n\t}\n}\n\n/**\n * Checks whether an unknown value is a {@link ProcessError}.\n *\n * @remarks\n * Recognition combines a global own-property brand with the native `Error` base, the subclass\n * prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is\n * recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy\n * earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a\n * plain or property-only lookalike.\n *\n * @param value - The value to inspect\n * @returns True only for a `ProcessError` instance; false otherwise\n *\n * @example\n * ```ts\n * isProcessError(new ProcessError('spawn failed', { code: 'spawn' })) // true\n * isProcessError(new Error('spawn failed')) // false\n * ```\n */\nexport function isProcessError(value: unknown): value is ProcessError {\n\tif (!isError(value)) return false\n\treturn holds(() => {\n\t\tif (Object.getPrototypeOf(value) === Error.prototype) return false\n\t\tif (value.name !== 'ProcessError' || !('code' in value)) return false\n\t\tconst descriptor = Object.getOwnPropertyDescriptor(\n\t\t\tvalue,\n\t\t\tSymbol.for('@orkestrel/process.error'),\n\t\t)\n\t\tif (descriptor?.value !== true) return false\n\t\tconst code: unknown = value.code\n\t\treturn PROCESS_ERROR_CODES.some((declared) => declared === code)\n\t})\n}\n\n/**\n * Creates the failure raised when a manager launch reuses a live id.\n *\n * @param id - The id already occupied by a live child\n * @returns A typed duplicate-id failure\n */\nexport function createDuplicateError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' is already live`, {\n\t\tcode: 'duplicate',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a launch is attempted on a registry that is being destroyed.\n *\n * @param id - The id the refused launch asked for\n * @returns A typed protocol failure\n */\nexport function createProtocolError(id: string): ProcessError {\n\treturn new ProcessError(`Process '${id}' cannot launch: the registry is destroyed`, {\n\t\tcode: 'protocol',\n\t\tcontext: { id },\n\t})\n}\n\n/**\n * Creates the failure raised when a public input is refused before anything is spawned.\n *\n * @param subject - The rejected input named as the caller wrote it, such as `option 'grace'`\n * @param value - The rejected value, carried as `context.value`\n * @returns A typed validation failure\n *\n * @example\n * ```ts\n * createInvalidError(\"option 'grace'\", -1).code // 'invalid'\n * ```\n */\nexport function createInvalidError(subject: string, value: unknown): ProcessError {\n\treturn new ProcessError(`Invalid ${subject}`, { code: 'invalid', context: { value } })\n}\n\n/**\n * Creates the failure raised when a run does not complete successfully and rejection is requested.\n *\n * @remarks\n * The category is `timeout` only when the run's own timeout elapsed; every other failure,\n * including an abort and an output overflow, is a `spawn` failure carrying its\n * {@link ExecuteResult}.\n *\n * @param result - The buffered run outcome that failed\n * @param cause - The underlying host fault, when one ended the run\n * @returns A typed run failure carrying its {@link ExecuteResult}\n */\nexport function createExecuteError(result: ExecuteResult, cause?: unknown): ProcessError {\n\tlet reason = `exited with code ${String(result.code)}`\n\tif (result.signal !== null) reason = `was killed by ${result.signal}`\n\tif (result.truncated) reason = 'exceeded its output limit'\n\tif (result.aborted) reason = 'was aborted'\n\tif (result.expired) reason = 'timed out'\n\treturn new ProcessError(`Command '${result.command}' ${reason}`, {\n\t\tcode: result.expired ? 'timeout' : 'spawn',\n\t\tcontext: { command: result.command, code: result.code, signal: result.signal },\n\t\t...(cause === undefined ? {} : { cause }),\n\t\tresult,\n\t})\n}\n"],"mappings":";;;AACA,IAAa,gBAAgB;;AAG7B,IAAa,uBAAuB;;AAGpC,IAAa,mBAAmB;;AAGhC,IAAa,kBAAkB;;AAG/B,IAAa,iBAAiB;;AAG9B,IAAa,gBAAgB;;AAG7B,IAAa,kBAAkB;;AAG/B,IAAa,sBAAsB,OAAO,OAAO;CAChD;CACA;CACA;CACA;CACA;AACD,CAAU;;;;AClBV,IAAa,eAAb,cAAkC,MAAM;CACvC,OAAyB;CACzB;CACA;;CAEA;;;;;;;CAQA,YAAY,SAAiB,SAA8B;EAC1D,MAAM,QAAQ,QAAQ;EACtB,MAAM,SAAS,UAAU,KAAA,IAAY,KAAA,IAAY,EAAE,MAAM,CAAC;EAC1D,OAAO,eAAe,MAAM,OAAO,IAAI,0BAA0B,GAAG,EAAE,OAAO,KAAK,CAAC;EACnF,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,WAAW,KAAA,GAAW,KAAK,SAAS,QAAQ;CACzD;AACD;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,eAAe,OAAuC;CACrE,IAAI,CAAC,QAAQ,KAAK,GAAG,OAAO;CAC5B,OAAO,YAAY;EAClB,IAAI,OAAO,eAAe,KAAK,MAAM,MAAM,WAAW,OAAO;EAC7D,IAAI,MAAM,SAAS,kBAAkB,EAAE,UAAU,QAAQ,OAAO;EAKhE,IAJmB,OAAO,yBACzB,OACA,OAAO,IAAI,0BAA0B,CAElC,CAAA,EAAY,UAAU,MAAM,OAAO;EACvC,MAAM,OAAgB,MAAM;EAC5B,OAAO,oBAAoB,MAAM,aAAa,aAAa,IAAI;CAChE,CAAC;AACF;;;;;;;AAQA,SAAgB,qBAAqB,IAA0B;CAC9D,OAAO,IAAI,aAAa,YAAY,GAAG,oBAAoB;EAC1D,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;AAQA,SAAgB,oBAAoB,IAA0B;CAC7D,OAAO,IAAI,aAAa,YAAY,GAAG,6CAA6C;EACnF,MAAM;EACN,SAAS,EAAE,GAAG;CACf,CAAC;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,SAAiB,OAA8B;CACjF,OAAO,IAAI,aAAa,WAAW,WAAW;EAAE,MAAM;EAAW,SAAS,EAAE,MAAM;CAAE,CAAC;AACtF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,QAAuB,OAA+B;CACxF,IAAI,SAAS,oBAAoB,OAAO,OAAO,IAAI;CACnD,IAAI,OAAO,WAAW,MAAM,SAAS,iBAAiB,OAAO;CAC7D,IAAI,OAAO,WAAW,SAAS;CAC/B,IAAI,OAAO,SAAS,SAAS;CAC7B,IAAI,OAAO,SAAS,SAAS;CAC7B,OAAO,IAAI,aAAa,YAAY,OAAO,QAAQ,IAAI,UAAU;EAChE,MAAM,OAAO,UAAU,YAAY;EACnC,SAAS;GAAE,SAAS,OAAO;GAAS,MAAM,OAAO;GAAM,QAAQ,OAAO;EAAO;EAC7E,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;EACvC;CACD,CAAC;AACF"}