ts-typed-api 0.2.18 → 0.2.20

package/dist/definition.d.ts

@@ -91,10 +91,13 @@ type RouteWithBody = {
     fileUpload?: FileUploadConfig;
     responses: Record<number, ZodTypeAny>;
 };
-export type RouteSchema = RouteWithoutBody | RouteWithBody;
-export type ApiDefinitionSchema = {
+export type RouteSchema = (RouteWithoutBody | RouteWithBody) & {
+    description?: string;
+};
+export type ApiDefinitionSchema<TEndpoints extends Record<string, Record<string, RouteSchema>> = Record<string, Record<string, RouteSchema>>> = {
     prefix?: string;
-    endpoints: Record<string, Record<string, RouteSchema>>;
+    sectionDescriptions?: Partial<Record<keyof TEndpoints, string>>;
+    endpoints: TEndpoints;
 };
 export declare function CreateApiDefinition<T extends ApiDefinitionSchema>(definition: T): T;
 export type ApiRouteKey<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints']> = keyof TDef['endpoints'][TDomain];

package/dist/handler.js

@@ -6,6 +6,55 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerRouteHandlers = registerRouteHandlers;
 const zod_1 = require("zod");
 const multer_1 = __importDefault(require("multer"));
+// Helper function to preprocess parameters for type coercion
+function preprocessParams(params, paramsSchema) {
+    if (!paramsSchema || !params)
+        return params;
+    // Create a copy to avoid mutating the original
+    const processedParams = { ...params };
+    // Get the shape of the schema if it's a ZodObject
+    if (paramsSchema instanceof zod_1.z.ZodObject) {
+        const shape = paramsSchema.shape;
+        for (const [key, value] of Object.entries(processedParams)) {
+            if (typeof value === 'string' && shape[key]) {
+                const fieldSchema = shape[key];
+                // Handle ZodOptional and ZodDefault wrappers
+                let innerSchema = fieldSchema;
+                if (fieldSchema instanceof zod_1.z.ZodOptional) {
+                    innerSchema = fieldSchema._def.innerType;
+                }
+                if (fieldSchema instanceof zod_1.z.ZodDefault) {
+                    innerSchema = fieldSchema._def.innerType;
+                }
+                // Handle nested ZodOptional/ZodDefault combinations
+                while (innerSchema instanceof zod_1.z.ZodOptional || innerSchema instanceof zod_1.z.ZodDefault) {
+                    if (innerSchema instanceof zod_1.z.ZodOptional) {
+                        innerSchema = innerSchema._def.innerType;
+                    }
+                    else if (innerSchema instanceof zod_1.z.ZodDefault) {
+                        innerSchema = innerSchema._def.innerType;
+                    }
+                }
+                // Convert based on the inner schema type
+                if (innerSchema instanceof zod_1.z.ZodNumber) {
+                    const numValue = Number(value);
+                    if (!isNaN(numValue)) {
+                        processedParams[key] = numValue;
+                    }
+                }
+                else if (innerSchema instanceof zod_1.z.ZodBoolean) {
+                    if (value === 'true') {
+                        processedParams[key] = true;
+                    }
+                    else if (value === 'false') {
+                        processedParams[key] = false;
+                    }
+                }
+            }
+        }
+    }
+    return processedParams;
+}
 // Helper function to preprocess query parameters for type coercion
 function preprocessQueryParams(query, querySchema) {
     if (!querySchema || !query)
@@ -277,9 +326,12 @@ middlewares) {
             try {
                 // Ensure TDef is correctly used for type inference if this section needs it.
                 // Currently, parsedParams,Query,Body are based on runtime routeDefinition.
-                const parsedParams = ('params' in routeDefinition && routeDefinition.params)
-                    ? routeDefinition.params.parse(expressReq.params)
+                const preprocessedParams = ('params' in routeDefinition && routeDefinition.params)
+                    ? preprocessParams(expressReq.params, routeDefinition.params)
                     : expressReq.params;
+                const parsedParams = ('params' in routeDefinition && routeDefinition.params)
+                    ? routeDefinition.params.parse(preprocessedParams)
+                    : preprocessedParams;
                 // Preprocess query parameters to handle type coercion from strings
                 const preprocessedQuery = ('query' in routeDefinition && routeDefinition.query)
                     ? preprocessQueryParams(expressReq.query, routeDefinition.query)
@@ -380,6 +432,26 @@ middlewares) {
                     Object.getPrototypeOf(expressRes).setHeader.call(expressRes, name, value);
                     return typedExpressRes;
                 };
+                // SSE streaming methods
+                typedExpressRes.startSSE = () => {
+                    typedExpressRes.setHeader('Content-Type', 'text/event-stream');
+                    typedExpressRes.setHeader('Cache-Control', 'no-cache');
+                    typedExpressRes.setHeader('Connection', 'keep-alive');
+                    typedExpressRes.setHeader('Access-Control-Allow-Origin', '*');
+                    typedExpressRes.setHeader('Access-Control-Allow-Headers', 'Cache-Control');
+                };
+                typedExpressRes.streamSSE = (eventName, data, id) => {
+                    let event = '';
+                    if (eventName)
+                        event += `event: ${eventName}\n`;
+                    if (id)
+                        event += `id: ${id}\n`;
+                    event += `data: ${JSON.stringify(data)}\n\n`;
+                    expressRes.write(event);
+                };
+                typedExpressRes.endStream = () => {
+                    expressRes.end();
+                };
                 const specificHandlerFn = handler;
                 await specificHandlerFn(finalTypedReq, typedExpressRes);
             }

package/dist/hono-cloudflare-workers.js

@@ -19,6 +19,55 @@ exports.honoFileSchema = zod_1.z.object({
     path: zod_1.z.string().optional(),
     stream: zod_1.z.any().optional(),
 });
+// Helper function to preprocess parameters for type coercion
+function preprocessParams(params, paramsSchema) {
+    if (!paramsSchema || !params)
+        return params;
+    // Create a copy to avoid mutating the original
+    const processedParams = { ...params };
+    // Get the shape of the schema if it's a ZodObject
+    if (paramsSchema instanceof zod_1.z.ZodObject) {
+        const shape = paramsSchema.shape;
+        for (const [key, value] of Object.entries(processedParams)) {
+            if (typeof value === 'string' && shape[key]) {
+                const fieldSchema = shape[key];
+                // Handle ZodOptional and ZodDefault wrappers
+                let innerSchema = fieldSchema;
+                if (fieldSchema instanceof zod_1.z.ZodOptional) {
+                    innerSchema = fieldSchema._def.innerType;
+                }
+                if (fieldSchema instanceof zod_1.z.ZodDefault) {
+                    innerSchema = fieldSchema._def.innerType;
+                }
+                // Handle nested ZodOptional/ZodDefault combinations
+                while (innerSchema instanceof zod_1.z.ZodOptional || innerSchema instanceof zod_1.z.ZodDefault) {
+                    if (innerSchema instanceof zod_1.z.ZodOptional) {
+                        innerSchema = innerSchema._def.innerType;
+                    }
+                    else if (innerSchema instanceof zod_1.z.ZodDefault) {
+                        innerSchema = innerSchema._def.innerType;
+                    }
+                }
+                // Convert based on the inner schema type
+                if (innerSchema instanceof zod_1.z.ZodNumber) {
+                    const numValue = Number(value);
+                    if (!isNaN(numValue)) {
+                        processedParams[key] = numValue;
+                    }
+                }
+                else if (innerSchema instanceof zod_1.z.ZodBoolean) {
+                    if (value === 'true') {
+                        processedParams[key] = true;
+                    }
+                    else if (value === 'false') {
+                        processedParams[key] = false;
+                    }
+                }
+            }
+        }
+    }
+    return processedParams;
+}
 // Helper function to preprocess query parameters for type coercion
 function preprocessQueryParams(query, querySchema) {
     if (!querySchema || !query)
@@ -240,9 +289,12 @@ function registerHonoRouteHandlers(app, apiDefinition, routeHandlers, middleware
         const honoMiddleware = async (c) => {
             try {
                 // Parse and validate request
-                const parsedParams = ('params' in routeDefinition && routeDefinition.params)
-                    ? routeDefinition.params.parse(c.req.param())
+                const preprocessedParams = ('params' in routeDefinition && routeDefinition.params)
+                    ? preprocessParams(c.req.param(), routeDefinition.params)
                     : c.req.param();
+                const parsedParams = ('params' in routeDefinition && routeDefinition.params)
+                    ? routeDefinition.params.parse(preprocessedParams)
+                    : preprocessedParams;
                 const preprocessedQuery = ('query' in routeDefinition && routeDefinition.query)
                     ? preprocessQueryParams(c.req.query(), routeDefinition.query)
                     : c.req.query();
@@ -351,6 +403,38 @@ function registerHonoRouteHandlers(app, apiDefinition, routeHandlers, middleware
                     setHeader: (name, value) => {
                         c.header(name, value);
                         return fakeRes;
+                    },
+                    // SSE streaming methods for Hono
+                    startSSE: () => {
+                        c.header('Content-Type', 'text/event-stream');
+                        c.header('Cache-Control', 'no-cache');
+                        c.header('Connection', 'keep-alive');
+                        c.header('Access-Control-Allow-Origin', '*');
+                        c.header('Access-Control-Allow-Headers', 'Cache-Control');
+                    },
+                    streamSSE: (eventName, data, id) => {
+                        let event = '';
+                        if (eventName)
+                            event += `event: ${eventName}\n`;
+                        if (id)
+                            event += `id: ${id}\n`;
+                        event += `data: ${JSON.stringify(data)}\n\n`;
+                        // For Hono, we need to accumulate the response
+                        if (!c.__sseBuffer) {
+                            c.__sseBuffer = '';
+                        }
+                        c.__sseBuffer += event;
+                    },
+                    endStream: () => {
+                        // Send the accumulated SSE data
+                        const sseData = c.__sseBuffer || '';
+                        c.__response = new Response(sseData, {
+                            headers: {
+                                'Content-Type': 'text/event-stream',
+                                'Cache-Control': 'no-cache',
+                                'Connection': 'keep-alive'
+                            }
+                        });
                     }
                 };
                 const specificHandlerFn = handler;

package/dist/openapi-self.d.ts

@@ -14,6 +14,10 @@ export interface OpenAPISpec {
     components?: {
         schemas?: Record<string, SchemaObject>;
     };
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
 }
 export interface PathItem {
     get?: Operation;

package/dist/openapi-self.js

@@ -417,10 +417,12 @@ function processRoute(route, fullPath, registry, domain, anonymousTypes = false)
     const responses = createResponses(route.responses, registry, anonymousTypes);
     const operation = {
         summary: `${route.method} ${fullPath}`,
-        description: `${route.method} operation for ${fullPath}`,
         responses,
         tags: [domain]
     };
+    if (route.description) {
+        operation.description = route.description;
+    }
     if (parameters.length > 0) {
         operation.parameters = parameters;
     }
@@ -450,6 +452,7 @@ function generateOpenApiSpec(definitions, options = {}) {
     const definitionsArray = Array.isArray(definitions) ? definitions : [definitions];
     const anonymousTypes = options.anonymousTypes || false;
     const allPaths = {};
+    const allTags = [];
     // Process each definition
     for (const definition of definitionsArray) {
         const paths = processApiDefinition(definition, registry, anonymousTypes);
@@ -463,6 +466,18 @@ function generateOpenApiSpec(definitions, options = {}) {
                 allPaths[path] = pathItem;
             }
         }
+        // Collect tags from sectionDescriptions
+        if (definition.sectionDescriptions) {
+            for (const [sectionName, description] of Object.entries(definition.sectionDescriptions)) {
+                // Avoid duplicates
+                if (!allTags.find(tag => tag.name === sectionName)) {
+                    allTags.push({
+                        name: sectionName,
+                        description: description
+                    });
+                }
+            }
+        }
     }
     const spec = {
         openapi: '3.0.0',
@@ -477,6 +492,10 @@ function generateOpenApiSpec(definitions, options = {}) {
     if (options.servers && options.servers.length > 0) {
         spec.servers = options.servers;
     }
+    // Add tags if any were found
+    if (allTags.length > 0) {
+        spec.tags = allTags;
+    }
     // Add components with schemas if any were registered and not using anonymous types
     if (!anonymousTypes) {
         const schemas = registry.getSchemas();

package/dist/openapi.d.ts

@@ -1,5 +1,5 @@
-import { ApiDefinitionSchema } from './definition';
-export declare function generateOpenApiSpec(definitions: ApiDefinitionSchema | ApiDefinitionSchema[], options?: {
+import { RouteSchema } from './definition';
+export declare function generateOpenApiSpec<TEndpoints extends Record<string, Record<string, RouteSchema>>>(definitions: import('./definition').ApiDefinitionSchema<TEndpoints> | import('./definition').ApiDefinitionSchema<TEndpoints>[], options?: {
     info?: {
         title?: string;
         version?: string;

package/dist/openapi.js

@@ -47,11 +47,20 @@ function generateOpenApiSpec(definitions, options = {}) {
             },
         };
     }
+    // Collect all tags with descriptions for the OpenAPI spec
+    const allTags = [];
     // Iterate over multiple API definitions to register routes
     definitionArray.forEach((definition) => {
         Object.keys(definition.endpoints).forEach(domainNameKey => {
             // domainNameKey is a string, representing the domain like 'users', 'products'
             const domain = definition.endpoints[domainNameKey];
+            // Add tag if not already present
+            if (!allTags.find(tag => tag.name === domainNameKey)) {
+                allTags.push({
+                    name: domainNameKey,
+                    description: definition.sectionDescriptions?.[domainNameKey]
+                });
+            }
             Object.keys(domain).forEach(routeNameKey => {
                 // routeNameKey is a string, representing the route name like 'getUser', 'createProduct'
                 const route = domain[routeNameKey];
@@ -91,6 +100,7 @@ function generateOpenApiSpec(definitions, options = {}) {
                 }
                 const operation = {
                     summary: `${domainNameKey} - ${routeNameKey}`, // Use keys directly for summary
+                    description: route.description, // Use route description if provided
                     tags: [domainNameKey], // Use domainNameKey for tags
                     parameters: parameters.length > 0 ? parameters : undefined,
                     requestBody: requestBody,
@@ -103,7 +113,6 @@ function generateOpenApiSpec(definitions, options = {}) {
                     method: route.method.toLowerCase(), // Ensure method is lowercase
                     path: openApiPath,
                     ...operation,
-                    // Add description or other OpenAPI fields if available in RouteSchema
                 });
             });
         });
@@ -118,6 +127,7 @@ function generateOpenApiSpec(definitions, options = {}) {
             description: options.info?.description ?? 'Automatically generated OpenAPI specification',
         },
         servers: options.servers ?? [{ url: '/api' }], // Adjust as needed
+        tags: allTags.filter(tag => tag.description), // Only include tags that have descriptions
     });
     return openApiDocument;
 }

package/dist/router.d.ts

@@ -17,6 +17,9 @@ export interface TypedResponse<TDef extends ApiDefinitionSchema, TDomain extends
     respondContentType: (status: number, data: any, contentType: string) => void;
     setHeader: (name: string, value: string) => this;
     json: <B = any>(body: B) => this;
+    startSSE: () => void;
+    streamSSE: (eventName?: string, data?: any, id?: string) => void;
+    endStream: () => void;
 }
 export declare function createRouteHandler<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints'], TRouteKey extends keyof TDef['endpoints'][TDomain], // Using direct keyof for simplicity
 Ctx extends Record<string, any> = Record<string, any>>(domain: TDomain, routeKey: TRouteKey, handler: (req: TypedRequest<TDef, TDomain, TRouteKey, ApiParams<TDef, TDomain, TRouteKey>, ApiBody<TDef, TDomain, TRouteKey>, ApiQuery<TDef, TDomain, TRouteKey>, Record<string, any>, Ctx>, res: TypedResponse<TDef, TDomain, TRouteKey>) => Promise<void> | void): {

package/examples/advanced/definitions.ts

@@ -20,11 +20,16 @@ const ProductSchema = z.object({
 
 export const PublicApiDefinition = CreateApiDefinition({
     prefix: '/api/v1/public',
+    sectionDescriptions: {
+        auth: 'Authentication endpoints for user login and logout',
+        products: 'Product management and listing endpoints'
+    },
     endpoints: {
         auth: {
             login: {
                 method: 'POST',
                 path: '/login',
+                description: 'Authenticate a user with username and password, returns JWT token',
                 body: z.object({
                     username: z.string(),
                     password: z.string()
@@ -42,6 +47,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             logout: {
                 method: 'POST',
                 path: '/logout',
+                description: 'Log out the current user and invalidate their session',
                 responses: CreateResponses({
                     200: z.object({
                         message: z.string()
@@ -53,6 +59,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             list: {
                 method: 'GET',
                 path: '/products',
+                description: 'Retrieve a paginated list of products with optional filtering',
                 query: z.object({
                     page: z.number().int().min(1).optional().default(1),
                     limit: z.number().int().min(1).max(100).optional().default(10),

package/examples/simple/definitions.ts

@@ -2,11 +2,16 @@ import { ZodSchema as z, CreateApiDefinition, CreateResponses } from '../../src'
 
 export const PublicApiDefinition = CreateApiDefinition({
     prefix: '/api/v1/public',
+    sectionDescriptions: {
+        status: 'Health check and status endpoints',
+        common: 'Common utility endpoints'
+    },
     endpoints: {
         status: {
             probe1: {
                 method: 'GET',
                 path: '/status/probe1',
+                description: 'Advanced health check with query parameters',
                 query: z.object({
                     match: z.boolean()
                 }),
@@ -21,6 +26,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             probe2: {
                 method: 'GET',
                 path: '/status/probe2',
+                description: 'Simple health check endpoint',
                 responses: CreateResponses({
                     200: z.enum(["pong"]),
                 })
@@ -30,6 +36,7 @@ export const PublicApiDefinition = CreateApiDefinition({
             ping: {
                 method: 'GET',
                 path: '/ping',
+                description: 'Basic ping endpoint to check if the service is alive',
                 query: z.object({
                     format: z.enum(["json", "html"]).optional()
                 }),
@@ -40,12 +47,36 @@ export const PublicApiDefinition = CreateApiDefinition({
             customHeaders: {
                 method: 'GET',
                 path: '/custom-headers',
+                description: 'Returns information about custom headers',
                 responses: CreateResponses({
                     200: z.object({
                         message: z.string()
                     }),
                 })
             },
+            longpoll: {
+                method: 'GET',
+                path: '/longpoll/:sequence',
+                description: 'Long polling endpoint that simulates delayed response',
+                params: z.object({
+                    sequence: z.number().int().min(1)
+                }),
+                responses: CreateResponses({
+                    200: z.object({
+                        sequence: z.number(),
+                        data: z.string(),
+                        timestamp: z.number()
+                    }),
+                })
+            },
+            stream: {
+                method: 'GET',
+                path: '/stream',
+                description: 'Server-Sent Events streaming endpoint',
+                responses: CreateResponses({
+                    200: z.string() // Raw SSE data
+                })
+            },
         }
     }
 })

package/examples/simple/server.ts

@@ -49,6 +49,33 @@ RegisterHandlers(app, PublicApiDefinition, {
             res.setHeader('x-custom-test', 'test-value');
             res.setHeader('x-another-header', 'another-value');
             res.respond(200, { message: "headers set" });
+        },
+        longpoll: async (req, res) => {
+            const sequence = req.params.sequence;
+            // Simulate long polling delay based on sequence
+            const delay = sequence * 100; // 100ms per sequence number
+            await new Promise(resolve => setTimeout(resolve, delay));
+            res.respond(200, {
+                sequence,
+                data: `object ${sequence}`,
+                timestamp: Date.now()
+            });
+        },
+        stream: async (req, res) => {
+            // Initialize SSE with proper headers
+            res.startSSE();
+
+            // Send SSE events with JSON data at intervals
+            await res.streamSSE('update', { sequence: 1, data: 'object 1' });
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            await res.streamSSE('update', { sequence: 2, data: 'object 2' });
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            await res.streamSSE('update', { sequence: 3, data: 'object 3' });
+
+            // Close the stream
+            res.endStream();
         }
     },
     status: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-typed-api",
-  "version": "0.2.18",
+  "version": "0.2.20",
   "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

@@ -184,13 +184,16 @@ type RouteWithBody = {
 };
 
 // Union type for all route schemas
-export type RouteSchema = RouteWithoutBody | RouteWithBody;
+export type RouteSchema = (RouteWithoutBody | RouteWithBody) & {
+    description?: string;
+};
 
 // Define the structure for the entire API definition object
 // Now includes an optional prefix and endpoints record
-export type ApiDefinitionSchema = {
+export type ApiDefinitionSchema<TEndpoints extends Record<string, Record<string, RouteSchema>> = Record<string, Record<string, RouteSchema>>> = {
     prefix?: string;
-    endpoints: Record<string, Record<string, RouteSchema>>;
+    sectionDescriptions?: Partial<Record<keyof TEndpoints, string>>;
+    endpoints: TEndpoints;
 };
 
 // Helper function to ensure the definition conforms to ApiDefinitionSchema

package/src/handler.ts

@@ -27,6 +27,59 @@ export type EndpointMiddleware<TDef extends ApiDefinitionSchema = ApiDefinitionS
     }[keyof TDef['endpoints']]
 ) => void | Promise<void>;
 
+// Helper function to preprocess parameters for type coercion
+function preprocessParams(params: any, paramsSchema?: z.ZodTypeAny): any {
+    if (!paramsSchema || !params) return params;
+
+    // Create a copy to avoid mutating the original
+    const processedParams = { ...params };
+
+    // Get the shape of the schema if it's a ZodObject
+    if (paramsSchema instanceof z.ZodObject) {
+        const shape = paramsSchema.shape;
+
+        for (const [key, value] of Object.entries(processedParams)) {
+            if (typeof value === 'string' && shape[key]) {
+                const fieldSchema = shape[key];
+
+                // Handle ZodOptional and ZodDefault wrappers
+                let innerSchema = fieldSchema;
+                if (fieldSchema instanceof z.ZodOptional) {
+                    innerSchema = fieldSchema._def.innerType;
+                }
+                if (fieldSchema instanceof z.ZodDefault) {
+                    innerSchema = fieldSchema._def.innerType;
+                }
+
+                // Handle nested ZodOptional/ZodDefault combinations
+                while (innerSchema instanceof z.ZodOptional || innerSchema instanceof z.ZodDefault) {
+                    if (innerSchema instanceof z.ZodOptional) {
+                        innerSchema = innerSchema._def.innerType;
+                    } else if (innerSchema instanceof z.ZodDefault) {
+                        innerSchema = innerSchema._def.innerType;
+                    }
+                }
+
+                // Convert based on the inner schema type
+                if (innerSchema instanceof z.ZodNumber) {
+                    const numValue = Number(value);
+                    if (!isNaN(numValue)) {
+                        processedParams[key] = numValue;
+                    }
+                } else if (innerSchema instanceof z.ZodBoolean) {
+                    if (value === 'true') {
+                        processedParams[key] = true;
+                    } else if (value === 'false') {
+                        processedParams[key] = false;
+                    }
+                }
+            }
+        }
+    }
+
+    return processedParams;
+}
+
 // Helper function to preprocess query parameters for type coercion
 function preprocessQueryParams(query: any, querySchema?: z.ZodTypeAny): any {
     if (!querySchema || !query) return query;
@@ -326,10 +379,14 @@ export function registerRouteHandlers<TDef extends ApiDefinitionSchema>(
             try {
                 // Ensure TDef is correctly used for type inference if this section needs it.
                 // Currently, parsedParams,Query,Body are based on runtime routeDefinition.
-                const parsedParams = ('params' in routeDefinition && routeDefinition.params)
-                    ? (routeDefinition.params as z.ZodTypeAny).parse(expressReq.params)
+                const preprocessedParams = ('params' in routeDefinition && routeDefinition.params)
+                    ? preprocessParams(expressReq.params, routeDefinition.params as z.ZodTypeAny)
                     : expressReq.params;
 
+                const parsedParams = ('params' in routeDefinition && routeDefinition.params)
+                    ? (routeDefinition.params as z.ZodTypeAny).parse(preprocessedParams)
+                    : preprocessedParams;
+
                 // Preprocess query parameters to handle type coercion from strings
                 const preprocessedQuery = ('query' in routeDefinition && routeDefinition.query)
                     ? preprocessQueryParams(expressReq.query, routeDefinition.query as z.ZodTypeAny)
@@ -444,6 +501,27 @@ export function registerRouteHandlers<TDef extends ApiDefinitionSchema>(
                     return typedExpressRes;
                 };
 
+                // SSE streaming methods
+                typedExpressRes.startSSE = () => {
+                    typedExpressRes.setHeader('Content-Type', 'text/event-stream');
+                    typedExpressRes.setHeader('Cache-Control', 'no-cache');
+                    typedExpressRes.setHeader('Connection', 'keep-alive');
+                    typedExpressRes.setHeader('Access-Control-Allow-Origin', '*');
+                    typedExpressRes.setHeader('Access-Control-Allow-Headers', 'Cache-Control');
+                };
+
+                typedExpressRes.streamSSE = (eventName?: string, data?: any, id?: string) => {
+                    let event = '';
+                    if (eventName) event += `event: ${eventName}\n`;
+                    if (id) event += `id: ${id}\n`;
+                    event += `data: ${JSON.stringify(data)}\n\n`;
+                    expressRes.write(event);
+                };
+
+                typedExpressRes.endStream = () => {
+                    expressRes.end();
+                };
+
                 const specificHandlerFn = handler as (
                     req: TypedRequest<TDef, typeof currentDomain, typeof currentRouteKey>,
                     res: TypedResponse<TDef, typeof currentDomain, typeof currentRouteKey>

package/src/hono-cloudflare-workers.ts

@@ -45,6 +45,59 @@ export type HonoTypedContext<
     respond: TypedResponse<TDef, TDomain, TRouteKey>['respond'];
 };
 
+// Helper function to preprocess parameters for type coercion
+function preprocessParams(params: any, paramsSchema?: z.ZodTypeAny): any {
+    if (!paramsSchema || !params) return params;
+
+    // Create a copy to avoid mutating the original
+    const processedParams = { ...params };
+
+    // Get the shape of the schema if it's a ZodObject
+    if (paramsSchema instanceof z.ZodObject) {
+        const shape = paramsSchema.shape;
+
+        for (const [key, value] of Object.entries(processedParams)) {
+            if (typeof value === 'string' && shape[key]) {
+                const fieldSchema = shape[key];
+
+                // Handle ZodOptional and ZodDefault wrappers
+                let innerSchema = fieldSchema;
+                if (fieldSchema instanceof z.ZodOptional) {
+                    innerSchema = fieldSchema._def.innerType;
+                }
+                if (fieldSchema instanceof z.ZodDefault) {
+                    innerSchema = fieldSchema._def.innerType;
+                }
+
+                // Handle nested ZodOptional/ZodDefault combinations
+                while (innerSchema instanceof z.ZodOptional || innerSchema instanceof z.ZodDefault) {
+                    if (innerSchema instanceof z.ZodOptional) {
+                        innerSchema = innerSchema._def.innerType;
+                    } else if (innerSchema instanceof z.ZodDefault) {
+                        innerSchema = innerSchema._def.innerType;
+                    }
+                }
+
+                // Convert based on the inner schema type
+                if (innerSchema instanceof z.ZodNumber) {
+                    const numValue = Number(value);
+                    if (!isNaN(numValue)) {
+                        processedParams[key] = numValue;
+                    }
+                } else if (innerSchema instanceof z.ZodBoolean) {
+                    if (value === 'true') {
+                        processedParams[key] = true;
+                    } else if (value === 'false') {
+                        processedParams[key] = false;
+                    }
+                }
+            }
+        }
+    }
+
+    return processedParams;
+}
+
 // Helper function to preprocess query parameters for type coercion
 function preprocessQueryParams(query: any, querySchema?: z.ZodTypeAny): any {
     if (!querySchema || !query) return query;
@@ -304,10 +357,14 @@ export function registerHonoRouteHandlers<
         ) => {
             try {
                 // Parse and validate request
-                const parsedParams = ('params' in routeDefinition && routeDefinition.params)
-                    ? (routeDefinition.params as z.ZodTypeAny).parse(c.req.param())
+                const preprocessedParams = ('params' in routeDefinition && routeDefinition.params)
+                    ? preprocessParams(c.req.param(), routeDefinition.params as z.ZodTypeAny)
                     : c.req.param();
 
+                const parsedParams = ('params' in routeDefinition && routeDefinition.params)
+                    ? (routeDefinition.params as z.ZodTypeAny).parse(preprocessedParams)
+                    : preprocessedParams;
+
                 const preprocessedQuery = ('query' in routeDefinition && routeDefinition.query)
                     ? preprocessQueryParams(c.req.query(), routeDefinition.query as z.ZodTypeAny)
                     : c.req.query();
@@ -429,6 +486,37 @@ export function registerHonoRouteHandlers<
                     setHeader: (name: string, value: string) => {
                         c.header(name, value);
                         return fakeRes;
+                    },
+                    // SSE streaming methods for Hono
+                    startSSE: () => {
+                        c.header('Content-Type', 'text/event-stream');
+                        c.header('Cache-Control', 'no-cache');
+                        c.header('Connection', 'keep-alive');
+                        c.header('Access-Control-Allow-Origin', '*');
+                        c.header('Access-Control-Allow-Headers', 'Cache-Control');
+                    },
+                    streamSSE: (eventName?: string, data?: any, id?: string) => {
+                        let event = '';
+                        if (eventName) event += `event: ${eventName}\n`;
+                        if (id) event += `id: ${id}\n`;
+                        event += `data: ${JSON.stringify(data)}\n\n`;
+
+                        // For Hono, we need to accumulate the response
+                        if (!(c as any).__sseBuffer) {
+                            (c as any).__sseBuffer = '';
+                        }
+                        (c as any).__sseBuffer += event;
+                    },
+                    endStream: () => {
+                        // Send the accumulated SSE data
+                        const sseData = (c as any).__sseBuffer || '';
+                        (c as any).__response = new Response(sseData, {
+                            headers: {
+                                'Content-Type': 'text/event-stream',
+                                'Cache-Control': 'no-cache',
+                                'Connection': 'keep-alive'
+                            }
+                        });
                     }
                 } as TypedResponse<TDef, typeof currentDomain, typeof currentRouteKey>;
 

package/src/openapi-self.ts

@@ -17,6 +17,10 @@ export interface OpenAPISpec {
     components?: {
         schemas?: Record<string, SchemaObject>;
     };
+    tags?: Array<{
+        name: string;
+        description?: string;
+    }>;
 }
 
 export interface PathItem {
@@ -558,11 +562,14 @@ function processRoute(
 
     const operation: Operation = {
         summary: `${route.method} ${fullPath}`,
-        description: `${route.method} operation for ${fullPath}`,
         responses,
         tags: [domain]
     };
 
+    if (route.description) {
+        operation.description = route.description;
+    }
+
     if (parameters.length > 0) {
         operation.parameters = parameters;
     }
@@ -609,6 +616,7 @@ export function generateOpenApiSpec(
     const anonymousTypes = options.anonymousTypes || false;
 
     const allPaths: Record<string, PathItem> = {};
+    const allTags: Array<{ name: string; description?: string }> = [];
 
     // Process each definition
     for (const definition of definitionsArray) {
@@ -623,6 +631,19 @@ export function generateOpenApiSpec(
                 allPaths[path] = pathItem;
             }
         }
+
+        // Collect tags from sectionDescriptions
+        if (definition.sectionDescriptions) {
+            for (const [sectionName, description] of Object.entries(definition.sectionDescriptions)) {
+                // Avoid duplicates
+                if (!allTags.find(tag => tag.name === sectionName)) {
+                    allTags.push({
+                        name: sectionName,
+                        description: description
+                    });
+                }
+            }
+        }
     }
 
     const spec: OpenAPISpec = {
@@ -640,6 +661,11 @@ export function generateOpenApiSpec(
         spec.servers = options.servers;
     }
 
+    // Add tags if any were found
+    if (allTags.length > 0) {
+        spec.tags = allTags;
+    }
+
     // Add components with schemas if any were registered and not using anonymous types
     if (!anonymousTypes) {
         const schemas = registry.getSchemas();

package/src/openapi.ts

@@ -1,12 +1,12 @@
-import { ApiDefinitionSchema, RouteSchema } from './definition';
+import { RouteSchema } from './definition';
 import { OpenAPIRegistry, OpenApiGeneratorV31, extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
 import { z, ZodTypeAny } from 'zod';
 
 // Extend Zod with OpenAPI capabilities
 extendZodWithOpenApi(z);
 
-export function generateOpenApiSpec(
-    definitions: ApiDefinitionSchema | ApiDefinitionSchema[],
+export function generateOpenApiSpec<TEndpoints extends Record<string, Record<string, RouteSchema>>>(
+    definitions: import('./definition').ApiDefinitionSchema<TEndpoints> | import('./definition').ApiDefinitionSchema<TEndpoints>[],
     options: {
         info?: {
             title?: string;
@@ -59,11 +59,23 @@ export function generateOpenApiSpec(
         };
     }
 
+    // Collect all tags with descriptions for the OpenAPI spec
+    const allTags: Array<{ name: string; description?: string }> = [];
+
     // Iterate over multiple API definitions to register routes
     definitionArray.forEach((definition) => {
         Object.keys(definition.endpoints).forEach(domainNameKey => {
             // domainNameKey is a string, representing the domain like 'users', 'products'
             const domain = definition.endpoints[domainNameKey];
+
+            // Add tag if not already present
+            if (!allTags.find(tag => tag.name === domainNameKey)) {
+                allTags.push({
+                    name: domainNameKey,
+                    description: definition.sectionDescriptions?.[domainNameKey]
+                });
+            }
+
             Object.keys(domain).forEach(routeNameKey => {
                 // routeNameKey is a string, representing the route name like 'getUser', 'createProduct'
                 const route: RouteSchema = domain[routeNameKey];
@@ -108,6 +120,7 @@ export function generateOpenApiSpec(
 
                 const operation = {
                     summary: `${domainNameKey} - ${routeNameKey}`, // Use keys directly for summary
+                    description: route.description, // Use route description if provided
                     tags: [domainNameKey], // Use domainNameKey for tags
                     parameters: parameters.length > 0 ? parameters : undefined,
                     requestBody: requestBody,
@@ -122,7 +135,6 @@ export function generateOpenApiSpec(
                     method: route.method.toLowerCase() as any, // Ensure method is lowercase
                     path: openApiPath,
                     ...operation,
-                    // Add description or other OpenAPI fields if available in RouteSchema
                 });
             });
         });
@@ -138,6 +150,7 @@ export function generateOpenApiSpec(
             description: options.info?.description ?? 'Automatically generated OpenAPI specification',
         },
         servers: options.servers ?? [{ url: '/api' }], // Adjust as needed
+        tags: allTags.filter(tag => tag.description), // Only include tags that have descriptions
     });
 
     return openApiDocument;

package/src/router.ts

@@ -62,6 +62,10 @@ export interface TypedResponse<
     respondContentType: (status: number, data: any, contentType: string) => void;
     setHeader: (name: string, value: string) => this;
     json: <B = any>(body: B) => this; // Keep original json
+    // SSE streaming methods
+    startSSE: () => void;
+    streamSSE: (eventName?: string, data?: any, id?: string) => void;
+    endStream: () => void;
 }
 
 // Type-safe route handler creation function, now generic over TDef and Ctx

package/tests/openapi-spec.test.ts

@@ -316,4 +316,105 @@ describe('OpenAPI Specification Generation', () => {
             }
         }
     });
+
+    test('should include section descriptions in OpenAPI tags', () => {
+        const spec = generateOpenApiSpec(PublicApiDefinition);
+
+        expect(spec).toBeDefined();
+        expect(spec.tags).toBeDefined();
+        expect(Array.isArray(spec.tags)).toBe(true);
+
+        // Check that tags with descriptions are included
+        const statusTag = spec.tags?.find((tag: any) => tag.name === 'status');
+        const commonTag = spec.tags?.find((tag: any) => tag.name === 'common');
+
+        expect(statusTag).toBeDefined();
+        expect(statusTag?.description).toBe('Health check and status endpoints');
+
+        expect(commonTag).toBeDefined();
+        expect(commonTag?.description).toBe('Common utility endpoints');
+    });
+
+    test('should include route descriptions in operation descriptions', () => {
+        const spec = generateOpenApiSpec(PublicApiDefinition);
+
+        expect(spec).toBeDefined();
+        expect(spec.paths).toBeDefined();
+
+        // Check specific endpoints for descriptions
+        const probe1Path = spec.paths?.['/api/v1/public/status/probe1'];
+        const pingPath = spec.paths?.['/api/v1/public/ping'];
+
+        expect(probe1Path?.get?.description).toBe('Advanced health check with query parameters');
+        expect(pingPath?.get?.description).toBe('Basic ping endpoint to check if the service is alive');
+    });
+
+    test('should handle API definitions without descriptions', () => {
+        // Create a definition without descriptions
+        const NoDescriptionDefinition = CreateApiDefinition({
+            endpoints: {
+                test: {
+                    simpleEndpoint: {
+                        method: 'GET' as const,
+                        path: '/test',
+                        responses: {
+                            200: z.object({ message: z.string() })
+                        }
+                    }
+                }
+            }
+        });
+
+        const spec = generateOpenApiSpec(NoDescriptionDefinition);
+
+        expect(spec).toBeDefined();
+        expect(spec.tags).toBeUndefined(); // No tags should be generated when no descriptions
+
+        const testPath = spec.paths?.['/test'];
+        expect(testPath?.get?.description).toBeUndefined(); // No description on operation
+    });
+
+    test('should handle partial section descriptions', () => {
+        // Create a definition with only some sections having descriptions
+        const PartialDescriptionDefinition = CreateApiDefinition({
+            sectionDescriptions: {
+                section1: 'Description for section 1'
+                // section2 intentionally omitted
+            },
+            endpoints: {
+                section1: {
+                    endpoint1: {
+                        method: 'GET' as const,
+                        path: '/section1/endpoint1',
+                        responses: {
+                            200: z.object({ data: z.string() })
+                        }
+                    }
+                },
+                section2: {
+                    endpoint2: {
+                        method: 'GET' as const,
+                        path: '/section2/endpoint2',
+                        responses: {
+                            200: z.object({ data: z.string() })
+                        }
+                    }
+                }
+            }
+        });
+
+        const spec = generateOpenApiSpec(PartialDescriptionDefinition);
+
+        expect(spec).toBeDefined();
+        expect(spec.tags).toBeDefined();
+        expect(spec.tags?.length).toBe(1); // Only one tag should be generated
+
+        const section1Tag = spec.tags?.find((tag: any) => tag.name === 'section1');
+        expect(section1Tag).toBeDefined();
+        expect(section1Tag?.description).toBe('Description for section 1');
+
+        // section2 should not have a tag since it has no description
+        const section2Tag = spec.tags?.find((tag: any) => tag.name === 'section2');
+        expect(section2Tag).toBeUndefined();
+    });
 });

package/tests/setup.ts

@@ -23,6 +23,33 @@ const simplePublicHandlers = {
             res.setHeader('X-Custom-Test', 'test-value');
             res.setHeader('X-Another-Header', 'another-value');
             res.respond(200, { message: "headers set" });
+        },
+        longpoll: async (req: any, res: any) => {
+            const sequence = req.params.sequence;
+            // Simulate long polling delay based on sequence
+            const delay = sequence * 100; // 100ms per sequence number
+            await new Promise(resolve => setTimeout(resolve, delay));
+            res.respond(200, {
+                sequence,
+                data: `object ${sequence}`,
+                timestamp: Date.now()
+            });
+        },
+        stream: async (req: any, res: any) => {
+            // Initialize SSE with proper headers
+            res.startSSE();
+
+            // Send SSE events with JSON data at intervals
+            await res.streamSSE('update', { sequence: 1, data: 'object 1' });
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            await res.streamSSE('update', { sequence: 2, data: 'object 2' });
+            await new Promise(resolve => setTimeout(resolve, 100));
+
+            await res.streamSSE('update', { sequence: 3, data: 'object 3' });
+
+            // Close the stream
+            res.endStream();
         }
     },
     status: {

package/tests/simple-api.test.ts

@@ -121,6 +121,136 @@ describe.each([
             expect(anotherHeader).toBe('another-value');
         });
 
+        test('should handle long polling with delayed responses', async () => {
+            const startTime = Date.now();
+
+            // Test multiple sequences to simulate intervals
+            for (let seq = 1; seq <= 3; seq++) {
+                const result = await client.callApi('common', 'longpoll', {
+                    params: { sequence: seq }
+                }, {
+                    200: ({ data }) => {
+                        expect(data.sequence).toBe(seq);
+                        expect(data.data).toBe(`object ${seq}`);
+                        expect(typeof data.timestamp).toBe('number');
+                        expect(data.timestamp).toBeGreaterThan(startTime);
+                        return data;
+                    },
+                    422: ({ error }) => {
+                        throw new Error(`Validation error: ${JSON.stringify(error)}`);
+                    }
+                });
+
+                expect(result.sequence).toBe(seq);
+                expect(result.data).toBe(`object ${seq}`);
+            }
+
+            // Verify that total time is at least the sum of delays (100ms * 1 + 100ms * 2 + 100ms * 3 = 600ms)
+            const elapsed = Date.now() - startTime;
+            expect(elapsed).toBeGreaterThanOrEqual(600); // Allow some tolerance for test execution
+        });
+
+        test('should handle SSE streaming with multiple JSON objects', async () => {
+            // Test SSE streaming by making a fetch request and parsing the response
+            const response = await fetch(`${baseUrl}/api/v1/public/stream`);
+            expect(response.status).toBe(200);
+            expect(response.headers.get('content-type')).toBe('text/event-stream');
+
+            const responseText = await response.text();
+
+            // Parse SSE events from the response
+            const events = responseText.trim().split('\n\n');
+            expect(events).toHaveLength(3);
+
+            // Verify each event
+            for (let i = 0; i < events.length; i++) {
+                const event = events[i];
+                const lines = event.split('\n');
+                expect(lines[0]).toBe('event: update');
+
+                const dataLine = lines.find(line => line.startsWith('data: '));
+                expect(dataLine).toBeDefined();
+
+                const data = JSON.parse(dataLine!.substring(6)); // Remove 'data: ' prefix
+                expect(data.sequence).toBe(i + 1);
+                expect(data.data).toBe(`object ${i + 1}`);
+            }
+        });
+
+        test('should handle SSE streaming incrementally', async () => {
+            const response = await fetch(`${baseUrl}/api/v1/public/stream`);
+            expect(response.status).toBe(200);
+            expect(response.headers.get('content-type')).toBe('text/event-stream');
+
+            return new Promise<void>((resolve, reject) => {
+                // node-fetch returns a Node.js stream, cast properly
+                const stream = response.body as any; // Node.js Readable stream
+                let buffer = '';
+                const events: any[] = [];
+
+                stream.on('data', (chunk: Buffer) => {
+                    buffer += chunk.toString();
+
+                    // Parse complete SSE events from buffer
+                    const lines = buffer.split('\n');
+                    buffer = lines.pop() || ''; // Keep incomplete line in buffer
+
+                    let currentEvent = '';
+                    for (const line of lines) {
+                        if (line === '') {
+                            // Empty line = end of event
+                            if (currentEvent.trim()) {
+                                const eventData = parseSSEEvent(currentEvent);
+                                if (eventData) events.push(eventData);
+                            }
+                            currentEvent = '';
+                        } else {
+                            currentEvent += line + '\n';
+                        }
+                    }
+
+                    // Check if we have all expected events
+                    if (events.length >= 3) {
+                        // For Node.js streams, just remove listeners to "close"
+                        stream.removeAllListeners('data');
+                        stream.removeAllListeners('error');
+                        stream.removeAllListeners('end');
+
+                        try {
+                            expect(events).toHaveLength(3);
+                            expect(events[0]).toEqual({ sequence: 1, data: 'object 1' });
+                            expect(events[1]).toEqual({ sequence: 2, data: 'object 2' });
+                            expect(events[2]).toEqual({ sequence: 3, data: 'object 3' });
+                            resolve();
+                        } catch (error) {
+                            reject(error);
+                        }
+                    }
+                });
+
+                stream.on('error', reject);
+                stream.on('end', () => {
+                    // If we get here without 3 events, test failed
+                    if (events.length < 3) {
+                        reject(new Error(`Expected 3 events, got ${events.length}`));
+                    }
+                });
+            });
+        });
+
+        function parseSSEEvent(eventText: string): any | null {
+            const lines = eventText.split('\n');
+            let data = '';
+
+            for (const line of lines) {
+                if (line.startsWith('data: ')) {
+                    data = line.substring(6);
+                }
+            }
+
+            return data ? JSON.parse(data) : null;
+        }
+
         test('generateUrl should return correct URL for ping', () => {
             const url = client.generateUrl('common', 'ping');
             expect(url).toBe(`${baseUrl}/api/v1/public/ping`);