ts-typed-api 0.2.21 → 0.2.22

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;
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-typed-api",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "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
@@ -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
+    });
+});