@contractspec/lib.contracts-runtime-server-rest 3.7.5 → 3.7.7

package/README.md

@@ -1,166 +1,68 @@
 # @contractspec/lib.contracts-runtime-server-rest
 
-REST runtime adapters for exposing ContractSpec operations over HTTP.
+**REST server runtime adapters for ContractSpec contracts.**
 
-Website: https://contractspec.io/
+## What It Provides
 
-## Why this package exists
+- **Layer**: lib.
+- **Consumers**: bundles, all REST apps.
+- Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
+- Related ContractSpec packages include `@contractspec/lib.contracts-spec`, `@contractspec/lib.schema`, `@contractspec/tool.bun`, `@contractspec/tool.typescript`.
 
-This package is the REST adapter layer extracted from `@contractspec/lib.contracts`.
+## Installation
 
-It lets you take an `OperationSpecRegistry` and expose it in multiple server environments with consistent behavior:
+`npm install @contractspec/lib.contracts-runtime-server-rest`
 
-- framework-agnostic fetch handler
-- Express adapter
-- Elysia adapter
-- Next.js App Router adapter
-- Next.js Pages Router adapter
+or
 
-## Package boundary (important)
+`bun add @contractspec/lib.contracts-runtime-server-rest`
 
-Use this package for:
+## Usage
 
-- HTTP transport projection of operation specs.
-- Shared REST concerns (route derivation, input parsing, CORS, error mapping).
-- Helper utilities reused by GraphQL runtime (`contracts-adapter-input`, `contracts-adapter-hydration`).
+Import the root entrypoint from `@contractspec/lib.contracts-runtime-server-rest`, or choose a documented subpath when you only need one part of the package surface.
 
-Do not use this package for:
+## Architecture
 
-- Defining operation contracts (use `@contractspec/lib.contracts-spec`).
-- Building GraphQL schema (use `@contractspec/lib.contracts-runtime-server-graphql`).
+- `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.
 
-## Installation
+## 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`.
+
+## Local Commands
+
+- `bun run dev` — contractspec-bun-build dev
+- `bun run build` — bun run prebuild && bun run build:bundle && bun run build:types
+- `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` — tsc --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
 
-```bash
-npm install @contractspec/lib.contracts-runtime-server-rest @contractspec/lib.contracts-spec
-# or
-bun add @contractspec/lib.contracts-runtime-server-rest @contractspec/lib.contracts-spec
-```
-
-Install whichever peer framework you use (`express`, `elysia`, `next`).
-
-## Export map
-
-- Generic handler:
-  - `createFetchHandler`
-  - `RestOptions`
-- Framework adapters:
-  - `expressRouter`
-  - `elysiaPlugin`
-  - `makeNextAppHandler`
-  - `makeNextPagesHandler`
-- Shared adapter internals:
-  - `createInputTypeBuilder`
-  - `hydrateResourceIfNeeded`
-  - `parseReturns`
-
-## Quick start (framework-agnostic)
-
-```ts
-import { createFetchHandler } from "@contractspec/lib.contracts-runtime-server-rest";
-import type { HandlerCtx } from "@contractspec/lib.contracts-spec";
-import type { OperationSpecRegistry } from "@contractspec/lib.contracts-spec/operations/registry";
-
-declare const operations: OperationSpecRegistry;
-
-const handler = createFetchHandler(
-  operations,
-  (request): HandlerCtx => ({
-    actor: "user",
-    channel: "web",
-    traceId: request.headers.get("x-trace-id") ?? undefined,
-  }),
-  {
-    basePath: "/api/contracts",
-    cors: true,
-    prettyJson: 2,
-  }
-);
-
-const response = await handler(
-  new Request("https://example.com/api/contracts/workspace/get/v1.0.0")
-);
-console.log(response.status);
-```
-
-## Framework examples
-
-### Express
-
-```ts
-import express from "express";
-import { expressRouter } from "@contractspec/lib.contracts-runtime-server-rest/rest-express";
-
-declare const operations: import("@contractspec/lib.contracts-spec/operations/registry").OperationSpecRegistry;
-
-const app = express();
-app.use(express.json());
-
-app.use(
-  expressRouter(
-    express,
-    operations,
-    () => ({ actor: "user", channel: "web" }),
-    { basePath: "/api/contracts", cors: true }
-  )
-);
-```
-
-### Next.js App Router
-
-```ts
-import { makeNextAppHandler } from "@contractspec/lib.contracts-runtime-server-rest/rest-next-app";
-
-declare const operations: import("@contractspec/lib.contracts-spec/operations/registry").OperationSpecRegistry;
-
-const handler = makeNextAppHandler(
-  operations,
-  () => ({ actor: "user", channel: "web" }),
-  { basePath: "/api/contracts" }
-);
-
-export const GET = handler;
-export const POST = handler;
-export const OPTIONS = handler;
-```
-
-## Runtime behavior details
-
-- Default method mapping:
-  - query -> `GET`
-  - command -> `POST`
-- Default path mapping:
-  - `/<operation.key with dots replaced by slashes>/v<version>`
-- GET input parsing:
-  - if `input` query param exists, parse it as JSON
-  - otherwise use query params as flat object
-- POST input parsing:
-  - supports `application/json` and `application/x-www-form-urlencoded`
-- Error mapping defaults:
-  - validation errors -> `400`
-  - `PolicyDenied*` errors -> `403`
-  - unknown errors -> `500`
-  - unsupported content type -> `415`
-
-You can override error serialization using `RestOptions.onError`.
-
-## AI assistant guidance
-
-When generating code:
-
-- Define operation specs first in `@contractspec/lib.contracts-spec`.
-- Start with `createFetchHandler` for deterministic behavior, then choose framework wrappers.
-- Keep `basePath` explicit to avoid route ambiguity in generated handlers.
-
-When debugging:
-
-- If a route is 404, verify operation key/version and derived path.
-- If input parsing fails on GET, check whether caller sends `input=` JSON vs plain query params.
-
-## Split migration from deprecated monolith
-
-- `@contractspec/lib.contracts/server/rest-generic` -> `@contractspec/lib.contracts-runtime-server-rest/rest-generic`
-- `@contractspec/lib.contracts/server/rest-express` -> `@contractspec/lib.contracts-runtime-server-rest/rest-express`
-- `@contractspec/lib.contracts/server/rest-elysia` -> `@contractspec/lib.contracts-runtime-server-rest/rest-elysia`
-- `@contractspec/lib.contracts/server/rest-next-app` -> `@contractspec/lib.contracts-runtime-server-rest/rest-next-app`
-- `@contractspec/lib.contracts/server/rest-next-pages` -> `@contractspec/lib.contracts-runtime-server-rest/rest-next-pages`
+- 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.

package/dist/rest-elysia.d.ts

@@ -1,7 +1,7 @@
-import type { Elysia } from 'elysia';
-import { type RestOptions } from './rest-generic';
 import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
 import type { HandlerCtx } from '@contractspec/lib.contracts-spec/types';
+import type { Elysia } from 'elysia';
+import { type RestOptions } from './rest-generic';
 export declare function elysiaPlugin(app: Elysia, reg: OperationSpecRegistry, ctxFactory: (c: {
     request: Request;
     store: unknown;

package/dist/rest-express.d.ts

@@ -1,7 +1,7 @@
-import type { Request as ExpressReq, Router } from 'express';
-import { type RestOptions } from './rest-generic';
 import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
 import type { HandlerCtx } from '@contractspec/lib.contracts-spec/types';
+import type { Request as ExpressReq, Router } from 'express';
+import { type RestOptions } from './rest-generic';
 export declare function expressRouter(express: {
     Router: () => Router;
 }, reg: OperationSpecRegistry, ctxFactory: (req: ExpressReq) => HandlerCtx, options?: RestOptions): Router;

package/dist/rest-next-app.d.ts

@@ -1,4 +1,4 @@
-import { type RestOptions } from './rest-generic';
 import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
 import type { HandlerCtx } from '@contractspec/lib.contracts-spec/types';
+import { type RestOptions } from './rest-generic';
 export declare function makeNextAppHandler(reg: OperationSpecRegistry, ctxFactory: (req: Request) => HandlerCtx, options?: RestOptions): (req: Request) => Promise<Response>;

package/dist/rest-next-pages.d.ts

@@ -1,5 +1,5 @@
-import type { NextApiRequest, NextApiResponse } from 'next';
-import { type RestOptions } from './rest-generic';
 import type { OperationSpecRegistry } from '@contractspec/lib.contracts-spec/operations/registry';
 import type { HandlerCtx } from '@contractspec/lib.contracts-spec/types';
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { type RestOptions } from './rest-generic';
 export declare function makeNextPagesHandler(reg: OperationSpecRegistry, ctxFactory: (req: NextApiRequest) => HandlerCtx, options?: RestOptions): (req: NextApiRequest, res: NextApiResponse) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contractspec/lib.contracts-runtime-server-rest",
-  "version": "3.7.5",
+  "version": "3.7.7",
   "description": "REST server runtime adapters for ContractSpec contracts",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -9,8 +9,8 @@
     "publish:pkg:canary": "bun publish:pkg --tag canary",
     "clean": "rm -rf dist",
     "lint": "bun run lint:fix",
-    "lint:fix": "eslint src --fix",
-    "lint:check": "eslint src",
+    "lint:fix": "biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .",
+    "lint:check": "biome check .",
     "build": "bun run prebuild && bun run build:bundle && bun run build:types",
     "build:bundle": "contractspec-bun-build transpile",
     "build:types": "contractspec-bun-build types",
@@ -24,19 +24,19 @@
     "directory": "packages/libs/contract-runtime-server-rest"
   },
   "dependencies": {
-    "@contractspec/lib.contracts-spec": "3.7.5",
-    "@contractspec/lib.schema": "3.7.5"
+    "@contractspec/lib.contracts-spec": "4.0.0",
+    "@contractspec/lib.schema": "3.7.6"
   },
   "peerDependencies": {
     "@pothos/core": "^4.9.1",
-    "elysia": "^1.4.27",
+    "elysia": "^1.4.28",
     "express": "^5.2.1",
-    "next": "16.1.6"
+    "next": "16.2.0"
   },
   "devDependencies": {
-    "@contractspec/tool.typescript": "3.7.5",
+    "@contractspec/tool.typescript": "3.7.6",
     "typescript": "^5.9.3",
-    "@contractspec/tool.bun": "3.7.5"
+    "@contractspec/tool.bun": "3.7.6"
   },
   "files": [
     "dist",