ts-typed-api 0.1.0

package/dist/handler.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRouteHandlers = registerRouteHandlers;
+const zod_1 = require("zod");
+// 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) {
+    routeHandlers.forEach((specificHandlerIterationItem) => {
+        const { domain, routeKey, handler } = specificHandlerIterationItem; // Use 'as any' for simplicity in destructuring union
+        const currentDomain = domain;
+        const currentRouteKey = routeKey;
+        // Use the passed apiDefinition object
+        const routeDefinition = apiDefinition.endpoints[currentDomain][currentRouteKey];
+        if (!routeDefinition) {
+            console.error(`Route definition not found for domain "${String(currentDomain)}" and routeKey "${String(currentRouteKey)}"`);
+            return;
+        }
+        const { path, method } = routeDefinition;
+        // Apply prefix from API definition if it exists
+        const fullPath = apiDefinition.prefix
+            ? `${apiDefinition.prefix.startsWith('/') ? apiDefinition.prefix : `/${apiDefinition.prefix}`}${path}`.replace(/\/+/g, '/')
+            : path;
+        const expressMiddleware = async (expressReq, expressRes) => {
+            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)
+                    : expressReq.params;
+                const parsedQuery = ('query' in routeDefinition && routeDefinition.query)
+                    ? routeDefinition.query.parse(expressReq.query)
+                    : expressReq.query;
+                const parsedBody = (method === 'POST' || method === 'PUT') && ('body' in routeDefinition && routeDefinition.body)
+                    ? routeDefinition.body.parse(expressReq.body)
+                    : expressReq.body;
+                // Construct TypedRequest using TDef, currentDomain, currentRouteKey
+                const finalTypedReq = {
+                    ...expressReq,
+                    params: parsedParams,
+                    query: parsedQuery,
+                    body: parsedBody,
+                    headers: expressReq.headers,
+                    cookies: expressReq.cookies,
+                    ip: expressReq.ip,
+                    ips: expressReq.ips,
+                    hostname: expressReq.hostname,
+                    protocol: expressReq.protocol,
+                    secure: expressReq.secure,
+                    xhr: expressReq.xhr,
+                    fresh: expressReq.fresh,
+                    stale: expressReq.stale,
+                    subdomains: expressReq.subdomains,
+                    path: expressReq.path,
+                    originalUrl: expressReq.originalUrl,
+                    baseUrl: expressReq.baseUrl,
+                    url: expressReq.url,
+                };
+                // Augment expressRes with the .respond method, using TDef
+                const typedExpressRes = expressRes;
+                typedExpressRes.respond = (status, dataForResponse) => {
+                    // Use the passed apiDefinition object
+                    const routeSchemaForHandler = apiDefinition.endpoints[currentDomain][currentRouteKey];
+                    const responseSchemaForStatus = routeSchemaForHandler.responses[status];
+                    if (!responseSchemaForStatus) {
+                        console.error(`No response schema defined for status ${status} in route ${String(currentDomain)}/${String(currentRouteKey)}`);
+                        typedExpressRes.status(500).json({
+                            // data: null, // data field might not be part of error schema for 500 if not using unified
+                            error: [{ field: "general", type: "general", message: "Internal server error: Undefined response schema for status." }]
+                        });
+                        return;
+                    }
+                    let responseBodyToValidate; // This will be the object { data: ..., error: ... }
+                    if (status === 422) {
+                        // For 422, dataForResponse is expected to be the UnifiedError array or null
+                        // The schema for 422 is errorUnifiedResponseSchema, expecting { error: UnifiedError }
+                        responseBodyToValidate = {
+                            data: null, // data is null for 422
+                            error: dataForResponse // dataForResponse should be UnifiedError for 422
+                        };
+                    }
+                    else {
+                        // For other statuses, dataForResponse is the actual data payload for the 'data' field
+                        // The schema is createSuccessUnifiedResponseSchema, expecting { data: ActualData }
+                        responseBodyToValidate = {
+                            data: dataForResponse,
+                            error: null // error is null for success
+                        };
+                    }
+                    // Validate the constructed responseBodyToValidate against the full schema for that status
+                    const validationResult = responseSchemaForStatus.safeParse(responseBodyToValidate);
+                    if (validationResult.success) {
+                        typedExpressRes.status(status).json(validationResult.data);
+                    }
+                    else {
+                        console.error(`FATAL: Constructed response body failed Zod validation for status ${status} in route ${String(currentDomain)}/${String(currentRouteKey)}. This indicates an issue with respond logic or schemas.`, validationResult.error.errors);
+                        console.error("Response body was:", responseBodyToValidate);
+                        typedExpressRes.status(500).json({
+                            // data: null,
+                            error: [{ field: "general", type: "general", message: "Internal server error: Constructed response failed validation." }]
+                        });
+                    }
+                };
+                const specificHandlerFn = handler;
+                await specificHandlerFn(finalTypedReq, typedExpressRes);
+            }
+            catch (error) {
+                if (error instanceof zod_1.z.ZodError) {
+                    const mappedErrors = error.errors.map(err => {
+                        let errorType = 'general';
+                        const pathZero = String(err.path[0]); // Ensure pathZero is a string
+                        if (pathZero === 'params')
+                            errorType = 'param'; // Corrected: 'params' from path maps to 'param' type
+                        else if (pathZero === 'query')
+                            errorType = 'query';
+                        else if (pathZero === 'body')
+                            errorType = 'body';
+                        return {
+                            field: err.path.join('.') || 'request',
+                            message: err.message,
+                            type: errorType,
+                        };
+                    });
+                    const errorResponseBody = { data: null, error: mappedErrors };
+                    const schema422 = routeDefinition.responses[422];
+                    if (schema422) {
+                        const validationResult = schema422.safeParse(errorResponseBody);
+                        if (validationResult.success) {
+                            expressRes.status(422).json(validationResult.data);
+                        }
+                        else {
+                            console.error("FATAL: Constructed 422 error response failed its own schema validation.", validationResult.error.errors);
+                            expressRes.status(500).json({ error: [{ field: "general", type: "general", message: "Internal server error constructing validation error response." }] });
+                        }
+                    }
+                    else {
+                        console.error("Error: 422 schema not found for route, sending raw Zod errors.");
+                        expressRes.status(422).json({ error: mappedErrors }); // Fallback
+                    }
+                }
+                else if (error instanceof Error) {
+                    console.error(`Error in ${method} ${path}:`, error.message, error.stack);
+                    expressRes.status(500).json({ error: [{ field: "general", type: "general", message: 'Internal server error' }] });
+                }
+                else {
+                    console.error(`Unknown error in ${method} ${path}:`, error);
+                    expressRes.status(500).json({ error: [{ field: "general", type: "general", message: 'An unknown error occurred' }] });
+                }
+            }
+        };
+        // Create middleware wrappers that include endpoint information
+        const middlewareWrappers = [];
+        if (middlewares && middlewares.length > 0) {
+            middlewares.forEach(middleware => {
+                const wrappedMiddleware = async (req, res, next) => {
+                    try {
+                        await middleware(req, res, next, { domain: currentDomain, routeKey: currentRouteKey });
+                    }
+                    catch (error) {
+                        next(error);
+                    }
+                };
+                middlewareWrappers.push(wrappedMiddleware);
+            });
+        }
+        // Register route with middlewares
+        const allHandlers = [...middlewareWrappers, expressMiddleware];
+        switch (method.toUpperCase()) {
+            case 'GET':
+                app.get(fullPath, ...allHandlers);
+                break;
+            case 'POST':
+                app.post(fullPath, ...allHandlers);
+                break;
+            case 'PUT':
+                app.put(fullPath, ...allHandlers);
+                break;
+            case 'DELETE':
+                app.delete(fullPath, ...allHandlers);
+                break;
+            default:
+                console.warn(`Unsupported HTTP method: ${method} for path ${fullPath}`);
+        }
+    });
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZodSchema = exports.RegisterHandlers = exports.CreateResponses = exports.CreateApiDefinition = exports.FetchHttpClientAdapter = exports.ApiClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "ApiClient", { enumerable: true, get: function () { return client_1.ApiClient; } });
+Object.defineProperty(exports, "FetchHttpClientAdapter", { enumerable: true, get: function () { return client_1.FetchHttpClientAdapter; } });
+var definition_1 = require("./definition");
+Object.defineProperty(exports, "CreateApiDefinition", { enumerable: true, get: function () { return definition_1.CreateApiDefinition; } });
+Object.defineProperty(exports, "CreateResponses", { enumerable: true, get: function () { return definition_1.CreateResponses; } });
+var object_handlers_1 = require("./object-handlers");
+Object.defineProperty(exports, "RegisterHandlers", { enumerable: true, get: function () { return object_handlers_1.RegisterHandlers; } });
+var zod_1 = require("zod");
+Object.defineProperty(exports, "ZodSchema", { enumerable: true, get: function () { return zod_1.z; } });

package/dist/object-handlers.d.ts

@@ -0,0 +1,16 @@
+import express from "express";
+import { ApiDefinitionSchema } from "./definition";
+import { TypedRequest, TypedResponse } from "./router";
+export type EndpointMiddleware = (req: express.Request, res: express.Response, next: express.NextFunction, endpointInfo: {
+    domain: string;
+    routeKey: string;
+}) => void | Promise<void>;
+type HandlerFunction<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef['endpoints'], TRouteKey extends keyof TDef['endpoints'][TDomain]> = (req: TypedRequest<TDef, TDomain, TRouteKey>, res: TypedResponse<TDef, TDomain, TRouteKey>) => Promise<void> | void;
+export type ObjectHandlers<TDef extends ApiDefinitionSchema> = {
+    [TDomain in keyof TDef['endpoints']]: {
+        [TRouteKey in keyof TDef['endpoints'][TDomain]]: HandlerFunction<TDef, TDomain, TRouteKey>;
+    };
+};
+export declare function RegisterHandlers<TDef extends ApiDefinitionSchema>(app: express.Express, apiDefinition: TDef, objectHandlers: ObjectHandlers<TDef>, middlewares?: EndpointMiddleware[]): void;
+export declare function makeObjectHandlerRegistrar<TDef extends ApiDefinitionSchema>(apiDefinition: TDef): (app: express.Express, objectHandlers: ObjectHandlers<TDef>, middlewares?: EndpointMiddleware[]) => void;
+export {};

package/dist/object-handlers.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegisterHandlers = RegisterHandlers;
+exports.makeObjectHandlerRegistrar = makeObjectHandlerRegistrar;
+const handler_1 = require("./handler");
+// Transform object-based handlers to array format
+function transformObjectHandlersToArray(objectHandlers) {
+    const handlerArray = [];
+    // Iterate through domains
+    for (const domain in objectHandlers) {
+        if (Object.prototype.hasOwnProperty.call(objectHandlers, domain)) {
+            const domainHandlers = objectHandlers[domain];
+            // Iterate through routes in this domain
+            for (const routeKey in domainHandlers) {
+                if (Object.prototype.hasOwnProperty.call(domainHandlers, routeKey)) {
+                    const handler = domainHandlers[routeKey];
+                    // Create the handler object in the format expected by registerRouteHandlers
+                    handlerArray.push({
+                        domain,
+                        routeKey,
+                        handler
+                    });
+                }
+            }
+        }
+    }
+    return handlerArray;
+}
+// Main utility function that registers object-based handlers
+function RegisterHandlers(app, apiDefinition, objectHandlers, middlewares) {
+    const handlerArray = transformObjectHandlersToArray(objectHandlers);
+    (0, handler_1.registerRouteHandlers)(app, apiDefinition, handlerArray, middlewares);
+}
+// Factory function to create a typed handler registrar for a specific API definition
+function makeObjectHandlerRegistrar(apiDefinition) {
+    return function (app, objectHandlers, middlewares) {
+        RegisterHandlers(app, apiDefinition, objectHandlers, middlewares);
+    };
+}

package/dist/openapiGenerator.d.ts

@@ -0,0 +1,2 @@
+import { ApiDefinitionSchema } from './router/definition';
+export declare function generateOpenApiSpec(definition: ApiDefinitionSchema): import("openapi3-ts/oas30").OpenAPIObject;

package/dist/openapiGenerator.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateOpenApiSpec = void 0;
+const zod_to_openapi_1 = require("@asteasolutions/zod-to-openapi");
+const zod_1 = require("zod");
+// Extend Zod with OpenAPI capabilities
+(0, zod_to_openapi_1.extendZodWithOpenApi)(zod_1.z);
+function generateOpenApiSpec(definition) {
+    const registry = new zod_to_openapi_1.OpenAPIRegistry();
+    // Helper to convert Zod schema to OpenAPI schema component
+    function registerSchema(name, schema) {
+        try {
+            return registry.register(name, schema); // Cast to any to handle complex Zod types
+        }
+        catch (error) {
+            console.warn(`Could not register schema ${name}: ${error.message}`);
+            // Fallback or simplified schema if registration fails
+            return registry.register(name, zod_1.z.object({}).openapi({ description: `Schema for ${name} (fallback due to registration error)` }));
+        }
+    }
+    // Function to convert Zod schema to OpenAPI Parameter Object or Request Body Object
+    function zodSchemaToOpenApiParameter(schema, inType) {
+        if (!schema || !(schema instanceof zod_1.z.ZodObject))
+            return []; // Ensure schema is a ZodObject
+        const shape = schema.shape;
+        return Object.entries(shape).map(([key, val]) => ({
+            name: key,
+            in: inType,
+            required: !val.isOptional(),
+            schema: registerSchema(`${inType}_${key}_${Date.now()}`, val),
+            description: val.description,
+        }));
+    }
+    function zodSchemaToOpenApiRequestBody(schema) {
+        if (!schema)
+            return undefined;
+        return {
+            required: true,
+            content: {
+                'application/json': {
+                    schema: registerSchema(`RequestBody_${Date.now()}`, schema), // Unique name
+                },
+            },
+        };
+    }
+    // Iterate over the API definition to register routes
+    Object.keys(definition).forEach(domainNameKey => {
+        // domainNameKey is a string, representing the domain like 'users', 'products'
+        const domain = definition[domainNameKey];
+        Object.keys(domain).forEach(routeNameKey => {
+            // routeNameKey is a string, representing the route name like 'getUser', 'createProduct'
+            const route = domain[routeNameKey];
+            const pathItem = {}; // Define PathItemObject structure
+            const parameters = [];
+            if (route.params) {
+                parameters.push(...zodSchemaToOpenApiParameter(route.params, 'path'));
+            }
+            if (route.query) {
+                parameters.push(...zodSchemaToOpenApiParameter(route.query, 'query'));
+            }
+            const requestBody = zodSchemaToOpenApiRequestBody(route.body);
+            const responses = {};
+            for (const statusCode in route.responses) {
+                const responseSchema = route.responses[parseInt(statusCode)];
+                if (responseSchema) {
+                    responses[statusCode] = {
+                        description: `Response for status code ${statusCode}`,
+                        content: {
+                            'application/json': {
+                                schema: registerSchema(`Response_${statusCode}_${routeNameKey}_${domainNameKey}`, responseSchema),
+                            },
+                        },
+                    };
+                }
+            }
+            // Add 422 response if not already defined, as it's a default in createResponses
+            // Assuming route.responses[422] would exist if it's a standard part of the definition
+            if (!responses['422'] && route.responses && route.responses[422]) {
+                responses['422'] = {
+                    description: 'Validation Error',
+                    content: {
+                        'application/json': {
+                            schema: registerSchema(`Response_422_${routeNameKey}_${domainNameKey}`, route.responses[422]),
+                        },
+                    },
+                };
+            }
+            const operation = {
+                summary: `${domainNameKey} - ${routeNameKey}`,
+                tags: [domainNameKey],
+                parameters: parameters.length > 0 ? parameters : undefined,
+                requestBody: requestBody,
+                responses: responses,
+            };
+            // Register the route with the registry
+            // The path needs to be transformed from Express-style (:param) to OpenAPI-style ({param})
+            const openApiPath = route.path.replace(/:(\w+)/g, '{$1}');
+            registry.registerPath({
+                method: route.method.toLowerCase(),
+                path: openApiPath,
+                ...operation,
+                // Add description or other OpenAPI fields if available in RouteSchema
+            });
+        });
+    });
+    // Generate the OpenAPI document
+    const generator = new zod_to_openapi_1.OpenApiGeneratorV3(registry.definitions);
+    const openApiDocument = generator.generateDocument({
+        openapi: '3.0.0',
+        info: {
+            title: 'My API',
+            version: '1.0.0',
+            description: 'Automatically generated OpenAPI specification',
+        },
+        servers: [{ url: '/api' }], // Adjust as needed
+    });
+    return openApiDocument;
+}
+exports.generateOpenApiSpec = generateOpenApiSpec;

package/dist/router/definition.d.ts

@@ -0,0 +1,118 @@
+import { z, ZodTypeAny, ZodType } from 'zod';
+export declare class TsTypeMarker<T> {
+    readonly _isTsTypeMarker = true;
+    readonly _type: T;
+    constructor();
+}
+export declare function CustomResponse<T>(): TsTypeMarker<T>;
+type InputSchemaOrMarker = ZodTypeAny | TsTypeMarker<any>;
+declare const unifiedErrorSchema: z.ZodNullable<z.ZodArray<z.ZodObject<{
+    field: z.ZodString;
+    type: z.ZodEnum<["body", "query", "param", "general"]>;
+    message: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    field: string;
+    type: "param" | "body" | "query" | "general";
+    message: string;
+}, {
+    field: string;
+    type: "param" | "body" | "query" | "general";
+    message: string;
+}>, "many">>;
+export type UnifiedError = z.infer<typeof unifiedErrorSchema>;
+declare const errorUnifiedResponseSchema: z.ZodObject<{
+    error: z.ZodEffects<z.ZodNullable<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        type: z.ZodEnum<["body", "query", "param", "general"]>;
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        field: string;
+        type: "param" | "body" | "query" | "general";
+        message: string;
+    }, {
+        field: string;
+        type: "param" | "body" | "query" | "general";
+        message: string;
+    }>, "many">>, {
+        field: string;
+        type: "param" | "body" | "query" | "general";
+        message: string;
+    }[] | null, {
+        field: string;
+        type: "param" | "body" | "query" | "general";
+        message: string;
+    }[] | null>;
+}, "strip", z.ZodTypeAny, {
+    error: {
+        field: string;
+        type: "param" | "body" | "query" | "general";
+        message: string;
+    }[] | null;
+}, {
+    error: {
+        field: string;
+        type: "param" | "body" | "query" | "general";
+        message: string;
+    }[] | null;
+}>;
+export declare const HttpSuccessCodes: readonly [200, 201, 202, 204];
+export declare const HttpClientErrorCodes: readonly [400, 401, 403, 404, 409];
+export declare const HttpServerErrorCodes: readonly [500];
+export type HttpSuccessStatusCode = typeof HttpSuccessCodes[number];
+export type HttpClientErrorStatusCode = typeof HttpClientErrorCodes[number];
+export type HttpServerErrorStatusCode = typeof HttpServerErrorCodes[number];
+export type AllowedInputStatusCode = HttpSuccessStatusCode | HttpClientErrorStatusCode | HttpServerErrorStatusCode;
+export type AllowedResponseStatusCode = AllowedInputStatusCode | 422;
+type CreateResponsesReturnType<InputSchemas extends Partial<Record<AllowedInputStatusCode, InputSchemaOrMarker>>> = {
+    [KStatus in keyof InputSchemas]: InputSchemas[KStatus] extends TsTypeMarker<infer T> ? z.ZodObject<{
+        data: ZodType<T, z.ZodTypeDef, T>;
+    }> : InputSchemas[KStatus] extends ZodTypeAny ? z.ZodObject<{
+        data: InputSchemas[KStatus];
+    }> : never;
+} & {
+    422: typeof errorUnifiedResponseSchema;
+};
+export declare function createResponses<TInputMap extends Partial<Record<AllowedInputStatusCode, InputSchemaOrMarker>>>(schemas: TInputMap): CreateResponsesReturnType<TInputMap>;
+export interface RouteSchema {
+    path: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
+    params?: ZodTypeAny;
+    query?: ZodTypeAny;
+    body?: ZodTypeAny;
+    responses: Record<number, ZodTypeAny>;
+}
+export type ApiDefinitionSchema = Record<string, Record<string, RouteSchema>>;
+export declare function createApiDefinition<T extends ApiDefinitionSchema>(definition: T): T;
+export type ApiRouteKey<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef> = keyof TDef[TDomain];
+export type ApiRoute<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef[TDomain][TRouteName];
+export type InferDataFromUnifiedResponse<S extends ZodTypeAny> = S extends z.ZodVoid ? void : z.infer<S> extends {
+    data: infer D;
+} ? D extends null ? null : D extends (infer ActualD | null) ? ActualD extends void ? void : ActualD : D : never;
+export type ApiResponse<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef[TDomain][TRouteName] extends {
+    responses: infer R;
+} ? R extends {
+    200: infer R200 extends ZodTypeAny;
+} ? InferDataFromUnifiedResponse<R200> : R extends {
+    201: infer R201 extends ZodTypeAny;
+} ? InferDataFromUnifiedResponse<R201> : R extends {
+    204: infer R204 extends ZodTypeAny;
+} ? InferDataFromUnifiedResponse<R204> : any : any;
+export type ApiBody<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef[TDomain][TRouteName] extends {
+    body: infer B extends z.ZodTypeAny;
+} ? z.infer<B> : Record<string, any>;
+export type ApiParams<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef[TDomain][TRouteName] extends {
+    params: infer P extends z.ZodTypeAny;
+} ? z.infer<P> : Record<string, any>;
+export type ApiQuery<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef[TDomain][TRouteName] extends {
+    query: infer Q extends z.ZodTypeAny;
+} ? z.infer<Q> : Record<string, any>;
+export type ApiClientBody<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef[TDomain][TRouteName] extends {
+    body: infer B extends ZodTypeAny;
+} ? z.input<B> : undefined;
+export type ApiClientParams<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef[TDomain][TRouteName] extends {
+    params: infer P extends ZodTypeAny;
+} ? z.input<P> : undefined;
+export type ApiClientQuery<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends ApiRouteKey<TDef, TDomain>> = TDef[TDomain][TRouteName] extends {
+    query: infer Q extends ZodTypeAny;
+} ? z.input<Q> : undefined;
+export {};

package/dist/router/definition.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiDefinition = exports.createResponses = exports.HttpServerErrorCodes = exports.HttpClientErrorCodes = exports.HttpSuccessCodes = exports.CustomResponse = exports.TsTypeMarker = void 0;
+const zod_1 = require("zod");
+// Marker class for raw TypeScript types
+class TsTypeMarker {
+    _isTsTypeMarker = true;
+    _type; // Phantom type, used for inference
+    constructor() {
+        // This constructor doesn't need to do anything with T at runtime.
+        // T is purely a compile-time construct.
+    }
+}
+exports.TsTypeMarker = TsTypeMarker;
+// Helper function to create a TsTypeMarker instance
+function CustomResponse() {
+    return new TsTypeMarker();
+}
+exports.CustomResponse = CustomResponse;
+// Define the structure for error details
+const errorDetailSchema = zod_1.z.object({
+    field: zod_1.z.string(),
+    type: zod_1.z.enum(['body', 'query', 'param', 'general']),
+    message: zod_1.z.string(),
+});
+// Define the schema for the error list
+const unifiedErrorSchema = zod_1.z.array(errorDetailSchema).nullable(); // Nullable if no errors
+// 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(dataSchema) {
+    return zod_1.z.object({
+        data: dataSchema, // Data is present as per dataSchema (can be nullable if dataSchema itself is)
+    });
+}
+// Schema for error responses (e.g., 422 Validation Error)
+// Ensures 'data' is null and 'error' is populated.
+const errorUnifiedResponseSchema = zod_1.z.object({
+    error: unifiedErrorSchema.refine(val => val !== null, { message: "Error list cannot be null for errorUnifiedResponseSchema" }), // Error list is mandatory
+});
+// Define allowed HTTP status codes
+exports.HttpSuccessCodes = [200, 201, 202, 204];
+exports.HttpClientErrorCodes = [400, 401, 403, 404, 409]; // 422 is handled separately
+exports.HttpServerErrorCodes = [500];
+// Helper function to create response schemas with unified structure and default 422 error
+// Schemas input is now constrained to use AllowedInputStatusCode as keys.
+function createResponses(schemas) {
+    const builtResult = {}; // Using any for intermediate dynamic construction.
+    for (const stringStatusKey in schemas) {
+        if (Object.prototype.hasOwnProperty.call(schemas, stringStatusKey)) {
+            const numericKey = parseInt(stringStatusKey);
+            const schemaOrMarker = schemas[numericKey];
+            if (schemaOrMarker) { // Check if schemaOrMarker is defined (due to Partial)
+                if (schemaOrMarker instanceof TsTypeMarker) {
+                    // For TsTypeMarker, create a ZodObject with data typed as z.any() at runtime.
+                    // The actual type T is carried by CreateResponsesReturnType for compile-time inference.
+                    builtResult[numericKey] = zod_1.z.object({
+                        data: zod_1.z.any(), // Runtime placeholder
+                    });
+                }
+                else if (schemaOrMarker instanceof zod_1.ZodType) { // It's a Zod schema
+                    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.
+            }
+        }
+    }
+    // Always set/overwrite the 422 response to use errorUnifiedResponseSchema
+    builtResult[422] = errorUnifiedResponseSchema;
+    // Cast to the more specific return type at the end.
+    // This is safe if builtResult's structure matches CreateResponsesReturnType<TInputMap>.
+    return builtResult;
+}
+exports.createResponses = createResponses;
+// Helper function to ensure the definition conforms to ApiDefinitionSchema
+// while preserving the literal types of the passed object.
+function createApiDefinition(definition) {
+    return definition;
+}
+exports.createApiDefinition = createApiDefinition;

package/dist/router/router.d.ts

@@ -0,0 +1,29 @@
+import express from "express";
+import { ApiDefinitionSchema, ApiBody, ApiParams, ApiQuery, InferDataFromUnifiedResponse } from './definition';
+export interface TypedRequest<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteKey extends keyof TDef[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>> extends express.Request<P, any, ReqBody, Q, L> {
+}
+type ResponseDataForStatus<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends keyof TDef[TDomain], TStatus extends keyof TDef[TDomain][TRouteName]['responses'] & number> = InferDataFromUnifiedResponse<TDef[TDomain][TRouteName]['responses'][TStatus]>;
+type RespondFunction<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends keyof TDef[TDomain]> = <TStatusLocal extends keyof TDef[TDomain][TRouteName]['responses'] & number>(status: TStatusLocal, data: ResponseDataForStatus<TDef, TDomain, TRouteName, TStatusLocal>) => void;
+export interface TypedResponse<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteName extends keyof TDef[TDomain], L extends Record<string, any> = Record<string, any>> extends express.Response<any, L> {
+    respond: RespondFunction<TDef, TDomain, TRouteName>;
+    json: <B = any>(body: B) => this;
+}
+export declare function createRouteHandler<TDef extends ApiDefinitionSchema, TDomain extends keyof TDef, TRouteKey extends keyof TDef[TDomain]>(domain: TDomain, routeKey: TRouteKey, handler: (req: TypedRequest<TDef, TDomain, TRouteKey>, res: TypedResponse<TDef, TDomain, TRouteKey>) => Promise<void> | void): {
+    domain: TDomain;
+    routeKey: TRouteKey;
+    handler: (req: TypedRequest<TDef, TDomain, TRouteKey>, res: TypedResponse<TDef, TDomain, TRouteKey>) => Promise<void> | void;
+};
+export declare function makeRouteHandlerCreator<TDef extends ApiDefinitionSchema>(): <TDomain extends keyof TDef, TRouteKey extends keyof TDef[TDomain]>(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>>, res: TypedResponse<TDef, TDomain, TRouteKey, Record<string, any>>) => Promise<void> | void) => {
+    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>>, res: TypedResponse<TDef, TDomain, TRouteKey, Record<string, any>>) => void | Promise<void>;
+};
+export type SpecificRouteHandler<TDef extends ApiDefinitionSchema> = {
+    [TDomain_ in keyof TDef]: {
+        [TRouteKey_ in keyof TDef[TDomain_]]: ReturnType<typeof createRouteHandler<TDef, TDomain_, TRouteKey_>>;
+    }[keyof TDef[TDomain_]];
+}[keyof TDef];
+export declare function registerRouteHandlers<TDef extends ApiDefinitionSchema>(app: express.Express, apiDefinition: TDef, // Pass the actual API definition object
+routeHandlers: Array<SpecificRouteHandler<TDef>>): void;
+export {};