transit-kit 0.3.0 → 0.4.0

package/README.md

@@ -2,3 +2,344 @@
 
 [![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.js

@@ -31,6 +31,24 @@ function extractQueryParameters(querySchema) {
         return [];
     }
 }
+function extractRequestSecuritySchemes(definition) {
+    const securitySchemes = definition.securitySchemes;
+    if (hasValue(securitySchemes)) {
+        return securitySchemes.map((schema) => {
+            switch (schema.type) {
+                case "http":
+                    return {
+                        [schema.name]: [],
+                    };
+                default:
+                    throw new Error(`Unsupported security scheme type: ${schema.type}`);
+            }
+        });
+    }
+    else {
+        return [];
+    }
+}
 function translateToOpenAPIPathItem(definition) {
     const { meta, path, method, requestBodySchema, querySchema, responseSchemas, } = definition;
     // 1. Path and Parameter extraction
@@ -80,6 +98,8 @@ function translateToOpenAPIPathItem(definition) {
         .reduce((acc, resp) => {
         return { ...acc, ...resp };
     }, {});
+    // 5. Security Requirements
+    const securityRequirements = extractRequestSecuritySchemes(definition);
     const operation = {
         operationId: meta.name,
         summary: meta.description,
@@ -88,12 +108,35 @@ function translateToOpenAPIPathItem(definition) {
         parameters: operationParameters,
         ...requestBody,
         responses,
+        security: securityRequirements,
     };
     const pathItem = {
         [method.toLowerCase()]: operation,
     };
     return [openApiPath, pathItem];
 }
+function extractSecuritySchemes(endpointDefinitions) {
+    const securitySchemes = Array.from(new Set(endpointDefinitions
+        .map((def) => def.securitySchemes)
+        .filter(hasValue)
+        .flat()));
+    const openApiSecuritySchemes = securitySchemes.map((scheme) => {
+        switch (scheme.type) {
+            case "http":
+                return {
+                    [scheme.name]: {
+                        type: "http",
+                        scheme: scheme.scheme,
+                    },
+                };
+            default:
+                throw new Error(`Unsupported security scheme type: ${scheme.type}`);
+        }
+    });
+    return openApiSecuritySchemes.reduce((acc, scheme) => {
+        return { ...acc, ...scheme };
+    }, {});
+}
 export async function generateOpenApiDoc(targetPath) {
     const serverModule = await import(path.resolve(process.cwd(), targetPath));
     const server = serverModule.default;
@@ -114,6 +157,7 @@ export async function generateOpenApiDoc(targetPath) {
             }
             return acc;
         }, {});
+        const securitySchemes = extractSecuritySchemes(endpointDefinitions);
         const openApiDocument = {
             openapi: "3.0.0",
             info: {
@@ -121,6 +165,9 @@ export async function generateOpenApiDoc(targetPath) {
                 version: "1.0.0",
             },
             paths: paths,
+            components: {
+                securitySchemes,
+            },
         };
         return openApiDocument;
     }

package/dist/cli/generateOpenApi.spec.js

@@ -47,6 +47,7 @@ describe("translateToOpenAPIPathItem", () => {
                         schema: { type: "string" },
                     },
                 ],
+                security: [],
                 responses: {
                     "200": {
                         description: "Response for status code 200",

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

@@ -1,16 +1,18 @@
 import z from "zod";
 import { HttpMethod } from "../../constants/HttpMethods";
+import { SecurityScheme } from "../../security/SecuritySchema";
 import { GenericResponseSchemaMap } from "./responses/index";
 export interface ApiEndpointMeta {
     name: string;
     group: string;
     description: string;
 }
-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> = {
+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, SecuritySchemes extends SecurityScheme<unknown>[] = SecurityScheme<unknown>[]> = {
     meta: ApiEndpointMeta;
     path: Path;
     method: Method;
     requestBodySchema?: RequestBody;
     querySchema?: Query;
     responseSchemas: ResponseMap;
+    securitySchemes?: SecuritySchemes;
 };

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

@@ -1,6 +1,11 @@
 import { Request } from "express";
 import { HttpStatusCodes } from "../../constants/HttpStatusCodes";
 import { GenericResponse } from "./responses";
-export type ApiEndpointHandler<PathParams extends Record<string, string> = {}, RequestBody = unknown, Query = unknown, Responses extends GenericResponse = never> = (request: Request<PathParams, unknown, RequestBody, Query, Record<string, unknown>>) => Promise<Responses | {
+export type ApiEndpointHandler<PathParams extends Record<string, string> = {}, RequestBody = unknown, Query = unknown, Responses extends GenericResponse = never, Caller = unknown> = (request: Request<PathParams, unknown, RequestBody, Query, Record<string, unknown>>, extractedRequestData: {
+    parameters: PathParams;
+    query: Query;
+    body: RequestBody;
+    caller: Caller;
+}) => Promise<Responses | {
     code: (typeof HttpStatusCodes)["InternalServerError_500"];
 }>;

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

@@ -1,11 +1,12 @@
 import z from "zod";
 import { HttpStatusCode } from "../../constants/HttpStatusCodes";
+import { SecurityScheme } from "../../security/SecuritySchema";
 import { Prettify } from "../../utils/types";
 import { ApiEndpointHandler } from "./EndpointHandler";
 import { ExtractPathParams } from "./PathParameters";
 import { EmptyResponse, EmptyResponseSchema } from "./responses/emptyResponse";
 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>, Exclude<Prettify<{
+export type HandlerForDefinition<Path extends string, RequestBody extends z.ZodType | undefined, Query extends z.ZodType | undefined, ResponsesMap extends GenericResponseSchemaMap, SecuritySchemas extends SecurityScheme<unknown>[] = []> = 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>>;
+}[keyof ResponsesMap]>, undefined>, SecuritySchemas extends SecurityScheme<infer Caller>[] ? Caller : unknown>;

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

@@ -1,11 +1,12 @@
 import z from "zod";
 import { HttpMethod } from "../../constants/HttpMethods";
+import { SecurityScheme } from "../../security/SecuritySchema";
 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: Prettify<ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponsesMap>>, handler: HandlerForDefinition<Path, 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, const SecuritySchemas extends SecurityScheme<unknown>[] = []>(definition: Prettify<ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponsesMap, SecuritySchemas>>, handler: HandlerForDefinition<Path, RequestBody, Query, ResponsesMap>): {
     definition: {
         meta: import("./EndpointDefinition").ApiEndpointMeta;
         path: Path;
@@ -13,6 +14,7 @@ export declare function createApiEndpointHandler<const ResponsesMap extends Gene
         requestBodySchema?: RequestBody | undefined;
         querySchema?: Query | undefined;
         responseSchemas: ResponsesMap;
+        securitySchemes?: SecuritySchemas | undefined;
     };
     handler: HandlerForDefinition<Path, RequestBody, Query, ResponsesMap>;
 };

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

@@ -8,7 +8,14 @@ export function createApiEndpointHandler(definition, handler) {
 }
 export function buildApiEndpointHandler(handler) {
     return expressAsyncHandler(async (request, response) => {
-        const result = await handler(request);
+        const caller = response.locals.caller;
+        const extractedRequestData = {
+            parameters: request.params,
+            query: request.query,
+            body: request.body,
+            caller,
+        };
+        const result = await handler(request, extractedRequestData);
         if (isJsonResponse(result)) {
             response.status(result.code).json(result.json);
         }

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
 export { createApiEndpointHandler } from "./handlers/api/createApiHandler";
+export { buildAuthenticationMiddleware } from "./middleware/auth";
 export { createServer, type Server, type ServerConfig } from "./server";
 declare const _default: {};
 export default _default;

package/dist/server/index.js

@@ -1,3 +1,4 @@
 export { createApiEndpointHandler } from "./handlers/api/createApiHandler";
+export { buildAuthenticationMiddleware } from "./middleware/auth";
 export { createServer } from "./server";
 export default {};

package/dist/server/middleware/auth.d.ts

@@ -0,0 +1,2 @@
+import { SecurityScheme } from "../security/SecuritySchema";
+export declare function buildAuthenticationMiddleware<Caller>(schemes: SecurityScheme<Caller>[]): import("express").RequestHandler<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>;

package/dist/server/middleware/auth.js

@@ -0,0 +1,13 @@
+import expressAsyncHandler from "express-async-handler";
+import { authenticate } from "../security/SecuritySchema";
+export function buildAuthenticationMiddleware(schemes) {
+    return expressAsyncHandler(async (request, response, next) => {
+        const caller = await authenticate(schemes, request);
+        if (caller == null) {
+            response.status(401).json({ message: "Unauthorized" });
+            return;
+        }
+        response.locals.caller = caller;
+        next();
+    });
+}

package/dist/server/security/SecuritySchema.d.ts

@@ -0,0 +1,5 @@
+import { Request } from "express";
+import { BasicAuthScheme } from "./basicAuth";
+import { BearerAuthScheme } from "./bearerAuth";
+export type SecurityScheme<Caller> = BasicAuthScheme<Caller> | BearerAuthScheme<Caller>;
+export declare function authenticate<Caller>(schemes: SecurityScheme<Caller>[], request: Request): Promise<Caller | null>;

package/dist/server/security/SecuritySchema.js

@@ -0,0 +1,14 @@
+import { buildBasicAuthenticator } from "./basicAuth";
+import { buildBearerAuthenticator } from "./bearerAuth";
+export async function authenticate(schemes, request) {
+    const authenticationResults = await Promise.all(schemes.map((scheme) => {
+        switch (scheme.scheme) {
+            case "basic":
+                return buildBasicAuthenticator(scheme)(request);
+            case "bearer":
+                return buildBearerAuthenticator(scheme)(request);
+        }
+    }));
+    const successfulAuthentication = authenticationResults.find((result) => result !== null);
+    return successfulAuthentication ?? null;
+}

package/dist/server/security/basicAuth.d.ts

@@ -0,0 +1,9 @@
+import { Request } from "express";
+export interface BasicAuthScheme<Caller = unknown> {
+    name: string;
+    type: "http";
+    scheme: "basic";
+    validateCaller: (username: string, password: string) => Promise<Caller | null>;
+}
+export declare function createBasicAuthSchema<Caller>(name: string, validateCaller: (username: string, password: string) => Promise<Caller | null>): BasicAuthScheme<Caller>;
+export declare function buildBasicAuthenticator<Caller>(scheme: BasicAuthScheme<Caller>): (request: Request) => Promise<Caller | null>;

package/dist/server/security/basicAuth.js

@@ -0,0 +1,21 @@
+import { hasNoValue } from "../utils/typeGuards";
+export function createBasicAuthSchema(name, validateCaller) {
+    return {
+        name,
+        type: "http",
+        scheme: "basic",
+        validateCaller,
+    };
+}
+export function buildBasicAuthenticator(scheme) {
+    return async (request) => {
+        const authHeader = request.headers.authorization;
+        if (hasNoValue(authHeader) || !authHeader.startsWith("Basic ")) {
+            return null;
+        }
+        const base64Credentials = authHeader.slice("Basic ".length);
+        const credentials = Buffer.from(base64Credentials, "base64").toString("utf-8");
+        const [username, password] = credentials.split(":", 2);
+        return scheme.validateCaller(username, password);
+    };
+}

package/dist/server/security/bearerAuth.d.ts

@@ -0,0 +1,9 @@
+import { Request } from "express";
+export interface BearerAuthScheme<Caller = unknown> {
+    name: string;
+    type: "http";
+    scheme: "bearer";
+    validateCaller: (token: string) => Promise<Caller | null>;
+}
+export declare function createBearerAuthSchema<Caller>(name: string, validateCaller: (token: string) => Promise<Caller | null>): BearerAuthScheme<Caller>;
+export declare function buildBearerAuthenticator<Caller>(scheme: BearerAuthScheme<Caller>): (request: Request) => Promise<Caller | null>;

package/dist/server/security/bearerAuth.js

@@ -0,0 +1,18 @@
+export function createBearerAuthSchema(name, validateCaller) {
+    return {
+        name,
+        type: "http",
+        scheme: "bearer",
+        validateCaller,
+    };
+}
+export function buildBearerAuthenticator(scheme) {
+    return async (request) => {
+        const authHeader = request.headers.authorization;
+        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
+            return null;
+        }
+        const token = authHeader.slice("Bearer ".length);
+        return scheme.validateCaller(token);
+    };
+}

package/dist/server/server.js

@@ -1,13 +1,18 @@
 import cookieParser from "cookie-parser";
 import express from "express";
 import { buildApiEndpointHandler } from "./handlers/api/createApiHandler";
+import { buildAuthenticationMiddleware } from "./middleware/auth";
 import { buildRequestLogger, buildResponseLogger } from "./middleware/logging";
 import { buildBodyValidatorMiddleware, buildQueryValidatorMiddleware, } from "./middleware/validation";
+import { isEmpty } from "./utils/funcs";
 import { NoOpLogger } from "./utils/logging";
 import { hasNoValue, hasValue } from "./utils/typeGuards";
 function registerApiEndpoint(expressApp, endpoint) {
     const { definition, handler } = endpoint;
     const handlerStack = [
+        hasValue(definition.securitySchemes) && !isEmpty(definition.securitySchemes)
+            ? buildAuthenticationMiddleware(definition.securitySchemes)
+            : null,
         hasValue(definition.querySchema)
             ? buildQueryValidatorMiddleware(definition.querySchema)
             : null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transit-kit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A declarative TypeScript framework for building type-safe Express.js APIs with automatic OpenAPI generation",
   "keywords": [
     "express",