ts-typed-api 0.2.21 → 0.2.23

package/.kilo/plans/1779977869703-shiny-squid.md

@@ -0,0 +1,49 @@
+# Fix PATCH/DELETE Body Parsing + Add Tests
+
+## Problem
+In `src/handler.ts:400`, the Express handler only validates body for `POST` and `PUT`. `PATCH` and `DELETE` bypass Zod validation entirely, receiving raw `expressReq.body`. This is inconsistent with:
+- The Hono handler (`src/hono-cloudflare-workers.ts:377`) which validates all four methods
+- The type system (`MethodsWithBody = 'POST' | 'PUT' | 'DELETE' | 'PATCH'` in `definition.ts`)
+
+## Plan
+
+### 1. Fix `src/handler.ts` — line 400
+Change:
+```typescript
+const parsedBody = (method === 'POST' || method === 'PUT') && ('body' in routeDefinition && routeDefinition.body)
+```
+To:
+```typescript
+const parsedBody = (method === 'POST' || method === 'PUT' || method === 'DELETE' || method === 'PATCH') && ('body' in routeDefinition && routeDefinition.body)
+```
+
+### 2. Add PATCH endpoint to test setup (`tests/setup.ts`)
+Add to `SimplePublicApiDefinition` (in `examples/simple/definitions.ts`) a new `patch` route with a body schema that validates fields:
+```typescript
+patch: {
+    method: 'PATCH',
+    path: '/patch',
+    body: z.object({
+        name: z.string().min(1),
+        value: z.number().min(0)
+    }),
+    responses: CreateResponses({
+        200: z.object({ message: z.string(), name: z.string(), value: z.number() })
+    })
+}
+```
+
+Add a corresponding handler in `simplePublicHandlers` in `tests/setup.ts` that returns the parsed body data.
+
+### 3. Add tests (`tests/simple-api.test.ts`)
+Add a `describe('PATCH body validation')` block inside the existing `describe('Public API')`:
+- **Success case**: Send valid body, expect 200 with echoed data
+- **Validation failure case**: Send body with missing fields or wrong types, expect 422 with error details
+- **Extra property rejection**: Send body with an unknown property, expect 422 (strict mode)
+
+These tests will run against both Express and Hono via the existing `describe.each(['Express', SIMPLE_PORT], ['Hono', HONO_PORT])`.
+
+### 4. Verify
+Run `npm test` to confirm:
+- Existing tests still pass
+- New PATCH validation tests pass for both Express and Hono

package/dist/definition.d.ts

@@ -1,4 +1,5 @@
 import { z, ZodTypeAny } from 'zod';
+import express from 'express';
 export declare class TsTypeMarker<T> {
     readonly _isTsTypeMarker = true;
     readonly _type: T;
@@ -17,6 +18,7 @@ declare const unifiedErrorSchema: z.ZodNullable<z.ZodArray<z.ZodObject<{
     message: z.ZodString;
 }, z.core.$strip>>>;
 export type UnifiedError = z.infer<typeof unifiedErrorSchema>;
+export type ErrorHandler = (error: unknown, routeDefinition: RouteSchema, method: string, path: string, expressRes: express.Response) => boolean | void;
 declare const errorUnifiedResponseSchema: z.ZodObject<{
     error: z.ZodNullable<z.ZodArray<z.ZodObject<{
         field: z.ZodString;

package/dist/handler.d.ts

@@ -1,4 +1,4 @@
-import { ApiDefinitionSchema } from "./definition";
+import { ApiDefinitionSchema, ErrorHandler } from "./definition";
 import { createRouteHandler } from "./router";
 import { MiddlewareResponse } from "./object-handlers";
 import express from "express";
@@ -15,4 +15,4 @@ export type EndpointMiddleware<TDef extends ApiDefinitionSchema = ApiDefinitionS
 }[keyof TDef['endpoints']]) => void | Promise<void>;
 export declare function registerRouteHandlers<TDef extends ApiDefinitionSchema>(app: express.Express, apiDefinition: TDef, // Pass the actual API definition object
 routeHandlers: Array<SpecificRouteHandler<TDef>>, // Use the generic handler type
-middlewares?: EndpointMiddleware<TDef>[]): void;
+middlewares?: EndpointMiddleware<TDef>[], errorHandler?: ErrorHandler): void;

package/dist/handler.js

@@ -306,7 +306,7 @@ function createFileUploadMiddleware(config) {
 // Register route handlers with Express, now generic over TDef
 function registerRouteHandlers(app, apiDefinition, // Pass the actual API definition object
 routeHandlers, // Use the generic handler type
-middlewares) {
+middlewares, errorHandler) {
     routeHandlers.forEach((specificHandlerIterationItem) => {
         const { domain, routeKey, handler } = specificHandlerIterationItem; // Use 'as any' for simplicity in destructuring union
         const currentDomain = domain;
@@ -339,7 +339,7 @@ middlewares) {
                 const parsedQuery = ('query' in routeDefinition && routeDefinition.query)
                     ? routeDefinition.query.parse(preprocessedQuery)
                     : preprocessedQuery;
-                const parsedBody = (method === 'POST' || method === 'PUT') && ('body' in routeDefinition && routeDefinition.body)
+                const parsedBody = (method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE') && ('body' in routeDefinition && routeDefinition.body)
                     ? routeDefinition.body.parse(expressReq.body)
                     : expressReq.body;
                 // Construct TypedRequest using TDef, currentDomain, currentRouteKey
@@ -465,6 +465,14 @@ middlewares) {
                 await specificHandlerFn(finalTypedReq, typedExpressRes);
             }
             catch (error) {
+                // Check if custom error handler is provided
+                if (errorHandler) {
+                    const handled = errorHandler(error, routeDefinition, method, path, expressRes);
+                    if (handled) {
+                        return; // Error was handled by custom handler
+                    }
+                }
+                // Default error handling
                 if (error instanceof zod_1.z.ZodError) {
                     const mappedErrors = error.issues.map(err => {
                         let errorType = 'general';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { ApiClient, FetchHttpClientAdapter } from './client';
 export { generateOpenApiSpec } from './openapi';
 export { generateOpenApiSpec as generateOpenApiSpec2 } from './openapi-self';
-export { CreateApiDefinition, CreateResponses, ApiDefinitionSchema } from './definition';
+export { CreateApiDefinition, CreateResponses, ApiDefinitionSchema, ErrorHandler } from './definition';
 export { RegisterHandlers, EndpointMiddleware, UniversalEndpointMiddleware, SimpleMiddleware, EndpointInfo, MiddlewareResponse } from './object-handlers';
 export { File as UploadedFile } from './router';
 export { z as ZodSchema } from 'zod';

package/dist/object-handlers.d.ts

@@ -31,6 +31,6 @@ export type ObjectHandlers<TDef extends ApiDefinitionSchema, Ctx extends Record<
         [TRouteKey in keyof TDef['endpoints'][TDomain]]: HandlerFunction<TDef, TDomain, TRouteKey, Ctx>;
     };
 };
-export declare function RegisterHandlers<TDef extends ApiDefinitionSchema, Ctx extends Record<string, any> = Record<string, any>>(app: express.Express, apiDefinition: TDef, objectHandlers: ObjectHandlers<TDef, Ctx>, middlewares?: AnyMiddleware<TDef>[]): void;
+export declare function RegisterHandlers<TDef extends ApiDefinitionSchema, Ctx extends Record<string, any> = Record<string, any>>(app: express.Express, apiDefinition: TDef, objectHandlers: ObjectHandlers<TDef, Ctx>, middlewares?: AnyMiddleware<TDef>[], errorHandler?: import('./definition').ErrorHandler): void;
 export declare function makeObjectHandlerRegistrar<TDef extends ApiDefinitionSchema>(apiDefinition: TDef): (app: express.Express, objectHandlers: ObjectHandlers<TDef>, middlewares?: EndpointMiddleware<TDef>[]) => void;
 export {};

package/dist/object-handlers.js

@@ -27,7 +27,7 @@ function transformObjectHandlersToArray(objectHandlers) {
     return handlerArray;
 }
 // Main utility function that registers object-based handlers
-function RegisterHandlers(app, apiDefinition, objectHandlers, middlewares) {
+function RegisterHandlers(app, apiDefinition, objectHandlers, middlewares, errorHandler) {
     const handlerArray = transformObjectHandlersToArray(objectHandlers);
     // Convert AnyMiddleware to EndpointMiddleware by checking function arity
     const endpointMiddlewares = middlewares?.map(middleware => {
@@ -43,7 +43,7 @@ function RegisterHandlers(app, apiDefinition, objectHandlers, middlewares) {
             });
         }
     }) || [];
-    (0, handler_1.registerRouteHandlers)(app, apiDefinition, handlerArray, endpointMiddlewares);
+    (0, handler_1.registerRouteHandlers)(app, apiDefinition, handlerArray, endpointMiddlewares, errorHandler);
 }
 // Factory function to create a typed handler registrar for a specific API definition
 function makeObjectHandlerRegistrar(apiDefinition) {

package/examples/simple/definitions.ts

@@ -77,6 +77,22 @@ export const PublicApiDefinition = CreateApiDefinition({
                     200: z.string() // Raw SSE data
                 })
             },
+            patchResource: {
+                method: 'PATCH',
+                path: '/patch-resource',
+                description: 'PATCH endpoint to test body validation for PATCH requests',
+                body: z.object({
+                    name: z.string().min(1, 'Name is required'),
+                    value: z.number().int().min(0, 'Value must be non-negative')
+                }),
+                responses: CreateResponses({
+                    200: z.object({
+                        message: z.string(),
+                        name: z.string(),
+                        value: z.number()
+                    })
+                })
+            },
             disconnectTest: {
                 method: 'GET',
                 path: '/disconnect-test',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-typed-api",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "A lightweight, type-safe RPC library for TypeScript with Zod validation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/definition.ts

@@ -1,4 +1,5 @@
 import { z, ZodTypeAny, ZodType } from 'zod';
+import express from 'express';
 
 // Marker class for raw TypeScript types
 export class TsTypeMarker<T> {
@@ -30,6 +31,15 @@ const errorDetailSchema = z.object({
 const unifiedErrorSchema = z.array(errorDetailSchema).nullable(); // Nullable if no errors
 export type UnifiedError = z.infer<typeof unifiedErrorSchema>;
 
+// Type for custom error handler function
+export type ErrorHandler = (
+    error: unknown,
+    routeDefinition: RouteSchema,
+    method: string,
+    path: string,
+    expressRes: express.Response
+) => boolean | void; // Return true if handled, void/null to use default
+
 // Helper function to create the success-specific unified response schema
 // This wraps the original data schema with a 'data' field and sets 'error' to null.
 function createSuccessUnifiedResponseSchema<TData extends ZodTypeAny>(dataSchema: TData) {

package/src/handler.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ApiDefinitionSchema, RouteSchema, UnifiedError, FileUploadConfig } from "./definition";
+import { ApiDefinitionSchema, RouteSchema, UnifiedError, FileUploadConfig, ErrorHandler } from "./definition";
 import { createRouteHandler, TypedRequest, TypedResponse } from "./router";
 import { MiddlewareResponse } from "./object-handlers";
 import express from "express";
@@ -350,7 +350,8 @@ export function registerRouteHandlers<TDef extends ApiDefinitionSchema>(
     app: express.Express,
     apiDefinition: TDef, // Pass the actual API definition object
     routeHandlers: Array<SpecificRouteHandler<TDef>>, // Use the generic handler type
-    middlewares?: EndpointMiddleware<TDef>[]
+    middlewares?: EndpointMiddleware<TDef>[],
+    errorHandler?: ErrorHandler
 ) {
     routeHandlers.forEach((specificHandlerIterationItem) => {
         const { domain, routeKey, handler } = specificHandlerIterationItem as any; // Use 'as any' for simplicity in destructuring union
@@ -396,7 +397,7 @@ export function registerRouteHandlers<TDef extends ApiDefinitionSchema>(
                     ? (routeDefinition.query as z.ZodTypeAny).parse(preprocessedQuery)
                     : preprocessedQuery;
 
-                const parsedBody = (method === 'POST' || method === 'PUT') && ('body' in routeDefinition && routeDefinition.body)
+                const parsedBody = (method === 'POST' || method === 'PUT' || method === 'PATCH' || method === 'DELETE') && ('body' in routeDefinition && routeDefinition.body)
                     ? (routeDefinition.body as z.ZodTypeAny).parse(expressReq.body)
                     : expressReq.body;
 
@@ -541,6 +542,15 @@ export function registerRouteHandlers<TDef extends ApiDefinitionSchema>(
                 await specificHandlerFn(finalTypedReq, typedExpressRes);
 
             } catch (error) {
+                // Check if custom error handler is provided
+                if (errorHandler) {
+                    const handled = errorHandler(error, routeDefinition, method, path, expressRes);
+                    if (handled) {
+                        return; // Error was handled by custom handler
+                    }
+                }
+
+                // Default error handling
                 if (error instanceof z.ZodError) {
                     const mappedErrors: UnifiedError = error.issues.map(err => {
                         let errorType: 'param' | 'query' | 'body' | 'general' = 'general';

package/src/index.ts

@@ -1,7 +1,7 @@
 export { ApiClient, FetchHttpClientAdapter } from './client';
 export { generateOpenApiSpec } from './openapi'
 export { generateOpenApiSpec as generateOpenApiSpec2 } from './openapi-self'
-export { CreateApiDefinition, CreateResponses, ApiDefinitionSchema } from './definition';
+export { CreateApiDefinition, CreateResponses, ApiDefinitionSchema, ErrorHandler } from './definition';
 export { RegisterHandlers, EndpointMiddleware, UniversalEndpointMiddleware, SimpleMiddleware, EndpointInfo, MiddlewareResponse } from './object-handlers';
 export { File as UploadedFile } from './router';
 export { z as ZodSchema } from 'zod';

package/src/object-handlers.ts

@@ -125,7 +125,8 @@ export function RegisterHandlers<
     app: express.Express,
     apiDefinition: TDef,
     objectHandlers: ObjectHandlers<TDef, Ctx>,
-    middlewares?: AnyMiddleware<TDef>[]
+    middlewares?: AnyMiddleware<TDef>[],
+    errorHandler?: import('./definition').ErrorHandler
 ): void {
     const handlerArray = transformObjectHandlersToArray(objectHandlers);
 
@@ -143,7 +144,7 @@ export function RegisterHandlers<
         }
     }) || [];
 
-    registerRouteHandlers(app, apiDefinition, handlerArray, endpointMiddlewares);
+    registerRouteHandlers(app, apiDefinition, handlerArray, endpointMiddlewares, errorHandler);
 }
 
 // Factory function to create a typed handler registrar for a specific API definition

package/tests/error-handler.test.ts

@@ -0,0 +1,146 @@
+import { describe, test, expect, beforeAll, afterAll } from '@jest/globals';
+import express from 'express';
+import { Server } from 'http';
+import { RegisterHandlers, CreateApiDefinition, CreateResponses, ErrorHandler } from '../src';
+import { z } from 'zod';
+
+const ErrorHandlerTestApiDefinition = CreateApiDefinition({
+    prefix: '/api',
+    endpoints: {
+        test: {
+            success: {
+                method: 'GET',
+                path: '/success',
+                responses: CreateResponses({
+                    200: z.object({ message: z.string() })
+                })
+            },
+            validationError: {
+                method: 'POST',
+                path: '/validation-error',
+                body: z.object({
+                    name: z.string().min(3, 'Name must be at least 3 characters'),
+                    email: z.string().email('Invalid email format')
+                }),
+                responses: CreateResponses({
+                    200: z.object({ message: z.string() })
+                })
+            },
+            customError: {
+                method: 'GET',
+                path: '/custom-error',
+                responses: CreateResponses({
+                    200: z.object({ message: z.string() })
+                })
+            }
+        }
+    }
+});
+
+const testHandlers = {
+    test: {
+        success: async (req: any, res: any) => {
+            res.respond(200, { message: 'success' });
+        },
+        validationError: async () => {
+            // This will cause a Zod validation error - validation happens before handler
+            throw new Error('Should not reach handler');
+        },
+        customError: async (req: any, res: any) => {
+            // Throw a custom error to test error handler
+            throw new Error('Custom application error');
+        }
+    }
+};
+
+describe('Error Handler Tests', () => {
+    let server: Server;
+    let port: number;
+
+    beforeAll(async () => {
+        port = 3009; // Use a different port
+        const app = express();
+        app.use(express.json());
+
+        // Custom error handler
+        const customErrorHandler: ErrorHandler = (error, routeDefinition, method, path, expressRes) => {
+            if (error instanceof z.ZodError) {
+                // Custom Zod error handling
+                const customErrors = error.issues.map(issue => ({
+                    field: issue.path.join('.'),
+                    message: `Custom: ${issue.message}`,
+                    type: issue.path[0] === 'body' ? 'body' : issue.path[0] === 'query' ? 'query' : 'param'
+                }));
+
+                expressRes.status(422).json({
+                    data: null,
+                    error: customErrors,
+                    customHandled: true
+                });
+                return true; // Handled
+            } else if (error instanceof Error && error.message === 'Custom application error') {
+                // Custom application error handling
+                expressRes.status(400).json({
+                    data: null,
+                    error: [{ field: 'general', message: 'Custom error message', type: 'general' }],
+                    customHandled: true
+                });
+                return true; // Handled
+            }
+
+            return false; // Not handled, use default
+        };
+
+        RegisterHandlers(app, ErrorHandlerTestApiDefinition, testHandlers, undefined, customErrorHandler);
+
+        server = app.listen(port);
+    });
+
+    afterAll(async () => {
+        if (server) {
+            server.close();
+        }
+    });
+
+    test('should handle success response normally', async () => {
+        const response = await fetch(`http://localhost:${port}/api/success`);
+        expect(response.status).toBe(200);
+        const data = await response.json();
+        expect(data).toEqual({
+            data: { message: 'success' }
+        });
+    });
+
+    test('should use custom error handler for Zod validation errors', async () => {
+        const response = await fetch(`http://localhost:${port}/api/validation-error`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name: 'A', email: 'invalid-email' })
+        });
+        expect(response.status).toBe(422);
+        const data = await response.json() as any;
+        expect(data.customHandled).toBe(true);
+        expect(data.error).toBeDefined();
+        expect(data.error.length).toBeGreaterThan(0);
+        expect(data.error[0].message).toContain('Custom:');
+    });
+
+    test('should use custom error handler for application errors', async () => {
+        const response = await fetch(`http://localhost:${port}/api/custom-error`);
+        expect(response.status).toBe(400);
+        const data = await response.json() as any;
+        expect(data.customHandled).toBe(true);
+        expect(data.error).toEqual([{
+            field: 'general',
+            message: 'Custom error message',
+            type: 'general'
+        }]);
+    });
+
+    test('should fall back to default error handler for unhandled errors', async () => {
+        // Test with a route that doesn't exist to trigger a different error
+        const response = await fetch(`http://localhost:${port}/api/nonexistent`);
+        expect(response.status).toBe(404);
+        // This would be handled by Express default 404 handler, not our error handler
+    });
+});

package/tests/setup.ts

@@ -69,7 +69,11 @@ const simplePublicHandlers = {
                 message: disconnected ? 'Client disconnected' : 'Operation completed',
                 disconnected
             });
-        }
+        },
+        patchResource: async (req: any, res: any) => {
+            const { name, value } = req.body;
+            res.respond(200, { message: 'Patched', name, value });
+        },
     },
     status: {
         probe1: async (req: any, res: any) => {

package/tests/simple-api.test.ts

@@ -328,6 +328,75 @@ describe.each([
         });
     });
 
+    describe('PATCH Body Validation', () => {
+        const client = new ApiClient(baseUrl, PublicApiDefinition);
+
+        test('should validate and parse PATCH body on success', async () => {
+            const result = await client.callApi('common', 'patchResource', {
+                body: { name: 'test-item', value: 42 }
+            }, {
+                200: ({ data }) => {
+                    expect(data.message).toBe('Patched');
+                    expect(data.name).toBe('test-item');
+                    expect(data.value).toBe(42);
+                    return data;
+                },
+                422: ({ error }) => {
+                    throw new Error(`Validation error: ${JSON.stringify(error)}`);
+                }
+            });
+
+            expect(result.message).toBe('Patched');
+            expect(result.name).toBe('test-item');
+            expect(result.value).toBe(42);
+        });
+
+        test('should reject PATCH body with missing required fields', async () => {
+            await expect(
+                client.callApi('common', 'patchResource', {
+                    body: { name: 'test' } as any
+                }, {
+                    200: ({ data }) => data,
+                    422: ({ error }) => {
+                        expect(error).toBeDefined();
+                        expect(Array.isArray(error)).toBe(true);
+                        throw new Error('Validation failed as expected');
+                    }
+                })
+            ).rejects.toThrow('Validation failed as expected');
+        });
+
+        test('should reject PATCH body with invalid field types', async () => {
+            await expect(
+                client.callApi('common', 'patchResource', {
+                    body: { name: 'test', value: 'not-a-number' } as any
+                }, {
+                    200: ({ data }) => data,
+                    422: ({ error }) => {
+                        expect(error).toBeDefined();
+                        expect(Array.isArray(error)).toBe(true);
+                        throw new Error('Validation failed as expected');
+                    }
+                })
+            ).rejects.toThrow('Validation failed as expected');
+        });
+
+        test('should reject PATCH body with extra unknown properties (strict)', async () => {
+            await expect(
+                client.callApi('common', 'patchResource', {
+                    body: { name: 'test', value: 1, extraField: 'should not be allowed' } as any
+                }, {
+                    200: ({ data }) => data,
+                    422: ({ error }) => {
+                        expect(error).toBeDefined();
+                        expect(Array.isArray(error)).toBe(true);
+                        throw new Error('Validation failed as expected');
+                    }
+                })
+            ).rejects.toThrow('Validation failed as expected');
+        });
+    });
+
     describe('Private API', () => {
         const client = new ApiClient(baseUrl, PrivateApiDefinition);