@orkestrel/scaffold 0.0.114 → 0.0.116
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 +137 -15
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/orchestration.md +5 -3
- package/dist/host/agents/platforms/windows.md +1 -0
- package/dist/host/agents/skills/orkestrel-align/references/integration.md +1 -1
- package/dist/host/agents/skills/orkestrel-debrief/SKILL.md +4 -4
- package/dist/host/agents/skills/orkestrel-dispatch/SKILL.md +4 -1
- package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +8 -2
- package/dist/host/agents/skills/orkestrel-harden/references/equivalence.md +1 -0
- package/dist/host/agents/skills/orkestrel-harden/references/hardening.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/references/codex.md +1 -0
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +9 -3
- package/dist/host/claude/agents/analyst.md +1 -1
- package/dist/host/claude/agents/astra.md +2 -2
- package/dist/host/claude/agents/builder.md +4 -4
- package/dist/host/claude/agents/opus.md +3 -3
- package/dist/host/claude/agents/orkestrel.md +5 -7
- package/dist/host/claude/agents/planner.md +8 -2
- package/dist/host/claude/rules/campaign.md +2 -1
- package/dist/host/claude/rules/documentation.md +1 -0
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/claude/rules/tests.md +7 -4
- package/dist/host/claude/rules/writing.md +1 -0
- package/dist/host/claude/skills/enterprise-bootstrap/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-align/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-build/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-debrief/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-dispatch/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-falsify/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-harden/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-journey/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/claude/skills/orkestrel-polish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-publish/SKILL.md +1 -2
- package/dist/host/claude/skills/orkestrel-scout/SKILL.md +1 -1
- package/dist/host/codex/agents/analyst.toml +8 -5
- package/dist/host/codex/agents/astra.toml +4 -5
- package/dist/host/codex/agents/builder.toml +5 -5
- package/dist/host/codex/agents/opus.toml +3 -4
- package/dist/host/codex/agents/orkestrel.toml +2 -1
- package/dist/host/codex/agents/planner.toml +8 -5
- package/dist/host/codex/agents/reviewer.toml +5 -4
- 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 +361 -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 +554 -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 +93 -93
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +89 -3
- 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 +87 -4
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +292 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +188 -6
- package/dist/src/server/index.d.ts +188 -6
- package/dist/src/server/index.js +287 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +4 -3
|
@@ -58,15 +58,15 @@ Cross-face and substrate usage appear under [Patterns](#patterns).
|
|
|
58
58
|
|
|
59
59
|
### Factories
|
|
60
60
|
|
|
61
|
-
|
|
|
62
|
-
| ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
63
|
-
| `createNegotiator` | function | Creates a `NegotiatorInterface` — the reusable content-negotiation machine over the weighted `Accept` family. |
|
|
64
|
-
| `createServer` | function | Creates a `ServerInterface` — the node face's HTTP server facade over a consumed `@orkestrel/router` dispatcher. |
|
|
65
|
-
| `createStream` | function | Creates a `StreamInterface` — a generic Server-Sent-Events stream whose `response` is a fetch-standard streaming `Response` a route returns. |
|
|
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) => StreamInterface` | Creates a `StreamInterface` — 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
|
|
|
69
|
-
|
|
|
69
|
+
| Name | Kind | Signature | Summary |
|
|
70
70
|
| --------------- | ----- | ------------------------- | --------------------------------------------------------------------------- |
|
|
71
71
|
| `ServerBinding` | class | `new () => ServerBinding` | Owns one startup attempt's listening subscription and validated bound port. |
|
|
72
72
|
|
|
@@ -79,109 +79,109 @@ cleanup finish before the start event is emitted.
|
|
|
79
79
|
|
|
80
80
|
A `Shape` cell holds the constant's declared type.
|
|
81
81
|
|
|
82
|
-
|
|
|
82
|
+
| Name | Kind | Signature | Summary |
|
|
83
83
|
| ---------------------------- | ----- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
-
| `DEFAULT_DRAIN_MS` | const | `
|
|
85
|
-
| `DEFAULT_BODY_LIMIT` | const | `
|
|
86
|
-
| `DEFAULT_DECOMPRESSED_LIMIT` | const | `
|
|
84
|
+
| `DEFAULT_DRAIN_MS` | const | `10000` | Names the default graceful-stop deadline `stop()` gives in-flight requests and claimed upgraded sockets, `10_000` ms. |
|
|
85
|
+
| `DEFAULT_BODY_LIMIT` | const | `1048576` | Names the default maximum request body size `readBody` accepts before a 413, `1_048_576` bytes. |
|
|
86
|
+
| `DEFAULT_DECOMPRESSED_LIMIT` | const | `16777216` | Names the default maximum decompressed request body size, `16_777_216` bytes — the zip-bomb cap the body pipeline's byte-counting `TransformStream` enforces when it transparently decompresses a `Content-Encoding` request body. |
|
|
87
87
|
| `SSE_HEADERS` | const | `Readonly<Record<string, string>>` | Holds the SSE response headers a `Stream` sets on its response, merged under any caller `headers` so a caller repeating one of these keys replaces its value. |
|
|
88
88
|
| `REQUEST_ID_PATTERN` | const | `Readonly<RegExp>` | Defines the strict charset `isValidRequestId` requires an incoming `X-Request-ID` to match, `^[A-Za-z0-9_-]{1,200}$`. |
|
|
89
89
|
| `COMPRESSIBLE_TYPES` | const | `ReadonlySet<string>` | Holds the bare `Content-Type` values `isCompressibleType` treats as compressible, beyond the `text/*` prefix and structured-suffix (`+json`, `+xml`) rules that helper also applies. |
|
|
90
|
-
| `HTTP_ERROR_BRAND` | const | `symbol`
|
|
90
|
+
| `HTTP_ERROR_BRAND` | const | `unique symbol` | Names the `Symbol.for`-interned brand `HTTPError` carries, `@orkestrel/server.HTTPError`, so `isHTTPError` recognizes an instance across package copies. A consumer never sets it by hand. |
|
|
91
91
|
| `DEFAULT_ENCODINGS` | const | `readonly Encoding[]` | Lists the default `Encoding` content-codings the substrate offers, in preference order — `gzip` then `deflate`. |
|
|
92
92
|
|
|
93
93
|
### Helpers
|
|
94
94
|
|
|
95
|
-
|
|
|
96
|
-
| ------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
97
|
-
| `compose` | function | Composes an ordered chain of `MiddlewareHandler` layers around a `terminal` handler into one request handler — the frozen middleware seam. |
|
|
98
|
-
| `wrapMiddleware` | function | Wraps one middleware layer around its downstream handler, enforcing the one-call `next` invariant. |
|
|
99
|
-
| `parseCookies` | function | Parses a raw `Cookie:` request header into a `name → value` lookup. |
|
|
100
|
-
| `isCookieName` | function | Checks whether a string is a valid RFC 6265 cookie name — a non-empty run of cookie-token characters with no surrounding or interior whitespace. |
|
|
101
|
-
| `decodeCookieValue` | function | Decodes a cookie value with `decodeURIComponent`, falling back to the raw text when the value is not valid percent-encoding. |
|
|
102
|
-
| `isCookieAttribute` | function | Checks whether a string is safe to interpolate as a `Set-Cookie` attribute value — the guard `serializeCookie` applies to a `Domain` and a `Path` before it emits them. |
|
|
103
|
-
| `serializeCookie` | function | Serializes a cookie into a `Set-Cookie` header value — `name=value` plus its attributes. |
|
|
104
|
-
| `resolveSecure` | function | Resolves a cookie's effective `Secure` flag from its `CookieOptions` `secure` setting and whether the request arrived over TLS. |
|
|
105
|
-
| `writeSignedCookie` | function | Writes a signed cookie — HMAC-signs `value` with `signToken` and appends it as a `Set-Cookie` (the inverse of `readSignedCookie`). |
|
|
106
|
-
| `readSignedCookie` | function | Reads and verifies a signed cookie off a request — total, returning the embedded value or `undefined` (the inverse of `writeSignedCookie`). |
|
|
107
|
-
| `clearCookie` | function | Clears a cookie — appends a `Set-Cookie` that expires it immediately (`Max-Age=0`). |
|
|
108
|
-
| `signToken` | function | Signs a value into a stateless, HMAC-SHA256 token — `<payload>.<signature>`. |
|
|
109
|
-
| `verifyToken` | function | Verifies a stateless token and returns its embedded value — total, never throws. |
|
|
110
|
-
| `decodeTokenPayload` | function | Decodes and narrows a signed token's base64url JSON payload, honoring its expiry — the shared decode step `verifyToken` applies after a signature match. |
|
|
111
|
-
| `normalizeSecret` | function | Normalizes a `TokenSecret` to a concrete list of usable secrets — the list behind both `signToken` and `verifyToken`. |
|
|
112
|
-
| `parseAcceptHeader` | function | Parses a weighted `Accept` / `Accept-Encoding` / `Accept-Language` header into its q-sorted entries. |
|
|
113
|
-
| `computeCodingQuality` | function | Computes the client's quality (q) for one content-coding from the parsed `Accept-Encoding` entries — the scoring leaf `resolveCoding` runs over each offered coding. |
|
|
114
|
-
| `resolveCoding` | function | Picks the highest-scoring content-coding the server offers against already parsed `Accept-Encoding` entries — the shared selection leaf behind `negotiateEncoding` and a `Negotiator`'s `encoding` axis. |
|
|
115
|
-
| `negotiateEncoding` | function | Selects the best content-coding for a raw `Accept-Encoding` header from the codings the server offers. |
|
|
116
|
-
| `matchMediaType` | function | Reports the rank and quality of one `candidate` media type against the parsed `Accept` entries — the generic media-type primitive the `Negotiator`'s `negotiate` uses to score each `available` candidate. |
|
|
117
|
-
| `computeLanguageQuality` | function | Computes the client's quality for one `candidate` language from the parsed `Accept-Language` entries — the scoring leaf the `Negotiator`'s `language` axis runs over each offered tag. |
|
|
118
|
-
| `isCompressibleType` | function | Checks whether a `Content-Type` is worth compressing. |
|
|
119
|
-
| `computeBodyETag` | function | Computes a content `ETag` over a fully-buffered response body by using WebCrypto. |
|
|
120
|
-
| `unwrapETag` | function | Strips the weak indicator (`W/`) from an entity-tag, returning its opaque comparison body — the reduction `matchesETag` applies to each side before the RFC 7232 §2.3.2 weak comparison. |
|
|
121
|
-
| `matchesETag` | function | Checks whether a request's `If-None-Match` header matches a resource's current `ETag` — the RFC 7232 §2.3.2 weak comparison. |
|
|
122
|
-
| `parseRange` | function | Parses an HTTP `Range` request header against a known resource `size` — total, returning a `RangeSpec` or `undefined`. |
|
|
123
|
-
| `resolveOrigin` | function | Resolves the `Access-Control-Allow-Origin` value for a request. |
|
|
124
|
-
| `mergeVary` | function | Merges a `Vary` value into an existing `Vary` header without duplication. |
|
|
125
|
-
| `resolveSecurityHeader` | function | Resolves one opt-out, value-bearing security header. |
|
|
126
|
-
| `isValidRequestId` | function | Checks whether a client-supplied `X-Request-ID` is safe to echo into a response header and `context.state`. |
|
|
127
|
-
| `computeIPv6Network` | function | Computes the `/64` network of a full IPv6 address, or `undefined` when the input is not a plain IPv6 address to collapse. |
|
|
128
|
-
| `computeClientKey` | function | Collapses a client IP into its rate-limit bucket key — an IPv6 address to its `/64` network, an IPv4 (or IPv4-mapped) address unchanged. |
|
|
129
|
-
| `serializeEvent` | function | Serializes one `SSEMessage` to the SSE wire. |
|
|
130
|
-
| `isDangerousKey` | function | Checks whether a key is a prototype-pollution vector — `__proto__`, `constructor`, or `prototype`, each of which can reach and mutate `Object.prototype` when it is assigned onto a normal object. |
|
|
131
|
-
| `scrubPrototype` | function | Strips the prototype-pollution keys from a parsed value in place, recursively. |
|
|
132
|
-
| `collectRequestBody` | function | Collects a `Request` body into a single `Uint8Array`, enforcing a size limit. |
|
|
133
|
-
| `parseEncoding` | function | Parses a raw `Content-Encoding` header value into a decompressible `Encoding` — the boundary `readBody` coerces through to decide whether a request body needs transparent decompression. |
|
|
134
|
-
| `decompressRequestBody` | function | Decompresses an already-collected, `gzip`/`deflate`-encoded byte sequence transparently through `DecompressionStream`, capping the decompressed output — the zip-bomb defense. |
|
|
135
|
-
| `readBody` | function | Collects and decodes a `Request` body — the shared body-collection pipeline surfaced to middleware and handlers as the middleware context's cached `body()`. An empty body and a malformed `application/json` body each decode to `undefined`. |
|
|
136
|
-
| `isHTTPError` | function | Narrows an unknown caught value to an `HTTPError`, including a subclass such as `ContentTooLargeError`, and recognizes an instance from another copy of this package through its own identity brand. |
|
|
137
|
-
| `isServerError` | function | Narrows an unknown caught value to a `ServerError` — the code-bearing refusal of a call the caller programmed. |
|
|
138
|
-
| `isAddressInfo` | function | Checks whether a `node:net` `server.address()` return is the structured `AddressInfo` (carrying a numeric `port`) rather than a pipe `string` or `null` — the total, never-throwing narrow `discoverPort` and the `Server`'s own port resolution read the bound port through. |
|
|
139
|
-
| `probePort` | function | Binds and closes a throwaway TCP server to resolve one available port. |
|
|
140
|
-
| `discoverPort` | function | Finds a free TCP port — binds a throwaway `node:net` server on a `preferred` port where one is given and on an ephemeral port otherwise, reads the bound port, closes the server, and resolves that port. |
|
|
95
|
+
| Name | Kind | Signature | Summary |
|
|
96
|
+
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
97
|
+
| `compose` | function | `<TState>(middleware: ReadonlyArray<MiddlewareHandler<TState>>, terminal: (request: Request, context: MiddlewareContext<TState>) => Promise<Response>) => (request: Request, context: MiddlewareContext<TState>) => Promise<Response>` | Composes an ordered chain of `MiddlewareHandler` layers around a `terminal` handler into one request handler — the frozen middleware seam. |
|
|
98
|
+
| `wrapMiddleware` | function | `<TState>(layer: MiddlewareHandler<TState>, next: (request: Request, context: MiddlewareContext<TState>) => Promise<Response>) => (request: Request, context: MiddlewareContext<TState>) => Promise<Response>` | Wraps one middleware layer around its downstream handler, enforcing the one-call `next` invariant. |
|
|
99
|
+
| `parseCookies` | function | `(header: string \| undefined) => Record<string, string>` | Parses a raw `Cookie:` request header into a `name → value` lookup. |
|
|
100
|
+
| `isCookieName` | function | `(value: string) => boolean` | Checks whether a string is a valid RFC 6265 cookie name — a non-empty run of cookie-token characters with no surrounding or interior whitespace. |
|
|
101
|
+
| `decodeCookieValue` | function | `(raw: string) => string` | Decodes a cookie value with `decodeURIComponent`, falling back to the raw text when the value is not valid percent-encoding. |
|
|
102
|
+
| `isCookieAttribute` | function | `(value: string) => boolean` | Checks whether a string is safe to interpolate as a `Set-Cookie` attribute value — the guard `serializeCookie` applies to a `Domain` and a `Path` before it emits them. |
|
|
103
|
+
| `serializeCookie` | function | `(name: string, value: string, options?: CookieOptions) => string` | Serializes a cookie into a `Set-Cookie` header value — `name=value` plus its attributes. |
|
|
104
|
+
| `resolveSecure` | function | `(secure: boolean \| undefined, encrypted: boolean) => boolean` | Resolves a cookie's effective `Secure` flag from its `CookieOptions` `secure` setting and whether the request arrived over TLS. |
|
|
105
|
+
| `writeSignedCookie` | function | `(headers: Headers, name: string, value: string, secret: TokenSecret, options?: CookieOptions) => Promise<void>` | Writes a signed cookie — HMAC-signs `value` with `signToken` and appends it as a `Set-Cookie` (the inverse of `readSignedCookie`). |
|
|
106
|
+
| `readSignedCookie` | function | `(request: Request, name: string, secret: TokenSecret) => Promise<string \| undefined>` | Reads and verifies a signed cookie off a request — total, returning the embedded value or `undefined` (the inverse of `writeSignedCookie`). |
|
|
107
|
+
| `clearCookie` | function | `(headers: Headers, name: string, options?: CookieOptions) => void` | Clears a cookie — appends a `Set-Cookie` that expires it immediately (`Max-Age=0`). |
|
|
108
|
+
| `signToken` | function | `(value: string, options: TokenOptions) => Promise<string>` | Signs a value into a stateless, HMAC-SHA256 token — `<payload>.<signature>`. |
|
|
109
|
+
| `verifyToken` | function | `(token: string, secret: TokenSecret) => Promise<string \| undefined>` | Verifies a stateless token and returns its embedded value — total, never throws. |
|
|
110
|
+
| `decodeTokenPayload` | function | `(encoded: string) => string \| undefined` | Decodes and narrows a signed token's base64url JSON payload, honoring its expiry — the shared decode step `verifyToken` applies after a signature match. |
|
|
111
|
+
| `normalizeSecret` | function | `(secret: TokenSecret) => readonly string[]` | Normalizes a `TokenSecret` to a concrete list of usable secrets — the list behind both `signToken` and `verifyToken`. |
|
|
112
|
+
| `parseAcceptHeader` | function | `(header: string) => readonly AcceptEntry[]` | Parses a weighted `Accept` / `Accept-Encoding` / `Accept-Language` header into its q-sorted entries. |
|
|
113
|
+
| `computeCodingQuality` | function | `(entries: readonly AcceptEntry[], coding: string) => number` | Computes the client's quality (q) for one content-coding from the parsed `Accept-Encoding` entries — the scoring leaf `resolveCoding` runs over each offered coding. |
|
|
114
|
+
| `resolveCoding` | function | `<T extends string>(entries: readonly AcceptEntry[], available: readonly T[]) => T \| undefined` | Picks the highest-scoring content-coding the server offers against already parsed `Accept-Encoding` entries — the shared selection leaf behind `negotiateEncoding` and a `Negotiator`'s `encoding` axis. |
|
|
115
|
+
| `negotiateEncoding` | function | `<T extends string>(header: string, available: readonly T[]) => T \| undefined` | Selects the best content-coding for a raw `Accept-Encoding` header from the codings the server offers. |
|
|
116
|
+
| `matchMediaType` | function | `(entries: readonly AcceptEntry[], candidate: string) => MediaMatch \| undefined` | Reports the rank and quality of one `candidate` media type against the parsed `Accept` entries — the generic media-type primitive the `Negotiator`'s `negotiate` uses to score each `available` candidate. |
|
|
117
|
+
| `computeLanguageQuality` | function | `(entries: readonly AcceptEntry[], candidate: string) => number` | Computes the client's quality for one `candidate` language from the parsed `Accept-Language` entries — the scoring leaf the `Negotiator`'s `language` axis runs over each offered tag. |
|
|
118
|
+
| `isCompressibleType` | function | `(type: string) => boolean` | Checks whether a `Content-Type` is worth compressing. |
|
|
119
|
+
| `computeBodyETag` | function | `(body: Uint8Array<ArrayBuffer>, weak?: boolean) => Promise<string>` | Computes a content `ETag` over a fully-buffered response body by using WebCrypto. |
|
|
120
|
+
| `unwrapETag` | function | `(tag: string) => string` | Strips the weak indicator (`W/`) from an entity-tag, returning its opaque comparison body — the reduction `matchesETag` applies to each side before the RFC 7232 §2.3.2 weak comparison. |
|
|
121
|
+
| `matchesETag` | function | `(header: string, etag: string) => boolean` | Checks whether a request's `If-None-Match` header matches a resource's current `ETag` — the RFC 7232 §2.3.2 weak comparison. |
|
|
122
|
+
| `parseRange` | function | `(header: string \| undefined, size: number) => RangeSpec \| undefined` | Parses an HTTP `Range` request header against a known resource `size` — total, returning a `RangeSpec` or `undefined`. |
|
|
123
|
+
| `resolveOrigin` | function | `(origin: string \| readonly string[], requestOrigin: string \| undefined) => string \| undefined` | Resolves the `Access-Control-Allow-Origin` value for a request. |
|
|
124
|
+
| `mergeVary` | function | `(existing: string \| undefined, value: string) => string` | Merges a `Vary` value into an existing `Vary` header without duplication. |
|
|
125
|
+
| `resolveSecurityHeader` | function | `(value: string \| false \| undefined, fallback: string) => string \| undefined` | Resolves one opt-out, value-bearing security header. |
|
|
126
|
+
| `isValidRequestId` | function | `(value: string) => boolean` | Checks whether a client-supplied `X-Request-ID` is safe to echo into a response header and `context.state`. |
|
|
127
|
+
| `computeIPv6Network` | function | `(address: string) => string \| undefined` | Computes the `/64` network of a full IPv6 address, or `undefined` when the input is not a plain IPv6 address to collapse. |
|
|
128
|
+
| `computeClientKey` | function | `(address: string) => string` | Collapses a client IP into its rate-limit bucket key — an IPv6 address to its `/64` network, an IPv4 (or IPv4-mapped) address unchanged. |
|
|
129
|
+
| `serializeEvent` | function | `(message: SSEMessage) => string` | Serializes one `SSEMessage` to the SSE wire. |
|
|
130
|
+
| `isDangerousKey` | function | `(key: string) => boolean` | Checks whether a key is a prototype-pollution vector — `__proto__`, `constructor`, or `prototype`, each of which can reach and mutate `Object.prototype` when it is assigned onto a normal object. |
|
|
131
|
+
| `scrubPrototype` | function | `(value: unknown) => unknown` | Strips the prototype-pollution keys from a parsed value in place, recursively. |
|
|
132
|
+
| `collectRequestBody` | function | `(request: Request, limit: number) => Promise<Uint8Array<ArrayBuffer>>` | Collects a `Request` body into a single `Uint8Array`, enforcing a size limit. |
|
|
133
|
+
| `parseEncoding` | function | `(header: string \| null) => Exclude<Encoding, 'identity'> \| undefined` | Parses a raw `Content-Encoding` header value into a decompressible `Encoding` — the boundary `readBody` coerces through to decide whether a request body needs transparent decompression. |
|
|
134
|
+
| `decompressRequestBody` | function | `(bytes: Uint8Array<ArrayBuffer>, encoding: Exclude<Encoding, 'identity'>, cap: number) => Promise<Uint8Array<ArrayBuffer>>` | Decompresses an already-collected, `gzip`/`deflate`-encoded byte sequence transparently through `DecompressionStream`, capping the decompressed output — the zip-bomb defense. |
|
|
135
|
+
| `readBody` | function | `(request: Request, options?: BodyOptions) => Promise<unknown>` | Collects and decodes a `Request` body — the shared body-collection pipeline surfaced to middleware and handlers as the middleware context's cached `body()`. An empty body and a malformed `application/json` body each decode to `undefined`. |
|
|
136
|
+
| `isHTTPError` | function | `(value: unknown) => value is HTTPError` | Narrows an unknown caught value to an `HTTPError`, including a subclass such as `ContentTooLargeError`, and recognizes an instance from another copy of this package through its own identity brand. |
|
|
137
|
+
| `isServerError` | function | `(value: unknown) => value is ServerError` | Narrows an unknown caught value to a `ServerError` — the code-bearing refusal of a call the caller programmed. |
|
|
138
|
+
| `isAddressInfo` | function | `(value: unknown) => value is AddressInfo` | Checks whether a `node:net` `server.address()` return is the structured `AddressInfo` (carrying a numeric `port`) rather than a pipe `string` or `null` — the total, never-throwing narrow `discoverPort` and the `Server`'s own port resolution read the bound port through. |
|
|
139
|
+
| `probePort` | function | `(port: number) => Promise<number>` | Binds and closes a throwaway TCP server to resolve one available port. |
|
|
140
|
+
| `discoverPort` | function | `(preferred?: number) => Promise<number>` | Finds a free TCP port — binds a throwaway `node:net` server on a `preferred` port where one is given and on an ephemeral port otherwise, reads the bound port, closes the server, and resolves that port. |
|
|
141
141
|
|
|
142
142
|
### Classes
|
|
143
143
|
|
|
144
|
-
|
|
|
145
|
-
| ---------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
146
|
-
| `HTTPError` | class | Represents an error a handler (or middleware) throws to produce an HTTP response of a specific status. |
|
|
147
|
-
| `ContentTooLargeError` | class | Represents the `HTTPError` thrown when a request body exceeds the body pipeline's size limit — a `413 Content Too Large`. |
|
|
148
|
-
| `ServerError` | class | Represents the error this package raises when a caller programmed a call the entity refuses, carrying `'STATUS'` or `'NEXT'` as its code. |
|
|
149
|
-
| `Negotiator` | class | Represents the content-negotiation machine over the weighted `Accept` family — a reusable, cross-middleware entity rather than a middleware. Implements exactly `NegotiatorInterface`. |
|
|
150
|
-
| `Server` | class | 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 | Represents the Server-Sent-Events handle over an open, fetch-standard streaming `Response`. Implements exactly `StreamInterface`. |
|
|
144
|
+
| Name | Kind | Signature | Summary |
|
|
145
|
+
| ---------------------- | ----- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
146
|
+
| `HTTPError` | class | `new (status: number, message: string, context?: Readonly<Record<string, unknown>>) => HTTPError` | Represents an error a handler (or middleware) throws to produce an HTTP response of a specific status. |
|
|
147
|
+
| `ContentTooLargeError` | class | `new (limit: number) => ContentTooLargeError` | Represents the `HTTPError` thrown when a request body exceeds the body pipeline's size limit — a `413 Content Too Large`. |
|
|
148
|
+
| `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
|
+
| `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
|
+
| `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) => StreamInterface` | Represents the Server-Sent-Events handle over an open, fetch-standard streaming `Response`. Implements exactly `StreamInterface`. |
|
|
152
152
|
|
|
153
153
|
### Types
|
|
154
154
|
|
|
155
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
156
|
|
|
157
|
-
|
|
|
158
|
-
| ------------------------- | --------- |
|
|
159
|
-
| `MiddlewareContext` | interface | `{ url, method, state }
|
|
160
|
-
| `NextFunction` | type | `(request?: Request) => Promise<Response>`
|
|
161
|
-
| `MiddlewareHandler` | type | `(request: Request, context: MiddlewareContext<TState>, next: NextFunction) => Response \| Promise<Response>`
|
|
162
|
-
| `Connection` | interface | `{ ip?, encrypted }`
|
|
163
|
-
| `TokenSecret` | type | `string \| readonly string[]`
|
|
164
|
-
| `TokenOptions` | interface | `{ secret, ttl? }`
|
|
165
|
-
| `CookieOptions` | interface | `{ path?, domain?, maxAge?, httpOnly?, secure?, sameSite? }`
|
|
166
|
-
| `AcceptEntry` | interface | `{ value, q }`
|
|
167
|
-
| `MediaMatch` | interface | `{ q, rank }`
|
|
168
|
-
| `Encoding` | type | `'gzip' \| 'deflate' \| 'identity'`
|
|
169
|
-
| `FormatHandlerMap` | type | `Readonly<Record<string, (request: Request, context: MiddlewareContext<TState>) => Response \| Promise<Response>>>`
|
|
170
|
-
| `NegotiatorInterface` | interface | `{
|
|
171
|
-
| `SSEMessage` | interface | `{ data, event?, id?, retry? }`
|
|
172
|
-
| `StreamOptions` | interface | `{ status?, headers? }`
|
|
173
|
-
| `StreamInterface` | interface | `{ response, closed
|
|
174
|
-
| `RangeSpec` | type | `{ readonly satisfiable: true; readonly start: number; readonly end: number } \| { readonly satisfiable: false }`
|
|
175
|
-
| `BodyOptions` | interface | `{ limit?, decompression? }`
|
|
176
|
-
| `ServerStatus` | type | `'idle' \| 'starting' \| 'listening' \| 'stopping' \| 'stopped'`
|
|
177
|
-
| `ServerErrorCode` | type | `'STATUS' \| 'NEXT'`
|
|
178
|
-
| `RequestLine` | interface | `{ method, url }`
|
|
179
|
-
| `ResponseRecord` | interface | `{ method, pathname, status, ms }`
|
|
180
|
-
| `ServerEventMap` | type | `{ start
|
|
181
|
-
| `UpgradeHandler` | type | `(request: IncomingMessage, socket: Duplex, head: Buffer) => boolean`
|
|
182
|
-
| `ConnectionStateFunction` | type | `(connection: Connection) => TState`
|
|
183
|
-
| `ServerOptions` | interface | `{ dispatcher, state, middleware?, host?, port?, drain?, limit?, expose?, report?, timeouts?, sockets?, on?, error? }`
|
|
184
|
-
| `ServerInterface` | interface | `{ id, status, port, address, dispatcher, emitter
|
|
157
|
+
| Name | Kind | Signature | Summary |
|
|
158
|
+
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
159
|
+
| `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. |
|
|
160
|
+
| `NextFunction` | type | `(request?: Request) => Promise<Response>` | Represents the downstream continuation a `MiddlewareHandler` invokes to run the rest of the onion — guarded so a second call within one invocation rejects. |
|
|
161
|
+
| `MiddlewareHandler` | type | `(request: Request, context: MiddlewareContext<TState>, next: NextFunction) => Response \| Promise<Response>` | Represents one link in the middleware onion — runs around the rest of the chain. |
|
|
162
|
+
| `Connection` | interface | `{ ip?, encrypted }` | Represents the per-request connection facts the server face injects — the only data that genuinely exists solely on the socket, surfaced so middleware and a consumer's `state` factory stay core-pure. |
|
|
163
|
+
| `TokenSecret` | type | `string \| readonly string[]` | Represents a secret, or a `[current, ...older]` rotation list, for signing and verifying a stateless, HMAC-signed token. |
|
|
164
|
+
| `TokenOptions` | interface | `{ secret, ttl? }` | Options for `signToken` — how a stateless, HMAC-signed token is minted. |
|
|
165
|
+
| `CookieOptions` | interface | `{ path?, domain?, maxAge?, httpOnly?, secure?, sameSite? }` | Represents the `Set-Cookie` attributes for `serializeCookie` (and any signed-cookie transport built over it). |
|
|
166
|
+
| `AcceptEntry` | interface | `{ value, q }` | Represents one parsed entry of a weighted `Accept` / `Accept-Encoding` / `Accept-Language` header — a value and its quality weight, the element type `parseAcceptHeader` returns (sorted by `q` descending). |
|
|
167
|
+
| `MediaMatch` | interface | `{ q, rank }` | Rates one candidate media type against a parsed `Accept` header — the quality and specificity `matchMediaType` reports for the best matching `AcceptEntry`. |
|
|
168
|
+
| `Encoding` | type | `'gzip' \| 'deflate' \| 'identity'` | Represents a content-coding the substrate compresses or decompresses with. Its members are the `Content-Encoding` and `Accept-Encoding` token vocabulary the substrate understands. |
|
|
169
|
+
| `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
|
+
| `NegotiatorInterface` | interface | `{ negotiate(), encoding(), language(), format() }` | Represents content negotiation over the weighted `Accept` family — a reusable, cross-middleware machine (not itself a middleware). |
|
|
171
|
+
| `SSEMessage` | interface | `{ data, event?, id?, retry? }` | Represents one Server-Sent Event to serialize to the wire. |
|
|
172
|
+
| `StreamOptions` | interface | `{ status?, headers? }` | Options for a `StreamInterface` — how `createStream` opens the streaming response. |
|
|
173
|
+
| `StreamInterface` | 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
|
+
| `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
|
+
| `BodyOptions` | interface | `{ limit?, decompression? }` | Options for `readBody` — how the shared body-collection pipeline caps and decompresses a request body. |
|
|
176
|
+
| `ServerStatus` | type | `'idle' \| 'starting' \| 'listening' \| 'stopping' \| 'stopped'` | Represents the `Server`'s lifecycle state. |
|
|
177
|
+
| `ServerErrorCode` | type | `'STATUS' \| 'NEXT'` | Represents the machine-readable category a `ServerError` carries — `'STATUS'` for a lifecycle call the current status forbids, `'NEXT'` for a middleware that called its `next` a second time. |
|
|
178
|
+
| `RequestLine` | interface | `{ method, url }` | Identifies the request a server-level fault came from — its method and its parsed URL. |
|
|
179
|
+
| `ResponseRecord` | interface | `{ method, pathname, status, ms }` | Records one finished request — the payload `ServerEventMap.response` carries. |
|
|
180
|
+
| `ServerEventMap` | type | `{ readonly start: readonly [port: number]; readonly request: readonly [method: string, pathname: string]; readonly upgrade: readonly [request: IncomingMessage, handled: boolean]; readonly error: readonly [error: unknown, request?: RequestLine]; readonly stop: readonly []; readonly drain: readonly [pending: number, upgraded: number]; readonly response: readonly [event: ResponseRecord]; }` | Represents the `Server`'s observable lifecycle events. |
|
|
181
|
+
| `UpgradeHandler` | type | `(request: IncomingMessage, socket: Duplex, head: Buffer) => boolean` | Represents a raw `node:http` protocol-upgrade claimant — registered through `ServerInterface.upgrade`. |
|
|
182
|
+
| `ConnectionStateFunction` | type | `(connection: Connection) => TState` | Derives a consumer's per-request `TState` from the adapter-injected `Connection` — `ServerOptions.state`, invoked once per request before the middleware onion runs. |
|
|
183
|
+
| `ServerOptions` | interface | `{ dispatcher, state, middleware?, host?, port?, drain?, limit?, expose?, report?, timeouts?, sockets?, on?, error? }` | Options for `createServer` — the dispatcher and per-request state factory the server requires, plus its listener, drain, boundary, timeout, socket-cap, and emitter knobs. |
|
|
184
|
+
| `ServerInterface` | interface | `{ id, status, port, address, dispatcher, emitter, use(), upgrade(), start(), stop(), destroy() }` | Represents the HTTP server facade — an observable `node:http` lifecycle that composes a middleware onion (this module's own middleware seam) around a consumed `@orkestrel/router` `DispatcherInterface`. |
|
|
185
185
|
|
|
186
186
|
Each interface's `readonly` data members stay Surface rows, and its call-signature
|
|
187
187
|
members are documented under [Methods](#methods). `ServerInterface.address` is the
|
|
@@ -191,13 +191,13 @@ bound node `AddressInfo` while the listener is active and `undefined` otherwise.
|
|
|
191
191
|
|
|
192
192
|
The error guards and request readers expose these primitives.
|
|
193
193
|
|
|
194
|
-
|
|
|
195
|
-
| ------------------------------- | -------- | ------------------------------------------------------------------------------------- |
|
|
196
|
-
| `SERVER_ERROR_BRAND` | const | Names the identity brand carried by lifecycle errors across package copies. |
|
|
197
|
-
| `CONTENT_TOO_LARGE_ERROR_BRAND` | const | Names the identity brand carried by body-limit errors across package copies. |
|
|
198
|
-
| `isContentTooLargeError` | function | Recognizes a branded body-limit error, including subclasses and other package copies. |
|
|
199
|
-
| `iterateMediaMatches` | function | Yields matching media ranges through the first exact rejection. |
|
|
200
|
-
| `iterateRequestBody` | function | Yields the same lazily collected request-body promise on every read. |
|
|
194
|
+
| Name | Kind | Signature | Summary |
|
|
195
|
+
| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
196
|
+
| `SERVER_ERROR_BRAND` | const | `unique symbol` | Names the identity brand carried by lifecycle errors across package copies. |
|
|
197
|
+
| `CONTENT_TOO_LARGE_ERROR_BRAND` | const | `unique symbol` | Names the identity brand carried by body-limit errors across package copies. |
|
|
198
|
+
| `isContentTooLargeError` | function | `(value: unknown) => value is ContentTooLargeError` | Recognizes a branded body-limit error, including subclasses and other package copies. |
|
|
199
|
+
| `iterateMediaMatches` | function | `(entries: readonly AcceptEntry[], candidate: string) => Generator<MediaMatch, void, unknown>` | Yields matching media ranges through the first exact rejection. |
|
|
200
|
+
| `iterateRequestBody` | function | `(request: Request, limit: number) => Generator<Promise<unknown>, never, unknown>` | Yields the same lazily collected request-body promise on every read. |
|
|
201
201
|
|
|
202
202
|
## Methods
|
|
203
203
|
|
|
@@ -33,34 +33,34 @@ db.prepare('SELECT name FROM users WHERE age >= ?').all([18]) // → [{ name: 'A
|
|
|
33
33
|
|
|
34
34
|
### Factories
|
|
35
35
|
|
|
36
|
-
|
|
|
37
|
-
| ---------------------- | -------- | -------------------------------------------------------------------------------------------- |
|
|
38
|
-
| `createSQLiteDatabase` | function | Creates a synchronous SQLite database over `node:sqlite`, defaulting its path to `:memory:`. |
|
|
36
|
+
| Name | Kind | Signature | Summary |
|
|
37
|
+
| ---------------------- | -------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
38
|
+
| `createSQLiteDatabase` | function | `(options?: SQLiteDatabaseOptions) => SQLiteDatabaseInterface` | Creates a synchronous SQLite database over `node:sqlite`, defaulting its path to `:memory:`. |
|
|
39
39
|
|
|
40
40
|
### Classes
|
|
41
41
|
|
|
42
|
-
|
|
|
43
|
-
| ----------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
44
|
-
| `SQLiteDatabase` | class | Implements `SQLiteDatabaseInterface` over a lazily opened `DatabaseSync` the instance owns, gating every operation on that connection and mapping each native fault to a `SQLiteError`. |
|
|
45
|
-
| `SQLiteStatement` | class | Implements `SQLiteStatementInterface` over one compiled `StatementSync`, gating each call on its owning connection still being open and mapping every native fault, a mid-stream one included, to a `SQLiteError`. |
|
|
42
|
+
| Name | Kind | Signature | Summary |
|
|
43
|
+
| ----------------- | ----- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
44
|
+
| `SQLiteDatabase` | class | `new (options: SQLiteDatabaseOptions) => SQLiteDatabaseInterface` | Implements `SQLiteDatabaseInterface` over a lazily opened `DatabaseSync` the instance owns, gating every operation on that connection and mapping each native fault to a `SQLiteError`. |
|
|
45
|
+
| `SQLiteStatement` | class | `new (statement: StatementSync, closed: () => boolean) => SQLiteStatementInterface` | Implements `SQLiteStatementInterface` over one compiled `StatementSync`, gating each call on its owning connection still being open and mapping every native fault, a mid-stream one included, to a `SQLiteError`. |
|
|
46
46
|
|
|
47
47
|
### Constants
|
|
48
48
|
|
|
49
49
|
A `Shape` cell holds the constant's declared type.
|
|
50
50
|
|
|
51
|
-
|
|
|
52
|
-
| ------------------- | ----- |
|
|
53
|
-
| `SQLITE_CONSTRAINT` | const | `
|
|
54
|
-
| `SQLITE_BUSY` | const | `
|
|
51
|
+
| Name | Kind | Signature | Summary |
|
|
52
|
+
| ------------------- | ----- | --------- | -------------------------------------------------------------------------------- |
|
|
53
|
+
| `SQLITE_CONSTRAINT` | const | `19` | Names the SQLite result code whose low byte, `19`, flags a constraint violation. |
|
|
54
|
+
| `SQLITE_BUSY` | const | `5` | Names the SQLite result code whose low byte, `5`, flags a locked-database fault. |
|
|
55
55
|
|
|
56
56
|
### Helpers and errors
|
|
57
57
|
|
|
58
|
-
|
|
|
59
|
-
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
-
| `wrapError` | function | Converts a thrown native `node:sqlite` error into a typed `SQLiteError` at the wrapper's one boundary. |
|
|
61
|
-
| `bindParameters` | function | Normalizes `SQLiteParameters` to the binding shape a native `StatementSync` call expects — a positional spread, or a single named record. |
|
|
62
|
-
| `SQLiteError` | class | Represents an error thrown by the SQLite wrapper, carrying a machine-readable `code` — `CLOSED`, `CONSTRAINT`, `BUSY`, `INVALID`, or `UNKNOWN`. |
|
|
63
|
-
| `isSQLiteError` | function | Checks whether a value is a `SQLiteError`. |
|
|
58
|
+
| Name | Kind | Signature | Summary |
|
|
59
|
+
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `wrapError` | function | `(error: unknown) => SQLiteError` | Converts a thrown native `node:sqlite` error into a typed `SQLiteError` at the wrapper's one boundary. |
|
|
61
|
+
| `bindParameters` | function | `(parameters?: SQLiteParameters) => SQLiteBinding` | Normalizes `SQLiteParameters` to the binding shape a native `StatementSync` call expects — a positional spread, or a single named record. |
|
|
62
|
+
| `SQLiteError` | class | `new (code: SQLiteErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => SQLiteError` | Represents an error thrown by the SQLite wrapper, carrying a machine-readable `code` — `CLOSED`, `CONSTRAINT`, `BUSY`, `INVALID`, or `UNKNOWN`. |
|
|
63
|
+
| `isSQLiteError` | function | `(value: unknown) => value is SQLiteError` | Checks whether a value is a `SQLiteError`. |
|
|
64
64
|
|
|
65
65
|
`isSQLiteError` recognizes the own identity brand and declared members across package copies
|
|
66
66
|
and module formats. It accepts subclass instances without requiring their name and refuses
|
|
@@ -72,17 +72,17 @@ non-writable own property.
|
|
|
72
72
|
|
|
73
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
74
|
|
|
75
|
-
|
|
|
76
|
-
| -------------------------- | --------- |
|
|
77
|
-
| `SQLiteValue` | type | `null \| number \| bigint \| string \| Uint8Array`
|
|
78
|
-
| `SQLiteRow` | type | `Record<string, SQLiteValue>`
|
|
79
|
-
| `SQLiteParameters` | type | `readonly SQLiteValue[] \| Readonly<Record<string, SQLiteValue>>`
|
|
80
|
-
| `SQLiteBinding` | type | `{ positional } \| { named }`
|
|
81
|
-
| `SQLiteExecuteResult` | interface | `{ changes, rowid }`
|
|
82
|
-
| `SQLiteErrorCode` | type | `'CLOSED' \| 'CONSTRAINT' \| 'BUSY' \| 'INVALID' \| 'UNKNOWN'`
|
|
83
|
-
| `SQLiteDatabaseOptions` | interface | `{ path?, readonly?, timeout?, foreignKeys?, bigints? }`
|
|
84
|
-
| `SQLiteStatementInterface` | interface | `{
|
|
85
|
-
| `SQLiteDatabaseInterface` | interface | `{ path, connected, transacting
|
|
75
|
+
| Name | Kind | Signature | Summary |
|
|
76
|
+
| -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| `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. |
|
|
78
|
+
| `SQLiteRow` | type | `Record<string, SQLiteValue>` | Represents a result row — a record of column name to `SQLiteValue`. |
|
|
79
|
+
| `SQLiteParameters` | type | `readonly SQLiteValue[] \| Readonly<Record<string, SQLiteValue>>` | Represents the bind parameters for a prepared statement — positional (an array, bound to `?`) or named (a record, bound to bare `:name` placeholders). |
|
|
80
|
+
| `SQLiteBinding` | type | `{ readonly positional: readonly SQLiteValue[]; } \| { readonly named: Readonly<Record<string, SQLiteValue>>; }` | Represents the normalized binding shape a native `StatementSync` call expects — what `SQLiteParameters` become on the way into `node:sqlite`. |
|
|
81
|
+
| `SQLiteExecuteResult` | interface | `{ changes, rowid }` | Represents the outcome of a non-query statement (`INSERT` / `UPDATE` / `DELETE` / DDL). |
|
|
82
|
+
| `SQLiteErrorCode` | type | `'CLOSED' \| 'CONSTRAINT' \| 'BUSY' \| 'INVALID' \| 'UNKNOWN'` | Represents a machine-readable `SQLiteError` code. |
|
|
83
|
+
| `SQLiteDatabaseOptions` | interface | `{ path?, readonly?, timeout?, foreignKeys?, bigints? }` | Represents the options for opening a SQLite connection, accepted by the `createSQLiteDatabase` function and the `SQLiteDatabase` constructor. |
|
|
84
|
+
| `SQLiteStatementInterface` | interface | `{ execute(), get(), all(), iterate() }` | Represents a prepared statement — the only way the wrapper runs SQL. |
|
|
85
|
+
| `SQLiteDatabaseInterface` | interface | `{ path, connected, transacting, connect(), close(), execute(), prepare(), transact(), begin(), commit(), rollback(), pragma(), [Symbol.dispose]() }` | Represents the contract a synchronous SQLite database fulfills over `node:sqlite`'s `DatabaseSync` — prepared statements, transactions, and pragmas, every call returning a plain value rather than a `Promise`. |
|
|
86
86
|
|
|
87
87
|
The `path`, `connected`, and `transacting` members of `SQLiteDatabaseInterface` are `readonly` data members (the preceding Surface row) — its call-signature methods are documented under [Methods](#methods).
|
|
88
88
|
|
package/dist/host/guides/sse.md
CHANGED
|
@@ -36,12 +36,12 @@ parser.clear() // drop any buffered partial line / event - ready for a fresh str
|
|
|
36
36
|
|
|
37
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
38
|
|
|
39
|
-
|
|
|
40
|
-
| -------------------- | --------- |
|
|
41
|
-
| `SSEEvent` | interface | `{ data, event?, id?, retry? }`
|
|
42
|
-
| `SSEParserInterface` | interface | `{
|
|
43
|
-
| `SSEParserOptions` | interface | `{ limit? }`
|
|
44
|
-
| `SSEErrorCode` | type | `'OVERFLOW'`
|
|
39
|
+
| Name | Kind | Signature | Summary |
|
|
40
|
+
| -------------------- | --------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
41
|
+
| `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. |
|
|
42
|
+
| `SSEParserInterface` | interface | `{ parse(), flush(), id, retry, clear() }` | Represents a stateful Server-Sent-Events (SSE) stream parser: feed it string chunks, get back the complete events dispatched so far. A trailing partial line / in-progress event is buffered until the rest arrives, and the sticky `id` / `retry` getters carry the connection state a dispatch leaves in place. |
|
|
43
|
+
| `SSEParserOptions` | interface | `{ limit? }` | Configures the parser `createSSEParser` builds and the `SSEParser` constructor accepts — `limit` caps the total buffered characters held at once, and leaving it unset keeps the buffering unbounded. |
|
|
44
|
+
| `SSEErrorCode` | type | `'OVERFLOW'` | Names the machine-readable code an `SSEError` carries — `'OVERFLOW'` alone, thrown when a `parse(chunk)` call would push the buffered total over a configured `limit`. |
|
|
45
45
|
|
|
46
46
|
```ts
|
|
47
47
|
import type { SSEParserOptions } from '@orkestrel/sse'
|
|
@@ -53,10 +53,10 @@ const options: SSEParserOptions = { limit: 1_000_000 }
|
|
|
53
53
|
|
|
54
54
|
A `Shape` cell holds the constant's declared type.
|
|
55
55
|
|
|
56
|
-
|
|
|
57
|
-
| ----- | ----- |
|
|
58
|
-
| `NUL` | const | string
|
|
59
|
-
| `BOM` | const | string
|
|
56
|
+
| Name | Kind | Signature | Summary |
|
|
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). |
|
|
60
60
|
|
|
61
61
|
```ts
|
|
62
62
|
import { BOM, NUL } from '@orkestrel/sse'
|
|
@@ -67,10 +67,10 @@ BOM.charCodeAt(0) // 0xfeff
|
|
|
67
67
|
|
|
68
68
|
### Errors
|
|
69
69
|
|
|
70
|
-
|
|
|
71
|
-
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
72
|
-
| `SSEError` | class | Represents an error the SSE parser throws, carrying the machine-readable `SSEErrorCode` a `catch` branches on and an optional `context` of diagnostic detail. |
|
|
73
|
-
| `isSSEError` | function | Narrows an unknown caught value to an `SSEError`. |
|
|
70
|
+
| Name | Kind | Signature | Summary |
|
|
71
|
+
| ------------ | -------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
72
|
+
| `SSEError` | class | `new (code: SSEErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => SSEError` | Represents an error the SSE parser throws, carrying the machine-readable `SSEErrorCode` a `catch` branches on and an optional `context` of diagnostic detail. |
|
|
73
|
+
| `isSSEError` | function | `(value: unknown) => value is SSEError` | Narrows an unknown caught value to an `SSEError`. |
|
|
74
74
|
|
|
75
75
|
```ts
|
|
76
76
|
import { isSSEError, SSEError } from '@orkestrel/sse'
|
|
@@ -93,9 +93,9 @@ non-writable own property.
|
|
|
93
93
|
|
|
94
94
|
### Factories
|
|
95
95
|
|
|
96
|
-
|
|
|
97
|
-
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
98
|
-
| `createSSEParser` | function | Creates a Server-Sent-Events (SSE) stream parser — a stateful `SSEParserInterface` handle, backed by `SSEParser`, that turns string chunks into the complete events dispatched so far. |
|
|
96
|
+
| Name | Kind | Signature | Summary |
|
|
97
|
+
| ----------------- | -------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
98
|
+
| `createSSEParser` | function | `(options?: SSEParserOptions) => SSEParserInterface` | Creates a Server-Sent-Events (SSE) stream parser — a stateful `SSEParserInterface` handle, backed by `SSEParser`, that turns string chunks into the complete events dispatched so far. |
|
|
99
99
|
|
|
100
100
|
#### Create a bounded parser and feed it chunks
|
|
101
101
|
|
|
@@ -112,9 +112,9 @@ parser.parse('\n\n') // [{ data: '1', event: 'ping' }]
|
|
|
112
112
|
|
|
113
113
|
### Classes
|
|
114
114
|
|
|
115
|
-
|
|
|
116
|
-
| ----------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
117
|
-
| `SSEParser` | class | Implements `SSEParserInterface` over one internal line buffer, reassembling an event split across chunk boundaries once its blank line arrives and holding the sticky `id` / `retry` connection state until `clear()` drops it. |
|
|
115
|
+
| Name | Kind | Signature | Summary |
|
|
116
|
+
| ----------- | ----- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
117
|
+
| `SSEParser` | class | `new (options?: SSEParserOptions) => SSEParserInterface` | Implements `SSEParserInterface` over one internal line buffer, reassembling an event split across chunk boundaries once its blank line arrives and holding the sticky `id` / `retry` connection state until `clear()` drops it. |
|
|
118
118
|
|
|
119
119
|
## Methods
|
|
120
120
|
|