@orkestrel/scaffold 0.0.119 → 0.0.121
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 +19 -19
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/layer.md +10 -10
- package/dist/host/agents/skills/orkestrel-journey/references/statechart.md +1 -1
- package/dist/host/agents/skills/orkestrel-journey/references/styles.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +52 -51
- package/dist/host/claude/rules/tests.md +2 -2
- package/dist/host/claude/rules/typescript.md +2 -3
- package/dist/host/guides/abort.md +0 -4
- package/dist/host/guides/agent.md +5 -5
- package/dist/host/guides/brief.md +7 -15
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/budget.md +1 -5
- package/dist/host/guides/capture.md +2 -2
- package/dist/host/guides/codec.md +18 -3
- package/dist/host/guides/console.md +4 -30
- package/dist/host/guides/contract.md +23 -44
- package/dist/host/guides/csv.md +86 -93
- package/dist/host/guides/database.md +0 -4
- package/dist/host/guides/emitter.md +0 -2
- package/dist/host/guides/form.md +26 -47
- package/dist/host/guides/guide.md +0 -1
- package/dist/host/guides/html.md +3 -7
- package/dist/host/guides/indexeddb.md +28 -32
- package/dist/host/guides/interpret.md +165 -182
- package/dist/host/guides/jsonrpc.md +187 -0
- package/dist/host/guides/lsp.md +26 -51
- package/dist/host/guides/markdown.md +132 -141
- package/dist/host/guides/mcp.md +220 -276
- package/dist/host/guides/middleware.md +14 -22
- package/dist/host/guides/msg.md +47 -63
- package/dist/host/guides/ndjson.md +0 -4
- package/dist/host/guides/ollama.md +1 -3
- package/dist/host/guides/pool.md +0 -4
- package/dist/host/guides/probe.md +71 -80
- package/dist/host/guides/process.md +71 -79
- package/dist/host/guides/program.md +26 -35
- package/dist/host/guides/qualifier.md +0 -6
- package/dist/host/guides/queue.md +0 -4
- package/dist/host/guides/rater.md +6 -12
- package/dist/host/guides/reason.md +30 -36
- package/dist/host/guides/relation.md +0 -2
- package/dist/host/guides/router.md +11 -18
- package/dist/host/guides/scaffold.md +148 -144
- package/dist/host/guides/sea.md +47 -51
- package/dist/host/guides/server.md +15 -19
- package/dist/host/guides/sqlite.md +0 -4
- package/dist/host/guides/sse.md +6 -10
- package/dist/host/guides/table.md +481 -493
- package/dist/host/guides/template.md +0 -4
- package/dist/host/guides/terminal.md +0 -26
- package/dist/host/guides/test.md +46 -66
- package/dist/host/guides/timeout.md +0 -6
- package/dist/host/guides/tool.md +2 -6
- package/dist/host/guides/toolbox.md +0 -10
- package/dist/host/guides/websocket.md +0 -4
- package/dist/host/guides/worker.md +57 -57
- package/dist/host/guides/workflow.md +13 -26
- package/dist/host/guides/workspace.md +15 -21
- package/dist/host/manifest.json +64 -909
- package/dist/src/core/index.cjs +128 -181
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +213 -213
- package/dist/src/core/index.d.ts +213 -213
- package/dist/src/core/index.js +117 -170
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +35 -34
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +62 -58
- package/dist/src/server/index.d.ts +62 -58
- package/dist/src/server/index.js +36 -35
- package/dist/src/server/index.js.map +1 -1
- package/package.json +13 -13
package/dist/host/guides/sea.md
CHANGED
|
@@ -68,8 +68,6 @@ On Windows, `SEAOptions.windows.sign` is optional Authenticode signing. When pre
|
|
|
68
68
|
|
|
69
69
|
### Constants
|
|
70
70
|
|
|
71
|
-
A `Shape` cell holds the constant's declared type.
|
|
72
|
-
|
|
73
71
|
| Name | Kind | Signature | Summary |
|
|
74
72
|
| --------------------------------- | ----- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
|
75
73
|
| `SEA_SENTINEL_FUSE` | const | `"NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2"` | Holds the SEA sentinel fuse value embedded in the Node.js binary, `NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`. |
|
|
@@ -108,55 +106,53 @@ A `Shape` cell holds the constant's declared type.
|
|
|
108
106
|
|
|
109
107
|
### Helpers and errors
|
|
110
108
|
|
|
111
|
-
| Name
|
|
112
|
-
|
|
|
113
|
-
| `isExecutableFormat`
|
|
114
|
-
| `resolvePlatform`
|
|
115
|
-
| `isPlatformSupported`
|
|
116
|
-
| `ensureExists`
|
|
117
|
-
| `isCompressible`
|
|
118
|
-
| `walkDirectory`
|
|
119
|
-
| `executeShell`
|
|
120
|
-
| `redactCommand`
|
|
121
|
-
| `
|
|
122
|
-
| `compressFile`
|
|
123
|
-
| `compressDirectory`
|
|
124
|
-
| `alignTo`
|
|
125
|
-
| `readPEOffset`
|
|
126
|
-
| `readU16`
|
|
127
|
-
| `readU32`
|
|
128
|
-
| `readU64`
|
|
129
|
-
| `writeU16`
|
|
130
|
-
| `writeU32`
|
|
131
|
-
| `writeU64`
|
|
132
|
-
| `appendFile`
|
|
133
|
-
| `stripTrailingNulls`
|
|
134
|
-
| `isPEExecutable`
|
|
135
|
-
| `patchPESubsystem`
|
|
136
|
-
| `stripPESignature`
|
|
137
|
-
| `buildSignCommand`
|
|
138
|
-
| `formatSize`
|
|
139
|
-
| `ensureSafeKey`
|
|
140
|
-
| `ensureContained`
|
|
141
|
-
| `ensureSafeName`
|
|
142
|
-
| `finalizeExecutable`
|
|
143
|
-
| `syncDirectory`
|
|
144
|
-
| `buildBlobConfig`
|
|
145
|
-
| `patchSentinelFuse`
|
|
146
|
-
| `buildELFNoteHeader`
|
|
147
|
-
| `alignELFNoteSize`
|
|
148
|
-
| `isPowerOfTwo`
|
|
149
|
-
| `copyRange`
|
|
150
|
-
| `openBrowser`
|
|
151
|
-
| `SEAError`
|
|
152
|
-
| `isSEAError`
|
|
153
|
-
| `ShellError`
|
|
154
|
-
| `isShellError`
|
|
109
|
+
| Name | Kind | Signature | Summary |
|
|
110
|
+
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
111
|
+
| `isExecutableFormat` | function | `(value: unknown) => value is ExecutableFormat` | Checks whether a value is a valid `ExecutableFormat`. |
|
|
112
|
+
| `resolvePlatform` | function | `(platform?: string) => SEAPlatform \| undefined` | Resolves the effective platform configuration. |
|
|
113
|
+
| `isPlatformSupported` | function | `(platform?: string) => boolean` | Checks whether the current or named platform is supported for SEA builds. |
|
|
114
|
+
| `ensureExists` | function | `(path: string, message: string, code?: SEAErrorCode) => void` | Asserts that a path exists, throwing a coded `SEAError` if not. |
|
|
115
|
+
| `isCompressible` | function | `(path: string) => boolean` | Checks whether a file's extension is outside `SKIP_EXTENSIONS`, so Brotli compression applies to it. |
|
|
116
|
+
| `walkDirectory` | function | `(directory: string, base?: string) => readonly string[]` | Walks a directory recursively and returns every file path it finds, relative to the base and skipping symlinks. |
|
|
117
|
+
| `executeShell` | function | `(command: readonly string[], options?: SEAShellOptions) => Buffer` | Executes a command synchronously and returns stdout. |
|
|
118
|
+
| `redactCommand` | function | `(command: readonly string[]) => readonly string[]` | Redacts password arguments from a shell command, so the command is safe to include in an error message. |
|
|
119
|
+
| `computeCompressionSize` | function | `(original: number, compressed: number) => SEACompressionSize` | Computes a size comparison between original and compressed byte counts. |
|
|
120
|
+
| `compressFile` | function | `(input: string, output: string, options?: SEABrotliOptions) => SEACompressionResult` | Brotli-compresses a single file, writing the output alongside it. |
|
|
121
|
+
| `compressDirectory` | function | `(directory: string, options?: SEABrotliOptions, progress?: SEACompressionHandler) => SEACompressionManifest` | Compresses all compressible files in a directory tree. |
|
|
122
|
+
| `alignTo` | function | `(value: number, alignment: number) => number` | Rounds a value up to the next multiple of an alignment boundary. |
|
|
123
|
+
| `readPEOffset` | function | `(fd: number) => number` | Reads the PE header offset from a Windows executable. |
|
|
124
|
+
| `readU16` | function | `(fd: number, offset: number) => number` | Reads a 16-bit unsigned integer from a file descriptor. |
|
|
125
|
+
| `readU32` | function | `(fd: number, offset: number) => number` | Reads a 32-bit unsigned little-endian integer from a file descriptor. |
|
|
126
|
+
| `readU64` | function | `(fd: number, offset: number) => bigint` | Reads a 64-bit unsigned little-endian integer from a file descriptor. |
|
|
127
|
+
| `writeU16` | function | `(fd: number, offset: number, value: number) => void` | Writes a 16-bit unsigned integer to a file descriptor. |
|
|
128
|
+
| `writeU32` | function | `(fd: number, offset: number, value: number) => void` | Writes a 32-bit unsigned little-endian integer to a file descriptor. |
|
|
129
|
+
| `writeU64` | function | `(fd: number, offset: number, value: bigint) => void` | Writes a 64-bit unsigned little-endian integer to a file descriptor. |
|
|
130
|
+
| `appendFile` | function | `(target: string, source: string, chunk?: number) => void` | Appends a source file to a target file, streaming in fixed-size chunks. |
|
|
131
|
+
| `stripTrailingNulls` | function | `(value: string) => string` | Truncates a NUL-padded binary name field at its first NUL character. |
|
|
132
|
+
| `isPEExecutable` | function | `(path: string) => boolean` | Checks whether a file is a Windows PE executable. |
|
|
133
|
+
| `patchPESubsystem` | function | `(path: string, subsystem: number) => void` | Patches the PE subsystem field in a Windows executable. |
|
|
134
|
+
| `stripPESignature` | function | `(path: string) => void` | Removes the Authenticode signature from a PE executable by zeroing the security directory entry in the optional header. |
|
|
135
|
+
| `buildSignCommand` | function | `(sign: SEAWindowsSignOptions, target: string) => readonly string[]` | Builds the `signtool sign` argv for signing a Windows executable. |
|
|
136
|
+
| `formatSize` | function | `(bytes: number) => string` | Formats a byte count as a human-readable string. |
|
|
137
|
+
| `ensureSafeKey` | function | `(key: string) => void` | Asserts that an asset key is safe to use as a relative filesystem/archive key. |
|
|
138
|
+
| `ensureContained` | function | `(base: string, path: string) => string` | Asserts that `path` (resolved against `base`) real-path-resolves to a location inside `base`, defeating a symlink escape. |
|
|
139
|
+
| `ensureSafeName` | function | `(name: string) => void` | Asserts that `name` is a single safe path segment suitable as an output executable base name. |
|
|
140
|
+
| `finalizeExecutable` | function | `(source: string, target: string) => void` | Finalizes a built executable by durably flushing it to disk and atomically moving it into place. |
|
|
141
|
+
| `syncDirectory` | function | `(path: string) => void` | Fsyncs a directory to durably persist a prior file rename/create within it. |
|
|
142
|
+
| `buildBlobConfig` | function | `(entry: SEAEntryOptions, blob: string, assets: Readonly<Record<string, string>> \| undefined, options?: SEABlobOptions) => Readonly<Record<string, unknown>>` | Builds the Node.js `--experimental-sea-config` JSON object for a SEA blob. |
|
|
143
|
+
| `patchSentinelFuse` | function | `(executable: string, fuse: string) => void` | Patches the sentinel fuse in a binary from `:0` to `:1`. |
|
|
144
|
+
| `buildELFNoteHeader` | function | `(resource: string, blobSize: number) => ELFNoteHeader` | Builds an ELF `PT_NOTE` entry's header bytes (namesz/descsz/type + padded name) for the SEA blob note, without the blob body itself. |
|
|
145
|
+
| `alignELFNoteSize` | function | `(value: number) => number` | Aligns an ELF note component size to its four-byte boundary. |
|
|
146
|
+
| `isPowerOfTwo` | function | `(value: number) => boolean` | Checks whether a number is a nonzero power of two. |
|
|
147
|
+
| `copyRange` | function | `(source: number, target: number, start: number, length: number, chunk?: number) => void` | Copies a byte range from one open file descriptor to another, streaming in fixed-size chunks instead of buffering the whole range in memory. |
|
|
148
|
+
| `openBrowser` | function | `(url: string) => void` | Launches the system default browser at an http(s) URL. |
|
|
149
|
+
| `SEAError` | class | `new (code: SEAErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => SEAError` | Represents the coded base error for every failure raised by the SEA build. |
|
|
150
|
+
| `isSEAError` | function | `(value: unknown) => value is SEAError` | Checks whether a value is a `SEAError`. |
|
|
151
|
+
| `ShellError` | class | `new (message: string, stdout: Buffer, stderr: Buffer) => ShellError` | Represents an error thrown when a shell command executed through `executeShell` exits non-zero. |
|
|
152
|
+
| `isShellError` | function | `(value: unknown) => value is ShellError` | Checks whether a value is a `ShellError`. |
|
|
155
153
|
|
|
156
154
|
### Types
|
|
157
155
|
|
|
158
|
-
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 `\|`. An extended interface's name comes before `plus`, with the members it adds after.
|
|
159
|
-
|
|
160
156
|
| Name | Kind | Signature | Summary |
|
|
161
157
|
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
|
|
162
158
|
| `SEACompressionSize` | interface | `{ original, compressed, ratio }` | Represents a size comparison between original and compressed data. |
|
|
@@ -197,7 +193,7 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
197
193
|
|
|
198
194
|
## Methods
|
|
199
195
|
|
|
200
|
-
The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. A `readonly` data member stays in the interface's `
|
|
196
|
+
The public methods of each behavioral interface — one table per type, keyed by its backticked name, every call-signature member listed. A `readonly` data member stays in the interface's `Signature` cell and off these tables: `format` on `InjectorInterface`, `emitter` and `status` on `SEAInterface`, `emitter` and `count` on `AssetManagerInterface`. Each concrete class implements its interface exactly, so this doubles as the class's instance-method surface.
|
|
201
197
|
|
|
202
198
|
#### `SEAInterface`
|
|
203
199
|
|
|
@@ -289,7 +285,7 @@ import {
|
|
|
289
285
|
ensureExists,
|
|
290
286
|
isCompressible,
|
|
291
287
|
walkDirectory,
|
|
292
|
-
|
|
288
|
+
computeCompressionSize,
|
|
293
289
|
compressFile,
|
|
294
290
|
compressDirectory,
|
|
295
291
|
formatSize,
|
|
@@ -333,7 +329,7 @@ ensureExists('dist/server/serve.cjs', 'entry file is missing')
|
|
|
333
329
|
walkDirectory('dist/app/browser') // every relative file path under the directory
|
|
334
330
|
isCompressible('dist/app/browser/index.html') // true — not in SKIP_EXTENSIONS
|
|
335
331
|
|
|
336
|
-
const size =
|
|
332
|
+
const size = computeCompressionSize(1000, 400) // { original: 1000, compressed: 400, ratio: 0.4 }
|
|
337
333
|
compressFile('dist/index.html', 'dist/index.html.br')
|
|
338
334
|
compressDirectory('dist/app/browser', { mode: 'text' })
|
|
339
335
|
|
|
@@ -58,11 +58,11 @@ Cross-face and substrate usage appear under [Patterns](#patterns).
|
|
|
58
58
|
|
|
59
59
|
### Factories
|
|
60
60
|
|
|
61
|
-
| Name | Kind | Signature | Summary
|
|
62
|
-
| ------------------ | -------- | --------------------------------------------------------------------- |
|
|
63
|
-
| `createNegotiator` | function | `() => NegotiatorInterface` | Creates a `NegotiatorInterface` — the reusable content-negotiation machine over the weighted `Accept` family.
|
|
64
|
-
| `createServer` | function | `<TState>(options: ServerOptions<TState>) => ServerInterface<TState>` | Creates a `ServerInterface` — the node face's HTTP server facade over a consumed `@orkestrel/router` dispatcher.
|
|
65
|
-
| `createStream` | function | `(options?: StreamOptions) =>
|
|
61
|
+
| Name | Kind | Signature | Summary |
|
|
62
|
+
| ------------------ | -------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
63
|
+
| `createNegotiator` | function | `() => NegotiatorInterface` | Creates a `NegotiatorInterface` — the reusable content-negotiation machine over the weighted `Accept` family. |
|
|
64
|
+
| `createServer` | function | `<TState>(options: ServerOptions<TState>) => ServerInterface<TState>` | Creates a `ServerInterface` — the node face's HTTP server facade over a consumed `@orkestrel/router` dispatcher. |
|
|
65
|
+
| `createStream` | function | `(options?: StreamOptions) => SSEStreamInterface` | Creates an `SSEStreamInterface` — a generic Server-Sent-Events stream whose `response` is a fetch-standard streaming `Response` a route returns. |
|
|
66
66
|
|
|
67
67
|
### Startup ownership
|
|
68
68
|
|
|
@@ -77,8 +77,6 @@ cleanup finish before the start event is emitted.
|
|
|
77
77
|
|
|
78
78
|
### Constants
|
|
79
79
|
|
|
80
|
-
A `Shape` cell holds the constant's declared type.
|
|
81
|
-
|
|
82
80
|
| Name | Kind | Signature | Summary |
|
|
83
81
|
| ---------------------------- | ----- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
82
|
| `DEFAULT_DRAIN_MS` | const | `10000` | Names the default graceful-stop deadline `stop()` gives in-flight requests and claimed upgraded sockets, `10_000` ms. |
|
|
@@ -148,12 +146,10 @@ A `Shape` cell holds the constant's declared type.
|
|
|
148
146
|
| `ServerError` | class | `new (code: ServerErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => ServerError` | Represents the error this package raises when a caller programmed a call the entity refuses, carrying `'STATUS'` or `'NEXT'` as its code. |
|
|
149
147
|
| `Negotiator` | class | `new () => NegotiatorInterface` | Represents the content-negotiation machine over the weighted `Accept` family — a reusable, cross-middleware entity rather than a middleware. Implements exactly `NegotiatorInterface`. |
|
|
150
148
|
| `Server` | class | `new <TState>(options: ServerOptions<TState>) => ServerInterface<TState>` | Represents the HTTP server facade — an observable `node:http` lifecycle composing this module's own middleware onion around a consumed `@orkestrel/router` dispatcher. Implements exactly `ServerInterface`. |
|
|
151
|
-
| `Stream` | class | `new (options?: StreamOptions) =>
|
|
149
|
+
| `Stream` | class | `new (options?: StreamOptions) => SSEStreamInterface` | Represents the Server-Sent-Events handle over an open, fetch-standard streaming `Response`. Implements exactly `SSEStreamInterface`. |
|
|
152
150
|
|
|
153
151
|
### Types
|
|
154
152
|
|
|
155
|
-
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 `\|`.
|
|
156
|
-
|
|
157
153
|
| Name | Kind | Signature | Summary |
|
|
158
154
|
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
159
155
|
| `MiddlewareContext` | interface | `{ url, method, state, body() }` | Represents the composition context — plain data, one per request, shared by every middleware and, as `state`, by the route handlers behind the dispatcher. |
|
|
@@ -169,8 +165,8 @@ A `Shape` cell holds an interface's data members as bare names in braces, `?` ma
|
|
|
169
165
|
| `FormatHandlerMap` | type | `Readonly<Record<string, (request: Request, context: MiddlewareContext<TState>) => Response \| Promise<Response>>>` | Represents a map of media type → handler for `NegotiatorInterface.format` — the content-negotiation dispatch table. |
|
|
170
166
|
| `NegotiatorInterface` | interface | `{ negotiate(), encoding(), language(), format() }` | Represents content negotiation over the weighted `Accept` family — a reusable, cross-middleware machine (not itself a middleware). |
|
|
171
167
|
| `SSEMessage` | interface | `{ data, event?, id?, retry? }` | Represents one Server-Sent Event to serialize to the wire. |
|
|
172
|
-
| `StreamOptions` | interface | `{ status?, headers? }` | Options for
|
|
173
|
-
| `
|
|
168
|
+
| `StreamOptions` | interface | `{ status?, headers? }` | Options for an `SSEStreamInterface` — how `createStream` opens the streaming response. |
|
|
169
|
+
| `SSEStreamInterface` | interface | `{ response, closed, write(), comment(), drain(), end() }` | Represents a handle to write Server-Sent Events to an open, fetch-standard streaming `Response` — the generic streaming surface `createStream` returns over a `ReadableStream`. |
|
|
174
170
|
| `RangeSpec` | type | `{ readonly satisfiable: true; readonly start: number; readonly end: number; } \| { readonly satisfiable: false; }` | Represents the parsed outcome of an HTTP `Range` request header. |
|
|
175
171
|
| `BodyOptions` | interface | `{ limit?, decompression? }` | Options for `readBody` — how the shared body-collection pipeline caps and decompresses a request body. |
|
|
176
172
|
| `ServerStatus` | type | `'idle' \| 'starting' \| 'listening' \| 'stopping' \| 'stopped'` | Represents the `Server`'s lifecycle state. |
|
|
@@ -201,7 +197,7 @@ The error guards and request readers expose these primitives.
|
|
|
201
197
|
|
|
202
198
|
## Methods
|
|
203
199
|
|
|
204
|
-
The public methods of `NegotiatorInterface`, `
|
|
200
|
+
The public methods of `NegotiatorInterface`, `SSEStreamInterface`, and
|
|
205
201
|
`ServerInterface` — every call-signature member listed (their `readonly` data
|
|
206
202
|
members stay Surface rows). `Negotiator`, `Server`, and `Stream` implement
|
|
207
203
|
their interfaces exactly, so their tables also double as each class's
|
|
@@ -226,7 +222,7 @@ coding, because an absent `Accept-Encoding` makes identity the correct answer;
|
|
|
226
222
|
| `language` | `string \| undefined` | Picks the best `available` language for an `Accept-Language` header — `negotiate` with a language-prefix match (`en` accepts `en-US`) and a bare `*` wildcard. |
|
|
227
223
|
| `format` | `Promise<Response>` | Dispatches to the handler whose media type the client most prefers — reads the request `Accept`, negotiates against `handlers`' keys, and invokes the winner; `406` when none is acceptable. |
|
|
228
224
|
|
|
229
|
-
#### `
|
|
225
|
+
#### `SSEStreamInterface`
|
|
230
226
|
|
|
231
227
|
`write` always accepts an event while open and returns whether the local
|
|
232
228
|
`ReadableStream` queue still has positive desired size afterward. A producer
|
|
@@ -274,7 +270,7 @@ These invariants hold across `src/server` ↔ `server.md`.
|
|
|
274
270
|
source directory, and every export appears as a Surface row — exhaustive,
|
|
275
271
|
both directions.
|
|
276
272
|
2. **Doc ↔ source method bijection.** The `## Methods` tables list exactly
|
|
277
|
-
`NegotiatorInterface`'s, `
|
|
273
|
+
`NegotiatorInterface`'s, `SSEStreamInterface`'s, and `ServerInterface`'s public
|
|
278
274
|
methods — exhaustive, both directions — and `Negotiator` / `Stream` /
|
|
279
275
|
`Server` expose the same public methods, no more.
|
|
280
276
|
3. **Status machine + bound address + restart-fresh-abort.**
|
|
@@ -484,7 +480,7 @@ These invariants hold across `src/server` ↔ `server.md`.
|
|
|
484
480
|
Object and callable contexts are accepted. Subclass names are unrestricted. Transparent
|
|
485
481
|
proxies, unbranded look-alikes, and branded plain objects are rejected.
|
|
486
482
|
19. **SSE producers can cooperate with real process-local transport
|
|
487
|
-
backpressure.** `
|
|
483
|
+
backpressure.** `SSEStreamInterface.write` returns `true` only while the
|
|
488
484
|
underlying `ReadableStream` controller retains positive desired size after
|
|
489
485
|
accepting the event. A `false` result tells a cooperative producer to await
|
|
490
486
|
`drain()`; that promise parks without polling until a consumer pull restores
|
|
@@ -592,10 +588,10 @@ handle afterwards; a `write` that reports `false` is backpressure `drain`
|
|
|
592
588
|
waits out.
|
|
593
589
|
|
|
594
590
|
```ts
|
|
595
|
-
import type {
|
|
591
|
+
import type { SSEStreamInterface } from '@orkestrel/server'
|
|
596
592
|
import { createStream } from '@orkestrel/server'
|
|
597
593
|
|
|
598
|
-
async function pumpStream(stream:
|
|
594
|
+
async function pumpStream(stream: SSEStreamInterface): Promise<void> {
|
|
599
595
|
if (!stream.write({ event: 'token', data: 'hello' })) await stream.drain()
|
|
600
596
|
stream.comment('keep-alive')
|
|
601
597
|
stream.end()
|
|
@@ -774,7 +770,7 @@ new TextDecoder().decode(body) // 'hi' — capped decompression, the zip-bomb de
|
|
|
774
770
|
## Tests
|
|
775
771
|
|
|
776
772
|
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔ `src/server`
|
|
777
|
-
bijection (value and type exports), the `NegotiatorInterface` / `
|
|
773
|
+
bijection (value and type exports), the `NegotiatorInterface` / `SSEStreamInterface` /
|
|
778
774
|
`ServerInterface` ↔ implementing-class method bijections, and the equality gate:
|
|
779
775
|
every `Summary` cell against its declaration's description paragraph, the titled
|
|
780
776
|
`Substrate direct use — tokens, cookies, negotiation` fence against the `@example`
|
|
@@ -46,8 +46,6 @@ db.prepare('SELECT name FROM users WHERE age >= ?').all([18]) // → [{ name: 'A
|
|
|
46
46
|
|
|
47
47
|
### Constants
|
|
48
48
|
|
|
49
|
-
A `Shape` cell holds the constant's declared type.
|
|
50
|
-
|
|
51
49
|
| Name | Kind | Signature | Summary |
|
|
52
50
|
| ------------------- | ----- | --------- | -------------------------------------------------------------------------------- |
|
|
53
51
|
| `SQLITE_CONSTRAINT` | const | `19` | Names the SQLite result code whose low byte, `19`, flags a constraint violation. |
|
|
@@ -70,8 +68,6 @@ non-writable own property.
|
|
|
70
68
|
|
|
71
69
|
### Types
|
|
72
70
|
|
|
73
|
-
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 `\|`.
|
|
74
|
-
|
|
75
71
|
| Name | Kind | Signature | Summary |
|
|
76
72
|
| -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
73
|
| `SQLiteValue` | type | `null \| number \| bigint \| string \| Uint8Array` | Represents a value SQLite stores and returns natively — the bridge between SQLite's storage classes and their JS types. |
|
package/dist/host/guides/sse.md
CHANGED
|
@@ -34,8 +34,6 @@ parser.clear() // drop any buffered partial line / event - ready for a fresh str
|
|
|
34
34
|
|
|
35
35
|
### Types
|
|
36
36
|
|
|
37
|
-
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 `\|`.
|
|
38
|
-
|
|
39
37
|
| Name | Kind | Signature | Summary |
|
|
40
38
|
| -------------------- | --------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
41
39
|
| `SSEEvent` | interface | `{ data, event?, id?, retry? }` | Represents one dispatched Server-Sent Event — the value a blank line flushes from an `SSEParserInterface`. Its `data` holds every `data:` field of that event joined by `\n` with no trailing newline, and `event` / `id` / `retry` hold the last field of each name the event carried. |
|
|
@@ -51,20 +49,18 @@ const options: SSEParserOptions = { limit: 1_000_000 }
|
|
|
51
49
|
|
|
52
50
|
### Constants
|
|
53
51
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
|
57
|
-
| ----- | ----- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
58
|
-
| `NUL` | const | `string` | Names the null byte (`U+0000`). The SSE spec voids an `id:` field whose value contains it, so an `id` carrying a NUL is never surfaced. |
|
|
59
|
-
| `BOM` | const | `string` | Names the byte-order mark (`U+FEFF`), stripped from the first non-empty chunk of an SSE stream (a leading mark on later chunks is ordinary content). |
|
|
52
|
+
| Name | Kind | Signature | Summary |
|
|
53
|
+
| ----- | ----- | --------- | --------------------------------------------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| `NUL` | const | `string` | Names the null byte (`U+0000`). The SSE spec voids an `id:` field whose value contains it, so an `id` carrying a NUL is never surfaced. |
|
|
60
55
|
|
|
61
56
|
```ts
|
|
62
|
-
import {
|
|
57
|
+
import { NUL } from '@orkestrel/sse'
|
|
63
58
|
|
|
64
59
|
NUL.charCodeAt(0) // 0
|
|
65
|
-
BOM.charCodeAt(0) // 0xfeff
|
|
66
60
|
```
|
|
67
61
|
|
|
62
|
+
The parser strips the byte-order mark `BOM` that `@orkestrel/codec` exports from the first non-empty chunk of a stream; a leading mark on a later chunk is ordinary content.
|
|
63
|
+
|
|
68
64
|
### Errors
|
|
69
65
|
|
|
70
66
|
| Name | Kind | Signature | Summary |
|