ts-procedures 10.0.0 → 10.1.1

package/src/schema/typebox.test.ts

@@ -9,6 +9,18 @@ describe('typebox schema detection', () => {
     expect(isTypeboxSchema(typebox)).toBe(true)
   })
 
+  test('it recognizes a top-level Type.Unsafe schema (~unsafe marker, no ~kind)', () => {
+    // typebox >= 1.2.0: Type.Unsafe carries `~unsafe` INSTEAD of `~kind`.
+    expect(isTypeboxSchema(Type.Unsafe({ type: 'string' }))).toBe(true)
+  })
+
+  test('it recognizes any future ~-prefixed marker (convention, not a name list)', () => {
+    // Detection keys off TypeBox's `~` namespace convention, so a marker that
+    // doesn't exist yet is still recognized without a code change.
+    const futureMarker = { '~somethingNew': true, type: 'object' }
+    expect(isTypeboxSchema(futureMarker)).toBe(true)
+  })
+
   test('it rejects non-TypeBox values', () => {
     expect(isTypeboxSchema({ type: 'object' })).toBe(false)
     expect(isTypeboxSchema('string value')).toBe(false)

package/src/schema/typebox.ts

@@ -3,10 +3,29 @@ import type { TJSONSchema } from './json-schema.js'
 
 const TYPEBOX_KIND = Symbol.for('TypeBox.Kind')
 
+/** TypeBox v1 prefixes every internal marker key with `~`. */
+const TILDE = '~'.charCodeAt(0)
+
+/**
+ * TypeBox v1 namespaces all of its internal markers under a `~` prefix
+ * (`~kind`, `~unsafe`, `~optional`, ...) — non-enumerable own properties that
+ * stay out of the serialized JSON Schema. Detecting the *convention* rather
+ * than specific marker names means new markers (e.g. `~unsafe`, added in
+ * typebox 1.2.0 and used by `Type.Unsafe(...)` *instead of* `~kind`) are
+ * recognized without a code change. Reflect.ownKeys is required because these
+ * markers are non-enumerable.
+ */
+function hasTypeBoxV1Marker(schema: object): boolean {
+  for (const key of Reflect.ownKeys(schema)) {
+    if (typeof key === 'string' && key.charCodeAt(0) === TILDE) return true
+  }
+  return false
+}
+
 /**
  * Built-in adapter for TypeBox (`import { Type } from 'typebox'`).
  *
- * Detection covers both typebox v1 (`~kind` property) and legacy
+ * Detection covers both typebox v1 (any `~`-prefixed marker) and legacy
  * `@sinclair/typebox` 0.3x (`Symbol.for('TypeBox.Kind')`). TypeBox schemas
  * already ARE JSON Schema, so conversion is the identity.
  */
@@ -14,7 +33,7 @@ export const typeboxAdapter: SchemaAdapter = {
   name: 'typebox',
   detect(schema: unknown): boolean {
     if (typeof schema !== 'object' || schema === null) return false
-    return '~kind' in schema || TYPEBOX_KIND in schema
+    return hasTypeBoxV1Marker(schema) || TYPEBOX_KIND in schema
   },
   toJsonSchema(schema: unknown): TJSONSchema {
     return schema as TJSONSchema

package/src/server/doc-registry.test.ts

@@ -5,7 +5,9 @@ import type {
   THttpStreamProcedureRegistration,
   TProcedureRegistration,
 } from '../core/types.js'
+import pkg from '../../package.json' with { type: 'json' }
 import { DocRegistry } from './doc-registry.js'
+import { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 import { defineErrorTaxonomy } from './errors/taxonomy.js'
 import { buildRpcRouteDoc } from './docs/rpc-doc.js'
 import { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
@@ -201,6 +203,38 @@ describe('DocRegistry', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // toJSON() spec metadata
+  // --------------------------------------------------------------------------
+  describe('toJSON() spec metadata', () => {
+    test('emits specVersion (the constant, a number) and generatorVersion (the package version)', () => {
+      const out = new DocRegistry().toJSON()
+      expect(out.specVersion).toBe(DOC_ENVELOPE_SPEC_VERSION)
+      expect(typeof out.specVersion).toBe('number')
+      expect(out.generatorVersion).toBe(pkg.version)
+      // the exported constant must track the real package version
+      expect(DOC_ENVELOPE_GENERATOR_VERSION).toBe(pkg.version)
+    })
+
+    test('metadata is present even on an otherwise-empty envelope', () => {
+      const out = new DocRegistry({ includeDefaults: false }).toJSON()
+      expect(out).toMatchObject({
+        specVersion: DOC_ENVELOPE_SPEC_VERSION,
+        generatorVersion: pkg.version,
+      })
+    })
+
+    test('transform receives the metadata on its envelope argument', () => {
+      const seen = new DocRegistry().toJSON({
+        transform: ({ specVersion, generatorVersion }) => ({ specVersion, generatorVersion }),
+      })
+      expect(seen).toEqual({
+        specVersion: DOC_ENVELOPE_SPEC_VERSION,
+        generatorVersion: pkg.version,
+      })
+    })
+  })
+
   // --------------------------------------------------------------------------
   // toJSON() filter
   // --------------------------------------------------------------------------

package/src/server/doc-registry.ts

@@ -13,6 +13,7 @@ import {
   taxonomyToErrorDocs,
   type ErrorTaxonomy,
 } from './errors/taxonomy.js'
+import { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 
 export type {
   AnyHttpRouteDoc,
@@ -112,6 +113,8 @@ export class DocRegistry {
     }
 
     const envelope: DocEnvelope = {
+      specVersion: DOC_ENVELOPE_SPEC_VERSION,
+      generatorVersion: DOC_ENVELOPE_GENERATOR_VERSION,
       basePath: this.basePath,
       headers: [...this.headers],
       errors: [...this.errors],

package/src/server/index.ts

@@ -25,5 +25,6 @@ export { buildStreamRouteDoc } from './docs/stream-doc.js'
 export { buildHttpRouteDoc } from './docs/http-doc.js'
 export { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
 export { DocRegistry } from './doc-registry.js'
+export { DOC_ENVELOPE_SPEC_VERSION, DOC_ENVELOPE_GENERATOR_VERSION } from './spec-version.js'
 export { writeDocEnvelope } from './doc-envelope.js'
 export type { DocEnvelopeSource } from './doc-envelope.js'

package/src/server/spec-version.ts

@@ -0,0 +1,27 @@
+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/server/types.ts

@@ -250,6 +250,21 @@ export interface DocRegistryOutputOptions<TEnvelope = DocEnvelope> {
 }
 
 export interface DocEnvelope {
+  /**
+   * Wire-format version of this envelope. Every envelope produced by
+   * `DocRegistry.toJSON()` / `builder.toDocEnvelope()` carries it. Downstream
+   * consumers branch on it to pick a parser; bumped only on envelope format
+   * changes, NOT on package releases. Optional on the type so hand-built
+   * envelopes and pre-existing documents remain valid — an absent value MUST be
+   * treated as spec version 1. See {@link DOC_ENVELOPE_SPEC_VERSION}.
+   */
+  specVersion?: number
+  /**
+   * ts-procedures package version that produced this envelope (e.g. `"10.0.0"`).
+   * Informational only — do not use for parse-compatibility decisions (use
+   * {@link specVersion} for that). See {@link DOC_ENVELOPE_GENERATOR_VERSION}.
+   */
+  generatorVersion?: string
   basePath: string
   headers: HeaderDoc[]
   errors: ErrorDoc[]

package/src/version.ts

@@ -0,0 +1,11 @@
+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