lib.contracts-runtime-server-rest

@lssm-tech/lib.contracts-runtime-server-rest

REST server runtime adapters for ContractSpec contracts.

What It Provides

• Layer: lib.
• Consumers: bundles, all REST apps.
• Related ContractSpec packages include @lssm-tech/lib.contracts-spec, @lssm-tech/lib.schema, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.
• Related ContractSpec packages include @lssm-tech/lib.contracts-spec, @lssm-tech/lib.schema, @lssm-tech/tool.bun, @lssm-tech/tool.typescript.

Installation

npm install @lssm-tech/lib.contracts-runtime-server-rest

or

bun add @lssm-tech/lib.contracts-runtime-server-rest

Usage

Import the root entrypoint from @lssm-tech/lib.contracts-runtime-server-rest, or choose a documented subpath when you only need one part of the package surface.

PWA update checks

createPwaUpdateCheckHandler from @lssm-tech/lib.contracts-runtime-server-rest/pwa-update turns a manifest resolver into a handler for the pwa.update.check contract. It merges app defaults with release overrides and returns none, optional, or required update decisions.

Scoped approvals

createFetchHandler accepts an approvalReceipt(request, operation) adapter. The adapter keeps receipt evidence outside operation input and places it in the common handler context. Operations with execution.approval.required are then denied by the shared registry before handler invocation unless the configured approval runtime validates and consumes the receipt.

Parameterized contract routes

createFetchHandler matches :parameter segments declared by operation REST transports, URI-decodes them, and merges them into validated input with path values authoritative over query or body fields. Its context factory may be asynchronous so authenticated hosts can resolve fresh session authority before registry execution.

Query envelope params

createFetchHandler rebuilds the full QueryEnvelope of every request and puts it on HandlerCtx.queryEnvelope: the routed operation, the decoded input and the $-prefixed URL params $search, $filters, $sort, $pagination, $cache, $tags, $consistency and $economicEvidenceRefs. $search and $consistency are plain strings and the rest are JSON; the params work beside ?input=, flat query params and POST bodies, and never enter flat input. createRestTransport sends them by default, except the client cache policy: $cache key parts often carry tenant or user ids, and GET URLs reach proxy and access logs. The envelope input is the decoded input plus path params, before contract validation. Handlers still receive the validated input as their first argument; input-only handlers need no change. The envelope is set on a per-request copy of the ctxFactory context, so a shared host context is never written. Malformed params return a BAD_REQUEST (400) problem after the auth gate and before the handler.

Architecture

• src/contracts-adapter-hydration.ts is part of the package's public or composition surface.
• src/contracts-adapter-input.ts is part of the package's public or composition surface.
• src/index.ts is the root public barrel and package entrypoint.
• src/rest-elysia.ts is part of the package's public or composition surface.
• src/rest-express.ts is part of the package's public or composition surface.
• src/rest-generic.ts is part of the package's public or composition surface.
• src/rest-next-app.ts is part of the package's public or composition surface.

Public Entry Points

• Export . resolves through ./src/index.ts.
• Export ./contracts-adapter-hydration resolves through ./src/contracts-adapter-hydration.ts.
• Export ./contracts-adapter-input resolves through ./src/contracts-adapter-input.ts.
• Export ./rest-elysia resolves through ./src/rest-elysia.ts.
• Export ./rest-express resolves through ./src/rest-express.ts.
• Export ./rest-generic resolves through ./src/rest-generic.ts.
• Export ./rest-next-app resolves through ./src/rest-next-app.ts.
• Export ./rest-next-pages resolves through ./src/rest-next-pages.ts.
• Export ./pwa-update resolves through ./src/pwa-update.ts.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run lint — bun run lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rm -rf dist
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun run prebuild — contractspec-bun-build prebuild

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.

Notes

• High blast radius — all REST APIs depend on this package.
• Framework adapters (Elysia, Express, Next.js) must stay independent of each other.
• Do not introduce cross-adapter coupling.