ts-procedures 10.1.2 → 10.2.1

package/docs/doc-envelope-v1.schema.json

@@ -1,253 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://ts-procedures.dev/schemas/doc-envelope-v1.schema.json",
-  "title": "ts-procedures DocEnvelope (specVersion 1)",
-  "description": "The JSON document a ts-procedures server exposes (via builder.toDocEnvelope() / DocRegistry.toJSON()). Describes every procedure/route the server serves, the global error catalog, and global headers. Payload schemas embedded under each route's `jsonSchema` are arbitrary JSON Schema (Draft-07) objects and are intentionally left unconstrained here.",
-  "type": "object",
-  "required": ["basePath", "headers", "errors", "routes"],
-  "properties": {
-    "specVersion": {
-      "type": "integer",
-      "minimum": 1,
-      "description": "Wire-format version of the envelope. A small monotonic integer, bumped ONLY when the envelope shape changes — not on every package release. Branch on this to pick a parser. ABSENT means treat as 1 (envelopes predating this field). Emitted by ts-procedures servers; optional here so older/hand-built documents still validate."
-    },
-    "generatorVersion": {
-      "type": "string",
-      "description": "ts-procedures package version that produced the envelope, e.g. \"10.0.0\". Informational only (telemetry/debugging) — do NOT use it for parse-compatibility decisions; use specVersion."
-    },
-    "basePath": {
-      "type": "string",
-      "description": "Path prefix shared by all routes, e.g. \"/api\". May be the empty string."
-    },
-    "headers": {
-      "type": "array",
-      "description": "Global HTTP headers documented for the whole API.",
-      "items": { "$ref": "#/definitions/HeaderDoc" }
-    },
-    "errors": {
-      "type": "array",
-      "description": "Catalog of every error the API may return (framework defaults + user-defined taxonomy). Routes reference these by name via their `errors` array.",
-      "items": { "$ref": "#/definitions/ErrorDoc" }
-    },
-    "routes": {
-      "type": "array",
-      "description": "All procedures/routes. Discriminated union on `kind`.",
-      "items": { "$ref": "#/definitions/AnyRouteDoc" }
-    }
-  },
-  "additionalProperties": true,
-  "definitions": {
-    "JsonSchema": {
-      "description": "An embedded JSON Schema (Draft-07) object describing a payload. Left unconstrained on purpose — render it generically.",
-      "type": "object",
-      "additionalProperties": true
-    },
-    "HeaderDoc": {
-      "type": "object",
-      "required": ["name"],
-      "properties": {
-        "name": { "type": "string" },
-        "description": { "type": "string" },
-        "required": { "type": "boolean" },
-        "example": { "type": "string" }
-      },
-      "additionalProperties": true
-    },
-    "ErrorDoc": {
-      "type": "object",
-      "required": ["name", "statusCode", "description"],
-      "properties": {
-        "name": {
-          "type": "string",
-          "description": "Unique error name. Routes link to it via their `errors` array."
-        },
-        "statusCode": {
-          "type": "integer",
-          "description": "HTTP status code returned for this error.",
-          "minimum": 100,
-          "maximum": 599
-        },
-        "description": { "type": "string" },
-        "schema": {
-          "$ref": "#/definitions/JsonSchema",
-          "description": "JSON Schema of the error response body. Optional."
-        }
-      },
-      "additionalProperties": true
-    },
-
-    "AnyRouteDoc": {
-      "oneOf": [
-        { "$ref": "#/definitions/RPCRouteDoc" },
-        { "$ref": "#/definitions/StreamRouteDoc" },
-        { "$ref": "#/definitions/APIRouteDoc" },
-        { "$ref": "#/definitions/HttpStreamRouteDoc" }
-      ]
-    },
-
-    "HttpMethod": {
-      "description": "HTTP method. Canonical wire form is lowercase; treat case-insensitively when rendering.",
-      "type": "string",
-      "enum": ["get", "post", "put", "delete", "patch", "head", "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD"]
-    },
-
-    "StreamMode": {
-      "type": "string",
-      "enum": ["sse", "text"],
-      "description": "Stream transport. `sse` = Server-Sent Events; `text` = raw text chunks."
-    },
-
-    "Scope": {
-      "description": "Logical grouping. A single segment or an array of segments.",
-      "oneOf": [
-        { "type": "string" },
-        { "type": "array", "items": { "type": "string" } }
-      ]
-    },
-
-    "RPCRouteDoc": {
-      "title": "RPC route (kind = rpc)",
-      "description": "JSON-RPC-style procedure. Always POST. Path embeds scope + version.",
-      "type": "object",
-      "required": ["kind", "name", "path", "method", "scope", "version", "jsonSchema"],
-      "properties": {
-        "kind": { "const": "rpc" },
-        "name": { "type": "string" },
-        "path": { "type": "string", "description": "Full path incl. basePath + version, e.g. /api/users/get-user/1" },
-        "method": { "const": "post" },
-        "scope": { "$ref": "#/definitions/Scope" },
-        "version": { "type": "number" },
-        "errors": { "type": "array", "items": { "type": "string" } },
-        "jsonSchema": {
-          "type": "object",
-          "properties": {
-            "body": { "$ref": "#/definitions/JsonSchema", "description": "Request body schema (validated)." },
-            "response": { "$ref": "#/definitions/JsonSchema", "description": "Response body schema (doc only)." }
-          },
-          "additionalProperties": true
-        }
-      },
-      "additionalProperties": true
-    },
-
-    "StreamRouteDoc": {
-      "title": "RPC stream route (kind = stream)",
-      "description": "Streaming RPC procedure. Served over both POST and GET. Path embeds scope + version.",
-      "type": "object",
-      "required": ["kind", "name", "path", "methods", "streamMode", "scope", "version", "jsonSchema"],
-      "properties": {
-        "kind": { "const": "stream" },
-        "name": { "type": "string" },
-        "path": { "type": "string" },
-        "methods": {
-          "type": "array",
-          "description": "Allowed methods, conventionally [\"post\", \"get\"].",
-          "items": { "type": "string", "enum": ["get", "post"] }
-        },
-        "streamMode": { "$ref": "#/definitions/StreamMode" },
-        "scope": { "$ref": "#/definitions/Scope" },
-        "version": { "type": "number" },
-        "errors": { "type": "array", "items": { "type": "string" }, "description": "Pre-stream errors only." },
-        "jsonSchema": {
-          "type": "object",
-          "properties": {
-            "params": { "$ref": "#/definitions/JsonSchema", "description": "Query params (GET) or body (POST)." },
-            "yieldType": {
-              "$ref": "#/definitions/JsonSchema",
-              "description": "Schema for each streamed value. In `sse` mode this is the SSE envelope { data, event, id, retry } whose `data` holds the user's yield schema; in `text` mode it is the raw yield schema."
-            },
-            "returnType": { "$ref": "#/definitions/JsonSchema", "description": "Final return value schema." }
-          },
-          "additionalProperties": true
-        }
-      },
-      "additionalProperties": true
-    },
-
-    "APIRouteDoc": {
-      "title": "REST route (kind = api)",
-      "description": "REST-style HTTP endpoint with explicit method + path.",
-      "type": "object",
-      "required": ["kind", "name", "method", "fullPath", "jsonSchema"],
-      "properties": {
-        "kind": { "const": "api" },
-        "name": { "type": "string" },
-        "scope": { "type": "string" },
-        "path": { "type": "string", "description": "Path as registered (may include :params), e.g. /users/:id. May be omitted in some envelopes; prefer fullPath." },
-        "method": { "$ref": "#/definitions/HttpMethod" },
-        "fullPath": { "type": "string", "description": "Resolved path incl. basePath prefix, e.g. /api/users/:id." },
-        "successStatus": { "type": "integer", "description": "Status on success. Defaults: POST→201, DELETE→204, else 200." },
-        "errors": { "type": "array", "items": { "type": "string" } },
-        "jsonSchema": {
-          "type": "object",
-          "properties": {
-            "req": {
-              "type": "object",
-              "properties": {
-                "pathParams": { "$ref": "#/definitions/JsonSchema" },
-                "query": { "$ref": "#/definitions/JsonSchema" },
-                "body": { "$ref": "#/definitions/JsonSchema" },
-                "headers": { "$ref": "#/definitions/JsonSchema" }
-              },
-              "additionalProperties": true
-            },
-            "res": {
-              "type": "object",
-              "properties": {
-                "body": { "$ref": "#/definitions/JsonSchema" },
-                "headers": { "$ref": "#/definitions/JsonSchema" }
-              },
-              "additionalProperties": true
-            }
-          },
-          "additionalProperties": true
-        }
-      },
-      "additionalProperties": true
-    },
-
-    "HttpStreamRouteDoc": {
-      "title": "REST stream route (kind = http-stream)",
-      "description": "REST-style streaming endpoint. Response has no single body; values arrive via `yield`. Currently always SSE.",
-      "type": "object",
-      "required": ["kind", "name", "method", "fullPath", "streamMode", "jsonSchema"],
-      "properties": {
-        "kind": { "const": "http-stream" },
-        "name": { "type": "string" },
-        "scope": { "type": "string" },
-        "path": { "type": "string" },
-        "method": { "$ref": "#/definitions/HttpMethod" },
-        "fullPath": { "type": "string" },
-        "streamMode": { "$ref": "#/definitions/StreamMode" },
-        "errors": { "type": "array", "items": { "type": "string" } },
-        "jsonSchema": {
-          "type": "object",
-          "properties": {
-            "req": {
-              "type": "object",
-              "properties": {
-                "pathParams": { "$ref": "#/definitions/JsonSchema" },
-                "query": { "$ref": "#/definitions/JsonSchema" },
-                "body": { "$ref": "#/definitions/JsonSchema" },
-                "headers": { "$ref": "#/definitions/JsonSchema" }
-              },
-              "additionalProperties": true
-            },
-            "res": {
-              "type": "object",
-              "description": "Response headers only — streaming responses have no single body.",
-              "properties": {
-                "headers": { "$ref": "#/definitions/JsonSchema" }
-              },
-              "additionalProperties": true
-            },
-            "yield": { "$ref": "#/definitions/JsonSchema", "description": "Schema for each streamed value. NOT wrapped in an SSE envelope (unlike kind=stream)." },
-            "returnType": { "$ref": "#/definitions/JsonSchema", "description": "Final return value schema." }
-          },
-          "additionalProperties": true
-        }
-      },
-      "additionalProperties": true
-    }
-  }
-}

package/src/schema/strip-internal-keywords.test.ts

@@ -1,43 +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' })) as unknown as Record<string, unknown>
-    expect(Object.keys(leaky).some((k) => k.startsWith('~'))).toBe(true)
-
-    const clean = stripInternalKeywords(leaky)
-    expect(clean).toEqual({ type: 'string' })
-    expect(Object.keys(clean as object).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) as any
-    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) as any
-    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)
-  })
-})

package/src/schema/strip-internal-keywords.ts

@@ -1,36 +0,0 @@
-import type { TJSONSchema } from './json-schema.js'
-
-/** TypeBox v1 prefixes every internal marker key with `~`. */
-const TILDE = '~'
-
-/**
- * Deep-removes TypeBox v1 internal markers (`~kind`, `~unsafe`, `~optional`, …)
- * from an extracted JSON Schema, returning a fresh structure (never mutates the
- * input).
- *
- * These markers are *usually* non-enumerable, so they stay out of JSON Schema on
- * their own. But some compositions leak them as **enumerable** own properties —
- * notably `Type.Optional(Type.Unsafe({...}))`, which emits `~unsafe`/`~optional`
- * inline. Left in place those markers (a) pollute serialized docs/codegen output
- * and (b) make strict AJV throw `unknown keyword: "~unsafe"` at registration.
- *
- * Stripping by the `~`-prefix convention (rather than a fixed name list) keeps
- * this robust against future TypeBox markers — same convention the TypeBox
- * adapter detects on.
- */
-export function stripInternalKeywords<T>(schema: T): T {
-  if (Array.isArray(schema)) {
-    return schema.map((item) => stripInternalKeywords(item)) as T
-  }
-  if (schema !== null && typeof schema === 'object') {
-    const out: Record<string, unknown> = {}
-    for (const [key, value] of Object.entries(schema)) {
-      if (key.startsWith(TILDE)) continue
-      out[key] = stripInternalKeywords(value)
-    }
-    return out as T
-  }
-  return schema
-}
-
-export type { TJSONSchema }

package/src/server/spec-version.ts

@@ -1,27 +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: string = PACKAGE_VERSION

package/src/version.ts

@@ -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: string = pkg.version