@orkestrel/scaffold 0.0.115 → 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/skills/orkestrel-publish/references/wave.md +1 -1
- package/dist/host/claude/agents/orkestrel.md +1 -1
- 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 +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 +55 -55
- 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
|
@@ -37,45 +37,45 @@ acme?.contacts // the relation property — broad (Row | readonly Row[] | undefi
|
|
|
37
37
|
|
|
38
38
|
### Factory & manager
|
|
39
39
|
|
|
40
|
-
|
|
|
41
|
-
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
|
|
42
|
-
| `createRelationManager` | function | Creates a `RelationManagerInterface` over a database and its relation map. |
|
|
43
|
-
| `RelationManager` | class | Resolves a `RelationsShape` once at construction and vends a typed `ModelInterface` per declared table. |
|
|
44
|
-
| `Model` | class | Pairs a typed table with relation-aware `load` / `find` and junction management. |
|
|
40
|
+
| Name | Kind | Signature | Summary |
|
|
41
|
+
| ----------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
42
|
+
| `createRelationManager` | function | `<T extends TableMap>(options: RelationManagerOptions<T>) => RelationManagerInterface<T>` | Creates a `RelationManagerInterface` over a database and its relation map. |
|
|
43
|
+
| `RelationManager` | class | `new <T extends TableMap = TableMap>(options: RelationManagerOptions<T>) => RelationManagerInterface<T>` | Resolves a `RelationsShape` once at construction and vends a typed `ModelInterface` per declared table. |
|
|
44
|
+
| `Model` | class | `new <T = Row>(name: string, table: TableInterface<T>, resolved: ReadonlyMap<string, ResolvedRelation>, relations: RelationMap, lookup: (model: string) => RelationContext \| undefined, database: DatabaseInterface, on?: EmitterHooks<ModelEventMap>, error?: EmitterErrorHandler) => ModelInterface<T>` | Pairs a typed table with relation-aware `load` / `find` and junction management. |
|
|
45
45
|
|
|
46
46
|
### Builders
|
|
47
47
|
|
|
48
|
-
|
|
|
49
|
-
| ------------ | -------- | --------------------------------------------------------------------------------------------------------------- |
|
|
50
|
-
| `belongsTo` | function | Builds a `belongs` relation — a foreign key on the owning table points at the related row (single). |
|
|
51
|
-
| `hasMany` | function | Builds a `many` relation — a foreign key on the related table points back at the owning row (array). |
|
|
52
|
-
| `hasOne` | function | Builds a `one` relation — like `hasMany`, but a single related row. |
|
|
53
|
-
| `hasThrough` | function | Builds a `through` relation — a junction table links the two sides (many-to-many). |
|
|
54
|
-
| `hasMorph` | function | Builds a `morph` relation — a polymorphic foreign key plus a discriminator column on the related table (array). |
|
|
48
|
+
| Name | Kind | Signature | Summary |
|
|
49
|
+
| ------------ | -------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
50
|
+
| `belongsTo` | function | `(column: string, model?: string) => RelationDescriptor` | Builds a `belongs` relation — a foreign key on the owning table points at the related row (single). |
|
|
51
|
+
| `hasMany` | function | `(key: string, model?: string) => RelationDescriptor` | Builds a `many` relation — a foreign key on the related table points back at the owning row (array). |
|
|
52
|
+
| `hasOne` | function | `(key: string, model?: string) => RelationDescriptor` | Builds a `one` relation — like `hasMany`, but a single related row. |
|
|
53
|
+
| `hasThrough` | function | `(through: string, source: string, target: string, model?: string) => RelationDescriptor` | Builds a `through` relation — a junction table links the two sides (many-to-many). |
|
|
54
|
+
| `hasMorph` | function | `(key: string, tag: string, label: string, model?: string) => RelationDescriptor` | Builds a `morph` relation — a polymorphic foreign key plus a discriminator column on the related table (array). |
|
|
55
55
|
|
|
56
56
|
### Resolution
|
|
57
57
|
|
|
58
|
-
|
|
|
59
|
-
| ---------------------- | -------- | ----------------------------------------------------------------------------- |
|
|
60
|
-
| `resolveRelation` | function | Resolves one raw `Relation` value into a flat `ResolvedRelation`. |
|
|
61
|
-
| `resolveRelationMap` | function | Resolves every entry of a `RelationMap` into a name → `ResolvedRelation` map. |
|
|
62
|
-
| `isRelationDescriptor` | function | Narrows a value to a `RelationDescriptor` (the object form of a relation). |
|
|
58
|
+
| Name | Kind | Signature | Summary |
|
|
59
|
+
| ---------------------- | -------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
|
|
60
|
+
| `resolveRelation` | function | `(name: string, value: Relation) => ResolvedRelation` | Resolves one raw `Relation` value into a flat `ResolvedRelation`. |
|
|
61
|
+
| `resolveRelationMap` | function | `(relations: RelationMap) => ReadonlyMap<string, ResolvedRelation>` | Resolves every entry of a `RelationMap` into a name → `ResolvedRelation` map. |
|
|
62
|
+
| `isRelationDescriptor` | function | `(value: unknown) => value is RelationDescriptor` | Narrows a value to a `RelationDescriptor` (the object form of a relation). |
|
|
63
63
|
|
|
64
64
|
### Row helpers
|
|
65
65
|
|
|
66
|
-
|
|
|
67
|
-
| --------------- | -------- | ---------------------------------------------------------------------- |
|
|
68
|
-
| `readColumn` | function | Reads one column off any record, whatever its declared type. |
|
|
69
|
-
| `countAttached` | function | Counts the related rows one relation attached across a record set. |
|
|
70
|
-
| `indexRows` | function | Indexes rows by the string form of one column, for keyed lookups. |
|
|
71
|
-
| `groupRows` | function | Groups rows by the string form of one column, for one-to-many lookups. |
|
|
66
|
+
| Name | Kind | Signature | Summary |
|
|
67
|
+
| --------------- | -------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
|
68
|
+
| `readColumn` | function | `(record: unknown, column: string) => unknown` | Reads one column off any record, whatever its declared type. |
|
|
69
|
+
| `countAttached` | function | `(values: ReadonlyArray<Row \| readonly Row[] \| undefined>) => number` | Counts the related rows one relation attached across a record set. |
|
|
70
|
+
| `indexRows` | function | `(rows: readonly Row[], column: string) => ReadonlyMap<string, Row>` | Indexes rows by the string form of one column, for keyed lookups. |
|
|
71
|
+
| `groupRows` | function | `(rows: readonly Row[], column: string) => ReadonlyMap<string, readonly Row[]>` | Groups rows by the string form of one column, for one-to-many lookups. |
|
|
72
72
|
|
|
73
73
|
### Errors
|
|
74
74
|
|
|
75
|
-
|
|
|
76
|
-
| ----------------- | -------- | --------------------------------------------------------------------------------------------------- |
|
|
77
|
-
| `RelationError` | class | Represents an error thrown by the relations layer, carrying a machine-readable `RelationErrorCode`. |
|
|
78
|
-
| `isRelationError` | function | Narrows an unknown caught value to a `RelationError`. |
|
|
75
|
+
| Name | Kind | Signature | Summary |
|
|
76
|
+
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| `RelationError` | class | `new (code: RelationErrorCode, message: string, context?: Readonly<Record<string, unknown>>) => RelationError` | Represents an error thrown by the relations layer, carrying a machine-readable `RelationErrorCode`. |
|
|
78
|
+
| `isRelationError` | function | `(value: unknown) => value is RelationError` | Narrows an unknown caught value to a `RelationError`. |
|
|
79
79
|
|
|
80
80
|
### Types
|
|
81
81
|
|
|
@@ -85,29 +85,29 @@ transparent proxies, unbranded look-alikes, and plain branded objects.
|
|
|
85
85
|
|
|
86
86
|
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.
|
|
87
87
|
|
|
88
|
-
|
|
|
89
|
-
| -------------------------- | --------- |
|
|
90
|
-
| `Relationship` | type | `'belongs' \| 'many' \| 'one' \| 'through' \| 'morph'`
|
|
91
|
-
| `RelationDescriptor` | interface | `{ relationship?, column?, key?, through?, source?, target?, tag?, label?, model? }`
|
|
92
|
-
| `Relation` | type | `string \| readonly string[] \| RelationDescriptor`
|
|
93
|
-
| `RelationMap` | type | `Readonly<Record<string, Relation>>`
|
|
94
|
-
| `RelationsShape` | type | `{ readonly [K in keyof T]?: RelationMap }`
|
|
95
|
-
| `ResolvedRelation` | type | `ResolvedBelongs \| ResolvedMany \| ResolvedOne \| ResolvedThrough \| ResolvedMorph`
|
|
96
|
-
| `ResolvedBelongs` | interface | `{ relationship, name, model, column }`
|
|
97
|
-
| `ResolvedMany` | interface | `{ relationship, name, model, key }`
|
|
98
|
-
| `ResolvedOne` | interface | `{ relationship, name, model, key }`
|
|
99
|
-
| `ResolvedThrough` | interface | `{ relationship, name, model, through, source, target }`
|
|
100
|
-
| `ResolvedMorph` | interface | `{ relationship, name, model, key, tag, label }`
|
|
101
|
-
| `RelationErrorCode` | type | `'INVALID' \| 'UNKNOWN_RELATION' \| 'NOT_THROUGH'`
|
|
102
|
-
| `Include` | interface | `{ [relation] }`
|
|
103
|
-
| `Loaded` | type | `T & Readonly<LoadedMap>`
|
|
104
|
-
| `LoadedMap` | type | `Record<string, Row \| readonly Row[] \| undefined>`
|
|
105
|
-
| `RelationContext` | interface | `{ resolved, primary }`
|
|
106
|
-
| `FindOptions` | interface | `
|
|
107
|
-
| `ModelEventMap` | type | `{ load, link, unlink }`
|
|
108
|
-
| `ModelInterface` | interface | `{ emitter, name, table, relations
|
|
109
|
-
| `RelationManagerOptions` | interface | `{ database, relations?, model? }`
|
|
110
|
-
| `RelationManagerInterface` | interface | `{ count
|
|
88
|
+
| Name | Kind | Signature | Summary |
|
|
89
|
+
| -------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
90
|
+
| `Relationship` | type | `'belongs' \| 'many' \| 'one' \| 'through' \| 'morph'` | Enumerates the relationships a relation can declare. |
|
|
91
|
+
| `RelationDescriptor` | interface | `{ relationship?, column?, key?, through?, source?, target?, tag?, label?, model? }` | Represents the object form of a relation. |
|
|
92
|
+
| `Relation` | type | `string \| readonly string[] \| RelationDescriptor` | Represents a single relation definition. |
|
|
93
|
+
| `RelationMap` | type | `Readonly<Record<string, Relation>>` | Holds a model's relations, keyed by relation name. |
|
|
94
|
+
| `RelationsShape` | type | `{ readonly [K in keyof T]?: RelationMap; }` | Holds per-table relation maps — the declarative input to `createRelationManager`. |
|
|
95
|
+
| `ResolvedRelation` | type | `ResolvedBelongs \| ResolvedMany \| ResolvedOne \| ResolvedThrough \| ResolvedMorph` | Represents a relation resolved at define-time into a flat, ready-to-load form. |
|
|
96
|
+
| `ResolvedBelongs` | interface | `{ relationship, name, model, column }` | Represents a `belongs` relation resolved at define-time — the foreign key sits on the owning table. |
|
|
97
|
+
| `ResolvedMany` | interface | `{ relationship, name, model, key }` | Represents a `many` relation resolved at define-time — the foreign key sits on the related table. |
|
|
98
|
+
| `ResolvedOne` | interface | `{ relationship, name, model, key }` | Represents a `one` relation resolved at define-time — `ResolvedMany`'s foreign key, one row. |
|
|
99
|
+
| `ResolvedThrough` | interface | `{ relationship, name, model, through, source, target }` | Represents a `through` relation resolved at define-time — a junction table links the two sides. |
|
|
100
|
+
| `ResolvedMorph` | interface | `{ relationship, name, model, key, tag, label }` | Represents a `morph` relation resolved at define-time — a polymorphic foreign key and its discriminator. |
|
|
101
|
+
| `RelationErrorCode` | type | `'INVALID' \| 'UNKNOWN_RELATION' \| 'NOT_THROUGH'` | Names a machine-readable `RelationError` code. |
|
|
102
|
+
| `Include` | interface | `{ readonly [relation: string]: boolean \| Include }` | Selects which relations to populate when loading — and, recursively, their own. |
|
|
103
|
+
| `Loaded` | type | `T & Readonly<LoadedMap>` | Represents a row with its loaded relation properties attached. |
|
|
104
|
+
| `LoadedMap` | type | `Record<string, Row \| readonly Row[] \| undefined>` | Holds the relation properties attached to a `Loaded` row — each relation name mapped to its loaded related row(s), or `undefined` when a `belongs` / `one` relation misses. |
|
|
105
|
+
| `RelationContext` | interface | `{ resolved, primary }` | Holds a related model's resolved relations and primary-key column, for nested loading. |
|
|
106
|
+
| `FindOptions` | interface | `{ limit?, offset?, sort?, direction? }` | Configures pagination, ordering, and cancellation for `find`. |
|
|
107
|
+
| `ModelEventMap` | type | `{ readonly load: readonly [name: string, count: number]; readonly link: readonly [key: Key, relation: string]; readonly unlink: readonly [key: Key, relation: string]; }` | Declares the push observation surface of a `ModelInterface` — the eager-load + junction-management moments a fire-and-forget observer (logging, metrics, a sync layer) subscribes to. |
|
|
108
|
+
| `ModelInterface` | interface | `{ emitter, name, table, relations, load(), find(), link(), unlink(), links() }` | Represents a typed table paired with relation-aware loading and junction management. |
|
|
109
|
+
| `RelationManagerOptions` | interface | `{ database, relations?, model? }` | Configures `createRelationManager`. |
|
|
110
|
+
| `RelationManagerInterface` | interface | `{ count, model(), names(), has() }` | Vends a typed `ModelInterface` per table. |
|
|
111
111
|
|
|
112
112
|
## Methods
|
|
113
113
|
|
|
@@ -50,110 +50,110 @@ Browser and server usage appear under [Patterns](#patterns).
|
|
|
50
50
|
|
|
51
51
|
### Factories
|
|
52
52
|
|
|
53
|
-
|
|
|
54
|
-
| ------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
-
| `createRouter` | function | Creates a `RouterInterface` — the pure path-matching + registry engine shared by the browser `Navigator` and the core `Dispatcher`. |
|
|
56
|
-
| `createDispatcher` | function | Creates a `DispatcherInterface` — the fetch-standard, method-dimensioned dispatch entity over one internal `Router<RouteRecord<TState>>`. |
|
|
57
|
-
| `createNavigator` | function | Creates a `NavigatorInterface` — the headless History/hash navigation entity composing one core `Router<Meta>`. |
|
|
53
|
+
| Name | Kind | Signature | Summary |
|
|
54
|
+
| ------------------ | -------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| `createRouter` | function | `<Meta>(options?: RouterOptions<Meta>) => RouterInterface<Meta>` | Creates a `RouterInterface` — the pure path-matching + registry engine shared by the browser `Navigator` and the core `Dispatcher`. |
|
|
56
|
+
| `createDispatcher` | function | `<TState = undefined>(options?: DispatcherOptions<TState>) => DispatcherInterface<TState>` | Creates a `DispatcherInterface` — the fetch-standard, method-dimensioned dispatch entity over one internal `Router<RouteRecord<TState>>`. |
|
|
57
|
+
| `createNavigator` | function | `<Meta>(options: NavigatorOptions<Meta>) => NavigatorInterface<Meta>` | Creates a `NavigatorInterface` — the headless History/hash navigation entity composing one core `Router<Meta>`. |
|
|
58
58
|
|
|
59
59
|
### Constants
|
|
60
60
|
|
|
61
61
|
A `Shape` cell holds the constant's declared type.
|
|
62
62
|
|
|
63
|
-
|
|
|
63
|
+
| Name | Kind | Signature | Summary |
|
|
64
64
|
| --------------- | ----- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
65
|
-
| `METHOD_LIST` | const | `readonly [
|
|
65
|
+
| `METHOD_LIST` | const | `readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]` | Lists the HTTP methods a `DispatcherInterface` registers routes under, in canonical order — a frozen literal tuple, and the single source the `Method` type, `METHODS`, and `parseMethod` are all derived from. |
|
|
66
66
|
| `METHODS` | const | `ReadonlySet<string>` | Holds every HTTP method a `DispatcherInterface` registers routes under as a `ReadonlySet` — backs the registration guard (`add` rejects any `method` outside this set) and the auto-`OPTIONS` `Allow` derivation. |
|
|
67
|
-
| `TIER_LITERAL` | const | `
|
|
68
|
-
| `TIER_PARAM` | const | `
|
|
69
|
-
| `TIER_WILDCARD` | const | `
|
|
67
|
+
| `TIER_LITERAL` | const | `2` | Names the specificity tier for a \*\*literal\*\* path segment (`/users`) — the highest tier, always outranking a param or wildcard segment at the same position. |
|
|
68
|
+
| `TIER_PARAM` | const | `1` | Names the specificity tier for a \*\*param\*\* path segment (`:name`) — ranks below a literal segment and above a wildcard segment at the same position. |
|
|
69
|
+
| `TIER_WILDCARD` | const | `0` | Names the specificity tier for a \*\*wildcard\*\* path segment (`*name`) — the lowest tier; a wildcard only ever wins against another wildcard shape (an equal-specificity tie resolved by registration order). |
|
|
70
70
|
|
|
71
71
|
### Helpers
|
|
72
72
|
|
|
73
|
-
|
|
|
74
|
-
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
75
|
-
| `escapeRegExp` | function | Escapes every regex metacharacter in a literal string so it can be embedded inside a larger `RegExp` source without being interpreted as syntax. |
|
|
76
|
-
| `canonicalizePath` | function | Canonicalizes a route path for registry identity — strips a single trailing slash, except the root `/` (and the empty pattern). The trailing-slash fold `compilePath` normalizes a pattern through, so identity agrees with the matcher. |
|
|
77
|
-
| `computeDispatchKey` | function | Computes the canonical `METHOD /path` registry key for a method-dimensioned dispatcher route. |
|
|
78
|
-
| `compilePath` | function | Compiles a route path pattern into an anchored regex and its ordered param names. |
|
|
79
|
-
| `decodeParam` | function | Decodes one captured param value from a URL, tolerating a malformed percent-escape — the decode `matchPath` applies to each captured group. |
|
|
80
|
-
| `matchPath` | function | Extracts the URL-decoded params a compiled path captures from a concrete pathname, or `undefined` when the pathname does not match. |
|
|
81
|
-
| `classifySegment` | function | Classifies one path segment into its specificity tier — the same syntax `compilePath` rewrites: a syntactically valid `:name` head is a param segment, a final `*name` is a wildcard segment, and everything else (including a literal segment that merely contains a `:` mid-string, for example `a:b`) is a literal segment. |
|
|
82
|
-
| `computeSpecificity` | function | Computes a route path's specificity vector — the per-segment type ranking that breaks a tie when several registered routes match the same concrete pathname. |
|
|
83
|
-
| `compareSpecificity` | function | Compares two route paths by specificity — the comparator that picks the most-specific matching route (literal-over-param-over-wildcard, registration-order-independent). |
|
|
84
|
-
| `joinPaths` | function | Joins a group prefix and a route path into one `/`-prefixed path, normalizing duplicate or missing joining slashes. |
|
|
85
|
-
| `defineRoute` | function | Provides an identity pass-through for a `RouteInput` that pins its `Path` generic to the literal registration-site string, so `context.params` types correctly through `PathParams` without an explicit type argument. |
|
|
86
|
-
| `computeNavigationKey` | function | Computes the canonical path key a `Navigator` registers a browser navigation route under. |
|
|
87
|
-
| `extractHashPath` | function | Extracts the `/`-prefixed pathname from a `location.hash` value — strips the leading `#` (keeping the route's own leading `/`) and any `?query` suffix. |
|
|
88
|
-
| `resolveLocationPath` | function | Resolves the `/`-prefixed pathname to match for the current location, in either navigation mode — the one seam `extractHashPath` (hash mode) and history-mode base-stripping share. |
|
|
89
|
-
| `findAnchor` | function | Finds the nearest enclosing `<a>` element a DOM event originated from, by walking its composed path — the pure lookup behind history-mode link interception. |
|
|
90
|
-
| `buildRequest` | function | Builds a fetch-standard `Request` from a `node:http` `IncomingMessage` — the server-adapter half of the fetch/node conversion seam. |
|
|
91
|
-
| `sendResponse` | function | Writes a fetch-standard `Response` back to a `node:http` `ServerResponse` — the reverse half of the fetch/node conversion seam. |
|
|
73
|
+
| Name | Kind | Signature | Summary |
|
|
74
|
+
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
75
|
+
| `escapeRegExp` | function | `(value: string) => string` | Escapes every regex metacharacter in a literal string so it can be embedded inside a larger `RegExp` source without being interpreted as syntax. |
|
|
76
|
+
| `canonicalizePath` | function | `(path: string) => string` | Canonicalizes a route path for registry identity — strips a single trailing slash, except the root `/` (and the empty pattern). The trailing-slash fold `compilePath` normalizes a pattern through, so identity agrees with the matcher. |
|
|
77
|
+
| `computeDispatchKey` | function | `(entry: RouteEntry<{ readonly method: Method; }>) => string` | Computes the canonical `METHOD /path` registry key for a method-dimensioned dispatcher route. |
|
|
78
|
+
| `compilePath` | function | `(path: string, sensitive?: boolean) => CompiledPath` | Compiles a route path pattern into an anchored regex and its ordered param names. |
|
|
79
|
+
| `decodeParam` | function | `(value: string) => string` | Decodes one captured param value from a URL, tolerating a malformed percent-escape — the decode `matchPath` applies to each captured group. |
|
|
80
|
+
| `matchPath` | function | `(compiled: CompiledPath, pathname: string) => Readonly<Record<string, string>> \| undefined` | Extracts the URL-decoded params a compiled path captures from a concrete pathname, or `undefined` when the pathname does not match. |
|
|
81
|
+
| `classifySegment` | function | `(segment: string, isFinal: boolean) => number` | Classifies one path segment into its specificity tier — the same syntax `compilePath` rewrites: a syntactically valid `:name` head is a param segment, a final `*name` is a wildcard segment, and everything else (including a literal segment that merely contains a `:` mid-string, for example `a:b`) is a literal segment. |
|
|
82
|
+
| `computeSpecificity` | function | `(path: string) => readonly number[]` | Computes a route path's specificity vector — the per-segment type ranking that breaks a tie when several registered routes match the same concrete pathname. |
|
|
83
|
+
| `compareSpecificity` | function | `(a: string, b: string) => number` | Compares two route paths by specificity — the comparator that picks the most-specific matching route (literal-over-param-over-wildcard, registration-order-independent). |
|
|
84
|
+
| `joinPaths` | function | `(prefix: string, path: string) => string` | Joins a group prefix and a route path into one `/`-prefixed path, normalizing duplicate or missing joining slashes. |
|
|
85
|
+
| `defineRoute` | function | `<const Path extends string, TState = undefined>(input: RouteInput<Path, TState>) => RouteInput<Path, TState>` | Provides an identity pass-through for a `RouteInput` that pins its `Path` generic to the literal registration-site string, so `context.params` types correctly through `PathParams` without an explicit type argument. |
|
|
86
|
+
| `computeNavigationKey` | function | `(entry: RouteEntry<unknown>) => string` | Computes the canonical path key a `Navigator` registers a browser navigation route under. |
|
|
87
|
+
| `extractHashPath` | function | `(hash: string) => string` | Extracts the `/`-prefixed pathname from a `location.hash` value — strips the leading `#` (keeping the route's own leading `/`) and any `?query` suffix. |
|
|
88
|
+
| `resolveLocationPath` | function | `(location: Pick<Location, 'hash' \| 'pathname'>, history: boolean, base?: string) => string` | Resolves the `/`-prefixed pathname to match for the current location, in either navigation mode — the one seam `extractHashPath` (hash mode) and history-mode base-stripping share. |
|
|
89
|
+
| `findAnchor` | function | `(event: Event) => HTMLAnchorElement \| undefined` | Finds the nearest enclosing `<a>` element a DOM event originated from, by walking its composed path — the pure lookup behind history-mode link interception. |
|
|
90
|
+
| `buildRequest` | function | `(message: IncomingMessage, options?: RequestOptions) => Request` | Builds a fetch-standard `Request` from a `node:http` `IncomingMessage` — the server-adapter half of the fetch/node conversion seam. |
|
|
91
|
+
| `sendResponse` | function | `(response: Response, target: ServerResponse) => Promise<void>` | Writes a fetch-standard `Response` back to a `node:http` `ServerResponse` — the reverse half of the fetch/node conversion seam. |
|
|
92
92
|
|
|
93
93
|
### Parsers
|
|
94
94
|
|
|
95
|
-
|
|
|
96
|
-
| ------------- | -------- | ---------------------------------------------------------------------------------- |
|
|
97
|
-
| `parseMethod` | function | Narrows a raw `request.method` string into a typed `Method` — total, never throws. |
|
|
95
|
+
| Name | Kind | Signature | Summary |
|
|
96
|
+
| ------------- | -------- | ---------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
97
|
+
| `parseMethod` | function | `(value: string) => Method \| undefined` | Narrows a raw `request.method` string into a typed `Method` — total, never throws. |
|
|
98
98
|
|
|
99
99
|
### Guards
|
|
100
100
|
|
|
101
101
|
In a guard table a `Shape` cell holds the type the guard narrows to.
|
|
102
102
|
|
|
103
|
-
|
|
|
104
|
-
| ------------------- | -------- |
|
|
105
|
-
| `isEncryptedSocket` | function | `{ encrypted }` | Determines whether a `node:http` connection socket is TLS-encrypted — the total, never-throwing narrow `buildRequest` uses to pick the derived scheme (`https` vs `http`). |
|
|
103
|
+
| Name | Kind | Signature | Summary |
|
|
104
|
+
| ------------------- | -------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
105
|
+
| `isEncryptedSocket` | function | `(socket: unknown) => socket is { readonly encrypted: true; }` | Determines whether a `node:http` connection socket is TLS-encrypted — the total, never-throwing narrow `buildRequest` uses to pick the derived scheme (`https` vs `http`). |
|
|
106
106
|
|
|
107
107
|
### Handlers
|
|
108
108
|
|
|
109
|
-
|
|
|
110
|
-
| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
111
|
-
| `handleListenerRequest` | function | Handles one `node:http` request through a core dispatcher and writes its fetch-standard response. |
|
|
112
|
-
| `createListener` | function | Creates a `node:http` request listener over a core `DispatcherInterface` — the whole server face's entry point: converts the incoming message to a fetch `Request`, hands it to the dispatcher with the consumer's per-request `state`, and writes the resulting `Response` back. |
|
|
109
|
+
| Name | Kind | Signature | Summary |
|
|
110
|
+
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
111
|
+
| `handleListenerRequest` | function | `<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>, request: IncomingMessage, response: ServerResponse) => Promise<void>` | Handles one `node:http` request through a core dispatcher and writes its fetch-standard response. |
|
|
112
|
+
| `createListener` | function | `<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>) => ListenerFunction` | Creates a `node:http` request listener over a core `DispatcherInterface` — the whole server face's entry point: converts the incoming message to a fetch `Request`, hands it to the dispatcher with the consumer's per-request `state`, and writes the resulting `Response` back. |
|
|
113
113
|
|
|
114
114
|
### Classes
|
|
115
115
|
|
|
116
|
-
|
|
|
117
|
-
| --------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
-
| `Router` | class | Represents the path-matching + registry engine — registers `{ path, meta, name? }` entries (compiling each path once) and resolves a concrete pathname to the most specific matching entry. The shared machine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
|
|
119
|
-
| `Group` | class | Represents a prefix-scoped registration handle over a `Router` — pure string composition, no independent state or storage. |
|
|
120
|
-
| `Dispatcher` | class | Represents the fetch-standard, method-dimensioned dispatch entity — layers HTTP method dispatch and web-standard `Request`/`Response` handling over one internal `Router<RouteRecord<TState>>`. The core machine the server face and any fetch-native runtime consume directly. |
|
|
121
|
-
| `DispatchGroup` | class | Represents a prefix-scoped registration handle over a `Dispatcher` — the method-dimensioned counterpart of `Group`. |
|
|
122
|
-
| `Navigator` | class | Represents the headless History/hash navigation entity — composes one core `Router<Meta>`, resolving the current location on `start()` and every subsequent navigation event, tracking `active`, and emitting `navigate` through the core `Emitter`. No `render` / `outlet` — the consumer owns rendering. |
|
|
116
|
+
| Name | Kind | Signature | Summary |
|
|
117
|
+
| --------------- | ----- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| `Router` | class | `new <Meta>(options?: RouterOptions<Meta>) => RouterInterface<Meta>` | Represents the path-matching + registry engine — registers `{ path, meta, name? }` entries (compiling each path once) and resolves a concrete pathname to the most specific matching entry. The shared machine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
|
|
119
|
+
| `Group` | class | `new <Meta>(parent: RouterInterface<Meta>, prefix: string) => GroupInterface<Meta>` | Represents a prefix-scoped registration handle over a `Router` — pure string composition, no independent state or storage. |
|
|
120
|
+
| `Dispatcher` | class | `new <TState = undefined>(options?: DispatcherOptions<TState>) => DispatcherInterface<TState>` | Represents the fetch-standard, method-dimensioned dispatch entity — layers HTTP method dispatch and web-standard `Request`/`Response` handling over one internal `Router<RouteRecord<TState>>`. The core machine the server face and any fetch-native runtime consume directly. |
|
|
121
|
+
| `DispatchGroup` | class | `new <TState>(parent: DispatcherInterface<TState>, prefix: string) => DispatchGroupInterface<TState>` | Represents a prefix-scoped registration handle over a `Dispatcher` — the method-dimensioned counterpart of `Group`. |
|
|
122
|
+
| `Navigator` | class | `new <Meta>(options: NavigatorOptions<Meta>) => NavigatorInterface<Meta>` | Represents the headless History/hash navigation entity — composes one core `Router<Meta>`, resolving the current location on `start()` and every subsequent navigation event, tracking `active`, and emitting `navigate` through the core `Emitter`. No `render` / `outlet` — the consumer owns rendering. |
|
|
123
123
|
|
|
124
124
|
### Types
|
|
125
125
|
|
|
126
126
|
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 `\|`.
|
|
127
127
|
|
|
128
|
-
|
|
|
128
|
+
| Name | Kind | Signature | Summary |
|
|
129
129
|
| ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
130
|
-
| `PathParams` | type | `{ readonly [K in keyof PathParamsRaw<Path>]: PathParamsRaw<Path>[K] }`
|
|
130
|
+
| `PathParams` | type | `{ readonly [K in keyof PathParamsRaw<Path>]: PathParamsRaw<Path>[K]; }` | Extracts `{ name: string }` param records from a path pattern at the type level — the typed half of the path grammar. |
|
|
131
131
|
| `PathParamsRaw` | type | ``string extends Path ? Readonly<Record<string, string>> : Path extends `${infer Segment}/${infer Rest}` ? SegmentParam<Segment> & PathParamsRaw<Rest> : SegmentParam<Path>`` | Performs recursive, unflattened param extraction for `PathParams` — walks a path pattern segment by segment (split on `/`), extracting each segment's `SegmentParam` contribution and intersecting the rest. |
|
|
132
132
|
| `IdentifierStartChar` | type | `'a' \| 'b' \| 'c' \| 'd' \| 'e' \| 'f' \| 'g' \| 'h' \| 'i' \| 'j' \| 'k' \| 'l' \| 'm' \| 'n' \| 'o' \| 'p' \| 'q' \| 'r' \| 's' \| 't' \| 'u' \| 'v' \| 'w' \| 'x' \| 'y' \| 'z' \| 'A' \| 'B' \| 'C' \| 'D' \| 'E' \| 'F' \| 'G' \| 'H' \| 'I' \| 'J' \| 'K' \| 'L' \| 'M' \| 'N' \| 'O' \| 'P' \| 'Q' \| 'R' \| 'S' \| 'T' \| 'U' \| 'V' \| 'W' \| 'X' \| 'Y' \| 'Z' \| '_'` | Names the identifier start characters an identifier-grammar param name may begin with — mirrors the runtime classifier's `[A-Za-z_]` head class, the one `classifySegment` and `compilePath` share. |
|
|
133
133
|
| `IdentifierChar` | type | `IdentifierStartChar \| '0' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'` | Names the identifier continuation characters after the first — mirrors the runtime classifier's `[A-Za-z0-9_]*` tail class. |
|
|
134
134
|
| `TakeIdentifierTail` | type | ``S extends `${infer Head}${infer Tail}` ? Head extends IdentifierChar ? TakeIdentifierTail<Tail, `${Acc}${Head}`> : Acc : Acc`` | Consumes the identifier-continuation run at the front of a string literal, char by char, appending each onto the accumulator. |
|
|
135
135
|
| `IdentifierHead` | type | ``S extends `${infer Head}${infer Tail}` ? Head extends IdentifierStartChar ? TakeIdentifierTail<Tail, Head> : '' : ''`` | Captures the identifier at the front of a string literal, or an empty string when the literal does not begin with an identifier-start char. |
|
|
136
|
-
| `SegmentParam` | type | ``Segment extends `:${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : { readonly [K in Name]: string } : unknown : Segment extends `*${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : { readonly [K in Name]: string } : unknown : unknown``
|
|
136
|
+
| `SegmentParam` | type | ``Segment extends `:${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : { readonly [K in Name]: string; } : unknown : Segment extends `*${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : { readonly [K in Name]: string; } : unknown : unknown`` | Contributes one path segment's type-level param record — the type-level mirror of the runtime `classifySegment` and `compilePath` segment parser. |
|
|
137
137
|
| `CompiledPath` | interface | `{ regex, params }` | Represents a compiled route path — the anchored regex plus its ordered param names. |
|
|
138
138
|
| `RouteEntry` | interface | `{ path, meta, name? }` | Represents one registered route in a `RouterInterface` — the `path` pattern plus the opaque `meta` payload to return on a match, with an optional `name`. |
|
|
139
139
|
| `RouterMatch` | interface | `{ path, params, meta, name? }` | Represents one matched route — the winning entry's registered pattern, its decoded params, its `meta` payload, and its optional `name`. |
|
|
140
140
|
| `AnswerHandler` | type | `(meta: Meta) => boolean` | Represents the native-override seam — a predicate deciding whether an entry's `meta` answers a given `match` call, beyond path matching. |
|
|
141
141
|
| `RouterOptions` | interface | `{ entries?, sensitive?, key? }` | Represents the options for `createRouter` — an optional initial entry set, the case-sensitivity toggle, and the dedup identity function. |
|
|
142
|
-
| `RouterInterface` | interface | `{ count
|
|
143
|
-
| `GroupInterface` | interface | `{ prefix
|
|
144
|
-
| `Method` | type | `
|
|
142
|
+
| `RouterInterface` | interface | `{ count, add(), match(), entries(), group(), clear() }` | Represents the path-matching + registry engine contract (the behavioral-interface role for the one-class-per-file `Router`). Registers `{ path, meta, name? }` entries (compiling each path once) and resolves a concrete pathname to the most specific matching entry — a literal segment beats a param beats a wildcard at the earliest differing segment, registration-order-independent. The shared engine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
|
|
143
|
+
| `GroupInterface` | interface | `{ prefix, add(), group() }` | Represents a prefix-scoped registration handle over a `RouterInterface` — pure string composition, no independent state or storage. |
|
|
144
|
+
| `Method` | type | `(typeof METHOD_LIST)[number]` | Names the HTTP methods a `DispatcherInterface` dimensions dispatch over — derived from `METHOD_LIST`, whose membership counterpart is `METHODS`. |
|
|
145
145
|
| `RouteContext` | interface | `{ params, pattern, url, state }` | Represents the ambient context a `RouteHandler` receives alongside the raw `Request` — decoded params, the winning pattern, the parsed URL, and the consumer's opaque per-request state. |
|
|
146
146
|
| `RouteHandler` | type | `(request: Request, context: RouteContext<Path, TState>) => Response \| Promise<Response>` | Receives the raw fetch `Request` plus its typed `RouteContext` and returns (or resolves) a fetch `Response`. |
|
|
147
147
|
| `RouteInput` | interface | `{ method, path, handler, name? }` | Represents one route registration input for `DispatcherInterface.add` — the method-dimensioned counterpart of `RouteEntry`. |
|
|
148
148
|
| `RouteRecord` | interface | `{ method, handler, name? }` | Represents the `meta` payload a `DispatcherInterface` stores in its underlying `Router` — what `RouterInterface.match` returns as `RouterMatch.meta` on a dispatch hit. |
|
|
149
|
-
| `DispatchResult` | type | `{ status: 'matched'
|
|
150
|
-
| `DispatcherEventMap` | type | `{ match, miss }`
|
|
149
|
+
| `DispatchResult` | type | `{ readonly status: 'matched'; readonly match: RouterMatch<RouteRecord<TState>>; } \| { readonly status: 'unmethoded'; readonly allow: readonly Method[]; } \| { readonly status: 'unmatched'; }` | Represents the outcome of `DispatcherInterface.match` — a discriminated union over the dispatch tiers: a full hit, a path that matches with no route for the method (405 territory), or nothing matched at all (404 territory). |
|
|
150
|
+
| `DispatcherEventMap` | type | `{ readonly match: readonly [method: Method, pattern: string]; readonly miss: readonly [method: string, pathname: string, status: 'unmatched' \| 'unmethoded']; }` | Represents the `Dispatcher`'s event map — the dispatch-outcome signals a consumer can observe alongside the return value of `handle`. |
|
|
151
151
|
| `DispatcherOptions` | interface | `{ routes?, sensitive?, unmatched?, unmethoded?, on?, error? }` | Represents the options for `createDispatcher` — initial routes, case sensitivity, the default-responder overrides, and the Emitter pattern's wiring. |
|
|
152
|
-
| `DispatcherInterface` | interface | `{ router, emitter
|
|
153
|
-
| `DispatchGroupInterface` | interface | `{ prefix
|
|
154
|
-
| `NavigatorEventMap` | type | `{ navigate }`
|
|
152
|
+
| `DispatcherInterface` | interface | `{ router, emitter, add(), group(), match(), handle(), destroy() }` | Represents the fetch-standard, method-dimensioned dispatch entity contract (the behavioral-interface role for the one-class-per-file `Dispatcher`). Layers HTTP method dispatch and web-standard `Request`/`Response` handling over a single internal `Router<RouteRecord<TState>>`. |
|
|
153
|
+
| `DispatchGroupInterface` | interface | `{ prefix, add(), group() }` | Represents a prefix-scoped registration handle over a `DispatcherInterface` — the method-dimensioned counterpart of `GroupInterface`. |
|
|
154
|
+
| `NavigatorEventMap` | type | `{ readonly navigate: readonly [match: RouterMatch<Meta>]; }` | Represents the `Navigator`'s event map — the single `navigate` signal a consumer observes. |
|
|
155
155
|
| `NavigatorOptions` | interface | `{ routes, history?, base?, fallback?, guard?, intercept?, sensitive?, on?, error? }` | Represents the options for `createNavigator` — the `routes` to dispatch between, the navigation substrate, the optional guard hook, and the Emitter pattern's wiring. |
|
|
156
|
-
| `NavigatorInterface` | interface | `{ router, emitter, active
|
|
156
|
+
| `NavigatorInterface` | interface | `{ router, emitter, active, start(), stop(), navigate(), match(), destroy() }` | Represents the headless History/hash navigation entity contract (the behavioral-interface role for the one-class-per-file `Navigator`). Composes a core `Router<Meta>`, resolves the current location on `start()` and on every subsequent navigation event, tracks `active`, and emits `navigate` through the `EmitterInterface`. |
|
|
157
157
|
| `RequestOptions` | interface | `{ origin?, response? }` | Represents the options for `buildRequest` — URL origin and response-side disconnect tracking. |
|
|
158
158
|
| `ListenerFunction` | type | `(request: IncomingMessage, response: ServerResponse) => void` | Represents a `node:http` request handler — the function `createListener` returns, matching `http.createServer`'s handler signature. |
|
|
159
159
|
| `StateFunction` | type | `(message: IncomingMessage) => TState` | Derives a consumer's opaque per-request `TState` from the raw `IncomingMessage` — the `state` argument `createListener` threads into `dispatcher.handle`. |
|