transit-kit 0.2.1 → 0.3.1

package/README.md

@@ -1 +1,345 @@
-# declarative-server
+# transit-kit
+
+[![CI](https://github.com/D4rkr34lm/transit-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/D4rkr34lm/transit-kit/actions/workflows/ci.yml)
+[![Coverage Status](https://coveralls.io/repos/github/D4rkr34lm/transit-kit/badge.svg?branch=main)](https://coveralls.io/github/D4rkr34lm/transit-kit?branch=main)
+
+A declarative TypeScript framework for building type-safe Express.js APIs with automatic OpenAPI generation.
+
+## Features
+
+- 🔒 **Type-Safe**: End-to-end type safety with TypeScript and Zod validation
+- 📝 **Declarative API Definition**: Define your endpoints with clear, declarative syntax
+- 🔄 **Automatic Validation**: Request body and query parameter validation using Zod schemas
+- 📚 **OpenAPI Generation**: Automatically generate OpenAPI documentation from your endpoint definitions
+- ⚡ **Express.js Powered**: Built on top of the battle-tested Express.js framework
+- 🪵 **Built-in Logging**: Request and response logging out of the box
+- 🎯 **Path Parameters**: Full support for path parameters with type safety
+
+## Installation
+
+```bash
+npm install transit-kit
+```
+
+## Quick Start
+
+### 1. Create a Server
+
+```typescript
+import { createServer } from "transit-kit/server";
+
+const server = createServer({
+  port: 3000,
+  inDevMode: true,
+  logger: true, // or pass a custom logger (console-like interface)
+});
+```
+
+### 2. Define an API Endpoint
+
+```typescript
+import { createApiEndpointHandler } from "transit-kit/server";
+import z from "zod";
+
+// Define a simple GET endpoint
+const getUserEndpoint = createApiEndpointHandler(
+  {
+    meta: {
+      name: "Get User",
+      description: "Retrieves a user by ID",
+      group: "Users",
+    },
+    method: "get",
+    path: "/users/:userId",
+    responseSchemas: {
+      200: {
+        dataType: "application/json",
+        dataSchema: z.object({
+          id: z.string(),
+          name: z.string(),
+          email: z.string().email(),
+        }),
+      },
+      404: {}, // Empty response
+    },
+  },
+  async (request) => {
+    const { userId } = request.params;
+
+    // Simulate fetching user
+    const user = await fetchUser(userId);
+
+    if (!user) {
+      return {
+        code: 404,
+      };
+    }
+
+    return {
+      code: 200,
+      dataType: "application/json",
+      json: user,
+    };
+  },
+);
+```
+
+### 3. Define an Endpoint with Request Body and Query Parameters
+
+```typescript
+const createUserEndpoint = createApiEndpointHandler(
+  {
+    meta: {
+      name: "Create User",
+      description: "Creates a new user",
+      group: "Users",
+    },
+    method: "post",
+    path: "/users",
+    requestBodySchema: z.object({
+      name: z.string().min(1),
+      email: z.string().email(),
+      age: z.number().min(18),
+    }),
+    querySchema: z.object({
+      notify: z.boolean().optional(),
+    }),
+    responseSchemas: {
+      201: {
+        dataType: "application/json",
+        dataSchema: z.object({
+          id: z.string(),
+          name: z.string(),
+          email: z.string().email(),
+        }),
+      },
+      400: {
+        dataType: "application/json",
+        dataSchema: z.object({
+          error: z.string(),
+        }),
+      },
+    },
+  },
+  async (request) => {
+    // Request body is automatically validated and typed
+    const { name, email, age } = request.body;
+    const { notify } = request.query;
+
+    try {
+      const newUser = await createUser({ name, email, age });
+
+      if (notify) {
+        await sendNotification(email);
+      }
+
+      return {
+        code: 201,
+        dataType: "application/json",
+        json: newUser,
+      };
+    } catch (error) {
+      return {
+        code: 400,
+        dataType: "application/json",
+        json: { error: error.message },
+      };
+    }
+  },
+);
+```
+
+### 4. Register Endpoints and Start Server
+
+```typescript
+server.registerApiEndpoint(getUserEndpoint);
+server.registerApiEndpoint(createUserEndpoint);
+
+server.start();
+```
+
+## Response Types
+
+### JSON Response
+
+For endpoints that return JSON data:
+
+```typescript
+return {
+  code: 200,
+  dataType: "application/json",
+  json: { message: "Success", data: myData },
+};
+```
+
+### Empty Response
+
+For endpoints that return no content (e.g., 204 No Content):
+
+```typescript
+return {
+  code: 204,
+};
+```
+
+## OpenAPI Generation
+
+Transit-kit can automatically generate OpenAPI documentation from your endpoint definitions.
+
+### Using the CLI
+
+```bash
+npx transit-kit generate-openapi --output openapi.json --target ./src
+```
+
+Options:
+
+- `-o, --output <path>`: Output path for the generated OpenAPI document (default: `openapi.json`)
+- `-t, --target <path>`: Target path to search for endpoint definitions (default: `.`)
+
+### Programmatic Usage
+
+```typescript
+import { generateOpenApiDoc } from "transit-kit/cli";
+
+const openApiDoc = await generateOpenApiDoc("./src");
+```
+
+The generated OpenAPI document will include:
+
+- All registered endpoints
+- Request/response schemas
+- Path parameters
+- Query parameters
+- Request body schemas
+- Response schemas for all status codes
+
+## Configuration
+
+### Server Configuration
+
+```typescript
+interface ServerConfig {
+  inDevMode: boolean; // Enable development mode features
+  port: number; // Port to listen on
+  logger: Logger | boolean; // Logger instance or boolean to enable/disable
+}
+```
+
+### Custom Logger
+
+You can provide a custom logger with a console-like interface:
+
+```typescript
+const customLogger = {
+  log: (message: string) => {
+    /* custom logging */
+  },
+  error: (message: string) => {
+    /* custom error logging */
+  },
+  // ... other console methods
+};
+
+const server = createServer({
+  port: 3000,
+  inDevMode: false,
+  logger: customLogger,
+});
+```
+
+## API Reference
+
+### `createServer(config: ServerConfig): Server`
+
+Creates a new server instance with the specified configuration.
+
+### `createApiEndpointHandler(definition, handler)`
+
+Creates an API endpoint handler with type-safe request/response handling.
+
+**Definition properties:**
+
+- `meta`: Metadata about the endpoint (name, description, group)
+- `method`: HTTP method (`get`, `post`, `put`, `patch`, `delete`)
+- `path`: Express-style path with optional parameters (e.g., `/users/:userId`)
+- `requestBodySchema`: (Optional) Zod schema for request body validation
+- `querySchema`: (Optional) Zod schema for query parameter validation
+- `responseSchemas`: Map of status codes to response schemas
+
+### `server.registerApiEndpoint(endpoint)`
+
+Registers an endpoint with the server.
+
+### `server.start()`
+
+Starts the Express server on the configured port.
+
+## Examples
+
+### Complete Example
+
+```typescript
+import { createServer, createApiEndpointHandler } from "transit-kit/server";
+import z from "zod";
+
+// Create server
+const server = createServer({
+  port: 3000,
+  inDevMode: true,
+  logger: true,
+});
+
+// Define endpoints
+const listUsersEndpoint = createApiEndpointHandler(
+  {
+    meta: {
+      name: "List Users",
+      description: "Get a list of all users",
+      group: "Users",
+    },
+    method: "get",
+    path: "/users",
+    querySchema: z.object({
+      page: z.number().optional(),
+      limit: z.number().optional(),
+    }),
+    responseSchemas: {
+      200: {
+        dataType: "application/json",
+        dataSchema: z.array(
+          z.object({
+            id: z.string(),
+            name: z.string(),
+          }),
+        ),
+      },
+    },
+  },
+  async (request) => {
+    const { page = 1, limit = 10 } = request.query;
+    const users = await fetchUsers(page, limit);
+
+    return {
+      code: 200,
+      dataType: "application/json",
+      json: users,
+    };
+  },
+);
+
+server.registerApiEndpoint(listUsersEndpoint);
+server.start();
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Author
+
+D4rkr34lm

package/dist/cli/generateOpenApi.d.ts

@@ -1,2 +1,11 @@
+import { HttpMethod } from "../server/constants/HttpMethods";
+import { ApiEndpointDefinition } from "../server/handlers/api/EndpointDefinition";
+import { GenericResponseSchemaMap } from "../server/handlers/api/responses";
+import { ZodType } from "zod";
 import { OpenAPIV3 } from "openapi-types";
+declare function translateToOpenAPIPathItem(definition: ApiEndpointDefinition<string, HttpMethod, ZodType | undefined, ZodType | undefined, GenericResponseSchemaMap>): [string, OpenAPIV3.PathItemObject];
 export declare function generateOpenApiDoc(targetPath: string): Promise<OpenAPIV3.Document<{}>>;
+export declare const __TEST_EXPORTS: {
+    translateToOpenAPIPathItem: typeof translateToOpenAPIPathItem;
+};
+export {};

package/dist/cli/generateOpenApi.js

@@ -128,3 +128,6 @@ export async function generateOpenApiDoc(targetPath) {
         throw new Error("The specified module does not export a valid server instance.");
     }
 }
+export const __TEST_EXPORTS = {
+    translateToOpenAPIPathItem,
+};

package/dist/cli/generateOpenApi.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/generateOpenApi.spec.js

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import z from "zod";
+import { createApiEndpointHandler } from "../server";
+import { __TEST_EXPORTS } from "./generateOpenApi";
+const { translateToOpenAPIPathItem } = __TEST_EXPORTS;
+describe("translateToOpenAPIPathItem", () => {
+    it("should translate endpoint definitions to OpenAPI path items", () => {
+        const { definition } = createApiEndpointHandler({
+            method: "get",
+            path: "/users/:id",
+            meta: {
+                name: "getUser",
+                description: "Retrieve a user by ID",
+                group: "User",
+            },
+            responseSchemas: {
+                200: {
+                    dataType: "application/json",
+                    dataSchema: z.string(),
+                },
+            },
+        }, async (req) => {
+            return {
+                code: 200,
+                dataType: "application/json",
+                json: req.params.id,
+            };
+        });
+        const [path, pathItem] = translateToOpenAPIPathItem(definition);
+        const expectedPath = "/users/{id}";
+        const expectedSchema = {
+            $schema: "https://json-schema.org/draft/2020-12/schema",
+            type: "string",
+        };
+        const expectedPathItem = {
+            get: {
+                operationId: "getUser",
+                summary: "Retrieve a user by ID",
+                tags: ["User"],
+                description: "Retrieve a user by ID",
+                parameters: [
+                    {
+                        description: "Path parameter :id",
+                        name: "id",
+                        in: "path",
+                        required: true,
+                        schema: { type: "string" },
+                    },
+                ],
+                responses: {
+                    "200": {
+                        description: "Response for status code 200",
+                        content: {
+                            "application/json": {
+                                schema: expectedSchema,
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        expect(path).toBe(expectedPath);
+        expect(pathItem).toEqual(expectedPathItem);
+    });
+});

package/dist/server/handlers/api/ApiEndpoint.d.ts

@@ -0,0 +1,9 @@
+import z from "zod";
+import { HttpMethod } from "../../constants/HttpMethods";
+import { ApiEndpointDefinition } from "./EndpointDefinition";
+import { HandlerForDefinition } from "./HandlerFromDefinition";
+import { GenericResponseSchemaMap } from "./responses";
+export interface ApiEndpoint<Path extends string = string, Method extends HttpMethod = HttpMethod, RequestBody extends z.ZodType | undefined = undefined | z.ZodType, Query extends z.ZodType | undefined = undefined | z.ZodType, ResponseMap extends GenericResponseSchemaMap = GenericResponseSchemaMap, Handler extends HandlerForDefinition<Path, RequestBody, Query, ResponseMap> = HandlerForDefinition<Path, RequestBody, Query, ResponseMap>> {
+    definition: ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponseMap>;
+    handler: Handler;
+}

package/dist/server/handlers/api/ApiEndpoint.js

@@ -0,0 +1 @@
+export {};

package/dist/server/handlers/api/EndpointDefinition.d.ts

@@ -6,7 +6,7 @@ export interface ApiEndpointMeta {
     group: string;
     description: string;
 }
-export type ApiEndpointDefinition<Path extends string, Method extends HttpMethod, RequestBody extends z.ZodType | undefined, Query extends z.ZodType | undefined, ResponseMap extends GenericResponseSchemaMap> = {
+export type ApiEndpointDefinition<Path extends string = string, Method extends HttpMethod = HttpMethod, RequestBody extends z.ZodType | undefined = z.ZodType | undefined, Query extends z.ZodType | undefined = z.ZodType | undefined, ResponseMap extends GenericResponseSchemaMap = GenericResponseSchemaMap> = {
     meta: ApiEndpointMeta;
     path: Path;
     method: Method;

package/dist/server/handlers/api/HandlerFromDefinition.d.ts

@@ -4,8 +4,8 @@ import { Prettify } from "../../utils/types";
 import { ApiEndpointHandler } from "./EndpointHandler";
 import { ExtractPathParams } from "./PathParameters";
 import { EmptyResponse, EmptyResponseSchema } from "./responses/emptyResponse";
-import { GenericResponseSchemaMap } from "./responses/index";
+import { GenericResponse, GenericResponseSchemaMap } from "./responses/index";
 import { JsonResponseSchema, JsonResponseSchemaToResponseType } from "./responses/jsonResponse";
-export type HandlerForDefinition<Path extends string, RequestBody extends z.ZodType | undefined, Query extends z.ZodType | undefined, ResponsesMap extends GenericResponseSchemaMap> = ApiEndpointHandler<ExtractPathParams<Path>, RequestBody extends undefined ? undefined : z.infer<RequestBody>, Query extends undefined ? undefined : z.infer<Query>, Prettify<{
-    [K in keyof ResponsesMap]: K extends HttpStatusCode ? ResponsesMap[K] extends JsonResponseSchema ? JsonResponseSchemaToResponseType<K, ResponsesMap[K]> : ResponsesMap[K] extends EmptyResponseSchema ? EmptyResponse<K> : never : never;
-}[keyof ResponsesMap]>>;
+export type HandlerForDefinition<Path extends string, RequestBody extends z.ZodType | undefined, Query extends z.ZodType | undefined, ResponsesMap extends GenericResponseSchemaMap> = ApiEndpointHandler<ExtractPathParams<Path>, RequestBody extends undefined ? undefined : z.infer<RequestBody>, Query extends undefined ? undefined : z.infer<Query>, Exclude<Prettify<{
+    [K in keyof ResponsesMap]: K extends HttpStatusCode ? ResponsesMap[K] extends JsonResponseSchema ? JsonResponseSchemaToResponseType<K, ResponsesMap[K]> : ResponsesMap[K] extends EmptyResponseSchema ? EmptyResponse<K> : ResponsesMap[K] extends undefined ? never : GenericResponse : never;
+}[keyof ResponsesMap]>, undefined>>;

package/dist/server/handlers/api/createApiHandler.d.ts

@@ -1,11 +1,19 @@
 import z from "zod";
 import { HttpMethod } from "../../constants/HttpMethods";
+import { Prettify } from "../../utils/types";
 import { ApiEndpointDefinition } from "./EndpointDefinition";
 import { ApiEndpointHandler } from "./EndpointHandler";
 import { HandlerForDefinition } from "./HandlerFromDefinition";
 import { GenericResponse, GenericResponseSchemaMap } from "./responses";
-export declare function createApiEndpointHandler<const ResponsesMap extends GenericResponseSchemaMap, const Path extends string, const Method extends HttpMethod, const RequestBody extends z.ZodType | undefined = undefined, const Query extends z.ZodType | undefined = undefined>(definition: ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponsesMap>, handler: HandlerForDefinition<Path, RequestBody, Query, ResponsesMap>): {
-    definition: ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponsesMap>;
+export declare function createApiEndpointHandler<const ResponsesMap extends GenericResponseSchemaMap, const Path extends string, const Method extends HttpMethod, const RequestBody extends z.ZodType | undefined = undefined, const Query extends z.ZodType | undefined = undefined>(definition: Prettify<ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponsesMap>>, handler: HandlerForDefinition<Path, RequestBody, Query, ResponsesMap>): {
+    definition: {
+        meta: import("./EndpointDefinition").ApiEndpointMeta;
+        path: Path;
+        method: Method;
+        requestBodySchema?: RequestBody | undefined;
+        querySchema?: Query | undefined;
+        responseSchemas: ResponsesMap;
+    };
     handler: HandlerForDefinition<Path, RequestBody, Query, ResponsesMap>;
 };
-export declare function buildApiEndpointHandler(handler: ApiEndpointHandler<Record<string, string>, unknown, unknown, GenericResponse>): import("express").RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;
+export declare function buildApiEndpointHandler<Handler extends ApiEndpointHandler<Record<string, string>, unknown, unknown, GenericResponse>>(handler: Handler): import("express").RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;

package/dist/server/handlers/api/createApiHandler.spec.js

@@ -2,6 +2,7 @@ import { describe, it } from "vitest";
 import { createServer } from "../../server";
 import { createApiEndpointHandler } from "./createApiHandler";
 import testRequest from "supertest";
+import z from "zod";
 describe("createApiHandler", () => {
     it("can create an API handler", () => {
         const endpoint = createApiEndpointHandler({
@@ -12,6 +13,7 @@ describe("createApiHandler", () => {
             },
             method: "get",
             path: "/test",
+            requestBodySchema: z.string(),
             responseSchemas: {
                 200: {},
             },
@@ -24,8 +26,8 @@ describe("createApiHandler", () => {
             inDevMode: true,
             port: 3000,
             logger: false,
-            endpoints: [endpoint],
         });
+        server.registerApiEndpoint(endpoint);
         testRequest(server.expressApp).get("/test").expect(200);
     });
 });

package/dist/server/server.d.ts

@@ -1,23 +1,20 @@
 import { Application } from "express";
-import z from "zod";
-import { HttpMethod } from "./constants/HttpMethods";
 import { ApiEndpointDefinition } from "./handlers/api/EndpointDefinition";
-import { ApiEndpointHandler } from "./handlers/api/EndpointHandler";
-import { GenericResponse, GenericResponseSchemaMap } from "./handlers/api/responses";
+import { HandlerForDefinition } from "./handlers/api/HandlerFromDefinition";
 import { Logger } from "./utils/logging";
 export interface ServerConfig {
     inDevMode: boolean;
     port: number;
     logger: Logger | boolean;
-    endpoints: Array<{
-        handler: ApiEndpointHandler<Record<string, string>, any, any, GenericResponse>;
-        definition: ApiEndpointDefinition<string, HttpMethod, z.ZodType | undefined, z.ZodType | undefined, GenericResponseSchemaMap>;
-    }>;
 }
 export interface Server {
     expressApp: Application;
     logger: Logger | boolean;
-    endpointDefinitions: ApiEndpointDefinition<string, HttpMethod, z.ZodType | undefined, z.ZodType | undefined, GenericResponseSchemaMap>[];
+    endpointDefinitions: ApiEndpointDefinition[];
+    registerApiEndpoint<Definition extends ApiEndpointDefinition>({ definition, handler, }: {
+        definition: Definition;
+        handler: HandlerForDefinition<Definition["path"], Definition["requestBodySchema"], Definition["querySchema"], Definition["responseSchemas"]>;
+    }): void;
     start: () => void;
 }
 export declare function createServer(config: ServerConfig): Server;

package/dist/server/server.js

@@ -5,20 +5,21 @@ import { buildRequestLogger, buildResponseLogger } from "./middleware/logging";
 import { buildBodyValidatorMiddleware, buildQueryValidatorMiddleware, } from "./middleware/validation";
 import { NoOpLogger } from "./utils/logging";
 import { hasNoValue, hasValue } from "./utils/typeGuards";
-function registerApiEndpoint(expressApp, endpointDefinition, endpointHandler) {
+function registerApiEndpoint(expressApp, endpoint) {
+    const { definition, handler } = endpoint;
     const handlerStack = [
-        hasValue(endpointDefinition.querySchema)
-            ? buildQueryValidatorMiddleware(endpointDefinition.querySchema)
+        hasValue(definition.querySchema)
+            ? buildQueryValidatorMiddleware(definition.querySchema)
             : null,
-        hasValue(endpointDefinition.requestBodySchema)
-            ? buildBodyValidatorMiddleware(endpointDefinition.requestBodySchema)
+        hasValue(definition.requestBodySchema)
+            ? buildBodyValidatorMiddleware(definition.requestBodySchema)
             : null,
-        buildApiEndpointHandler(endpointHandler),
+        buildApiEndpointHandler(handler),
     ].filter(hasValue);
-    expressApp[endpointDefinition.method](endpointDefinition.path, handlerStack);
+    expressApp[definition.method](definition.path, handlerStack);
 }
 export function createServer(config) {
-    const { port, inDevMode, endpoints } = config;
+    const { port, inDevMode } = config;
     const logger = config.logger === true
         ? console
         : config.logger === false || hasNoValue(config.logger)
@@ -30,14 +31,14 @@ export function createServer(config) {
     app.use(cookieParser());
     app.use(buildRequestLogger(logger, inDevMode));
     app.use(buildResponseLogger(logger, inDevMode));
-    endpoints.forEach(({ definition, handler }) => {
-        registerApiEndpoint(app, definition, handler);
-    });
     return {
         expressApp: app,
         logger: logger,
-        endpointDefinitions: endpoints.map((e) => e.definition),
-        start: () => {
+        endpointDefinitions: [],
+        registerApiEndpoint(endpoint) {
+            registerApiEndpoint(app, endpoint);
+        },
+        start() {
             app.listen(port);
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transit-kit",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "A declarative TypeScript framework for building type-safe Express.js APIs with automatic OpenAPI generation",
   "keywords": [
     "express",
@@ -28,9 +28,9 @@
   ],
   "exports": {
     "./server": {
+      "types": "./dist/server/server.d.ts",
       "import": "./dist/server/index.js",
-      "require": "./dist/server/index.js",
-      "types": "./dist/server/server.d.ts"
+      "require": "./dist/server/index.js"
     }
   },
   "bin": "./dist/cli/cli.js",