ts-procedures 5.2.0 → 5.4.0

package/agent_config/claude-code/skills/guide/anti-patterns.md

@@ -0,0 +1,608 @@
+# ts-procedures Anti-Patterns
+
+These are common mistakes when using ts-procedures. Each anti-pattern includes a fix.
+
+---
+
+## 1. Throwing Raw Errors Instead of ctx.error()
+
+**Problem:** Throwing plain `Error` loses procedure metadata and makes error handling inconsistent.
+
+```typescript
+// BAD
+async (ctx, params) => {
+  if (!params.id) {
+    throw new Error('ID is required')
+  }
+}
+```
+
+**Fix:** Use `ctx.error()` for business logic errors.
+
+```typescript
+// GOOD
+async (ctx, params) => {
+  if (!params.id) {
+    throw ctx.error('ID is required', { code: 'MISSING_ID' })
+  }
+}
+```
+
+**Why:** `ctx.error()` creates a `ProcedureError` with `procedureName`, `meta`, `definedAt`, and enhanced stack trace. Raw errors get wrapped but lose the `meta` field and intentional error semantics.
+
+---
+
+## 2. Putting Validation Logic in the Handler
+
+**Problem:** Manually validating params when schema validation handles it automatically.
+
+```typescript
+// BAD
+Create('GetUser', {}, async (ctx, params) => {
+  if (!params.userId || typeof params.userId !== 'string') {
+    throw ctx.error('userId is required and must be a string')
+  }
+  return fetchUser(params.userId)
+})
+```
+
+**Fix:** Use `schema.params` — AJV validates automatically.
+
+```typescript
+// GOOD
+Create('GetUser', {
+  schema: {
+    params: Type.Object({ userId: Type.String() }),
+  },
+}, async (ctx, params) => {
+  // params.userId is guaranteed to be a string
+  return fetchUser(params.userId)
+})
+```
+
+**Why:** AJV provides detailed error messages, collects all errors (`allErrors: true`), coerces types, and removes additional properties. Manual validation duplicates this and is less thorough.
+
+---
+
+## 3. Expecting returnType to Be Validated at Runtime
+
+**Problem:** Assuming `schema.returnType` validates the handler's return value.
+
+```typescript
+// BAD — developer expects runtime validation of return value
+Create('GetUser', {
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, params) => {
+  return { id: 123, wrong: 'field' }  // No error thrown!
+})
+```
+
+**Fix:** Understand that `returnType` is documentation only. Rely on TypeScript for return type safety.
+
+```typescript
+// GOOD — TypeScript enforces return type via generic inference
+Create('GetUser', {
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, params): Promise<{ id: string; name: string }> => {
+  return { id: params.id, name: 'John' }  // TypeScript catches mismatches
+})
+```
+
+---
+
+## 4. Ignoring ctx.signal in Async Operations
+
+**Problem:** Not passing `signal` to downstream calls, preventing cancellation on client disconnect.
+
+```typescript
+// BAD
+async (ctx, params) => {
+  const data = await fetch('https://api.example.com/heavy-query')
+  const processed = await heavyComputation(data)
+  return processed
+}
+```
+
+**Fix:** Pass `ctx.signal` to all async calls.
+
+```typescript
+// GOOD
+async (ctx, params) => {
+  const data = await fetch('https://api.example.com/heavy-query', {
+    signal: ctx.signal,
+  })
+  const processed = await heavyComputation(data, { signal: ctx.signal })
+  return processed
+}
+```
+
+**Why:** When a client disconnects, the HTTP implementation aborts the signal. Without passing it, the handler continues wasting resources on a response nobody will receive.
+
+---
+
+## 5. Not Checking signal.aborted in Stream Loops
+
+**Problem:** Stream continues producing values after client disconnects.
+
+```typescript
+// BAD
+async function* (ctx, params) {
+  while (true) {
+    const data = await pollForData()
+    yield data
+    await delay(1000)
+  }
+}
+```
+
+**Fix:** Check `ctx.signal.aborted` in the loop condition.
+
+```typescript
+// GOOD
+async function* (ctx, params) {
+  while (!ctx.signal.aborted) {
+    const data = await pollForData({ signal: ctx.signal })
+    yield data
+    await delay(1000)
+  }
+}
+```
+
+---
+
+## 6. Duplicate Procedure Names
+
+**Problem:** Registering two procedures with the same name in the same factory.
+
+```typescript
+// BAD — throws ProcedureRegistrationError
+Create('GetUser', { scope: 'users', version: 1 }, handler1)
+Create('GetUser', { scope: 'admin', version: 1 }, handler2)
+```
+
+**Fix:** Use unique names. Use scope/version to differentiate routes.
+
+```typescript
+// GOOD
+Create('GetUser', { scope: 'users', version: 1 }, handler1)
+Create('GetUserAdmin', { scope: 'admin', version: 1 }, handler2)
+
+// Or use separate factories
+const UserRPC = Procedures<UserContext, RPCConfig>()
+const AdminRPC = Procedures<AdminContext, RPCConfig>()
+UserRPC.Create('GetUser', { scope: 'users', version: 1 }, handler1)
+AdminRPC.Create('GetUser', { scope: 'admin', version: 1 }, handler2)
+```
+
+---
+
+## 7. Using validateYields Without yieldType Schema
+
+**Problem:** Setting `validateYields: true` without providing a `yieldType` schema.
+
+```typescript
+// BAD — validateYields has no effect without yieldType schema
+CreateStream('Stream', {
+  validateYields: true,
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+  },
+}, async function* (ctx, params) {
+  yield { anything: 'goes' }
+})
+```
+
+**Fix:** Provide `yieldType` schema when using `validateYields`.
+
+```typescript
+// GOOD
+CreateStream('Stream', {
+  validateYields: true,
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+    yieldType: Type.Object({ id: Type.String(), value: Type.Number() }),
+  },
+}, async function* (ctx, params) {
+  yield { id: '1', value: 42 }
+})
+```
+
+---
+
+## 8. Swallowing Errors in Handlers
+
+**Problem:** Catching errors without re-throwing, hiding failures from the caller.
+
+```typescript
+// BAD
+async (ctx, params) => {
+  try {
+    return await riskyOperation(params)
+  } catch (err) {
+    console.error('Operation failed:', err)
+    return null  // Caller thinks it succeeded
+  }
+}
+```
+
+**Fix:** Let errors propagate. The framework wraps them in `ProcedureError` with enhanced stack traces.
+
+```typescript
+// GOOD — let the framework handle it
+async (ctx, params) => {
+  return await riskyOperation(params)
+}
+
+// Or rethrow as a business error with context
+async (ctx, params) => {
+  try {
+    return await riskyOperation(params)
+  } catch (err) {
+    throw ctx.error('Operation failed', { originalError: err.message, params })
+  }
+}
+```
+
+---
+
+## 9. Not Using AJV's coerceTypes Behavior
+
+**Problem:** Treating query string values as strings when AJV will coerce them.
+
+```typescript
+// BAD — unnecessary manual parsing
+async (ctx, params) => {
+  const page = parseInt(params.page, 10)
+  const limit = parseInt(params.limit, 10)
+  return fetchPage(page, limit)
+}
+```
+
+**Fix:** Let AJV coerce types via the schema.
+
+```typescript
+// GOOD — AJV coerces "5" → 5 automatically
+Create('ListUsers', {
+  schema: {
+    params: Type.Object({
+      page: Type.Number(),
+      limit: Type.Number(),
+    }),
+  },
+}, async (ctx, params) => {
+  // params.page and params.limit are already numbers
+  return fetchPage(params.page, params.limit)
+})
+```
+
+**Why:** AJV is configured with `coerceTypes: true`. String `"5"` from query params becomes number `5` after validation.
+
+---
+
+## 10. Forgetting removeAdditional Strips Extra Fields
+
+**Problem:** Passing extra fields in params and expecting them to survive validation.
+
+```typescript
+// BAD — extra fields silently removed
+const result = await GetUser(ctx, {
+  userId: '123',
+  debug: true,        // Stripped by AJV
+  extraData: 'value', // Stripped by AJV
+})
+```
+
+**Fix:** Only pass fields defined in the schema. If you need additional fields, add them to the schema.
+
+```typescript
+// GOOD
+Create('GetUser', {
+  schema: {
+    params: Type.Object({
+      userId: Type.String(),
+      debug: Type.Optional(Type.Boolean()),  // Include in schema if needed
+    }),
+  },
+}, handler)
+```
+
+**Why:** AJV is configured with `removeAdditional: true`. Any property not defined in the schema is silently removed before the handler receives params.
+
+---
+
+## 11. Creating Factory Without Context Type When Using HTTP Builders
+
+**Problem:** Using `Procedures()` without a context type, then registering with an HTTP builder that injects context.
+
+```typescript
+// BAD — handler ctx has no type information
+const { Create } = Procedures()
+
+Create('GetUser', {}, async (ctx, params) => {
+  ctx.userId  // Type error: Property 'userId' does not exist
+})
+```
+
+**Fix:** Always specify the context type.
+
+```typescript
+// GOOD
+const { Create } = Procedures<{ userId: string }>()
+
+Create('GetUser', {}, async (ctx, params) => {
+  ctx.userId  // Typed correctly
+})
+```
+
+---
+
+## 12. Registering Standard Procedures with HonoStreamAppBuilder
+
+**Problem:** Using `Create` procedures with `HonoStreamAppBuilder` — it only handles `CreateStream` procedures.
+
+```typescript
+// BAD — Create procedures are silently ignored
+const { Create, CreateStream } = Procedures<AppContext, RPCConfig>()
+Create('GetUser', { scope: 'users', version: 1 }, handler)
+CreateStream('StreamEvents', { scope: 'events', version: 1 }, streamHandler)
+
+new HonoStreamAppBuilder()
+  .register(factory, ctx)  // Only StreamEvents is registered
+  .build()
+```
+
+**Fix:** Use `HonoRPCAppBuilder` or `ExpressRPCAppBuilder` for standard procedures. Use `HonoStreamAppBuilder` only for stream procedures.
+
+```typescript
+// GOOD
+const rpcApp = new HonoRPCAppBuilder().register(RPC, ctx).build()
+const streamApp = new HonoStreamAppBuilder().register(StreamRPC, ctx).build()
+```
+
+---
+
+## 13. Missing Schema at Registration Time
+
+**Problem:** Providing malformed or incompatible schema objects.
+
+```typescript
+// BAD — plain objects are not valid schemas
+Create('GetUser', {
+  schema: {
+    params: { type: 'object', properties: { id: { type: 'string' } } },
+  },
+}, handler)
+```
+
+**Fix:** Use TypeBox schema builders.
+
+```typescript
+// GOOD — TypeBox
+Create('GetUser', {
+  schema: { params: Type.Object({ id: Type.String() }) },
+}, handler)
+```
+
+**Why:** ts-procedures detects schema type via TypeBox's `~kind` symbol. Plain JSON Schema objects are not recognized and will throw `ProcedureRegistrationError`.
+
+---
+
+## 14. Not Handling Pre-Stream vs Mid-Stream Errors Differently
+
+**Problem:** Using a single error handler for both validation errors (before streaming) and runtime errors (during streaming).
+
+```typescript
+// BAD — onError doesn't apply to streaming
+new HonoStreamAppBuilder({
+  onError: (proc, c, err) => { /* This doesn't exist */ },
+})
+```
+
+**Fix:** Use `onPreStreamError` for validation errors and `onMidStreamError` for runtime errors.
+
+```typescript
+// GOOD
+new HonoStreamAppBuilder({
+  onPreStreamError: (proc, c, error) => {
+    // Validation/context error — return normal HTTP response
+    return c.json({ error: error.message }, 400)
+  },
+  onMidStreamError: (proc, c, error) => {
+    // Runtime error during streaming — yield error event, then close
+    return { data: { error: error.message }, closeStream: true }
+  },
+})
+```
+
+---
+
+## 15. Not Using extendProcedureDoc for Documentation
+
+**Problem:** Manually building documentation from procedure metadata instead of using the built-in extension point.
+
+```typescript
+// BAD — manual doc building, fragile and incomplete
+const docs = getProcedures().map(p => ({
+  name: p.name,
+  path: `/${p.config.scope}/${p.name}/${p.config.version}`,
+}))
+```
+
+**Fix:** Use `extendProcedureDoc` in the HTTP builder registration.
+
+```typescript
+// GOOD — base doc auto-generated with correct paths and schemas
+builder.register(factory, context, ({ base, procedure }) => ({
+  summary: procedure.config.description,
+  tags: [base.scope],
+}))
+
+// Access via builder.docs
+console.log(builder.docs)
+```
+
+**Why:** The builder generates correct kebab-case paths, includes JSON schemas for body/response, and merges your extensions. Manual building duplicates this logic and easily drifts.
+
+---
+
+## 16. Using Async Context Factory Without Error Handling
+
+**Problem:** Async context factories that throw unhandled errors, crashing the request.
+
+```typescript
+// BAD — if authenticate() throws, request crashes
+builder.register(factory, async (req) => {
+  const user = await authenticate(req.headers.authorization)
+  return { userId: user.id }
+})
+```
+
+**Fix:** Use the builder's `onError` callback to handle context resolution failures gracefully.
+
+```typescript
+// GOOD
+new ExpressRPCAppBuilder({
+  onError: (procedure, req, res, error) => {
+    if (error.message.includes('Unauthorized')) {
+      res.status(401).json({ error: 'Unauthorized' })
+    } else {
+      res.status(500).json({ error: 'Internal server error' })
+    }
+  },
+})
+```
+
+---
+
+## 17. Using Both schema.params and schema.input
+
+**Problem:** Defining both `schema.params` and `schema.input` on the same procedure.
+
+```typescript
+// BAD — throws ProcedureRegistrationError at registration
+Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+    },
+  },
+}, handler)
+```
+
+**Fix:** Choose one. Use `schema.params` for flat RPC-style input, `schema.input` for structured multi-channel input.
+
+```typescript
+// GOOD — schema.input for REST-style with per-channel validation
+Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+    },
+  },
+}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
+
+// GOOD — schema.params for simple RPC-style
+Create('GetUser', {
+  scope: 'users', version: 1,
+  schema: { params: Type.Object({ id: Type.String() }) },
+}, async (ctx, params) => fetchUser(params.id))
+```
+
+**Why:** `schema.params` and `schema.input` are mutually exclusive by design. They represent different input paradigms — flat (RPC) vs structured (HTTP API).
+
+---
+
+## 18. Mismatched Path Param Names in schema.input
+
+**Problem:** Path template param names don't match `schema.input.pathParams` property names.
+
+```typescript
+// BAD — path has :id but schema declares userId — throws at build time
+Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    input: {
+      pathParams: Type.Object({ userId: Type.String() }), // Wrong name!
+    },
+  },
+}, handler)
+```
+
+**Fix:** Ensure path param names match schema property names exactly.
+
+```typescript
+// GOOD
+Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }), // Matches :id
+    },
+  },
+}, handler)
+```
+
+**Why:** `HonoAPIAppBuilder` validates at build time that `:param` names in the path match schema properties. A mismatch would cause runtime validation failures with confusing error messages.
+
+---
+
+## 19. Forgetting build() is Async on HonoAPIAppBuilder
+
+**Problem:** Not awaiting `build()` on `HonoAPIAppBuilder`.
+
+```typescript
+// BAD — build() returns Promise<Hono>, not Hono
+const app = new HonoAPIAppBuilder()
+  .register(API, ctx)
+  .build() // This is a Promise!
+```
+
+**Fix:** Await the build call.
+
+```typescript
+// GOOD
+const app = await new HonoAPIAppBuilder()
+  .register(API, ctx)
+  .build()
+```
+
+**Why:** `HonoAPIAppBuilder.build()` is async because it resolves the query parser (lazy-loads `qs` optional peer dependency) once at build time for synchronous per-request usage.
+
+---
+
+## Summary Table
+
+| # | Anti-Pattern | Risk | Severity |
+|---|-------------|------|----------|
+| 1 | Raw Error instead of ctx.error() | Lost metadata, inconsistent handling | CRITICAL |
+| 2 | Manual validation in handler | Duplicated logic, less thorough | WARNING |
+| 3 | Expecting returnType validation | Silent data contract violations | CRITICAL |
+| 4 | Ignoring ctx.signal | Resource waste on cancelled requests | WARNING |
+| 5 | No signal check in stream loops | Infinite resource consumption | CRITICAL |
+| 6 | Duplicate procedure names | ProcedureRegistrationError at startup | CRITICAL |
+| 7 | validateYields without yieldType | Silent no-op, false confidence | WARNING |
+| 8 | Swallowing errors | Hidden failures, debugging difficulty | CRITICAL |
+| 9 | Manual type coercion | Unnecessary code, coercion mismatch | SUGGESTION |
+| 10 | Expecting extra fields to survive | Silent data loss | WARNING |
+| 11 | Missing context type | No type safety in handlers | WARNING |
+| 12 | Create with HonoStreamAppBuilder | Procedures silently ignored | CRITICAL |
+| 13 | Plain JSON Schema objects instead of TypeBox | ProcedureRegistrationError | CRITICAL |
+| 14 | Wrong error handler for streams | Unhandled errors or wrong response format | WARNING |
+| 15 | Manual doc building | Fragile, incomplete documentation | SUGGESTION |
+| 16 | Unhandled async context factory | Request crashes | WARNING |
+| 17 | Both schema.params and schema.input | ProcedureRegistrationError at startup | CRITICAL |
+| 18 | Mismatched path param names | Build-time error or confusing validation failures | CRITICAL |
+| 19 | Not awaiting HonoAPIAppBuilder.build() | Using unresolved Promise as app | CRITICAL |