ts-procedures 7.1.1 → 7.2.0

package/build/implementations/http/astro/rewrite-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rewrite-request.js","sourceRoot":"","sources":["../../../../src/implementations/http/astro/rewrite-request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgB,EAAE,MAA0B;IACtE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,CAAA;IACxC,MAAM,UAAU,GAAG,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAA;IACvD,IAAI,UAAU,KAAK,GAAG;QAAE,OAAO,OAAO,CAAA;IAEtC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAA;IAErD,2EAA2E;IAC3E,yEAAyE;IACzE,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IAChD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,KAAK,GAAG;QAAE,OAAO,IAAI,CAAA;IAE3D,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IAClD,GAAG,CAAC,QAAQ,GAAG,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAA;IAEvC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;AAClC,CAAC"}

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.