ts-procedures 8.6.0 → 9.1.0

package/package.json

@@ -1,22 +1,21 @@
 {
   "name": "ts-procedures",
-  "version": "8.6.0",
+  "version": "9.1.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",
   "type": "module",
   "sideEffects": false,
   "bin": {
-    "ts-procedures-setup": "./agent_config/bin/setup.mjs",
-    "ts-procedures-codegen": "./build/codegen/bin/cli.js"
+    "ts-procedures-setup": "agent_config/bin/setup.mjs",
+    "ts-procedures-codegen": "build/codegen/bin/cli.js"
   },
   "scripts": {
     "build": "tsc",
     "lint": "npx eslint src/ --quiet",
-    "check-docs": "bash scripts/check-docs-consistency.sh",
-    "prepublishOnly": "npm run lint && npm run build && npm run check-docs",
-    "postinstall": "node ./agent_config/bin/postinstall.mjs",
-    "test": "vitest run"
+    "test": "vitest run",
+    "check": "tsc --noEmit && vitest run && npm run lint",
+    "postinstall": "node ./agent_config/bin/postinstall.mjs"
   },
   "exports": {
     "./package.json": "./package.json",
@@ -25,23 +24,27 @@
       "import": "./build/exports.js"
     },
     "./astro": {
-      "types": "./build/implementations/http/astro/index.d.ts",
-      "import": "./build/implementations/http/astro/index.js"
+      "types": "./build/adapters/astro/index.d.ts",
+      "import": "./build/adapters/astro/index.js"
     },
     "./http": {
-      "types": "./build/implementations/types.d.ts"
+      "types": "./build/server/types.d.ts"
     },
     "./hono": {
-      "types": "./build/implementations/http/hono/index.d.ts",
-      "import": "./build/implementations/http/hono/index.js"
+      "types": "./build/adapters/hono/index.d.ts",
+      "import": "./build/adapters/hono/index.js"
+    },
+    "./server": {
+      "types": "./build/server/index.d.ts",
+      "import": "./build/server/index.js"
     },
     "./http-docs": {
-      "types": "./build/implementations/http/doc-registry.d.ts",
-      "import": "./build/implementations/http/doc-registry.js"
+      "types": "./build/server/doc-registry.d.ts",
+      "import": "./build/server/doc-registry.js"
     },
     "./http-errors": {
-      "types": "./build/implementations/http/error-taxonomy.d.ts",
-      "import": "./build/implementations/http/error-taxonomy.js"
+      "types": "./build/server/errors/taxonomy.d.ts",
+      "import": "./build/server/errors/taxonomy.js"
     },
     "./client": {
       "types": "./build/client/index.d.ts",
@@ -55,37 +58,11 @@
   "author": "coryrobinson42@gmail.com",
   "license": "MIT",
   "files": [
-    "assets",
     "build",
     "docs",
     "agent_config",
-    "src"
-  ],
-  "keywords": [
-    "typescript",
-    "rpc",
-    "type-safe",
-    "validation",
-    "procedures",
-    "api",
-    "framework",
-    "hono",
-    "http",
-    "rest",
-    "schema",
-    "json-schema",
-    "typebox",
-    "ajv",
-    "schema-validation",
-    "type-inference",
-    "codegen",
-    "code-generation",
-    "client-generation",
-    "streaming",
-    "sse",
-    "server-sent-events",
-    "endpoint",
-    "trpc"
+    "src",
+    "CHANGELOG.md"
   ],
   "optionalDependencies": {
     "ajsc": "^7.3.0",
@@ -96,18 +73,18 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "es-toolkit": "^1.44.0",
-    "suretype": "^3.3.1",
     "typebox": "^1.0.30"
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
     "astro": "^6.3.1",
     "eslint": "^9.17.0",
+    "globals": "^15.0.0",
     "hono": "^4.7.4",
-    "prettier": "^3.8.1",
-    "suretype": "^3.3.1",
-    "typebox": "^1.0.77",
+    "typescript": "^5.7.0",
     "typescript-eslint": "^8.53.0",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
     "vitest": "^4.0.18"
   }
 }

package/src/{implementations/http → adapters}/astro/index.test.ts

@@ -4,9 +4,9 @@ import { Type } from 'typebox'
 import { stripPrefix } from './rewrite-request.js'
 import { setAstroContext, getAstroContext } from './astro-context.js'
 import { createAstroHandler } from './create-handler.js'
-import { Procedures } from '../../../index.js'
+import { Procedures } from '../../core/procedures.js'
 import { HonoAppBuilder } from '../hono/index.js'
-import type { RPCConfig } from '../../types.js'
+import type { RPCConfig } from '../../server/types.js'
 
 // Minimal stand-in for Astro's APIContext for unit tests.
 function fakeApiContext(overrides: Record<string, unknown> = {}) {

package/src/adapters/hono/__fixtures__/parity-envelope.json

@@ -0,0 +1,389 @@
+{
+  "basePath": "/api",
+  "headers": [],
+  "errors": [
+    {
+      "name": "ProcedureValidationError",
+      "statusCode": 400,
+      "description": "Schema validation failed for the procedure input parameters.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "ProcedureValidationError"
+          },
+          "procedureName": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "errors": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "instancePath": {
+                  "type": "string"
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "required": [
+          "name",
+          "procedureName",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "ProcedureYieldValidationError",
+      "statusCode": 500,
+      "description": "Schema validation failed for a yielded value in a streaming procedure.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "ProcedureYieldValidationError"
+          },
+          "procedureName": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "errors": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "instancePath": {
+                  "type": "string"
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "required": [
+          "name",
+          "procedureName",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "ProcedureError",
+      "statusCode": 500,
+      "description": "An error thrown from within a procedure handler via ctx.error().",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "ProcedureError"
+          },
+          "procedureName": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "meta": {
+            "type": "object"
+          }
+        },
+        "required": [
+          "name",
+          "procedureName",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "ProcedureRegistrationError",
+      "statusCode": 500,
+      "description": "An invalid schema or configuration was detected at procedure registration time.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "ProcedureRegistrationError"
+          },
+          "procedureName": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "procedureName",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "Teapot",
+      "statusCode": 418,
+      "description": "Short and stout.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "Teapot"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "message"
+        ]
+      }
+    }
+  ],
+  "routes": [
+    {
+      "kind": "rpc",
+      "name": "GetUser",
+      "version": 1,
+      "scope": "users",
+      "path": "/api/users/get-user/1",
+      "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"
+      ]
+    },
+    {
+      "kind": "stream",
+      "name": "WatchUser",
+      "version": 2,
+      "scope": [
+        "users",
+        "live"
+      ],
+      "path": "/api/users/live/watch-user/2",
+      "methods": [
+        "post",
+        "get"
+      ],
+      "streamMode": "sse",
+      "jsonSchema": {
+        "params": {
+          "type": "object",
+          "required": [
+            "id"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            }
+          }
+        },
+        "yieldType": {
+          "type": "object",
+          "description": "SSE message envelope. The data field contains the procedure yield value.",
+          "required": [
+            "data",
+            "event",
+            "id"
+          ],
+          "properties": {
+            "data": {
+              "type": "object",
+              "required": [
+                "at"
+              ],
+              "properties": {
+                "at": {
+                  "type": "number"
+                }
+              }
+            },
+            "event": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "retry": {
+              "type": "number"
+            }
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "required": [
+            "total"
+          ],
+          "properties": {
+            "total": {
+              "type": "number"
+            }
+          }
+        }
+      }
+    },
+    {
+      "kind": "api",
+      "name": "UpdateUser",
+      "scope": "users",
+      "path": "/users/:id",
+      "method": "put",
+      "fullPath": "/api/users/:id",
+      "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"
+              }
+            }
+          }
+        },
+        "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"
+              }
+            }
+          }
+        }
+      },
+      "successStatus": 200,
+      "errors": [
+        "Teapot"
+      ]
+    },
+    {
+      "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"
+              }
+            }
+          }
+        },
+        "yield": {
+          "type": "object",
+          "required": [
+            "line"
+          ],
+          "properties": {
+            "line": {
+              "type": "string"
+            }
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "required": [
+            "lines"
+          ],
+          "properties": {
+            "lines": {
+              "type": "number"
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/src/adapters/hono/envelope-parity.test.ts

@@ -0,0 +1,126 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from '../../core/procedures.js'
+import { HonoAppBuilder, defineErrorTaxonomy } from './index.js'
+import type { RPCConfig } from '../../server/types.js'
+
+/**
+ * THE envelope contract test: the v9 builder must emit a DocEnvelope
+ * deep-equal to what v8.6.0 emitted for the same procedure set. The fixture
+ * was captured from the v8 build by `tools/capture-parity-envelope.mjs` —
+ * the procedure set below is that script's twin and MUST stay in sync with it.
+ *
+ * The envelope is codegen's input; if this test fails, generated client output
+ * WILL drift.
+ *
+ * ONE documented deviation from the raw v8 capture: v8's CreateHttpStream
+ * dropped the `yield` schema (and `res.headers`) from http-stream route docs —
+ * the registration stored `yieldType` while the doc builder read `yield`. v9
+ * fixes that, so the fixture's TailUser route was patched to include the
+ * `yield` schema the builder now (correctly) emits. Everything else is the
+ * untouched v8 capture.
+ */
+class TeapotError extends Error {}
+
+describe('DocEnvelope parity with v8.6.0', () => {
+  it('emits a deep-equal envelope for the reference procedure set', async () => {
+    const factory = Procedures<unknown, RPCConfig>()
+    const { Create, CreateStream, CreateHttp, CreateHttpStream } = factory
+
+    Create(
+      'GetUser',
+      {
+        scope: 'users',
+        version: 1,
+        errors: ['Teapot'],
+        description: 'Fetch one user',
+        schema: {
+          params: Type.Object({ id: Type.String() }),
+          returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+        },
+      },
+      async (_ctx, params) => ({ id: params.id, name: 'x' }),
+    )
+
+    CreateStream(
+      'WatchUser',
+      {
+        scope: ['users', 'live'],
+        version: 2,
+        schema: {
+          params: Type.Object({ id: Type.String() }),
+          yieldType: Type.Object({ at: Type.Number() }),
+          returnType: Type.Object({ total: Type.Number() }),
+        },
+      },
+      async function* () {
+        yield { at: 1 }
+        return { total: 1 }
+      },
+    )
+
+    CreateHttp(
+      'UpdateUser',
+      {
+        path: '/users/:id',
+        method: 'put',
+        successStatus: 200,
+        scope: 'users',
+        errors: ['Teapot'],
+        schema: {
+          req: {
+            pathParams: Type.Object({ id: Type.String() }),
+            query: Type.Object({ dryRun: Type.Optional(Type.Boolean()) }),
+            body: Type.Object({ name: Type.String() }),
+          },
+          res: {
+            body: Type.Object({ id: Type.String(), name: Type.String() }),
+            headers: Type.Object({ 'x-rev': Type.String() }),
+          },
+        },
+      },
+      async (_ctx, req) => ({
+        body: { id: req.pathParams.id, name: req.body.name },
+        headers: { 'x-rev': '1' },
+      }),
+    )
+
+    CreateHttpStream(
+      'TailUser',
+      {
+        path: '/users/:id/tail',
+        method: 'get',
+        scope: 'users',
+        schema: {
+          req: { pathParams: Type.Object({ id: Type.String() }) },
+          yield: Type.Object({ line: Type.String() }),
+          returnType: Type.Object({ lines: Type.Number() }),
+        },
+      },
+      async function* () {
+        yield { line: 'a' }
+        return { lines: 1 }
+      },
+    )
+
+    const taxonomy = defineErrorTaxonomy({
+      Teapot: { class: TeapotError, statusCode: 418, description: 'Short and stout.' },
+    })
+
+    const builder = new HonoAppBuilder({ pathPrefix: '/api', errors: taxonomy })
+    builder.register(factory, {})
+    builder.build()
+
+    const fixturePath = resolve(
+      dirname(fileURLToPath(import.meta.url)),
+      '__fixtures__/parity-envelope.json',
+    )
+    const expected = JSON.parse(await readFile(fixturePath, 'utf-8'))
+    const actual = JSON.parse(JSON.stringify(builder.toDocEnvelope()))
+
+    expect(actual).toEqual(expected)
+  })
+})

package/src/{implementations/http → adapters}/hono/handlers/http-stream.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'vitest'
 import { Hono } from 'hono'
 import { Type } from 'typebox'
-import { Procedures } from '../../../../index.js'
+import { Procedures } from '../../../core/procedures.js'
 import { installHttpStreamRoute } from './http-stream.js'
 
 function buildApp(setup: (P: ReturnType<typeof Procedures<{ uid: string }>>) => void, cfg: any = {}) {