ts-procedures 10.1.2 → 10.2.1

package/build/schema/strip-internal-keywords.test.js

@@ -1,38 +0,0 @@
-import { describe, expect, test } from 'vitest';
-import { Type } from 'typebox';
-import { stripInternalKeywords } from './strip-internal-keywords.js';
-describe('stripInternalKeywords', () => {
-    test('removes enumerable ~-prefixed markers leaked by Type.Optional(Type.Unsafe(...))', () => {
-        // This composition emits `~unsafe`/`~optional` as ENUMERABLE own props.
-        const leaky = Type.Optional(Type.Unsafe({ type: 'string' }));
-        expect(Object.keys(leaky).some((k) => k.startsWith('~'))).toBe(true);
-        const clean = stripInternalKeywords(leaky);
-        expect(clean).toEqual({ type: 'string' });
-        expect(Object.keys(clean).some((k) => k.startsWith('~'))).toBe(false);
-    });
-    test('strips markers nested inside object properties', () => {
-        const schema = Type.Object({ x: Type.Optional(Type.Unsafe({ type: 'string' })) });
-        const clean = stripInternalKeywords(schema);
-        expect(JSON.stringify(clean)).not.toMatch(/~/);
-        expect(clean.properties.x).toEqual({ type: 'string' });
-    });
-    test('strips markers inside arrays (e.g. anyOf members)', () => {
-        const schema = {
-            anyOf: [Type.Unsafe({ type: 'string' }), { type: 'number', '~optional': true }],
-        };
-        const clean = stripInternalKeywords(schema);
-        expect(clean.anyOf).toEqual([{ type: 'string' }, { type: 'number' }]);
-    });
-    test('leaves a clean schema structurally equal and does not mutate the input', () => {
-        const input = { type: 'object', properties: { a: { type: 'string' } } };
-        const clean = stripInternalKeywords(input);
-        expect(clean).toEqual(input);
-        expect(clean).not.toBe(input); // fresh structure
-    });
-    test('passes primitives through unchanged', () => {
-        expect(stripInternalKeywords('x')).toBe('x');
-        expect(stripInternalKeywords(5)).toBe(5);
-        expect(stripInternalKeywords(null)).toBe(null);
-    });
-});
-//# sourceMappingURL=strip-internal-keywords.test.js.map

package/build/schema/strip-internal-keywords.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"strip-internal-keywords.test.js","sourceRoot":"","sources":["../../src/schema/strip-internal-keywords.test.ts"],"names":[],"mappings":"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"}

package/build/server/spec-version.d.ts

@@ -1,24 +0,0 @@
-/**
- * Spec version of the {@link DocEnvelope} wire format.
- *
- * Bump this ONLY when the envelope shape changes in a way downstream parsers
- * must react to — field renames, nesting changes, or semantic changes. Do NOT
- * bump it on ordinary package releases (dependency upgrades, bug fixes, new
- * optional fields that older parsers can safely ignore). It is decoupled from
- * the npm package version on purpose, so consumers get a small monotonic
- * integer to branch on instead of having to interpret semver.
- *
- * Consumer contract: an envelope with no `specVersion` field predates this
- * field and MUST be treated as spec version 1.
- */
-export declare const DOC_ENVELOPE_SPEC_VERSION = 1;
-/**
- * The ts-procedures package version that produced an envelope (e.g. `"10.0.0"`).
- * Populates the envelope's `generatorVersion` field.
- *
- * Informational only — for telemetry, debugging, and "which release served
- * this?" questions. Do NOT use it to decide parse compatibility; it churns on
- * every release regardless of whether the envelope format changed. Use
- * {@link DOC_ENVELOPE_SPEC_VERSION} for compatibility decisions.
- */
-export declare const DOC_ENVELOPE_GENERATOR_VERSION: string;

package/build/server/spec-version.js

@@ -1,26 +0,0 @@
-import { PACKAGE_VERSION } from '../version.js';
-/**
- * Spec version of the {@link DocEnvelope} wire format.
- *
- * Bump this ONLY when the envelope shape changes in a way downstream parsers
- * must react to — field renames, nesting changes, or semantic changes. Do NOT
- * bump it on ordinary package releases (dependency upgrades, bug fixes, new
- * optional fields that older parsers can safely ignore). It is decoupled from
- * the npm package version on purpose, so consumers get a small monotonic
- * integer to branch on instead of having to interpret semver.
- *
- * Consumer contract: an envelope with no `specVersion` field predates this
- * field and MUST be treated as spec version 1.
- */
-export const DOC_ENVELOPE_SPEC_VERSION = 1;
-/**
- * The ts-procedures package version that produced an envelope (e.g. `"10.0.0"`).
- * Populates the envelope's `generatorVersion` field.
- *
- * Informational only — for telemetry, debugging, and "which release served
- * this?" questions. Do NOT use it to decide parse compatibility; it churns on
- * every release regardless of whether the envelope format changed. Use
- * {@link DOC_ENVELOPE_SPEC_VERSION} for compatibility decisions.
- */
-export const DOC_ENVELOPE_GENERATOR_VERSION = PACKAGE_VERSION;
-//# sourceMappingURL=spec-version.js.map

package/build/server/spec-version.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"spec-version.js","sourceRoot":"","sources":["../../src/server/spec-version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAA;AAE1C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAW,eAAe,CAAA"}

package/build/version.d.ts

@@ -1,9 +0,0 @@
-/**
- * The ts-procedures package version (e.g. `"10.0.0"`), read from `package.json`.
- *
- * Single source of truth for "which version is this build?" — consumed by the
- * codegen file header and the doc-envelope `generatorVersion`. Import this
- * rather than re-importing `package.json`, so there's one place the version
- * enters the source tree.
- */
-export declare const PACKAGE_VERSION: string;

package/build/version.js

@@ -1,11 +0,0 @@
-import pkg from '../package.json' with { type: 'json' };
-/**
- * The ts-procedures package version (e.g. `"10.0.0"`), read from `package.json`.
- *
- * Single source of truth for "which version is this build?" — consumed by the
- * codegen file header and the doc-envelope `generatorVersion`. Import this
- * rather than re-importing `package.json`, so there's one place the version
- * enters the source tree.
- */
-export const PACKAGE_VERSION = pkg.version;
-//# sourceMappingURL=version.js.map

package/build/version.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAW,GAAG,CAAC,OAAO,CAAA"}

package/docs/doc-envelope-spec-v1.md

@@ -1,296 +0,0 @@
-# ts-procedures DocEnvelope — Consumer Spec (`specVersion: 1`)
-
-> **This document describes DocEnvelope `specVersion: 1`.** The filename is
-> pinned to the spec version (`-v1`) so future format changes land as a sibling
-> (`doc-envelope-spec-v2.md`) and the differences stay diffable. Check the
-> envelope's `specVersion` field (absent ⇒ `1`) to know which spec applies.
-
-A spec for a GUI that fetches a `DocEnvelope` JSON document from a ts-procedures
-server URL and renders it. This is the **stable wire contract** between a
-ts-procedures server and any documentation/codegen consumer. It is a *frozen*
-contract in the framework (changing field names/nesting breaks codegen goldens),
-so you can build against it confidently.
-
-Companion file: `doc-envelope-v1.schema.json` (JSON Schema Draft-07) — validate
-fetched documents against it.
-
----
-
-## 1. How you get the document
-
-There is **no built-in endpoint**. A server author calls
-`builder.toDocEnvelope()` (or `DocRegistry.toJSON()`) and exposes the resulting
-JSON at a route of their choosing (e.g. `GET /api/docs`, `/openapi`, a static
-`.json` file, etc.).
-
-So your website's "paste a URL" flow should:
-
-1. `fetch(url)` the user-supplied URL.
-2. Expect `Content-Type` ~ JSON; `JSON.parse` the body.
-3. Validate that it is an object with a `routes` **array**. That single check is
-   what the official codegen uses as its "is this an envelope?" gate. If
-   `routes` is missing/not-an-array, show a clear "not a ts-procedures docs
-   document" error.
-4. Optionally validate fully against `doc-envelope-v1.schema.json`.
-
-CORS: the server must allow your origin, or you'll need a proxy. Worth surfacing
-as a distinct error from "bad JSON".
-
----
-
-## 2. Top-level shape
-
-```ts
-interface DocEnvelope {
-  specVersion?: number       // envelope wire-format version; absent ⇒ treat as 1
-  generatorVersion?: string  // producing ts-procedures version, e.g. "10.0.0" (informational)
-  basePath: string           // e.g. "/api" (may be "")
-  headers: HeaderDoc[]       // global headers (often [])
-  errors: ErrorDoc[]         // the error catalog
-  routes: AnyRouteDoc[]      // every procedure/route
-}
-```
-
-The authoritative producer (`DocRegistry.toJSON`) emits these six keys.
-Resilience notes:
-
-- **`specVersion`** is your compatibility signal — a small monotonic integer
-  that increments **only** when the envelope format changes (never on routine
-  package releases). **Branch your parser on this.** Treat a **missing**
-  `specVersion` as `1` (documents predating the field). Refuse / warn on a
-  `specVersion` higher than your GUI knows about. Current value: `1`.
-- **`generatorVersion`** is the producing ts-procedures package version (e.g.
-  `"10.0.0"`). **Informational only** — show it in a footer/tooltip, but do
-  **not** use it to decide how to parse; it changes every release regardless of
-  format. (Note: one internal codegen *input* fixture carries an unrelated
-  top-level `"version"` string and uppercase methods — that's a loose
-  hand-authored fixture, not server output; ignore `version` if you ever see it.)
-- Be tolerant of **extra top-level keys** — treat unknown keys as opaque.
-- `headers` and `errors` are commonly empty arrays. Render gracefully.
-
----
-
-## 3. The error catalog (`errors`)
-
-```ts
-interface ErrorDoc {
-  name: string                       // unique; routes reference it by this name
-  statusCode: number                 // HTTP status, e.g. 400, 404, 418, 500
-  description: string
-  schema?: Record<string, unknown>   // JSON Schema of the error body (optional)
-}
-```
-
-Framework defaults are auto-merged and always present unless opted out:
-`ProcedureValidationError` (400), `ProcedureYieldValidationError` (500),
-`ProcedureError` (500), `ProcedureRegistrationError` (500). User taxonomy errors
-(e.g. `NotFound` 404, `Teapot` 418) appear alongside them.
-
-**GUI tip:** build a `Map<name, ErrorDoc>`. Each route's `errors: string[]` is a
-list of these names — render them as links/badges that resolve to the catalog
-entry (status code + description + body schema).
-
----
-
-## 4. Global headers (`headers`)
-
-```ts
-interface HeaderDoc {
-  name: string
-  description?: string
-  required?: boolean
-  example?: string
-}
-```
-
-Simple list; render as a small table. Often empty.
-
----
-
-## 5. Routes — discriminated union on `kind`
-
-`routes[]` mixes four kinds. **Always switch on `route.kind`.** Every route has a
-`name` and a `jsonSchema` object; the rest varies by kind.
-
-| `kind`          | Transport            | Path field(s)        | Method field        | Payload schema keys                          |
-|-----------------|----------------------|----------------------|---------------------|----------------------------------------------|
-| `rpc`           | JSON-RPC (POST)      | `path`               | `method: "post"`    | `body`, `response`                           |
-| `stream`        | RPC stream (SSE/text)| `path`               | `methods: string[]` | `params`, `yieldType`, `returnType`          |
-| `api`           | REST                 | `path?`, `fullPath`  | `method`            | `req.{pathParams,query,body,headers}`, `res.{body,headers}` |
-| `http-stream`   | REST stream (SSE)    | `path?`, `fullPath`  | `method`            | `req.{...}`, `res.{headers}`, `yield`, `returnType` |
-
-Common fields: `name` (string), `errors?` (string[] → catalog names),
-`scope` (grouping; `string | string[]` for rpc/stream, `string` for api/http-stream).
-
-> **No per-route `description`.** A `description` passed at procedure-definition
-> time is **not** carried into the route doc. Don't build UI that depends on it.
-
-### 5.1 `rpc`
-
-```jsonc
-{
-  "kind": "rpc",
-  "name": "GetUser",
-  "version": 1,
-  "scope": "users",
-  "path": "/api/users/get-user/1",   // full path; embeds scope + version
-  "method": "post",
-  "jsonSchema": {
-    "body":     { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } },
-    "response": { "type": "object", "required": ["id","name"], "properties": { "id":{"type":"string"}, "name":{"type":"string"} } }
-  },
-  "errors": ["Teapot"]
-}
-```
-
-- `jsonSchema.body` = request input (runtime-validated).
-- `jsonSchema.response` = response shape (documentation only).
-- Both are optional (a no-arg/no-return procedure yields `jsonSchema: {}`).
-
-### 5.2 `stream` (RPC stream)
-
-```jsonc
-{
-  "kind": "stream",
-  "name": "WatchUser",
-  "version": 2,
-  "scope": ["users", "live"],
-  "path": "/api/users/live/watch-user/2",
-  "methods": ["post", "get"],
-  "streamMode": "sse",                 // "sse" | "text"
-  "jsonSchema": {
-    "params":     { "type": "object", "required": ["id"], "properties": { "id": { "type": "string" } } },
-    "yieldType":  { /* see note */ },
-    "returnType": { "type": "object", "required": ["total"], "properties": { "total": { "type": "number" } } }
-  }
-}
-```
-
-- `params` = input (query params for GET, body for POST).
-- **`yieldType` in `sse` mode is the SSE envelope**, not the bare value:
-  ```jsonc
-  {
-    "type": "object",
-    "description": "SSE message envelope. The data field contains the procedure yield value.",
-    "required": ["data", "event", "id"],
-    "properties": {
-      "data":  { /* the actual per-yield value schema */ },
-      "event": { "type": "string" },
-      "id":    { "type": "string" },
-      "retry": { "type": "number" }
-    }
-  }
-  ```
-  In `text` mode `yieldType` is the bare value schema. **GUI tip:** to show "what
-  each event carries", detect the SSE envelope (object with `data`/`event`/`id`)
-  and surface `properties.data`; otherwise show `yieldType` directly.
-- `returnType` = value delivered on stream completion (carried by the `return`
-  SSE event). Optional.
-- `errors` here are pre-stream errors only.
-
-### 5.3 `api` (REST)
-
-```jsonc
-{
-  "kind": "api",
-  "name": "UpdateUser",
-  "scope": "users",
-  "path": "/users/:id",          // as registered (may have :params)
-  "method": "put",
-  "fullPath": "/api/users/:id",  // resolved, incl. basePath — prefer this for display
-  "successStatus": 200,          // optional; defaults POST→201, DELETE→204, else 200
-  "jsonSchema": {
-    "req": {
-      "pathParams": { "type":"object", "required":["id"], "properties":{"id":{"type":"string"}} },
-      "query":      { "type":"object", "properties":{"dryRun":{"type":"boolean"}} },
-      "body":       { "type":"object", "required":["name"], "properties":{"name":{"type":"string"}} }
-      // "headers" also possible
-    },
-    "res": {
-      "body":    { "type":"object", "required":["id","name"], "properties":{"id":{"type":"string"},"name":{"type":"string"}} },
-      "headers": { "type":"object", "required":["x-rev"], "properties":{"x-rev":{"type":"string"}} }
-    }
-  },
-  "errors": ["Teapot"]
-}
-```
-
-- `req` channels: any of `pathParams`, `query`, `body`, `headers` (all optional).
-- `res` channels: `body`, `headers` (both optional).
-- `jsonSchema.req`/`res` may be `{}` or absent for trivial endpoints.
-- Prefer `fullPath` for the displayed URL; `path` may be omitted in some
-  envelopes.
-
-### 5.4 `http-stream` (REST stream)
-
-```jsonc
-{
-  "kind": "http-stream",
-  "name": "TailUser",
-  "scope": "users",
-  "path": "/users/:id/tail",
-  "method": "get",
-  "fullPath": "/api/users/:id/tail",
-  "streamMode": "sse",
-  "jsonSchema": {
-    "req":        { "pathParams": { "type":"object", "required":["id"], "properties":{"id":{"type":"string"}} } },
-    "res":        { "headers": { /* optional response headers schema */ } },
-    "yield":      { "type":"object", "required":["line"], "properties":{"line":{"type":"string"}} },
-    "returnType": { "type":"object", "required":["lines"], "properties":{"lines":{"type":"number"}} }
-  }
-}
-```
-
-- Same `req` channels as `api`.
-- `res` has **`headers` only** (no `body` — streaming responses have no single body).
-- `yield` = per-event value schema, **raw** (NOT wrapped in an SSE envelope,
-  unlike `kind: "stream"`).
-- `returnType` = completion value. Optional.
-
----
-
-## 6. Embedded payload schemas
-
-Every `jsonSchema.*` leaf (`body`, `response`, `params`, `yield`, `req.query`,
-error `schema`, …) is a plain **JSON Schema (Draft-07)** object as produced by
-the server's schema layer (TypeBox → JSON Schema). Expect standard keywords:
-`type`, `properties`, `required`, `items`, `enum`, `const`, `format`, `oneOf`,
-nested objects/arrays, etc.
-
-**Render these with a generic JSON-Schema viewer.** Don't hard-code field lists.
-Useful libraries: `@apidevtools/json-schema-ref-parser` (deref `$ref` if any),
-or any JSON-Schema-to-table/form renderer. They are validation-grade schemas, so
-you can also drive a "try it" form or example generator from them.
-
----
-
-## 7. Suggested rendering model
-
-1. **Header:** `basePath`, route count, kind breakdown.
-2. **Sidebar:** group routes by `scope` (join array scopes with `/`), then by
-   `kind`. Label each with `name` + method/path.
-3. **Route detail:**
-   - Title: `name`; badge: `kind`; method(s); display path (`fullPath` ?? `path`).
-   - For `rpc`/`stream`: also show `version`.
-   - **Request** section from `body`/`params`/`req.*`.
-   - **Response** section from `response`/`res.*`; for streams, a **Stream**
-     section from `yield`/`yieldType` (+ `returnType`).
-   - **Errors** section: resolve each `errors[]` name against the catalog and
-     show status + description + body schema.
-4. **Errors page:** full `errors[]` catalog.
-5. **Headers page:** `headers[]` table.
-
----
-
-## 8. Defensive checklist for the GUI
-
-- Validate `routes` is an array before anything else; otherwise it's not an envelope.
-- Switch on `kind`; render unknown `kind` values generically (future-proofing).
-- Treat HTTP methods case-insensitively (canonical output is lowercase, but
-  normalize anyway).
-- Tolerate empty/absent `headers`, `errors`, `jsonSchema`, `req`, `res`.
-- Tolerate extra/unknown properties at every level.
-- Read `specVersion` first (default 1 if absent) and branch parsing on it; warn on unknown-higher.
-- Don't expect a per-route `description`. `generatorVersion` is display-only, never a parse signal.
-- Prefer `fullPath` over `path` for `api`/`http-stream` display.
-- Unwrap the SSE envelope for `stream` `yieldType.data` when showing "event payload".