@owlmeans/route 0.1.18-rc.17 → 0.1.18-rc.19

package/README.md

@@ -1,13 +1,12 @@
 # @owlmeans/route
 
-Route model factory and type definitions for OwlMeans entrypoints.
-
-## Overview
-
-- `route()` creates a `RouteModel` used as the first argument to `protocol()` or `openProtocol()`
-- `frontend()` / `backend()` / `socket()` helpers set the route's `AppType` and parent
-- `RouteMethod` enum covers HTTP verbs; `RouteProtocols` covers `http`/`ws`
-- This package is a dependency of `@owlmeans/entrypoint` — you rarely use it directly unless defining entrypoint-level routes
+The route declaration vocabulary for OwlMeans entrypoints. An app imports it in its shared contract
+package, next to `@owlmeans/entrypoint`, to state for each entrypoint the URL segment, parent,
+HTTP method, app type (backend or frontend) and transport (HTTP, WebSocket or queue). It is not a
+router and serves nothing: server binding is `@owlmeans/server-route` / `@owlmeans/server-app`,
+client binding is `@owlmeans/client-route` / `@owlmeans/client-entrypoint`, UI routing is
+`@owlmeans/router`. Application code usually reads addresses through the entrypoint accessors
+(`path()`, `mount()`, `address()`) rather than through this package's `./utils`.
 
 A `RouteDeclaration` is plain, immutable data: its `path` is the segment the route contributes under
 its parent, and it is never rewritten. Where the route actually answers — the full path, the mount
@@ -17,88 +16,256 @@ context that asks, so the same declaration serves a server and a browser alike.
 ## Installation
 
 ```bash
-bun add @owlmeans/route@^0.1.18-rc.8
+bun add @owlmeans/route@^0.1.18-rc.18
 ```
 
-## Usage
+## Concepts
+
+- **Declaration** — the `RouteDeclaration` a `route()` call produces: `alias`, `path` (the segment
+  under `parent`), `type`, `method`, `protocol`, the service coordinates, and the queue fields.
+- **Model** — `RouteModel` is `{ route: RouteDeclaration }` and nothing more. `protocol()` and
+  `openProtocol()` from `@owlmeans/entrypoint` take it as their first argument.
+- **Marker** — `backend()`, `frontend()`, `socket()`, `job()` return `Partial<RouteOptions>` that set
+  the app type and protocol; `route()` accepts them as its options.
+- **Parent** — a route nests under another entrypoint. Pass the parent protocol object
+  (`parent: storyProtocols.base`); the declaration stores only its alias.
+- **Service** — `service` names the configured service (`cfg.services`) that answers the route.
+  Without it the route belongs to the asking context's own service or the default one of its type.
+- **Protocol** — `RouteProtocols` picks the transport that carries a call: HTTP request, socket
+  frame or queued job. The call site never chooses.
 
-Define routes for protocols:
-
-```typescript
-import { route, frontend, backend, socket, RouteMethod } from '@owlmeans/route'
-import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+## Usage
 
-// Backend REST route
-const createProtocol = protocol(
-  route('story-create', '/stories', backend('api', RouteMethod.POST)),
-  contract(typed<CreateStory>()),
-)
-
-// Frontend client route nested under parent
-const storyProtocol = openProtocol(
-  route('story-view', '/stories/:id', frontend('app'))
-)
-
-// WebSocket route
-const wsProtocol = protocol(
-  route('story-ws', '/stories/stream', socket('api')),
-  contract(typed<StoryEvent>()),
-)
+### A backend protocol tree
+
+Aliases stay private to the declaration module; the exported value is a tree of protocol objects.
+
+```ts
+import { contract, protocol } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod } from '@owlmeans/route'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import { InvoiceSchema, CreateInvoiceBodySchema } from './schemas.js'
+
+const aliases = {
+  base: 'my-app:api:invoice:base',
+  list: 'my-app:api:invoice:list',
+  create: 'my-app:api:invoice:create',
+} as const
+
+const base = protocol(route(aliases.base, '/invoice', backend()), contract(), {
+  guards: DEFAULT_GUARD,
+})
+
+export const invoiceProtocols = {
+  base,
+  list: protocol(
+    route(aliases.list, '/', backend({ parent: base, method: RouteMethod.GET })),
+    contract(InvoiceSchema),
+  ),
+  create: protocol(
+    route(aliases.create, '/', backend({ parent: base, method: RouteMethod.POST })),
+    contract(CreateInvoiceBodySchema, InvoiceSchema),
+  ),
+} as const
 ```
 
-## API
+`invoiceProtocols.create` resolves to `/invoice` on the backend service, answering `POST`, and
+inherits the guard declared on `base`.
 
-### `route(alias, path, opts?): RouteModel`
+### Path params, screens and default children
 
-Creates a route model. `path` is the segment this route contributes under its parent. `opts` can be a `RouteOptions` object or the result of `frontend()`, `backend()`, or `socket()`.
+Path params use the `:name` form and are typed through `contract.request`. `frontend()` marks a
+screen; `default: true` marks the child screen shown at the parent's path.
+
+```ts
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import { backend, frontend, route, RouteMethod } from '@owlmeans/route'
+import type { ProjectParams, Project, RenameProject } from './types.js'
+import { ProjectParamsSchema, RenameProjectSchema } from './schemas.js'
+
+const aliases = {
+  base: 'my-app:api:project:base',
+  rename: 'my-app:api:project:rename',
+  web: 'my-app:web:project:base',
+  dashboard: 'my-app:web:project:dashboard',
+  overview: 'my-app:web:project:overview',
+} as const
+
+const base = openProtocol(route(aliases.base, '/project', backend()))
+const web = openProtocol(route(aliases.web, '/project/:projectId', frontend()))
+
+export const projectProtocols = {
+  base,
+  rename: protocol(
+    route(aliases.rename, '/:id/rename', backend({ parent: base, method: RouteMethod.PATCH })),
+    contract.request(
+      { params: typed<ProjectParams>(ProjectParamsSchema), body: typed<RenameProject>(RenameProjectSchema) },
+      typed<Project>(),
+    ),
+  ),
+  web: {
+    base: web,
+    dashboard: openProtocol(route(aliases.dashboard, '/dashboard', frontend({ parent: web }))),
+    overview: openProtocol(route(aliases.overview, '/', frontend({ parent: web, default: true }))),
+  },
+} as const
+```
 
-### `frontend(parent?, sticky?): Partial<RouteOptions>`
+### Sockets, queued jobs and other services
 
-Returns options marking the route as frontend (`AppType.Frontend`), optionally with a parent alias.
+`socket()` and `job()` are `backend()` with a different protocol. A route pointed at another
+service carries `service`; a queue route also names its `queue`, `timeout` and, optionally, `reply`.
 
-### `backend(parent?, method?): Partial<RouteOptions>`
+```ts
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import { job, route, RouteMethod, socket } from '@owlmeans/route'
+import { GUARD_ED25519 } from '@owlmeans/auth-common'
+import type { ProjectParams, StoryUpdate, Story } from './types.js'
+import { ProjectParamsSchema } from './schemas.js'
+
+const WORKER = 'my-app-worker'
+const aliases = {
+  updates: 'my-app:api:update:base',
+  story: 'my-app:api:update:story',
+  jobs: 'my-app:worker:story:base',
+  develop: 'my-app:worker:story:develop',
+  cleanup: 'my-app:worker:story:cleanup',
+} as const
+
+const updates = openProtocol(route(aliases.updates, '/update'))
+const jobs = openProtocol(route(aliases.jobs, '/story', { service: WORKER }), { guards: GUARD_ED25519 })
+
+export const storyProtocols = {
+  updates,
+  // WebSocket subscription under /update
+  story: protocol(
+    route(aliases.story, '/story/:id', socket({ parent: updates })),
+    contract.request({ params: typed<ProjectParams>(ProjectParamsSchema) }, typed<StoryUpdate>()),
+  ),
+  jobs,
+  // Queued job: the caller waits up to timeout ms for the job's result
+  develop: protocol(
+    route(aliases.develop, '/:id/develop', job({
+      parent: jobs, method: RouteMethod.POST, service: WORKER, queue: 'story-work', timeout: 600_000,
+    })),
+    contract.request({ params: typed<ProjectParams>(ProjectParamsSchema) }, typed<Story>()),
+  ),
+  // reply: false resolves once the broker accepts the job; the outcome is Accepted
+  cleanup: protocol(
+    route(aliases.cleanup, '/:id/cleanup', job({
+      parent: jobs, method: RouteMethod.POST, service: WORKER, queue: 'story-ops', reply: false, timeout: 30_000,
+    })),
+    contract.request({ params: typed<ProjectParams>(ProjectParamsSchema) }, typed<unknown>()),
+  ),
+} as const
+```
 
-Returns options marking the route as backend (`AppType.Backend`), optionally with a parent alias and `RouteMethod`.
+Which queues a process consumes is configuration of that process (`listenQueues()`), never part of
+the declaration.
 
-### `socket(parent?): Partial<RouteOptions>`
+### Reading where a route answers
 
-Returns options for a WebSocket route with `RouteProtocols.SOCKET`.
+Once protocols are registered on a context, the entrypoint accessors answer address questions. The
+`./utils` helpers are the same functions over a bare declaration.
 
-### `RouteMethod`
+```ts
+import { AppType } from '@owlmeans/context'
+import { service } from '@owlmeans/config'
+import { resolveAddress, resolveMount } from '@owlmeans/route/utils'
+import { invoiceProtocols } from 'my-app-common'
 
-```typescript
-enum RouteMethod { GET, POST, PATCH, PUT, DELETE }
-```
+// Config side: the service the backend routes resolve against
+const cfg = service({ service: 'my-app-api', type: AppType.Backend, host: 'localhost', port: 8080, base: 'api' }, baseCfg)
 
-### `RouteProtocols`
+// Runtime side, through the registered entrypoint
+const entrypoint = context.entrypoint(invoiceProtocols.create)
+entrypoint.path()    // '/invoice'
+entrypoint.mount()   // '/api/invoice'
+entrypoint.address() // { host: 'localhost', port: 8080, base: 'api', secure: true, protocol: 'http' }
+entrypoint.isLocal() // true inside the my-app-api process
 
-```typescript
-enum RouteProtocols { WEB = 'http', SOCKET = 'ws' }
+// Same answers from a declaration
+const declaration = invoiceProtocols.create.route.route
+resolveMount(context, declaration)
+resolveAddress(context, declaration)
 ```
 
-The protocol also selects the transport that carries a call to an entrypoint on this route.
-
-### Types
+## API
 
-- `RouteDeclaration` — the plain, immutable data a `route()` call produces: `alias`, `path`,
-  `parent`, `method`, `protocol`, `secure`, plus the service coordinates
-- `RouteModel` — `{ route: RouteDeclaration }`, the model an entrypoint carries
-- `RouteAddress` — `{ host, port?, base?, secure, protocol }`, where a route answers once its
-  service has been picked
+### `@owlmeans/route`
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `route(alias, path, opts?)` | function | Build a `RouteModel`; `opts` is `RouteOptions` or a parent alias string |
+| `createRoute(alias, path, opts?)` | function | Build the bare `RouteDeclaration` (parent reference collapsed to its alias) |
+| `makeRouteModel(declaration)` | function | Wrap a declaration as `{ route }` |
+| `backend(opts?, method?)` | function | Mark `AppType.Backend`; `opts` is options, a parent alias or `null`; `method` is a `RouteMethod` or more options |
+| `frontend(opts?, default?)` | function | Mark `AppType.Frontend`; `default` is a boolean flag or more options |
+| `socket(opts?, secondary?)` | function | `backend()` with `protocol: RouteProtocols.SOCKET` |
+| `job(opts?, secondary?)` | function | `backend()` with `protocol: RouteProtocols.QUEUE` |
+| `service(alias, opts?)` | function | Set `service` on `opts` (mutated and returned) |
+| `rtype(type, opts?)` | function | Set an arbitrary `AppType`; the primitive behind `backend()` / `frontend()` |
+| `normalizePath(path)` | function | Trim whitespace and one leading and trailing `/` |
+| `RouteMethod` | enum | `GET = 'get'`, `POST = 'post'`, `PATCH = 'patch'`, `PUT = 'put'`, `DELETE = 'delete'` |
+| `RouteProtocols` | enum | `WEB = 'http'`, `SOCKET = 'ws'`, `QUEUE = 'queue'` |
+| `SEP` | const | Path separator `'/'` |
+| `PARAM` | const | Path param prefix `':'` |
+| `BasicRoute` | interface | `type`, `service?`, `host?`, `port?`, `base?`, `internalHost?`, `internalPort?` |
+| `RouteDeclaration` | interface | `BasicRoute` + `alias`, `path`, `parent?`, `default?`, `method?`, `protocol?`, `secure?`, `queue?`, `reply?`, `timeout?` |
+| `RouteOptions` | interface | `Partial<RouteDeclaration>` whose `parent` is a `RouteParent` |
+| `RouteParent` | type | `string \| EntrypointReference` |
+| `RouteModel` | interface | `{ route: RouteDeclaration }` |
+| `RouteAddress` | interface | `{ host, port?, base?, secure, protocol }` |
+| `CommonServiceRoute` | interface | A service entry: `BasicRoute` + `service`, `home?`, `default?` |
+| `ResolvedServiceRoute` | interface | A service entry that names its `host` |
 
 ### `@owlmeans/route/utils`
 
-The pure functions the entrypoint accessors are built on. Each takes a context and a declaration:
-
-- `resolveService(ctx, route)` / `isLocalRoute(ctx, route)`
-- `resolvePath(ctx, route)` — the route's segment under every ancestor's
-- `resolveMount(ctx, route)` — that path under the service base
-- `resolveAddress(ctx, route)` — host, port, scheme and protocol
-
-## Related Packages
-
-- [`@owlmeans/entrypoint`](../entrypoint) — `protocol()` and `openProtocol()` consume a `RouteModel`
-- [`@owlmeans/server-app`](../server-app) — re-exports `route` as `broute` (backend) alongside `route`
+The first six take `(context, declaration)`; the other four are pure and take no context.
+
+| Symbol | Kind | Purpose |
+|--------|------|---------|
+| `resolvePath(context, route)` | function | Every ancestor's segment, then this one |
+| `resolveMount(context, route)` | function | Service `base` + the full path |
+| `resolveService(context, route)` | function | The named service, else the default of the route's type, else the first of that type |
+| `resolveAddress(context, route)` | function | The `RouteAddress`; a hop over the service's internal host is never TLS |
+| `isLocalRoute(context, route)` | function | Does the route belong to the context's own service |
+| `getParentRoute(context, route)` | function | The parent declaration, with parentship-cycle detection |
+| `overrideParams(route, overrides?, filter?)` | function | Fill only blank fields of `route` from `overrides`; mutates, returns nothing |
+| `prependBase(route, path)` | function | `path` prefixed with `route.base` when set |
+| `isServiceRoute(obj?)` | type guard | Is `obj` a `CommonServiceRoute` with a known `AppType` |
+| `isServiceRouteResolved(route)` | type guard | Does the service entry name a host |
+| `CreateRouteSignature<R>` | interface | Call signature shared by `route()` and `createRoute()` |
+
+## Common pitfalls
+
+- Pass the parent protocol object in route options, never an exported alias string. Keep aliases
+  private to the declaration module and export a `*Protocols` tree.
+- The positional marker forms (`backend(parent, method)`, `frontend(parent, true)`) accept a parent
+  only as an alias string: a protocol object in first position is spread into the options and
+  overwrites the child's alias. Pass protocols as `{ parent }`.
+- `path` is only this route's segment. Do not repeat the parent's path in it; `resolvePath()` joins
+  the chain.
+- `job()` routes must name `service`, `queue` and `timeout`. `reply: false` returns the job identity
+  with an `Accepted` outcome, not the job's result.
+- Do not pass a context to the pure `./utils` helpers: `overrideParams(ctx, decl)` writes route
+  fields into the context object instead of resolving anything.
+- A mis-wired tree (no `cfg.services`, a service without a host, a parentship cycle) throws
+  `SyntaxError` when an address is resolved. Fix the config; do not catch it.
+- `transportAlias` and `EntrypointTransport` live in `@owlmeans/entrypoint`, not here. A route only
+  names its protocol.
+
+## Related packages
+
+- [`@owlmeans/entrypoint`](../entrypoint) — `protocol()` / `openProtocol()` consume a `RouteModel` and
+  expose `path()`, `mount()`, `address()`, `isLocal()`
+- [`@owlmeans/context`](../context) — `AppType`, `EntrypointReference` and the registry the address helpers walk
+- [`@owlmeans/config`](../config) — `service()` declares the service entries routes resolve against
+- [`@owlmeans/server-route`](../server-route) — server-side route model; re-exported by
+  [`@owlmeans/server-app`](../server-app) as `broute`
+- [`@owlmeans/client-route`](../client-route) — marks a route as client-side and extracts its params
+- [`@owlmeans/queue`](../queue) — the QUEUE transport a `job()` route is carried by
+- [`@owlmeans/socket`](../socket) — the SOCKET transport contracts
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -108,7 +275,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.20
+npx @owlmeans/agent-skills@^0.1.18-rc.22
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/route",
-  "version": "0.1.18-rc.17",
-  "generatedAt": "2026-09-12T14:21:25.468Z",
+  "version": "0.1.18-rc.19",
+  "generatedAt": "2026-09-15T12:38:15.211Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/route/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/route
 
 **Layer:** Core
-**Install:** `"@owlmeans/route": "^0.1.18-rc.17"` in `dependencies`
+**Install:** `"@owlmeans/route": "^0.1.18-rc.19"` in `dependencies`
 
 ## Key Exports
 
@@ -18,7 +18,7 @@ user-invocable: false
 | `frontend(options?, default?)` | Mark a route as a React page (web only) |
 | `backend(options?, method?)` | Mark a route as a backend endpoint |
 | `socket(options?, secondary?)` | A backend route answering over `RouteProtocols.SOCKET` |
-| `job(options?, secondary?)` | A backend route carried by the queue (`RouteProtocols.QUEUE`); its declaration adds `queue`, `reply` and `timeout` |
+| `job(options?, secondary?)` | A backend route carried by the queue (`RouteProtocols.QUEUE`); its declaration names `service`, `queue`, `reply` and `timeout` |
 | `service(alias, options?)` | Point a route at a named service |
 | `RouteMethod` | enum of GET, POST, PUT, PATCH, DELETE |
 | `RouteProtocols` | enum of WEB (`http`), SOCKET (`ws`), QUEUE (`queue`) |
@@ -51,7 +51,8 @@ not by this package; a route only names the protocol.
 `job()` is `backend()` with `RouteProtocols.QUEUE`. Three declaration fields matter only for that
 protocol: `queue` (which queue carries it), `reply` and `timeout`. `reply: false` resolves once the
 broker has taken the job — the value is the job's identity and the outcome is `Accepted`, not the
-job's result; the default is to wait for the result.
+job's result; the default is to wait for the result. Use the parent protocol object in a route
+option (`job({ parent: storyProtocols.base, service, queue, timeout })`), never an exported alias string.
 
 ## Subpath Exports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/route",
-  "version": "0.1.18-rc.17",
+  "version": "0.1.18-rc.19",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -28,7 +28,7 @@
     }
   },
   "dependencies": {
-    "@owlmeans/context": "^0.1.18-rc.16"
+    "@owlmeans/context": "^0.1.18-rc.18"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",