@orkestrel/scaffold 0.0.115 → 0.0.117
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/dist/bin/main.js +138 -16
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
- package/dist/host/claude/agents/orkestrel.md +2 -2
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/guides/abort.md +17 -17
- package/dist/host/guides/agent.md +445 -445
- package/dist/host/guides/brief.md +143 -143
- package/dist/host/guides/browser.md +731 -731
- package/dist/host/guides/budget.md +39 -39
- package/dist/host/guides/capture.md +298 -298
- package/dist/host/guides/console.md +109 -109
- package/dist/host/guides/contract.md +335 -335
- package/dist/host/guides/csv.md +30 -30
- package/dist/host/guides/database.md +163 -163
- package/dist/host/guides/emitter.md +17 -17
- package/dist/host/guides/form.md +99 -99
- package/dist/host/guides/guide.md +368 -183
- package/dist/host/guides/html.md +49 -49
- package/dist/host/guides/indexeddb.md +40 -40
- package/dist/host/guides/interpret.md +139 -139
- package/dist/host/guides/lsp.md +114 -114
- package/dist/host/guides/markdown.md +68 -68
- package/dist/host/guides/mcp.md +3745 -3745
- package/dist/host/guides/middleware.md +170 -170
- package/dist/host/guides/msg.md +95 -95
- package/dist/host/guides/ndjson.md +8 -8
- package/dist/host/guides/ollama.md +56 -56
- package/dist/host/guides/pool.md +21 -21
- package/dist/host/guides/probe.md +82 -82
- package/dist/host/guides/process.md +99 -99
- package/dist/host/guides/program.md +98 -96
- package/dist/host/guides/qualifier.md +70 -70
- package/dist/host/guides/queue.md +37 -37
- package/dist/host/guides/rater.md +38 -38
- package/dist/host/guides/reason.md +308 -308
- package/dist/host/guides/relation.md +50 -50
- package/dist/host/guides/router.md +58 -58
- package/dist/host/guides/scaffold.md +558 -419
- package/dist/host/guides/sea.md +128 -128
- package/dist/host/guides/server.md +100 -100
- package/dist/host/guides/sqlite.md +28 -28
- package/dist/host/guides/sse.md +20 -20
- package/dist/host/guides/study.md +444 -444
- package/dist/host/guides/table.md +82 -82
- package/dist/host/guides/template.md +41 -41
- package/dist/host/guides/terminal.md +121 -121
- package/dist/host/guides/test.md +273 -273
- package/dist/host/guides/timeout.md +18 -18
- package/dist/host/guides/tool.md +27 -27
- package/dist/host/guides/toolbox.md +166 -166
- package/dist/host/guides/websocket.md +54 -54
- package/dist/host/guides/worker.md +24 -24
- package/dist/host/guides/workflow.md +187 -187
- package/dist/host/guides/workspace.md +55 -55
- package/dist/host/manifest.json +55 -55
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +90 -4
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +229 -144
- package/dist/src/core/index.d.ts +229 -144
- package/dist/src/core/index.js +88 -5
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +295 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +193 -6
- package/dist/src/server/index.d.ts +193 -6
- package/dist/src/server/index.js +290 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -4
|
@@ -41,79 +41,79 @@ Narrow the header before the call. `sec-websocket-key` is typed `string | undefi
|
|
|
41
41
|
|
|
42
42
|
### Factories
|
|
43
43
|
|
|
44
|
-
|
|
|
45
|
-
| --------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
-
| `createNodeWebSocket` | function | Creates a server-native WebSocket over a raw upgraded `node:stream` Duplex socket — server mode when a `key` is given, client mode otherwise. |
|
|
44
|
+
| Name | Kind | Signature | Summary |
|
|
45
|
+
| --------------------- | -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
+
| `createNodeWebSocket` | function | `(options: NodeWebSocketOptions) => NodeWebSocketInterface` | Creates a server-native WebSocket over a raw upgraded `node:stream` Duplex socket — server mode when a `key` is given, client mode otherwise. |
|
|
47
47
|
|
|
48
48
|
### Classes
|
|
49
49
|
|
|
50
|
-
|
|
|
51
|
-
| --------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
52
|
-
| `NodeWebSocket` | class | Implements the wrapper contract over a raw upgraded `node:stream` Duplex socket, driving the RFC 6455 handshake, the frame codec, auto-pong, and the close handshake, and surfacing every event on an owned `emitter`. |
|
|
50
|
+
| Name | Kind | Signature | Summary |
|
|
51
|
+
| --------------- | ----- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
52
|
+
| `NodeWebSocket` | class | `new (options: NodeWebSocketOptions) => NodeWebSocketInterface` | Implements the wrapper contract over a raw upgraded `node:stream` Duplex socket, driving the RFC 6455 handshake, the frame codec, auto-pong, and the close handshake, and surfacing every event on an owned `emitter`. |
|
|
53
53
|
|
|
54
54
|
### Errors
|
|
55
55
|
|
|
56
|
-
|
|
|
57
|
-
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
-
| `WebSocketError` | class | Represents an error the WebSocket wrapper throws for a refused caller-supplied value, carrying a machine-readable `code` and an optional `context`. |
|
|
59
|
-
| `isWebSocketError` | function | Checks whether a caught value is a `WebSocketError`, narrowing it so a `catch` can branch on `error.code`. |
|
|
56
|
+
| Name | Kind | Signature | Summary |
|
|
57
|
+
| ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
+
| `WebSocketError` | class | `new (code: WebSocketErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => WebSocketError` | Represents an error the WebSocket wrapper throws for a refused caller-supplied value, carrying a machine-readable `code` and an optional `context`. |
|
|
59
|
+
| `isWebSocketError` | function | `(value: unknown) => value is WebSocketError` | Checks whether a caught value is a `WebSocketError`, narrowing it so a `catch` can branch on `error.code`. |
|
|
60
60
|
|
|
61
61
|
### Codec helpers
|
|
62
62
|
|
|
63
|
-
|
|
|
64
|
-
| --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
65
|
-
| `computeWebSocketAccept` | function | Computes the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade. |
|
|
66
|
-
| `isWebSocketKey` | function | Checks whether a value is a canonical RFC 6455 `Sec-WebSocket-Key`. |
|
|
67
|
-
| `isWebSocketProtocol` | function | Checks whether a value is one valid WebSocket subprotocol token. |
|
|
68
|
-
| `parseWebSocketFrame` | function | Decodes a single RFC 6455 frame from the front of a buffer, answering `undefined` while the buffer is incomplete so the caller accumulates and retries. |
|
|
69
|
-
| `measureWebSocketFrame` | function | Reads the declared payload length off the front of a buffer without buffering or reading the payload itself, answering `undefined` until the length field is complete. |
|
|
70
|
-
| `matchesWebSocketCanonical` | function | Checks whether the next frame uses the shortest valid RFC 6455 payload-length encoding, answering `undefined` until its length prefix is complete. |
|
|
71
|
-
| `parseUTF8` | function | Decodes a byte sequence as strict UTF-8, answering `undefined` when the sequence is malformed. |
|
|
72
|
-
| `isCloseCode` | function | Checks whether a numeric value is a close status code an RFC 6455 endpoint may receive (§7.4.1). |
|
|
73
|
-
| `encodeWebSocketFrame` | function | Encodes a single RFC 6455 frame to its wire bytes — the inverse of `parseWebSocketFrame`. |
|
|
63
|
+
| Name | Kind | Signature | Summary |
|
|
64
|
+
| --------------------------- | -------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
65
|
+
| `computeWebSocketAccept` | function | `(key: string) => string` | Computes the `Sec-WebSocket-Accept` response value for an RFC 6455 upgrade. |
|
|
66
|
+
| `isWebSocketKey` | function | `(key: string) => boolean` | Checks whether a value is a canonical RFC 6455 `Sec-WebSocket-Key`. |
|
|
67
|
+
| `isWebSocketProtocol` | function | `(protocol: string) => boolean` | Checks whether a value is one valid WebSocket subprotocol token. |
|
|
68
|
+
| `parseWebSocketFrame` | function | `(buffer: Buffer) => WebSocketFrame \| undefined` | Decodes a single RFC 6455 frame from the front of a buffer, answering `undefined` while the buffer is incomplete so the caller accumulates and retries. |
|
|
69
|
+
| `measureWebSocketFrame` | function | `(buffer: Buffer) => number \| undefined` | Reads the declared payload length off the front of a buffer without buffering or reading the payload itself, answering `undefined` until the length field is complete. |
|
|
70
|
+
| `matchesWebSocketCanonical` | function | `(buffer: Buffer) => boolean \| undefined` | Checks whether the next frame uses the shortest valid RFC 6455 payload-length encoding, answering `undefined` until its length prefix is complete. |
|
|
71
|
+
| `parseUTF8` | function | `(bytes: Buffer) => string \| undefined` | Decodes a byte sequence as strict UTF-8, answering `undefined` when the sequence is malformed. |
|
|
72
|
+
| `isCloseCode` | function | `(code: number) => boolean` | Checks whether a numeric value is a close status code an RFC 6455 endpoint may receive (§7.4.1). |
|
|
73
|
+
| `encodeWebSocketFrame` | function | `(opcode: number, payload: Buffer \| string, options?: WebSocketEncodeOptions) => Buffer` | Encodes a single RFC 6455 frame to its wire bytes — the inverse of `parseWebSocketFrame`. |
|
|
74
74
|
|
|
75
75
|
### Constants
|
|
76
76
|
|
|
77
77
|
A `Shape` cell holds the constant's declared type.
|
|
78
78
|
|
|
79
|
-
|
|
|
80
|
-
| ----------------------------------- | ----- |
|
|
81
|
-
| `WEBSOCKET_GUID` | const | `
|
|
82
|
-
| `WEBSOCKET_VERSION` | const | `
|
|
83
|
-
| `WEBSOCKET_OPCODE_TEXT` | const | `
|
|
84
|
-
| `WEBSOCKET_OPCODE_BINARY` | const | `
|
|
85
|
-
| `WEBSOCKET_OPCODE_CONTINUATION` | const | `
|
|
86
|
-
| `WEBSOCKET_OPCODE_CLOSE` | const | `
|
|
87
|
-
| `WEBSOCKET_OPCODE_PING` | const | `
|
|
88
|
-
| `WEBSOCKET_OPCODE_PONG` | const | `
|
|
89
|
-
| `WEBSOCKET_READY_CONNECTING` | const | `WebSocketReadyState`
|
|
90
|
-
| `WEBSOCKET_READY_OPEN` | const | `WebSocketReadyState`
|
|
91
|
-
| `WEBSOCKET_READY_CLOSING` | const | `WebSocketReadyState`
|
|
92
|
-
| `WEBSOCKET_READY_CLOSED` | const | `WebSocketReadyState`
|
|
93
|
-
| `WEBSOCKET_CLOSE_NORMAL` | const | `
|
|
94
|
-
| `WEBSOCKET_CLOSE_PROTOCOL` | const | `
|
|
95
|
-
| `WEBSOCKET_CLOSE_UNSUPPORTED` | const | `
|
|
96
|
-
| `WEBSOCKET_CLOSE_INVALID` | const | `
|
|
97
|
-
| `WEBSOCKET_CLOSE_TOO_BIG` | const | `
|
|
98
|
-
| `WEBSOCKET_MAX_PAYLOAD` | const | `
|
|
99
|
-
| `WEBSOCKET_CLOSE_TIMEOUT_MS` | const | `
|
|
100
|
-
| `WEBSOCKET_CONTROL_MAX_LENGTH` | const | `
|
|
101
|
-
| `WEBSOCKET_CLOSE_REASON_MAX_LENGTH` | const | `number`
|
|
102
|
-
| `WEBSOCKET_FAIL_TIMEOUT_MS` | const | `
|
|
79
|
+
| Name | Kind | Signature | Summary |
|
|
80
|
+
| ----------------------------------- | ----- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
81
|
+
| `WEBSOCKET_GUID` | const | `"258EAFA5-E914-47DA-95CA-C5AB0DC85B11"` | Names the accept GUID concatenated to a client's `Sec-WebSocket-Key` before the accept hash, '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'. |
|
|
82
|
+
| `WEBSOCKET_VERSION` | const | `"13"` | Names the supported protocol version, '13'. |
|
|
83
|
+
| `WEBSOCKET_OPCODE_TEXT` | const | `1` | Names the text frame opcode, 0x01. |
|
|
84
|
+
| `WEBSOCKET_OPCODE_BINARY` | const | `2` | Names the binary frame opcode, 0x02. |
|
|
85
|
+
| `WEBSOCKET_OPCODE_CONTINUATION` | const | `0` | Names the continuation frame opcode, 0x00. |
|
|
86
|
+
| `WEBSOCKET_OPCODE_CLOSE` | const | `8` | Names the close frame opcode, 0x08. |
|
|
87
|
+
| `WEBSOCKET_OPCODE_PING` | const | `9` | Names the ping frame opcode, 0x09. |
|
|
88
|
+
| `WEBSOCKET_OPCODE_PONG` | const | `10` | Names the pong frame opcode, 0x0a. |
|
|
89
|
+
| `WEBSOCKET_READY_CONNECTING` | const | `WebSocketReadyState` | Names the connecting ready state, 0. |
|
|
90
|
+
| `WEBSOCKET_READY_OPEN` | const | `WebSocketReadyState` | Names the open ready state, 1. |
|
|
91
|
+
| `WEBSOCKET_READY_CLOSING` | const | `WebSocketReadyState` | Names the closing ready state, 2. |
|
|
92
|
+
| `WEBSOCKET_READY_CLOSED` | const | `WebSocketReadyState` | Names the closed ready state, 3. |
|
|
93
|
+
| `WEBSOCKET_CLOSE_NORMAL` | const | `1000` | Names the normal-closure status code, 1000. |
|
|
94
|
+
| `WEBSOCKET_CLOSE_PROTOCOL` | const | `1002` | Names the protocol-error status code, 1002. |
|
|
95
|
+
| `WEBSOCKET_CLOSE_UNSUPPORTED` | const | `1003` | Names the unsupported-data status code, 1003. |
|
|
96
|
+
| `WEBSOCKET_CLOSE_INVALID` | const | `1007` | Names the invalid-frame-payload-data status code, 1007. |
|
|
97
|
+
| `WEBSOCKET_CLOSE_TOO_BIG` | const | `1009` | Names the message-too-big status code, 1009. |
|
|
98
|
+
| `WEBSOCKET_MAX_PAYLOAD` | const | `104857600` | Names the default cap on both an inbound frame's declared length and a reassembled message's total byte count, 104,857,600 bytes (100 MiB). |
|
|
99
|
+
| `WEBSOCKET_CLOSE_TIMEOUT_MS` | const | `30000` | Names the default close-handshake timeout, 30,000 milliseconds — how long `close` waits for the peer's echo. |
|
|
100
|
+
| `WEBSOCKET_CONTROL_MAX_LENGTH` | const | `125` | Names the maximum control-frame payload length, 125 bytes. |
|
|
101
|
+
| `WEBSOCKET_CLOSE_REASON_MAX_LENGTH` | const | `number` | Names the maximum UTF-8 close-reason length after the two-byte status code, 123. |
|
|
102
|
+
| `WEBSOCKET_FAIL_TIMEOUT_MS` | const | `1000` | Names the flush grace, 1,000 milliseconds, a validation-breach close frame is given before the hard teardown fallback destroys the socket. |
|
|
103
103
|
|
|
104
104
|
### Types
|
|
105
105
|
|
|
106
106
|
A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
|
|
107
107
|
|
|
108
|
-
|
|
|
109
|
-
| ------------------------ | --------- |
|
|
110
|
-
| `WebSocketReadyState` | type | `0 \| 1 \| 2 \| 3`
|
|
111
|
-
| `WebSocketFrame` | interface | `{ fin, opcode, payload, consumed, masked, rsv }`
|
|
112
|
-
| `WebSocketEncodeOptions` | interface | `{ masked?, mask? }`
|
|
113
|
-
| `WebSocketErrorCode` | type | `'OPTION' \| 'LIMIT' \| 'CLOSE' \| 'FRAME'`
|
|
114
|
-
| `NodeWebSocketEventMap` | type | `{ open
|
|
115
|
-
| `NodeWebSocketOptions` | interface | `{ socket, key?, head?, protocol?, on?, error?, payload?, timeout?, signal? }`
|
|
116
|
-
| `NodeWebSocketInterface` | interface | `{ emitter, readyState
|
|
108
|
+
| Name | Kind | Signature | Summary |
|
|
109
|
+
| ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
110
|
+
| `WebSocketReadyState` | type | `0 \| 1 \| 2 \| 3` | Represents a WebSocket ready state — the stage a connection has reached between the handshake and the socket's end. |
|
|
111
|
+
| `WebSocketFrame` | interface | `{ fin, opcode, payload, consumed, masked, rsv }` | Represents a parsed RFC 6455 frame — the structured result of decoding one frame off the wire. |
|
|
112
|
+
| `WebSocketEncodeOptions` | interface | `{ masked?, mask? }` | Represents the options for `encodeWebSocketFrame` — how a frame is masked on the wire. |
|
|
113
|
+
| `WebSocketErrorCode` | type | `'OPTION' \| 'LIMIT' \| 'CLOSE' \| 'FRAME'` | Represents the subject a `WebSocketError` names as refused. |
|
|
114
|
+
| `NodeWebSocketEventMap` | type | `{ readonly open: readonly []; readonly message: readonly [message: string]; readonly close: readonly [code: number \| undefined, reason: string \| undefined]; readonly error: readonly [error: unknown]; readonly ping: readonly []; readonly pong: readonly []; }` | Represents the event map a `NodeWebSocketInterface` emitter carries. |
|
|
115
|
+
| `NodeWebSocketOptions` | interface | `{ socket, key?, head?, protocol?, on?, error?, payload?, timeout?, signal? }` | Represents the options for `createNodeWebSocket` — the upgraded `socket`, the `key` that selects server or client mode, and the listeners, caps, and cancellation signal the wrapper runs under. |
|
|
116
|
+
| `NodeWebSocketInterface` | interface | `{ emitter, readyState, send(), ping(), close(), destroy() }` | Represents the behavioral contract a server-native WebSocket exposes over a raw upgraded socket. |
|
|
117
117
|
|
|
118
118
|
Frame payloads are raw `Buffer`s off the wire; a text frame decodes to a `string` at the boundary, and the untyped socket `data` chunk is narrowed to a `Buffer` with a guard, never an assertion.
|
|
119
119
|
|
|
@@ -46,12 +46,12 @@ The package publishes these factories. `createWorker` is the `@orkestrel/worker`
|
|
|
46
46
|
`createJSONQueueStore`, `createNodeWorker`, and `serveWorker` are the
|
|
47
47
|
`@orkestrel/worker/server` exports.
|
|
48
48
|
|
|
49
|
-
|
|
|
50
|
-
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
-
| `createWorker` | function | Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) composed with a `Pool` (`@orkestrel/pool`), where each enqueued input runs through the handler against an automatically acquired pooled resource released when the job settles. |
|
|
52
|
-
| `createJSONQueueStore` | function | Creates a persistent JSON-file `QueueStoreInterface` — the core `createDatabaseQueueStore` over a server `createJSONDriver`. |
|
|
53
|
-
| `createNodeWorker` | function | Creates a CPU-parallel worker over `node:worker_threads` — a thin specialization of the core `createWorker` whose pooled resource is a worker thread. |
|
|
54
|
-
| `serveWorker` | function | Registers a worker-thread handler — the worker-side half of `createNodeWorker`. |
|
|
49
|
+
| Name | Kind | Signature | Summary |
|
|
50
|
+
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `createWorker` | function | `<TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) => WorkerInterface<TInput, TResult>` | Creates a resource-backed job worker — a `Queue` (`@orkestrel/queue`) composed with a `Pool` (`@orkestrel/pool`), where each enqueued input runs through the handler against an automatically acquired pooled resource released when the job settles. |
|
|
52
|
+
| `createJSONQueueStore` | function | `<TInput extends ContractShape>(path: string, input: TInput) => QueueStoreInterface<Infer<TInput>>` | Creates a persistent JSON-file `QueueStoreInterface` — the core `createDatabaseQueueStore` over a server `createJSONDriver`. |
|
|
53
|
+
| `createNodeWorker` | function | `<TInput, TResult>(options: NodeWorkerOptions<TInput, TResult>) => WorkerInterface<TInput, TResult>` | Creates a CPU-parallel worker over `node:worker_threads` — a thin specialization of the core `createWorker` whose pooled resource is a worker thread. |
|
|
54
|
+
| `serveWorker` | function | `<TInput, TResult>(options: ServeWorkerOptions<TInput, TResult>) => void` | Registers a worker-thread handler — the worker-side half of `createNodeWorker`. |
|
|
55
55
|
|
|
56
56
|
### Threads
|
|
57
57
|
|
|
@@ -79,19 +79,19 @@ try {
|
|
|
79
79
|
|
|
80
80
|
The thread-level functions behind `createNodeWorker`:
|
|
81
81
|
|
|
82
|
-
|
|
|
83
|
-
| -------------- | -------- | --------------------------------------------------------------------------------------- |
|
|
84
|
-
| `createThread` | function | Creates one live worker thread and resolves it as a `NodeThread` after it comes online. |
|
|
85
|
-
| `isReply` | function | Narrows an inbound `message` to a `Reply` for a given correlation `id` — no assertion. |
|
|
82
|
+
| Name | Kind | Signature | Summary |
|
|
83
|
+
| -------------- | -------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
84
|
+
| `createThread` | function | `(script: string \| URL, workerData?: unknown) => Promise<NodeThread>` | Creates one live worker thread and resolves it as a `NodeThread` after it comes online. |
|
|
85
|
+
| `isReply` | function | `(value: unknown, id: string) => value is Reply` | Narrows an inbound `message` to a `Reply` for a given correlation `id` — no assertion. |
|
|
86
86
|
|
|
87
87
|
### Classes
|
|
88
88
|
|
|
89
89
|
The classes the core and server faces export:
|
|
90
90
|
|
|
91
|
-
|
|
|
92
|
-
| ---------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
-
| `Dispatch` | class | Represents one dispatched worker-thread job — the lifecycle entity behind a job posted to a leased `NodeThread`, whose `promise` settles with the narrowed reply. |
|
|
94
|
-
| `Worker` | class | Represents a resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`). |
|
|
91
|
+
| Name | Kind | Signature | Summary |
|
|
92
|
+
| ---------- | ----- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `Dispatch` | class | `new <TResult>(thread: NodeThread, input: unknown, context: QueueContext, result: Guard<TResult>) => Dispatch<TResult>` | Represents one dispatched worker-thread job — the lifecycle entity behind a job posted to a leased `NodeThread`, whose `promise` settles with the narrowed reply. |
|
|
94
|
+
| `Worker` | class | `new <TInput, TResource, TResult>(options: WorkerOptions<TInput, TResource, TResult>) => WorkerInterface<TInput, TResult>` | Represents a resource-backed job worker — a thin facade composing a `Queue` (`@orkestrel/queue`) with a `Pool` (`@orkestrel/pool`). |
|
|
95
95
|
|
|
96
96
|
### Types
|
|
97
97
|
|
|
@@ -99,16 +99,16 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
99
99
|
|
|
100
100
|
Each type and interface the core and server faces publish:
|
|
101
101
|
|
|
102
|
-
|
|
|
103
|
-
| -------------------- | --------- |
|
|
104
|
-
| `WorkerHandler` | type | `(input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> \| TResult`
|
|
105
|
-
| `WorkerOptions` | interface | `{ on?, error?, handler, pool, concurrency?, retries?, timeout?, store? }`
|
|
106
|
-
| `WorkerInterface` | interface | `{ emitter, count, active, paused, stopped
|
|
107
|
-
| `WorkerEventMap` | type | `{ enqueue
|
|
108
|
-
| `NodeWorkerOptions` | interface | `{ on?, error?, script, input, result, workerData?, concurrency?, retries?, timeout?, store? }`
|
|
109
|
-
| `ServeWorkerOptions` | interface | `{ input, handler }`
|
|
110
|
-
| `NodeThread` | interface | `{ worker, alive, death }`
|
|
111
|
-
| `Reply` | type | `{ id
|
|
102
|
+
| Name | Kind | Signature | Summary |
|
|
103
|
+
| -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
104
|
+
| `WorkerHandler` | type | `(input: TInput, resource: TResource, context: QueueContext) => Promise<TResult> \| TResult` | Runs one worker job with a leased pool resource. |
|
|
105
|
+
| `WorkerOptions` | interface | `{ on?, error?, handler, pool, concurrency?, retries?, timeout?, store? }` | Configures `createWorker`. |
|
|
106
|
+
| `WorkerInterface` | interface | `{ emitter, count, active, paused, stopped, enqueue(), restore(), start(), stop(), pause(), resume(), abort(), clear(), destroy() }` | Represents the job-worker contract a consumer holds — a `Queue` whose handler runs each job against a pooled resource. |
|
|
107
|
+
| `WorkerEventMap` | type | `{ readonly enqueue: readonly [id: string]; readonly start: readonly [id: string]; readonly retry: readonly [id: string, attempt: number]; readonly success: readonly [id: string, result: TResult]; readonly failure: readonly [id: string, error: unknown]; readonly abort: readonly [reason: unknown]; readonly drain: readonly []; }` | Represents the push observation surface of a `WorkerInterface` — the job lifecycle a fire-and-forget observer subscribes to. |
|
|
108
|
+
| `NodeWorkerOptions` | interface | `{ on?, error?, script, input, result, workerData?, concurrency?, retries?, timeout?, store? }` | Configures `createNodeWorker` — a CPU-parallel worker over `node:worker_threads`. |
|
|
109
|
+
| `ServeWorkerOptions` | interface | `{ input, handler }` | Configures `serveWorker` — the worker-side entry a thread script registers. |
|
|
110
|
+
| `NodeThread` | interface | `{ worker, alive, death }` | Represents a live worker thread plus its latched liveness state — the pooled resource a `createNodeWorker` leases per job. |
|
|
111
|
+
| `Reply` | type | `{ readonly id: string; readonly ok: true; readonly value: unknown; } \| { readonly id: string; readonly ok: false; readonly error: string; }` | Represents a thread→main reply envelope — a success carrying an opaque `value`, or a failure with a message — the reply half of the wire protocol `createNodeWorker` posts and `serveWorker` answers. |
|
|
112
112
|
|
|
113
113
|
The `emitter` / `count` / `active` / `paused` / `stopped` members of `WorkerInterface` are
|
|
114
114
|
`readonly` data members (Surface rows, earlier) — `emitter` is the typed push observation
|