@orkestrel/scaffold 0.0.115 → 0.0.117
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/main.js +138 -16
- package/dist/bin/main.js.map +1 -1
- package/dist/host/agents/skills/orkestrel-publish/references/wave.md +1 -1
- package/dist/host/claude/agents/orkestrel.md +2 -2
- package/dist/host/claude/rules/names.md +3 -1
- package/dist/host/guides/abort.md +17 -17
- package/dist/host/guides/agent.md +445 -445
- package/dist/host/guides/brief.md +143 -143
- package/dist/host/guides/browser.md +731 -731
- package/dist/host/guides/budget.md +39 -39
- package/dist/host/guides/capture.md +298 -298
- package/dist/host/guides/console.md +109 -109
- package/dist/host/guides/contract.md +335 -335
- package/dist/host/guides/csv.md +30 -30
- package/dist/host/guides/database.md +163 -163
- package/dist/host/guides/emitter.md +17 -17
- package/dist/host/guides/form.md +99 -99
- package/dist/host/guides/guide.md +368 -183
- package/dist/host/guides/html.md +49 -49
- package/dist/host/guides/indexeddb.md +40 -40
- package/dist/host/guides/interpret.md +139 -139
- package/dist/host/guides/lsp.md +114 -114
- package/dist/host/guides/markdown.md +68 -68
- package/dist/host/guides/mcp.md +3745 -3745
- package/dist/host/guides/middleware.md +170 -170
- package/dist/host/guides/msg.md +95 -95
- package/dist/host/guides/ndjson.md +8 -8
- package/dist/host/guides/ollama.md +56 -56
- package/dist/host/guides/pool.md +21 -21
- package/dist/host/guides/probe.md +82 -82
- package/dist/host/guides/process.md +99 -99
- package/dist/host/guides/program.md +98 -96
- package/dist/host/guides/qualifier.md +70 -70
- package/dist/host/guides/queue.md +37 -37
- package/dist/host/guides/rater.md +38 -38
- package/dist/host/guides/reason.md +308 -308
- package/dist/host/guides/relation.md +50 -50
- package/dist/host/guides/router.md +58 -58
- package/dist/host/guides/scaffold.md +558 -419
- package/dist/host/guides/sea.md +128 -128
- package/dist/host/guides/server.md +100 -100
- package/dist/host/guides/sqlite.md +28 -28
- package/dist/host/guides/sse.md +20 -20
- package/dist/host/guides/study.md +444 -444
- package/dist/host/guides/table.md +82 -82
- package/dist/host/guides/template.md +41 -41
- package/dist/host/guides/terminal.md +121 -121
- package/dist/host/guides/test.md +273 -273
- package/dist/host/guides/timeout.md +18 -18
- package/dist/host/guides/tool.md +27 -27
- package/dist/host/guides/toolbox.md +166 -166
- package/dist/host/guides/websocket.md +54 -54
- package/dist/host/guides/worker.md +24 -24
- package/dist/host/guides/workflow.md +187 -187
- package/dist/host/guides/workspace.md +55 -55
- package/dist/host/manifest.json +55 -55
- package/dist/host/tests/setupPolicy.ts +5 -3
- package/dist/src/core/index.cjs +90 -4
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.d.cts +229 -144
- package/dist/src/core/index.d.ts +229 -144
- package/dist/src/core/index.js +88 -5
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +295 -66
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +193 -6
- package/dist/src/server/index.d.ts +193 -6
- package/dist/src/server/index.js +290 -69
- package/dist/src/server/index.js.map +1 -1
- package/package.json +5 -4
|
@@ -74,18 +74,18 @@ Pass `tools` (a non-empty `ToolDefinition[]` from `@orkestrel/tool`) to advertis
|
|
|
74
74
|
|
|
75
75
|
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. A function row's `Shape` cell holds its signature, and a guard row's the type it narrows to. A class row's `Shape` cell holds the interface it implements, or its constructor signature where it implements none. A `Shape` cell holds the constant's declared type.
|
|
76
76
|
|
|
77
|
-
|
|
|
77
|
+
| Name | Kind | Signature | Summary |
|
|
78
78
|
| -------------------- | --------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
79
|
| `createOllama` | function | `(options: OllamaOptions) => ProviderInterface` | Creates a local Ollama inference provider — a `ProviderInterface` over the daemon's `POST /api/chat`, assembling `generate` from the same NDJSON engine as `stream`. |
|
|
80
|
-
| `OllamaProvider` | class | `AgentProviderInterface`
|
|
81
|
-
| `OllamaOptions` | interface | `
|
|
80
|
+
| `OllamaProvider` | class | `new (options: OllamaOptions) => AgentProviderInterface` | Implements the Ollama `/api/chat` wire over the shared `AgentProvider` engine. |
|
|
81
|
+
| `OllamaOptions` | interface | `{ model, url?, keepAlive?, options?, think?, truncate?, shift? }` | Represents the configuration `createOllama` accepts for the local Ollama backend. |
|
|
82
82
|
| `WireChatRequest` | interface | `{ model, messages, stream, keep_alive, think, options?, tools?, format?, truncate?, shift? }` | Represents the exact `POST /api/chat` request body `OllamaProvider` sends — the internal typed wire contract. |
|
|
83
83
|
| `OllamaDurations` | interface | `{ total, load, prompt, decode }` | Carries the daemon durations of one terminal record in raw nanoseconds. |
|
|
84
84
|
| `OllamaCounts` | interface | `{ prompt, decode, cached }` | Carries the token counts of one terminal record. |
|
|
85
85
|
| `OllamaTiming` | interface | `{ durations, counts, invalid }` | Carries the timing observation of one terminal record. |
|
|
86
|
-
| `DEFAULT_OLLAMA_URL` | const | `
|
|
87
|
-
| `DEFAULT_KEEP_ALIVE` | const | `
|
|
88
|
-
| `OLLAMA_CHAT_PATH` | const | `
|
|
86
|
+
| `DEFAULT_OLLAMA_URL` | const | `"http://localhost:11434"` | Names the local Ollama daemon base URL, `'http://localhost:11434'`, assumed when `OllamaOptions.url` is omitted. |
|
|
87
|
+
| `DEFAULT_KEEP_ALIVE` | const | `"5m"` | Names how long the model stays resident after a call — `'5m'` when `OllamaOptions.keepAlive` is omitted, Ollama's own `keep_alive` default, expressed as a duration string. |
|
|
88
|
+
| `OLLAMA_CHAT_PATH` | const | `"/api/chat"` | Names the Ollama chat endpoint appended to the configured base URL. |
|
|
89
89
|
| `mapMessages` | function | `(messages: readonly Message[]) => WireChatRequest['messages']` | Maps conversation turns onto the `/api/chat` wire's minimal message shape. |
|
|
90
90
|
| `extractContent` | function | `(record: Readonly<Record<string, unknown>>) => string` | Extracts the assistant text of one wire record. |
|
|
91
91
|
| `extractThinking` | function | `(record: Readonly<Record<string, unknown>>) => string` | Extracts the daemon-side reasoning of one wire record. |
|
|
@@ -103,66 +103,66 @@ The wire leaves — `mapMessages` and the `extract*` narrowing set — are the p
|
|
|
103
103
|
|
|
104
104
|
The raw judge exports the following declarations.
|
|
105
105
|
|
|
106
|
-
|
|
|
107
|
-
| ---------------------- | --------- |
|
|
108
|
-
| `OllamaJudge` | class | `AgentJudgeInterface`
|
|
109
|
-
| `OllamaJudgeOptions` | interface | `
|
|
110
|
-
| `WireGenerateRequest` | interface | `{ model, prompt, raw, stream, logprobs, top_logprobs, keep_alive, options }`
|
|
111
|
-
| `Logprob` | interface | `{ token, logprob }`
|
|
112
|
-
| `createOllamaJudge` | function | `(options: OllamaJudgeOptions) => JudgeInterface`
|
|
113
|
-
| `escapeSpecialTokens` | function | `(text: string) => string`
|
|
114
|
-
| `renderJudgePrompt` | function | `(state: JudgeEntry, question: JudgeQuestion, system: string) => string`
|
|
115
|
-
| `buildJudgeLabels` | function | `(question: JudgeQuestion) => ReadonlyMap<string, string>`
|
|
116
|
-
| `extractTopLogprobs` | function | `(value: unknown) => readonly Logprob[]`
|
|
117
|
-
| `computeAnswer` | function | `(question: JudgeQuestion, top: readonly Logprob[], temperature?: number) => JudgeAnswer \| Refusal`
|
|
118
|
-
| `renderJudgeIdentity` | function | `(options: OllamaJudgeOptions, revision?: string) => string`
|
|
119
|
-
| `OLLAMA_GENERATE_PATH` | const | `
|
|
120
|
-
| `TOP_LOGPROBS` | const | `
|
|
121
|
-
| `MAX_MICA_LEVELS` | const | `
|
|
122
|
-
| `MICA_RENDER_REVISION` | const | `
|
|
123
|
-
| `MICA_OPTION_LABELS` | const | `readonly string[]`
|
|
124
|
-
| `MICA_NOUL_LABELS` | const | `readonly string[]`
|
|
125
|
-
| `MICA_SPECIAL_TOKENS` | const | `readonly string[]`
|
|
106
|
+
| Name | Kind | Signature | Summary |
|
|
107
|
+
| ---------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
108
|
+
| `OllamaJudge` | class | `new (options: OllamaJudgeOptions) => AgentJudgeInterface` | Implements Mica's raw Ollama logprob wire over the shared judge engine. |
|
|
109
|
+
| `OllamaJudgeOptions` | interface | `{ model, system, calibration?, url?, keepAlive?, options? }` | Configures the raw Mica judge wire, its calibration, and its transport. |
|
|
110
|
+
| `WireGenerateRequest` | interface | `{ model, prompt, raw, stream, logprobs, top_logprobs, keep_alive, options }` | Transliterates the Ollama raw, non-streaming `POST /api/generate` request. |
|
|
111
|
+
| `Logprob` | interface | `{ token, logprob }` | Carries a token and its log probability from Ollama's top logprob list. |
|
|
112
|
+
| `createOllamaJudge` | function | `(options: OllamaJudgeOptions) => JudgeInterface` | Creates a Mica judge that reads calibrated candidate probabilities from raw Ollama logprobs. |
|
|
113
|
+
| `escapeSpecialTokens` | function | `(text: string) => string` | Escapes Mica control tokens by inserting U+200B after their opening angle bracket. |
|
|
114
|
+
| `renderJudgePrompt` | function | `(state: JudgeEntry, question: JudgeQuestion, system: string) => string` | Mirrors the TypeSafe adapter path of Mica's server, from the `rows_from_request` function in the `typesafe_server.py` file to the `prompt_for` function in the `native.py` file, with disabled thinking. Serializes structured state as JSON with a one-space indent and JavaScript numeric spelling; parity is byte-exact for string states and structured states whose numbers spell the same in both runtimes. |
|
|
115
|
+
| `buildJudgeLabels` | function | `(question: JudgeQuestion) => ReadonlyMap<string, string>` | Pairs caller candidate keys with Mica's output labels in criteria order. |
|
|
116
|
+
| `extractTopLogprobs` | function | `(value: unknown) => readonly Logprob[]` | Extracts the first generated position's top logprobs without changing token text. |
|
|
117
|
+
| `computeAnswer` | function | `(question: JudgeQuestion, top: readonly Logprob[], temperature?: number) => JudgeAnswer \| Refusal` | Computes a calibrated distribution over candidate labels or refuses missing candidates. |
|
|
118
|
+
| `renderJudgeIdentity` | function | `(options: OllamaJudgeOptions, revision?: string) => string` | Renders a stable identity from the model tag, system prompt, calibration, sorted effective options, and render revision. |
|
|
119
|
+
| `OLLAMA_GENERATE_PATH` | const | `"/api/generate"` | Names the Ollama raw generation endpoint. |
|
|
120
|
+
| `TOP_LOGPROBS` | const | `20` | Bounds the top logprob list to Ollama's limit of 20 tokens. |
|
|
121
|
+
| `MAX_MICA_LEVELS` | const | `10` | Bounds a Mica score question to 10 levels. |
|
|
122
|
+
| `MICA_RENDER_REVISION` | const | `"mica-native-2026-10-07-v1"` | Identifies the Mica prompt render revision used in judge identities. |
|
|
123
|
+
| `MICA_OPTION_LABELS` | const | `readonly string[]` | Lists Mica's letter labels in codebook order. |
|
|
124
|
+
| `MICA_NOUL_LABELS` | const | `readonly string[]` | Lists Mica's false and true labels in readout order. |
|
|
125
|
+
| `MICA_SPECIAL_TOKENS` | const | `readonly string[]` | Lists the control tokens escaped by Mica's native renderer. |
|
|
126
126
|
|
|
127
127
|
The server face, `@orkestrel/ollama/server`, exports the following daemon session declarations. It runs in Node only; [Daemon session](#daemon-session) states the lifecycle these declarations carry.
|
|
128
128
|
|
|
129
|
-
|
|
|
130
|
-
| ------------------------- | --------- |
|
|
131
|
-
| `createOllamaDaemon` | function | `(options: OllamaDaemonOptions) => OllamaDaemonInterface`
|
|
132
|
-
| `OllamaDaemon` | class | `OllamaDaemonInterface`
|
|
133
|
-
| `OllamaDaemonInterface` | interface | `{ url, identity, maintenance, emitter
|
|
134
|
-
| `OllamaDaemonOptions` | interface | `
|
|
135
|
-
| `OllamaExecutable` | interface | `{ path, digest, version, arguments? }`
|
|
136
|
-
| `OllamaModel` | interface | `{ name, digest }`
|
|
137
|
-
| `OllamaMetadataOptions` | interface | `{ timeout?, bytes? }`
|
|
138
|
-
| `OllamaDaemonIdentity` | interface | `{ executable, url, pid, models }`
|
|
139
|
-
| `OllamaBytes` | interface | `{ content, size, digest, complete }`
|
|
140
|
-
| `OllamaMaintenance` | interface | `{ sequence, model, url, request, response?, status?, timing?, error? }`
|
|
141
|
-
| `OllamaDaemonEventMap` | type | `{ start: [identity: OllamaDaemonIdentity]
|
|
142
|
-
| `OLLAMA_READINESS` | const | `
|
|
143
|
-
| `OLLAMA_METADATA_TIMEOUT` | const | `
|
|
144
|
-
| `OLLAMA_METADATA_BYTES` | const | `
|
|
129
|
+
| Name | Kind | Signature | Summary |
|
|
130
|
+
| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
131
|
+
| `createOllamaDaemon` | function | `(options: OllamaDaemonOptions) => OllamaDaemonInterface` | Creates an unstarted daemon with a snapshot of the caller's declaration and lifecycle hooks. |
|
|
132
|
+
| `OllamaDaemon` | class | `new (options: OllamaDaemonOptions) => OllamaDaemonInterface` | Owns a dedicated daemon through verified startup, declared maintenance, and permanent cleanup. |
|
|
133
|
+
| `OllamaDaemonInterface` | interface | `{ url, identity, maintenance, emitter, start(), unload(), stop(), destroy() }` | Owns a dedicated daemon from validated startup through declared-model maintenance and stop. |
|
|
134
|
+
| `OllamaDaemonOptions` | interface | `{ on?, error?, executable, url, models, workspace, environment?, store?, readiness?, metadata?, termination?, signal? }` | Configures a dedicated daemon with explicit executable, endpoint, and model declarations. |
|
|
135
|
+
| `OllamaExecutable` | interface | `{ path, digest, version, arguments? }` | Declares the executable identity required before a daemon starts. |
|
|
136
|
+
| `OllamaModel` | interface | `{ name, digest }` | Declares a model name and the digest its inventory entry must report. |
|
|
137
|
+
| `OllamaMetadataOptions` | interface | `{ timeout?, bytes? }` | Bounds each metadata or unload response independently of the startup deadline. |
|
|
138
|
+
| `OllamaDaemonIdentity` | interface | `{ executable, url, pid, models }` | Records the executable, endpoint, root process, and model identities verified at startup. |
|
|
139
|
+
| `OllamaBytes` | interface | `{ content, size, digest, complete }` | Preserves a bounded HTTP body as base64 with its byte count and SHA-256 digest. |
|
|
140
|
+
| `OllamaMaintenance` | interface | `{ sequence, model, url, request, response?, status?, timing?, error? }` | Records one declared model's unload request and the response observed for that attempt. |
|
|
141
|
+
| `OllamaDaemonEventMap` | type | `{ readonly start: readonly [identity: OllamaDaemonIdentity]; readonly unload: readonly [maintenance: OllamaMaintenance]; readonly stop: readonly [confirmed: boolean]; readonly error: readonly [error: unknown]; }` | Reports verified startup, recorded unloads, permanent stop, and daemon failures. |
|
|
142
|
+
| `OLLAMA_READINESS` | const | `60000` | Bounds startup through version and model verification to 60000 milliseconds by default. |
|
|
143
|
+
| `OLLAMA_METADATA_TIMEOUT` | const | `10000` | Bounds each metadata or unload request and body read to 10000 milliseconds by default. |
|
|
144
|
+
| `OLLAMA_METADATA_BYTES` | const | `1048576` | Bounds each retained metadata or unload response to 1048576 bytes by default. |
|
|
145
145
|
|
|
146
146
|
The server face reports every refusal as one branded error class.
|
|
147
147
|
|
|
148
|
-
|
|
|
149
|
-
| -------------------- | --------- |
|
|
150
|
-
| `OllamaError` | class | `(message: string, options: OllamaErrorOptions)`
|
|
151
|
-
| `OllamaErrorOptions` | interface | `{ code, context?, cause? }`
|
|
152
|
-
| `OllamaErrorContext` | interface | `{ operation?, path?, url?, model?, expected?, received?, evidence? }`
|
|
153
|
-
| `OllamaErrorCode` | type | `(typeof OLLAMA_ERROR_CODES)[number]`
|
|
154
|
-
| `OLLAMA_ERROR_CODES` | const | `readonly
|
|
155
|
-
| `OLLAMA_ERROR_BRAND` | const | `unique symbol`
|
|
156
|
-
| `isOllamaError` | function | `OllamaError`
|
|
148
|
+
| Name | Kind | Signature | Summary |
|
|
149
|
+
| -------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
|
|
150
|
+
| `OllamaError` | class | `new (message: string, options: OllamaErrorOptions) => OllamaError` | Carries a daemon refusal with a machine-readable category, observations, and original cause. |
|
|
151
|
+
| `OllamaErrorOptions` | interface | `{ code, context?, cause? }` | Configures a daemon refusal with its category, observations, and original cause. |
|
|
152
|
+
| `OllamaErrorContext` | interface | `{ operation?, path?, url?, model?, expected?, received?, evidence? }` | Carries the operation and identity observations accompanying a daemon refusal. |
|
|
153
|
+
| `OllamaErrorCode` | type | `(typeof OLLAMA_ERROR_CODES)[number]` | Defines the machine-readable refusal categories of the daemon lifecycle. |
|
|
154
|
+
| `OLLAMA_ERROR_CODES` | const | `readonly ["invalid", "occupied", "digest", "spawn", "readiness", "version", "model", "owner", "metadata", "unload", "cleanup", "aborted", "state"]` | Lists every machine-readable daemon refusal category. |
|
|
155
|
+
| `OLLAMA_ERROR_BRAND` | const | `unique symbol` | Identifies daemon errors across installations and module formats through the global symbol registry. |
|
|
156
|
+
| `isOllamaError` | function | `(value: unknown) => value is OllamaError` | Checks whether an unknown value carries the daemon error brand and declared members. |
|
|
157
157
|
|
|
158
158
|
The session composes the following validators and protocol helpers, each exported so a caller can check a declaration or a retained body without starting a daemon.
|
|
159
159
|
|
|
160
|
-
|
|
|
160
|
+
| Name | Kind | Signature | Summary |
|
|
161
161
|
| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
162
|
-
| `isOllamaDaemonOptions` | function | `OllamaDaemonOptions`
|
|
163
|
-
| `isOllamaExecutable` | function | `OllamaExecutable`
|
|
164
|
-
| `isOllamaModel` | function | `OllamaModel`
|
|
165
|
-
| `isOllamaOrigin` | function | `string`
|
|
162
|
+
| `isOllamaDaemonOptions` | function | `(value: unknown) => value is OllamaDaemonOptions` | Checks whether an unknown declaration can safely reach daemon preflight. |
|
|
163
|
+
| `isOllamaExecutable` | function | `(value: unknown) => value is OllamaExecutable` | Checks whether a value declares an absolute executable and its offline identity. |
|
|
164
|
+
| `isOllamaModel` | function | `(value: unknown) => value is OllamaModel` | Checks whether a value declares an exact model name and inventory digest. |
|
|
165
|
+
| `isOllamaOrigin` | function | `(value: unknown) => value is string` | Checks whether a string selects an explicit dedicated HTTP loopback origin. |
|
|
166
166
|
| `buildOllamaEnvironment` | function | `(inherited: Readonly<Record<string, string \| undefined>>, environment: Readonly<Record<string, string \| undefined>> \| undefined, url: string, store?: string) => Readonly<Record<string, string \| undefined>>` | Builds the environment with dedicated values overriding every inherited or caller casing. |
|
|
167
167
|
| `matchesOllamaAnnouncement` | function | `(line: string, url: string) => boolean` | Checks whether stderr announces the dedicated loopback listener. |
|
|
168
168
|
| `verifyOllamaVersion` | function | `(value: unknown, expected: string) => void` | Verifies a metadata reply against the declared executable version. |
|
package/dist/host/guides/pool.md
CHANGED
|
@@ -39,40 +39,40 @@ try {
|
|
|
39
39
|
|
|
40
40
|
### Factories
|
|
41
41
|
|
|
42
|
-
|
|
|
43
|
-
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
-
| `createPool` | function | Creates a distinct `PoolInterface` from resource lifecycle hooks, with optional bounded capacity, exclusive leases by default, and FIFO settlement. |
|
|
42
|
+
| Name | Kind | Signature | Summary |
|
|
43
|
+
| ------------ | -------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
44
|
+
| `createPool` | function | `<T>(options: PoolOptions<T>) => PoolInterface<T>` | Creates a distinct `PoolInterface` from resource lifecycle hooks, with optional bounded capacity, exclusive leases by default, and FIFO settlement. |
|
|
45
45
|
|
|
46
46
|
### Classes
|
|
47
47
|
|
|
48
|
-
|
|
|
49
|
-
| ----------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
50
|
-
| `Pool` | class | Represents a resource pool with optional bounded capacity and a warm floor, whose opaque ownership records preserve FIFO settlement, cancellation, exact lease release, and deterministic teardown under concurrent hooks. |
|
|
51
|
-
| `PoolError` | class | Represents a stable, machine-readable pool failure that retains the original thrown value as its cause without unsafe coercion, alongside structured context. |
|
|
48
|
+
| Name | Kind | Signature | Summary |
|
|
49
|
+
| ----------- | ----- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
50
|
+
| `Pool` | class | `new <T>(options: PoolOptions<T>) => PoolInterface<T>` | Represents a resource pool with optional bounded capacity and a warm floor, whose opaque ownership records preserve FIFO settlement, cancellation, exact lease release, and deterministic teardown under concurrent hooks. |
|
|
51
|
+
| `PoolError` | class | `new (options: PoolErrorOptions) => PoolError` | Represents a stable, machine-readable pool failure that retains the original thrown value as its cause without unsafe coercion, alongside structured context. |
|
|
52
52
|
|
|
53
53
|
### Guards
|
|
54
54
|
|
|
55
55
|
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
56
56
|
|
|
57
|
-
|
|
|
58
|
-
| -------------- | -------- |
|
|
59
|
-
| `isPoolError` | function | `PoolError` | Tests whether an unknown value is a branded `PoolError` with declared code and context. |
|
|
60
|
-
| `isPoolLimit` | function | `number` | Tests whether a value is a positive safe integer for a pool record or lease limit. |
|
|
61
|
-
| `isPoolSignal` | function | `AbortSignal` | Tests whether a value is a native `AbortSignal` for the acquire boundary, returning `false` for hostile proxies. |
|
|
57
|
+
| Name | Kind | Signature | Summary |
|
|
58
|
+
| -------------- | -------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
|
|
59
|
+
| `isPoolError` | function | `(value: unknown) => value is PoolError` | Tests whether an unknown value is a branded `PoolError` with declared code and context. |
|
|
60
|
+
| `isPoolLimit` | function | `(value: unknown) => value is number` | Tests whether a value is a positive safe integer for a pool record or lease limit. |
|
|
61
|
+
| `isPoolSignal` | function | `(value: unknown) => value is AbortSignal` | Tests whether a value is a native `AbortSignal` for the acquire boundary, returning `false` for hostile proxies. |
|
|
62
62
|
|
|
63
63
|
### Types
|
|
64
64
|
|
|
65
65
|
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 `\|`.
|
|
66
66
|
|
|
67
|
-
|
|
|
68
|
-
| ------------------ | --------- |
|
|
69
|
-
| `PoolCode` | type | `'invalid' \| 'destroyed' \| 'create' \| 'cleanup'`
|
|
70
|
-
| `PoolContext` | interface | `{ value?, failures? }`
|
|
71
|
-
| `PoolErrorOptions` | interface | `{ code, cause?, context? }`
|
|
72
|
-
| `PoolEventMap` | type | `{ create
|
|
73
|
-
| `PoolToken` | interface | `{ value
|
|
74
|
-
| `PoolOptions` | interface | `{ on?, error?, create, destroy?, validate?, watch?, capacity?, max?, min?, restarts? }`
|
|
75
|
-
| `PoolInterface` | interface | `{ emitter, size, idle, active
|
|
67
|
+
| Name | Kind | Signature | Summary |
|
|
68
|
+
| ------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
69
|
+
| `PoolCode` | type | `'invalid' \| 'destroyed' \| 'create' \| 'cleanup'` | Names the machine-readable failure codes produced by `PoolError`. |
|
|
70
|
+
| `PoolContext` | interface | `{ value?, failures? }` | Represents the structured context attached to a `PoolError`: the rejected input, or the distinct destroy-hook failures an aggregate cleanup collected. |
|
|
71
|
+
| `PoolErrorOptions` | interface | `{ code, cause?, context? }` | Represents the construction options for `PoolError`: the stable code, an optional cause, and optional structured context. |
|
|
72
|
+
| `PoolEventMap` | type | `{ readonly create: readonly []; readonly acquire: readonly []; readonly release: readonly []; readonly destroy: readonly []; }` | Represents the observable resource lifecycle events emitted by a `PoolInterface`. |
|
|
73
|
+
| `PoolToken` | interface | `{ value, release(), destroy() }` | Represents a unique lease over one pool-owned resource record, exposing that record as a readonly `value` and ending it through an idempotent `release` or `destroy`. |
|
|
74
|
+
| `PoolOptions` | interface | `{ on?, error?, create, destroy?, validate?, watch?, capacity?, max?, min?, restarts? }` | Represents the resource lifecycle options for `Pool` and `createPool`: creation, destruction, validation, capacity, a bounded warm floor, and loss observation. |
|
|
75
|
+
| `PoolInterface` | interface | `{ emitter, size, idle, active, start(), acquire(), clear(), destroy() }` | Represents a FIFO resource pool with optional bounded capacity, a warm floor, loss recovery, and deterministic teardown, exposing its record counts and a typed lifecycle emitter. |
|
|
76
76
|
|
|
77
77
|
`size` counts every owned record, including records being validated, destroyed, or retained
|
|
78
78
|
after failed cleanup under `min`. `idle` counts available records with no live lease or pending
|