@orkestrel/process 0.0.3 → 0.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -17
- package/dist/src/core/index.cjs +31 -6
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +197 -151
- package/dist/src/core/index.d.ts +197 -151
- package/dist/src/core/index.js +31 -7
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +560 -370
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +270 -131
- package/dist/src/server/index.d.ts +270 -131
- package/dist/src/server/index.js +554 -369
- package/dist/src/server/index.js.map +1 -1
- package/package.json +16 -6
package/README.md
CHANGED
|
@@ -1,19 +1,20 @@
|
|
|
1
1
|
# @orkestrel/process
|
|
2
2
|
|
|
3
|
-
A typed **child-process toolkit** in
|
|
3
|
+
A typed **child-process toolkit** in tiers. `Process` supervises one
|
|
4
4
|
child: stdout is framed into lines under a bounded backlog, stderr is forwarded
|
|
5
5
|
live and kept as a byte-bounded tail, stdin is a writable channel, and
|
|
6
6
|
termination is bounded and reports whether the real exit arrived — `SIGTERM` then
|
|
7
7
|
`SIGKILL` after a grace window on a POSIX host, a whole-tree kill on Windows.
|
|
8
|
-
`
|
|
9
|
-
|
|
10
|
-
`
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
8
|
+
`execute` and `executeSync` buffer a child to completion and settle with an
|
|
9
|
+
`ExecuteResult` carrying the captured output, the exit, and `failed` /
|
|
10
|
+
`expired` / `aborted` / `truncated`, rejecting with a `ProcessError` by default
|
|
11
|
+
or resolving the result when you pass `strict: false`. `ProcessManager` is a
|
|
12
|
+
keyed registry of live children: `launch` spawns and registers by id, a settled
|
|
13
|
+
child evicts itself with no polling, and `stop` terminates one id, a list, or
|
|
14
|
+
every child. `Process` and `ProcessManager` expose typed `emitter` properties.
|
|
15
|
+
`Process`, `launch`, and `execute` take an `AbortSignal` that terminates the
|
|
16
|
+
child; `executeSync` and `detach` take none. No spawn uses a shell, so a
|
|
17
|
+
metacharacter in an argument is data rather than syntax. The contracts are
|
|
17
18
|
host-independent and ship from `@orkestrel/process`; the Node engine ships from
|
|
18
19
|
`@orkestrel/process/server`. Part of the `@orkestrel` line.
|
|
19
20
|
|
|
@@ -27,14 +28,15 @@ npm install @orkestrel/process
|
|
|
27
28
|
|
|
28
29
|
- Node.js >= 22.12.0
|
|
29
30
|
- ESM and CommonJS builds
|
|
31
|
+
- TypeScript `moduleResolution` set to `node16`, `nodenext`, or `bundler`
|
|
30
32
|
|
|
31
33
|
## Usage
|
|
32
34
|
|
|
33
35
|
```ts
|
|
34
|
-
import {
|
|
36
|
+
import { execute } from '@orkestrel/process/server'
|
|
35
37
|
|
|
36
38
|
// One-shot: buffer a command to completion and read its output and exit.
|
|
37
|
-
const { stdout } = await
|
|
39
|
+
const { stdout } = await execute({ file: 'node', arguments: ['--version'] })
|
|
38
40
|
console.log(stdout.trim()) // for example, "v22.12.0"
|
|
39
41
|
```
|
|
40
42
|
|
|
@@ -55,16 +57,16 @@ await child.destroy()
|
|
|
55
57
|
|
|
56
58
|
## Guide
|
|
57
59
|
|
|
58
|
-
For the full surface — the supervised `Process`, the `
|
|
59
|
-
spawns, the keyed `ProcessManager`, the observable `emitter`, the
|
|
60
|
-
failure type, and the lower-level helpers — see
|
|
60
|
+
For the full surface — the supervised `Process`, the `execute` / `executeSync` /
|
|
61
|
+
`detach` spawns, the keyed `ProcessManager`, the observable `emitter`, the
|
|
62
|
+
`ProcessError` failure type, and the lower-level helpers — see
|
|
61
63
|
[`guides/process.md`](guides/process.md).
|
|
62
64
|
|
|
63
65
|
## Package
|
|
64
66
|
|
|
65
|
-
|
|
67
|
+
Typed entry points per the `exports` field in `package.json`: the
|
|
66
68
|
host-independent contracts, constants, errors, and `isProcessError` guard from
|
|
67
|
-
`@orkestrel/process`, and the Node engine — `Process`, `
|
|
69
|
+
`@orkestrel/process`, and the Node engine — `Process`, `execute`, `executeSync`,
|
|
68
70
|
`detach`, `ProcessManager`, and their factories and helpers — from
|
|
69
71
|
`@orkestrel/process/server`.
|
|
70
72
|
|
package/dist/src/core/index.cjs
CHANGED
|
@@ -15,6 +15,14 @@ var PROCESS_OUTPUT = 10485760;
|
|
|
15
15
|
var PROCESS_TIMER = 2147483647;
|
|
16
16
|
/** The executable extensions a Windows lookup applies when the environment declares no `PATHEXT`. */
|
|
17
17
|
var PROCESS_PATHEXT = ".COM;.EXE;.BAT;.CMD";
|
|
18
|
+
/** The machine-readable failure categories a {@link ProcessError} carries, in declaration order. */
|
|
19
|
+
var PROCESS_ERROR_CODES = Object.freeze([
|
|
20
|
+
"spawn",
|
|
21
|
+
"timeout",
|
|
22
|
+
"duplicate",
|
|
23
|
+
"protocol",
|
|
24
|
+
"invalid"
|
|
25
|
+
]);
|
|
18
26
|
//#endregion
|
|
19
27
|
//#region src/core/errors.ts
|
|
20
28
|
/** A child-process failure with a stable machine-readable category. */
|
|
@@ -33,6 +41,7 @@ var ProcessError = class extends Error {
|
|
|
33
41
|
constructor(message, options) {
|
|
34
42
|
const cause = options.cause;
|
|
35
43
|
super(message, cause === void 0 ? void 0 : { cause });
|
|
44
|
+
Object.defineProperty(this, Symbol.for("@orkestrel/process.error"), { value: true });
|
|
36
45
|
this.code = options.code;
|
|
37
46
|
if (options.context !== void 0) this.context = options.context;
|
|
38
47
|
if (options.result !== void 0) this.result = options.result;
|
|
@@ -41,6 +50,13 @@ var ProcessError = class extends Error {
|
|
|
41
50
|
/**
|
|
42
51
|
* Checks whether an unknown value is a {@link ProcessError}.
|
|
43
52
|
*
|
|
53
|
+
* @remarks
|
|
54
|
+
* Recognition combines a global own-property brand with the native `Error` base, the subclass
|
|
55
|
+
* prototype, the fixed name, and a code {@link PROCESS_ERROR_CODES} declares. The brand is
|
|
56
|
+
* recognized across duplicate installations and ESM/CommonJS module copies at 0.0.4 or later. A copy
|
|
57
|
+
* earlier than 0.0.4 stamps no brand, so an error it throws stays outside the type, and so does a
|
|
58
|
+
* plain or property-only lookalike.
|
|
59
|
+
*
|
|
44
60
|
* @param value - The value to inspect
|
|
45
61
|
* @returns True only for a `ProcessError` instance; false otherwise
|
|
46
62
|
*
|
|
@@ -51,7 +67,14 @@ var ProcessError = class extends Error {
|
|
|
51
67
|
* ```
|
|
52
68
|
*/
|
|
53
69
|
function isProcessError(value) {
|
|
54
|
-
|
|
70
|
+
if (!(0, _orkestrel_contract.isError)(value)) return false;
|
|
71
|
+
return (0, _orkestrel_contract.holds)(() => {
|
|
72
|
+
if (Object.getPrototypeOf(value) === Error.prototype) return false;
|
|
73
|
+
if (value.name !== "ProcessError" || !("code" in value)) return false;
|
|
74
|
+
if (Object.getOwnPropertyDescriptor(value, Symbol.for("@orkestrel/process.error"))?.value !== true) return false;
|
|
75
|
+
const code = value.code;
|
|
76
|
+
return PROCESS_ERROR_CODES.some((declared) => declared === code);
|
|
77
|
+
});
|
|
55
78
|
}
|
|
56
79
|
/**
|
|
57
80
|
* Creates the failure raised when a manager launch reuses a live id.
|
|
@@ -99,14 +122,15 @@ function createInvalidError(subject, value) {
|
|
|
99
122
|
* Creates the failure raised when a run does not complete successfully and rejection is requested.
|
|
100
123
|
*
|
|
101
124
|
* @remarks
|
|
102
|
-
* The category is `timeout` only when the run's own timeout elapsed; every other failure,
|
|
103
|
-
* an abort and an output overflow, is a `spawn` failure carrying its
|
|
125
|
+
* The category is `timeout` only when the run's own timeout elapsed; every other failure,
|
|
126
|
+
* including an abort and an output overflow, is a `spawn` failure carrying its
|
|
127
|
+
* {@link ExecuteResult}.
|
|
104
128
|
*
|
|
105
129
|
* @param result - The buffered run outcome that failed
|
|
106
130
|
* @param cause - The underlying host fault, when one ended the run
|
|
107
|
-
* @returns A typed run failure carrying its {@link
|
|
131
|
+
* @returns A typed run failure carrying its {@link ExecuteResult}
|
|
108
132
|
*/
|
|
109
|
-
function
|
|
133
|
+
function createExecuteError(result, cause) {
|
|
110
134
|
let reason = `exited with code ${String(result.code)}`;
|
|
111
135
|
if (result.signal !== null) reason = `was killed by ${result.signal}`;
|
|
112
136
|
if (result.truncated) reason = "exceeded its output limit";
|
|
@@ -126,6 +150,7 @@ function createRunError(result, cause) {
|
|
|
126
150
|
//#endregion
|
|
127
151
|
exports.PROCESS_BACKLOG = PROCESS_BACKLOG;
|
|
128
152
|
exports.PROCESS_CONFIRMATION = PROCESS_CONFIRMATION;
|
|
153
|
+
exports.PROCESS_ERROR_CODES = PROCESS_ERROR_CODES;
|
|
129
154
|
exports.PROCESS_EVIDENCE = PROCESS_EVIDENCE;
|
|
130
155
|
exports.PROCESS_GRACE = PROCESS_GRACE;
|
|
131
156
|
exports.PROCESS_OUTPUT = PROCESS_OUTPUT;
|
|
@@ -133,9 +158,9 @@ exports.PROCESS_PATHEXT = PROCESS_PATHEXT;
|
|
|
133
158
|
exports.PROCESS_TIMER = PROCESS_TIMER;
|
|
134
159
|
exports.ProcessError = ProcessError;
|
|
135
160
|
exports.createDuplicateError = createDuplicateError;
|
|
161
|
+
exports.createExecuteError = createExecuteError;
|
|
136
162
|
exports.createInvalidError = createInvalidError;
|
|
137
163
|
exports.createProtocolError = createProtocolError;
|
|
138
|
-
exports.createRunError = createRunError;
|
|
139
164
|
exports.isProcessError = isProcessError;
|
|
140
165
|
|
|
141
166
|
//# sourceMappingURL=index.cjs.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.cjs","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
|
|
1
|
+
{"version":3,"file":"index.cjs","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,EAAA,GAAC,oBAAA,QAAA,CAAQ,KAAK,GAAG,OAAO;CAC5B,QAAA,GAAO,oBAAA,MAAA,OAAY;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"}
|