ts-typed-api 0.1.0 → 0.1.2

package/README.md

@@ -27,7 +27,7 @@ This module is specifically designed to make coding with Large Language Models (
 ## 📦 Installation
 
 ```bash
-npm install ts-typed-api
+npm install --save ts-typed-api
 ```
 
 
@@ -144,6 +144,63 @@ async function runClientExample(): Promise<void> {
 
 **Now both server and client are type safe and in sync! The moment you change the definition of the API, type system will let you know about potential changes you need to handle (like additional response code or a change request body schema).**
 
+### 4. File Upload Example
+
+Handle file uploads with type-safe validation:
+
+```typescript
+// Define file upload endpoints
+const FileUploadApiDefinition = CreateApiDefinition({
+    prefix: '/api',
+    endpoints: {
+        files: {
+            uploadSingle: {
+                path: '/upload/single',
+                method: 'POST',
+                body: z.object({
+                    description: z.string().optional(),
+                }),
+                fileUpload: {
+                    single: {
+                        fieldName: 'file',
+                        maxSize: 5 * 1024 * 1024, // 5MB
+                        allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif']
+                    }
+                },
+                responses: CreateResponses({
+                    200: z.object({
+                        message: z.string(),
+                        fileInfo: z.object({
+                            originalName: z.string(),
+                            size: z.number(),
+                            mimetype: z.string()
+                        })
+                    })
+                })
+            }
+        }
+    }
+});
+
+// Implement handler
+RegisterHandlers(app, FileUploadApiDefinition, {
+    files: {
+        uploadSingle: async (req, res) => {
+            const file = req.file as UploadedFile | undefined;
+            
+            res.respond(200, {
+                message: 'File uploaded successfully',
+                fileInfo: {
+                    originalName: file!.originalname,
+                    size: file!.size,
+                    mimetype: file!.mimetype
+                }
+            });
+        }
+    }
+});
+```
+
 ## 🌟 Features
 
 ### Custom HTTP Client Adapters

package/dist/definition.d.ts

@@ -73,12 +73,36 @@ type CreateResponsesReturnType<InputSchemas extends Partial<Record<AllowedInputS
     422: typeof errorUnifiedResponseSchema;
 };
 export declare function CreateResponses<TInputMap extends Partial<Record<AllowedInputStatusCode, InputSchemaOrMarker>>>(schemas: TInputMap): CreateResponsesReturnType<TInputMap>;
+export interface FileUploadConfig {
+    single?: {
+        fieldName: string;
+        maxSize?: number;
+        allowedMimeTypes?: string[];
+    };
+    array?: {
+        fieldName: string;
+        maxCount?: number;
+        maxSize?: number;
+        allowedMimeTypes?: string[];
+    };
+    fields?: Array<{
+        fieldName: string;
+        maxCount?: number;
+        maxSize?: number;
+        allowedMimeTypes?: string[];
+    }>;
+    any?: {
+        maxSize?: number;
+        allowedMimeTypes?: string[];
+    };
+}
 export interface RouteSchema {
     path: string;
     method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
     params?: ZodTypeAny;
     query?: ZodTypeAny;
     body?: ZodTypeAny;
+    fileUpload?: FileUploadConfig;
     responses: Record<number, ZodTypeAny>;
 }
 export type ApiDefinitionSchema = {
@@ -118,4 +142,50 @@ export type ApiClientParams<TDef extends ApiDefinitionSchema, TDomain extends ke
 export type ApiClientQuery<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints'], TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef['endpoints'][TDomain][TRouteName] extends {
     query: infer Q extends ZodTypeAny;
 } ? z.input<Q> : undefined;
+export declare const fileSchema: z.ZodObject<{
+    fieldname: z.ZodString;
+    originalname: z.ZodString;
+    encoding: z.ZodString;
+    mimetype: z.ZodString;
+    size: z.ZodNumber;
+    buffer: z.ZodType<Buffer<ArrayBufferLike>, z.ZodTypeDef, Buffer<ArrayBufferLike>>;
+    destination: z.ZodOptional<z.ZodString>;
+    filename: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+    stream: z.ZodOptional<z.ZodAny>;
+}, "strip", z.ZodTypeAny, {
+    fieldname: string;
+    originalname: string;
+    encoding: string;
+    mimetype: string;
+    size: number;
+    buffer: Buffer<ArrayBufferLike>;
+    path?: string | undefined;
+    destination?: string | undefined;
+    filename?: string | undefined;
+    stream?: any;
+}, {
+    fieldname: string;
+    originalname: string;
+    encoding: string;
+    mimetype: string;
+    size: number;
+    buffer: Buffer<ArrayBufferLike>;
+    path?: string | undefined;
+    destination?: string | undefined;
+    filename?: string | undefined;
+    stream?: any;
+}>;
+export type FileType = z.infer<typeof fileSchema>;
+export declare function createFileValidationSchema(options?: {
+    maxSize?: number;
+    allowedMimeTypes?: string[];
+    required?: boolean;
+}): z.ZodTypeAny;
+export declare function createFilesArrayValidationSchema(options?: {
+    maxCount?: number;
+    maxSize?: number;
+    allowedMimeTypes?: string[];
+    required?: boolean;
+}): z.ZodArray<z.ZodTypeAny, "many"> | z.ZodOptional<z.ZodArray<z.ZodTypeAny, "many">>;
 export {};

package/dist/definition.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HttpServerErrorCodes = exports.HttpClientErrorCodes = exports.HttpSuccessCodes = exports.TsTypeMarker = void 0;
+exports.fileSchema = exports.HttpServerErrorCodes = exports.HttpClientErrorCodes = exports.HttpSuccessCodes = exports.TsTypeMarker = void 0;
 exports.CustomResponse = CustomResponse;
 exports.CreateResponses = CreateResponses;
 exports.CreateApiDefinition = CreateApiDefinition;
+exports.createFileValidationSchema = createFileValidationSchema;
+exports.createFilesArrayValidationSchema = createFilesArrayValidationSchema;
 const zod_1 = require("zod");
 // Marker class for raw TypeScript types
 class TsTypeMarker {
@@ -61,6 +63,9 @@ function CreateResponses(schemas) {
                 else if (schemaOrMarker instanceof zod_1.ZodType) { // It's a Zod schema
                     builtResult[numericKey] = createSuccessUnifiedResponseSchema(schemaOrMarker);
                 }
+                else {
+                    builtResult[numericKey] = createSuccessUnifiedResponseSchema(schemaOrMarker);
+                }
                 // Note: If schemaOrMarker is something else, it would be a type error
                 // based on InputSchemaOrMarker, or this runtime check would skip it.
             }
@@ -77,3 +82,41 @@ function CreateResponses(schemas) {
 function CreateApiDefinition(definition) {
     return definition;
 }
+// --- File Upload Validation Schemas ---
+// Schema for validating uploaded files
+exports.fileSchema = zod_1.z.object({
+    fieldname: zod_1.z.string(),
+    originalname: zod_1.z.string(),
+    encoding: zod_1.z.string(),
+    mimetype: zod_1.z.string(),
+    size: zod_1.z.number(),
+    buffer: zod_1.z.instanceof(Buffer),
+    destination: zod_1.z.string().optional(),
+    filename: zod_1.z.string().optional(),
+    path: zod_1.z.string().optional(),
+    stream: zod_1.z.any().optional(),
+});
+// Helper function to create file validation schema with constraints
+function createFileValidationSchema(options) {
+    let schema = exports.fileSchema;
+    if (options?.maxSize) {
+        schema = schema.refine((file) => file.size <= options.maxSize, { message: `File size must be less than ${options.maxSize} bytes` });
+    }
+    if (options?.allowedMimeTypes && options.allowedMimeTypes.length > 0) {
+        schema = schema.refine((file) => options.allowedMimeTypes.includes(file.mimetype), { message: `File type must be one of: ${options.allowedMimeTypes.join(', ')}` });
+    }
+    return options?.required === false ? schema.optional() : schema;
+}
+// Helper function to create array of files validation schema
+function createFilesArrayValidationSchema(options) {
+    const singleFileSchema = createFileValidationSchema({
+        maxSize: options?.maxSize,
+        allowedMimeTypes: options?.allowedMimeTypes,
+        required: true, // Individual files in array are required
+    });
+    let schema = zod_1.z.array(singleFileSchema);
+    if (options?.maxCount) {
+        schema = schema.max(options.maxCount, `Maximum ${options.maxCount} files allowed`);
+    }
+    return options?.required === false ? schema.optional() : schema;
+}

package/dist/handler.js

@@ -1,7 +1,155 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerRouteHandlers = registerRouteHandlers;
 const zod_1 = require("zod");
+const multer_1 = __importDefault(require("multer"));
+// Helper function to create multer middleware based on file upload configuration
+function createFileUploadMiddleware(config) {
+    // Default multer configuration
+    const storage = multer_1.default.memoryStorage(); // Store files in memory by default
+    let multerMiddleware;
+    if (config.single) {
+        const upload = (0, multer_1.default)({
+            storage,
+            limits: {
+                fileSize: config.single.maxSize || 10 * 1024 * 1024, // Default 10MB
+            },
+            fileFilter: (req, file, cb) => {
+                if (config.single.allowedMimeTypes && !config.single.allowedMimeTypes.includes(file.mimetype)) {
+                    cb(new Error(`File type ${file.mimetype} not allowed`));
+                    return;
+                }
+                cb(null, true);
+            }
+        });
+        multerMiddleware = upload.single(config.single.fieldName);
+    }
+    else if (config.array) {
+        const upload = (0, multer_1.default)({
+            storage,
+            limits: {
+                fileSize: config.array.maxSize || 10 * 1024 * 1024, // Default 10MB per file
+                files: config.array.maxCount || 10, // Default max 10 files
+            },
+            fileFilter: (req, file, cb) => {
+                if (config.array.allowedMimeTypes && !config.array.allowedMimeTypes.includes(file.mimetype)) {
+                    cb(new Error(`File type ${file.mimetype} not allowed`));
+                    return;
+                }
+                cb(null, true);
+            }
+        });
+        multerMiddleware = upload.array(config.array.fieldName, config.array.maxCount);
+    }
+    else if (config.fields) {
+        const upload = (0, multer_1.default)({
+            storage,
+            limits: {
+                fileSize: Math.max(...config.fields.map(f => f.maxSize || 10 * 1024 * 1024)), // Use max size from all fields
+            },
+            fileFilter: (req, file, cb) => {
+                const fieldConfig = config.fields.find(f => f.fieldName === file.fieldname);
+                if (fieldConfig?.allowedMimeTypes && !fieldConfig.allowedMimeTypes.includes(file.mimetype)) {
+                    cb(new Error(`File type ${file.mimetype} not allowed for field ${file.fieldname}`));
+                    return;
+                }
+                cb(null, true);
+            }
+        });
+        const fields = config.fields.map(f => ({ name: f.fieldName, maxCount: f.maxCount || 1 }));
+        multerMiddleware = upload.fields(fields);
+    }
+    else if (config.any) {
+        const upload = (0, multer_1.default)({
+            storage,
+            limits: {
+                fileSize: config.any.maxSize || 10 * 1024 * 1024, // Default 10MB per file
+            },
+            fileFilter: (req, file, cb) => {
+                if (config.any.allowedMimeTypes && !config.any.allowedMimeTypes.includes(file.mimetype)) {
+                    cb(new Error(`File type ${file.mimetype} not allowed`));
+                    return;
+                }
+                cb(null, true);
+            }
+        });
+        multerMiddleware = upload.any();
+    }
+    else {
+        // Fallback - should not reach here if config is valid
+        throw new Error('Invalid file upload configuration');
+    }
+    // Wrap multer middleware with error handling to format errors as 422 JSON responses
+    return (req, res, next) => {
+        multerMiddleware(req, res, (error) => {
+            if (error) {
+                // Convert multer errors to UnifiedError format
+                const mappedErrors = [];
+                if (error instanceof multer_1.default.MulterError) {
+                    let errorMessage = error.message;
+                    let fieldName = 'file';
+                    switch (error.code) {
+                        case 'LIMIT_FILE_SIZE':
+                            errorMessage = 'File size exceeds the allowed limit';
+                            break;
+                        case 'LIMIT_FILE_COUNT':
+                            errorMessage = 'Too many files uploaded';
+                            break;
+                        case 'LIMIT_UNEXPECTED_FILE':
+                            errorMessage = `Unexpected field: ${error.field}`;
+                            fieldName = error.field || 'file';
+                            break;
+                        case 'LIMIT_FIELD_KEY':
+                            errorMessage = 'Field name too long';
+                            break;
+                        case 'LIMIT_FIELD_VALUE':
+                            errorMessage = 'Field value too long';
+                            break;
+                        case 'LIMIT_FIELD_COUNT':
+                            errorMessage = 'Too many fields';
+                            break;
+                        case 'LIMIT_PART_COUNT':
+                            errorMessage = 'Too many parts';
+                            break;
+                        default:
+                            errorMessage = error.message || 'File upload error';
+                    }
+                    mappedErrors.push({
+                        field: fieldName,
+                        message: errorMessage,
+                        type: 'body',
+                    });
+                }
+                else if (error instanceof Error) {
+                    // Handle custom errors from fileFilter
+                    mappedErrors.push({
+                        field: 'file',
+                        message: error.message,
+                        type: 'body',
+                    });
+                }
+                else {
+                    mappedErrors.push({
+                        field: 'file',
+                        message: 'File upload error',
+                        type: 'body',
+                    });
+                }
+                // Send 422 response with structured error format
+                res.status(422).json({
+                    data: null,
+                    error: mappedErrors
+                });
+            }
+            else {
+                next();
+            }
+        });
+    };
+}
 // 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
@@ -150,6 +298,17 @@ middlewares) {
         };
         // Create middleware wrappers that include endpoint information
         const middlewareWrappers = [];
+        // Add file upload middleware if configured
+        if (routeDefinition.fileUpload) {
+            try {
+                const fileUploadMiddleware = createFileUploadMiddleware(routeDefinition.fileUpload);
+                middlewareWrappers.push(fileUploadMiddleware);
+            }
+            catch (error) {
+                console.error(`Error creating file upload middleware for ${currentDomain}.${currentRouteKey}:`, error);
+                return; // Skip this route if file upload middleware creation fails
+            }
+        }
         if (middlewares && middlewares.length > 0) {
             middlewares.forEach(middleware => {
                 const wrappedMiddleware = async (req, res, next) => {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { ApiClient, FetchHttpClientAdapter } from './client';
 export { CreateApiDefinition, CreateResponses } from './definition';
 export { RegisterHandlers, EndpointMiddleware } from './object-handlers';
+export { File as UploadedFile } from './router';
 export { z as ZodSchema } from 'zod';

package/dist/router.d.ts

@@ -1,8 +1,14 @@
 import express from "express";
 import { ApiDefinitionSchema, // Changed from ApiDefinition
 ApiBody, ApiParams, ApiQuery, InferDataFromUnifiedResponse } from './definition';
+export type File = Express.Multer.File;
 export type TypedRequest<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints'], TRouteKey extends keyof TDef['endpoints'][TDomain], // Using direct keyof for simplicity here
-P extends ApiParams<TDef, TDomain, TRouteKey> = ApiParams<TDef, TDomain, TRouteKey>, ReqBody extends ApiBody<TDef, TDomain, TRouteKey> = ApiBody<TDef, TDomain, TRouteKey>, Q extends ApiQuery<TDef, TDomain, TRouteKey> = ApiQuery<TDef, TDomain, TRouteKey>, L extends Record<string, any> = Record<string, any>> = express.Request<P, any, ReqBody, Q, L>;
+P extends ApiParams<TDef, TDomain, TRouteKey> = ApiParams<TDef, TDomain, TRouteKey>, ReqBody extends ApiBody<TDef, TDomain, TRouteKey> = ApiBody<TDef, TDomain, TRouteKey>, Q extends ApiQuery<TDef, TDomain, TRouteKey> = ApiQuery<TDef, TDomain, TRouteKey>, L extends Record<string, any> = Record<string, any>> = express.Request<P, any, ReqBody, Q, L> & {
+    file?: File;
+    files?: File[] | {
+        [fieldname: string]: File[];
+    };
+};
 type ResponseDataForStatus<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints'], TRouteName extends keyof TDef['endpoints'][TDomain], TStatus extends keyof TDef['endpoints'][TDomain][TRouteName]['responses'] & number> = InferDataFromUnifiedResponse<TDef['endpoints'][TDomain][TRouteName]['responses'][TStatus]>;
 type RespondFunction<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints'], TRouteName extends keyof TDef['endpoints'][TDomain]> = <TStatusLocal extends keyof TDef['endpoints'][TDomain][TRouteName]['responses'] & number>(status: TStatusLocal, data: ResponseDataForStatus<TDef, TDomain, TRouteName, TStatusLocal>) => void;
 export interface TypedResponse<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints'], TRouteName extends keyof TDef['endpoints'][TDomain], L extends Record<string, any> = Record<string, any>> extends express.Response<any, L> {

package/examples/file-upload-example.ts

@@ -0,0 +1,158 @@
+import express from 'express';
+import { z } from 'zod';
+import {
+    CreateApiDefinition,
+    CreateResponses,
+    RegisterHandlers,
+    UploadedFile
+} from '../src';
+
+// Define API with file upload endpoints
+const FileUploadApiDefinition = CreateApiDefinition({
+    prefix: '/api',
+    endpoints: {
+        files: {
+            // Single file upload
+            uploadSingle: {
+                path: '/upload/single',
+                method: 'POST',
+                body: z.object({
+                    description: z.string().optional(),
+                }),
+                fileUpload: {
+                    single: {
+                        fieldName: 'file',
+                        maxSize: 5 * 1024 * 1024, // 5MB
+                        allowedMimeTypes: ['image/jpeg', 'image/png', 'image/gif']
+                    }
+                },
+                responses: CreateResponses({
+                    200: z.object({
+                        message: z.string(),
+                        fileInfo: z.object({
+                            originalName: z.string(),
+                            size: z.number(),
+                            mimetype: z.string()
+                        })
+                    })
+                })
+            },
+
+            // Multiple files upload (array)
+            uploadMultiple: {
+                path: '/upload/multiple',
+                method: 'POST',
+                body: z.object({
+                    category: z.string(),
+                }),
+                fileUpload: {
+                    array: {
+                        fieldName: 'files',
+                        maxCount: 5,
+                        maxSize: 2 * 1024 * 1024, // 2MB per file
+                        allowedMimeTypes: ['image/jpeg', 'image/png']
+                    }
+                },
+                responses: CreateResponses({
+                    200: z.object({
+                        message: z.string(),
+                        uploadedFiles: z.array(z.object({
+                            originalName: z.string(),
+                            size: z.number(),
+                            mimetype: z.string()
+                        }))
+                    })
+                })
+            },
+        }
+    }
+});
+
+// Create Express app
+const app = express();
+const port = 3002;
+
+// Note: Don't use express.json() for file upload routes as it conflicts with multipart parsing
+// Only use it for non-file routes or apply it selectively
+
+// Register handlers
+RegisterHandlers(app, FileUploadApiDefinition, {
+    files: {
+        uploadSingle: async (req, res) => {
+            // req.file contains the uploaded file
+            // req.body contains the form data
+
+            const file = req.file as UploadedFile | undefined;
+
+            try {
+
+                // Process the file here (save to disk, upload to cloud, etc.)
+                console.log('Uploaded file:', {
+                    name: file!.originalname,
+                    size: file!.size,
+                    type: file!.mimetype
+                });
+
+                res.respond(200, {
+                    message: 'File uploaded successfully',
+                    fileInfo: {
+                        originalName: file!.originalname,
+                        size: file!.size,
+                        mimetype: file!.mimetype
+                    }
+                });
+            } catch (error) {
+                console.error('File validation error:', error);
+
+            }
+        },
+
+        uploadMultiple: async (req, res) => {
+            // req.files contains array of uploaded files
+            // req.body contains the form data
+            const files = req.files as UploadedFile[] | undefined;
+
+            try {
+                // Process the files here
+                const uploadedFiles = files!.map(file => ({
+                    originalName: file.originalname,
+                    size: file.size,
+                    mimetype: file.mimetype
+                }));
+                console.log('Uploaded files:', uploadedFiles, req.body.category);
+
+                res.respond(200, {
+                    message: `${uploadedFiles.length} files uploaded successfully`,
+                    uploadedFiles
+                });
+
+            } catch (error) {
+                console.error('Files validation error:', error);
+
+            }
+        },
+    }
+});
+
+app.listen(port, () => {
+    console.log(`File upload server listening at http://localhost:${port}`);
+    console.log('\nExample curl commands:');
+    console.log('\n1. Single file upload:');
+    console.log(`curl -X POST http://localhost:${port}/api/upload/single \\`);
+    console.log(`  -F "file=@/path/to/image.jpg" \\`);
+    console.log(`  -F "description=My uploaded image"`);
+
+    console.log('\n2. Multiple files upload:');
+    console.log(`curl -X POST http://localhost:${port}/api/upload/multiple \\`);
+    console.log(`  -F "files=@/path/to/image1.jpg" \\`);
+    console.log(`  -F "files=@/path/to/image2.png" \\`);
+    console.log(`  -F "category=photos"`);
+
+    console.log('\n3. Mixed fields upload:');
+    console.log(`curl -X POST http://localhost:${port}/api/upload/mixed \\`);
+    console.log(`  -F "avatar=@/path/to/avatar.jpg" \\`);
+    console.log(`  -F "documents=@/path/to/doc1.pdf" \\`);
+    console.log(`  -F "documents=@/path/to/doc2.txt" \\`);
+    console.log(`  -F "title=My Upload" \\`);
+    console.log(`  -F "tags=tag1,tag2"`);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-typed-api",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A lightweight, type-safe RPC library for TypeScript with Zod validation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,8 +26,10 @@
   "license": "ISC",
   "dependencies": {
     "@types/express": "^5.0.3",
+    "@types/multer": "^1.4.13",
     "@types/node": "^24.0.3",
     "express": "^5.1.0",
+    "multer": "^2.0.1",
     "zod": "^3.22.4"
   },
   "devDependencies": {