ts-procedures 7.1.2 → 7.3.0

package/docs/astro-adapter.md

@@ -0,0 +1,227 @@
+# Astro adapter walkthrough
+
+This walkthrough builds an Astro app that serves ts-procedures handlers from a single catch-all endpoint.
+
+> **Requires SSR.** Your Astro project must use `output: 'server'` or `output: 'hybrid'` with `export const prerender = false` in the catch-all file. Static-prerender mode bypasses live endpoints.
+
+## Project shape
+
+```
+my-astro-app/
+├── astro.config.mjs
+├── package.json
+└── src/
+    ├── server/
+    │   ├── db.ts
+    │   ├── procedures/
+    │   │   └── users.ts
+    │   └── api.ts
+    └── pages/
+        └── api/
+            └── [...rest].ts
+```
+
+## 1. Define procedures
+
+```ts
+// src/server/procedures/users.ts
+import { Procedures } from 'ts-procedures'
+import type { APIConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+type UserContext = {
+  db: { findUser(id: string): Promise<{ id: string; name: string } | null> }
+  currentUser: { id: string } | null
+}
+
+export const usersAPI = Procedures<UserContext, APIConfig>()
+
+usersAPI.Create(
+  'GetUser',
+  {
+    path: '/users/:id',
+    method: 'get',
+    scope: 'users', // drives the generated client namespace: api.users.GetUser(...)
+    schema: {
+      input: { pathParams: Type.Object({ id: Type.String() }) },
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, { pathParams }) => {
+    const u = await ctx.db.findUser(pathParams.id)
+    if (!u) throw new Error('not found')
+    return u
+  }
+)
+```
+
+## 2. Build the Hono app once
+
+```ts
+// src/server/api.ts
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { getAstroContext } from 'ts-procedures/astro'
+import { usersAPI } from './procedures/users'
+import { db } from './db'
+
+export const apiApp = new HonoAPIAppBuilder()
+  .register(usersAPI, (c) => {
+    const astro = getAstroContext(c)
+    return {
+      db,
+      currentUser: astro.locals.user ?? null,
+    }
+  })
+  .build()
+```
+
+## 3. Mount the catch-all
+
+```ts
+// src/pages/api/[...rest].ts
+import { createAstroHandler } from 'ts-procedures/astro'
+import { apiApp } from '../../server/api'
+
+export const { ALL } = createAstroHandler({
+  apps: apiApp,
+  pathPrefix: '/api',
+})
+```
+
+That's it — `GET /api/users/123` runs through `usersAPI.GetUser`. The factory closure sees `astro.locals.user` populated from your Astro middleware.
+
+### Troubleshooting: routes 404
+
+The most common cause is a `pathPrefix` mismatch. The prefix MUST match the directory the catch-all file lives in:
+
+- `src/pages/api/[...rest].ts` → `pathPrefix: '/api'`
+- `src/pages/v1/[...rest].ts` → `pathPrefix: '/v1'`
+- `src/pages/[...rest].ts` (root) → omit `pathPrefix`
+
+If you mount at `/api` but forget `pathPrefix`, the inner Hono app sees the full path including `/api/...`, so routes registered as `/users/:id` won't match `/api/users/123`.
+
+## Where do `Astro.locals.user` come from?
+
+A typical pattern: an Astro middleware that reads a session cookie and sets `locals.user`:
+
+```ts
+// src/middleware.ts
+import { defineMiddleware } from 'astro:middleware'
+import { db } from './server/db'
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  const sessionId = context.cookies.get('sid')?.value
+  if (sessionId) {
+    context.locals.user = await db.findUserBySession(sessionId)
+  }
+  return next()
+})
+```
+
+The Astro runtime invokes this before your endpoint. The adapter then forwards the same `APIContext` (with `locals.user` populated) into the WeakMap, so `getAstroContext(c)` returns it inside the procedure factory.
+
+## Client codegen — where does it go?
+
+The adapter does NOT couple to `DocRegistry`. Wire codegen separately, against the same builders. The cleanest DX is a one-line `npm run gen:api` that emits an envelope from your procedures and runs the codegen CLI in a single step.
+
+### Emit an envelope from your procedures
+
+```ts
+// scripts/build-docs.ts
+import { writeFileSync } from 'node:fs'
+import { DocRegistry } from 'ts-procedures/http-docs'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { usersAPI } from '../src/server/procedures/users'
+
+// Use the SAME builders as your runtime app — types can't drift, because
+// both call sites import the exact same `Procedures<...>()` registration.
+const builder = new HonoAPIAppBuilder().register(usersAPI, () => ({} as never))
+builder.build()
+
+const envelope = new DocRegistry().from(builder).toEnvelope()
+writeFileSync('envelope.json', JSON.stringify(envelope, null, 2))
+```
+
+### Wire it as an npm script
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "gen:api": "tsx scripts/build-docs.ts && ts-procedures-codegen --file envelope.json --out src/generated/api --service-name Api"
+  }
+}
+```
+
+CLI defaults are already optimal: `--self-contained` (no runtime dependency on `ts-procedures/client`), `--namespace-types` (clean `Api.Users.GetUser.Params`), and `--jsdoc` are all on. The default `--service-name` is `Api`, which gives you `createApiClient`, `createApiBindings`, and an `ApiErrors` namespace.
+
+> **Tip:** add `src/generated/api` to `.gitignore` and run `npm run gen:api` in CI / pre-commit. The output is a pure function of `envelope.json`.
+
+## Use the typed client in pages
+
+Generated client is fully typed end-to-end — params, response, and (via `.safe()`) typed errors.
+
+```ts
+---
+// src/pages/users/[id].astro
+import { createApiClient } from '../../generated/api'
+
+const api = createApiClient({ basePath: '/api' })
+
+// Throwing form: typed Response, typed Params (with structured channels)
+const user = await api.users.GetUser({ pathParams: { id: Astro.params.id! } })
+
+// Result form: typed errors via the route's declared `errors`
+const result = await api.users.GetUser.safe({ pathParams: { id: Astro.params.id! } })
+if (!result.ok) {
+  if (result.kind === 'typed') {
+    // result.error is narrowed to the route's declared error union
+    return Astro.redirect('/login')
+  }
+  // result.kind === 'transport' — network/parse/timeout/abort
+  throw result.error
+}
+---
+<h1>{user.name}</h1>
+```
+
+For client-side islands (React/Svelte/Vue components), the same `createApiClient` works in the browser — pass an absolute `basePath` if calling cross-origin, or omit it to use relative paths.
+
+### Per-call options
+
+Every callable accepts a second arg with `signal`, `timeout`, `headers`, `basePath`, `meta`, and per-call hooks:
+
+```ts
+const controller = new AbortController()
+await api.users.GetUser(
+  { pathParams: { id: '123' } },
+  { signal: controller.signal, timeout: 5000, headers: { 'X-Trace-Id': 'abc' } },
+)
+```
+
+`signal`s combine via `AbortSignal.any`; `timeout: 0` disables an inherited default. Set client-wide defaults via `createApiClient({ basePath, defaults: { timeout, headers, meta } })`.
+
+## Multi-app composition
+
+For larger projects with separate API/RPC/Stream surfaces, pass an array:
+
+```ts
+export const { ALL } = createAstroHandler({
+  apps: [apiApp, rpcApp, streamsApp],
+  pathPrefix: '/api',
+})
+```
+
+Order matters — first non-404 wins. See the module README for full dispatch rules.
+
+## DX summary — what makes this streamlined
+
+- **One file mounts everything.** `src/pages/api/[...rest].ts` is 4 lines; all routing happens inside the Hono app(s) you already built.
+- **Same builders power runtime AND codegen.** Your procedure registration is the single source of truth — types can't drift between server and client.
+- **`getAstroContext(c)` inside the factory closure.** Full `APIContext` (locals, cookies, redirect, params) is available without leaking Astro into your procedure handlers.
+- **Generated client is self-contained.** No runtime dependency on `ts-procedures/client`; ships as plain `.ts` files you can read and audit.
+- **`.safe()` on every callable.** Opt into `Result<T, TypedErrors>` per call site instead of try/catch — typed against the route's declared `errors`.
+- **Streams just work.** `HonoStreamAppBuilder` returns a `Response` with a `ReadableStream` body; Astro SSR forwards it verbatim, and client disconnects abort `ctx.signal`.
+- **Multi-app composition.** Mix API + RPC + Stream surfaces under one catch-all with first-match dispatch.
+
+The single biggest footgun: `pathPrefix` MUST match the catch-all directory. Mismatch produces silent 404s. See the troubleshooting section above.

package/docs/core.md

@@ -10,6 +10,7 @@ The `Procedures()` function creates a factory for defining procedures. It accept
 
 ```typescript
 Procedures<TContext, TExtendedConfig>(builder?: {
+    config?: { noRuntimeValidation?: true }
     onCreate?: (procedure: TProcedureRegistration<TContext, TExtendedConfig>) => void
 })
 ```
@@ -18,6 +19,7 @@ Procedures<TContext, TExtendedConfig>(builder?: {
 |-----------|----------------------------------------------------------------------------|
 | `TContext` | The base context type passed to all handlers as the first parameter        |
 | `TExtendedConfig` | Additional configuration properties for all procedures `config` properties |
+| `builder.config.noRuntimeValidation` | When `true`, every procedure created by this factory skips AJV validation of `schema.params` and `schema.input` at call time. Applies to both `Create` and `CreateStream`. Default: validation runs.   |
 | `builder.onCreate` | Optional callback invoked when each procedure is registered (runtime)      |
 
 ## Create Function
@@ -221,6 +223,22 @@ AJV is configured with:
 
 **Note:** `schema.params` is validated at runtime. `schema.returnType` is for documentation/introspection only.
 
+### Disabling Runtime Validation
+
+For trusted internal callers — for example, a back-of-house factory whose inputs are already type-checked at build time and whose handlers are never invoked from public HTTP — pass `config.noRuntimeValidation: true` when constructing the factory:
+
+```typescript
+const { Create, CreateStream } = Procedures({
+  config: { noRuntimeValidation: true },
+})
+```
+
+When set, every procedure registered by this factory skips AJV validation of `schema.params` and `schema.input` on every call. JSON Schema is still computed at registration time (so `info.schema` and codegen are unaffected) — only the per-call validator runs are bypassed.
+
+**Use sparingly.** Do not enable this for procedures that accept input from public clients, untyped JSON bodies, or anything you do not control end-to-end. The flag is shaped as `noRuntimeValidation?: true` (only `true` is accepted) to make the opt-out explicit at the call site.
+
+This is independent of the per-call `ctx.isPrevalidated` escape hatch used by HTTP builders that have already validated upstream — both paths short-circuit the same validators.
+
 ## Error Handling
 
 ### Using ctx.error()
@@ -419,6 +437,7 @@ describe('GetUser', () => {
 Creates a procedure factory.
 
 **Parameters:**
+- `builder.config.noRuntimeValidation` - When `true`, every procedure registered through this factory skips AJV validation of `schema.params` and `schema.input` at call time. Default: validation runs. See [Disabling Runtime Validation](#disabling-runtime-validation).
 - `builder.onCreate` - Callback invoked when each procedure is registered
 
 **Returns:**