transit-kit 0.2.0 → 0.3.0

package/README.md

@@ -1 +1,4 @@
-# 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)

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.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/EndpointHandler.d.ts

@@ -1,6 +1,6 @@
 import { Request } from "express";
 import { HttpStatusCodes } from "../../constants/HttpStatusCodes";
 import { GenericResponse } from "./responses";
-export type ApiEndpointHandler<PathParams extends Record<string, string> | undefined = {}, 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> = (request: Request<PathParams, unknown, RequestBody, Query, Record<string, unknown>>) => Promise<Responses | {
     code: (typeof HttpStatusCodes)["InternalServerError_500"];
 }>;

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/HandlerFromDefinition.spec.d.ts

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

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

@@ -2,4 +2,4 @@ export type ExtractPathParams<Path extends string> = Path extends `${string}:${i
     [K in Param | keyof ExtractPathParams<Rest>]: string;
 } : Path extends `${string}:${infer Param}` ? {
     [K in Param]: string;
-} : undefined;
+} : {};

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

@@ -1,12 +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 { 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>): {
-    type: string;
-    definition: ApiEndpointDefinition<Path, Method, RequestBody, Query, ResponsesMap>;
+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>): {
+    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): 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.js

@@ -2,7 +2,6 @@ import expressAsyncHandler from "express-async-handler";
 import { isJsonResponse } from "./responses/jsonResponse";
 export function createApiEndpointHandler(definition, handler) {
     return {
-        type: "__API_ENDPOINT_DEFINITION__",
         definition,
         handler,
     };

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

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

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

@@ -0,0 +1,33 @@
+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({
+            meta: {
+                name: "",
+                description: "",
+                group: "",
+            },
+            method: "get",
+            path: "/test",
+            requestBodySchema: z.string(),
+            responseSchemas: {
+                200: {},
+            },
+        }, async () => {
+            return {
+                code: 200,
+            };
+        });
+        const server = createServer({
+            inDevMode: true,
+            port: 3000,
+            logger: false,
+        });
+        server.registerApiEndpoint(endpoint);
+        testRequest(server.expressApp).get("/test").expect(200);
+    });
+});

package/dist/server/server.d.ts

@@ -1,22 +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 { HandlerForDefinition } from "./handlers/api/HandlerFromDefinition";
 import { Logger } from "./utils/logging";
 export interface ServerConfig {
     inDevMode: boolean;
     port: number;
     logger: Logger | boolean;
-    endpoints: Array<{
-        endpointHandler: ApiEndpointHandler;
-        endpointDefinition: ApiEndpointDefinition<string, HttpMethod, z.ZodType, z.ZodType, {}>;
-    }>;
 }
 export interface Server {
     expressApp: Application;
     logger: Logger | boolean;
-    endpointDefinitions: ApiEndpointDefinition<string, HttpMethod, z.ZodType, z.ZodType, {}>[];
+    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(({ endpointDefinition, endpointHandler }) => {
-        registerApiEndpoint(app, endpointDefinition, endpointHandler);
-    });
     return {
         expressApp: app,
         logger: logger,
-        endpointDefinitions: endpoints.map((e) => e.endpointDefinition),
-        start: () => {
+        endpointDefinitions: [],
+        registerApiEndpoint(endpoint) {
+            registerApiEndpoint(app, endpoint);
+        },
+        start() {
             app.listen(port);
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "transit-kit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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",
@@ -42,6 +42,7 @@
   "devDependencies": {
     "@types/cookie-parser": "^1.4.9",
     "@types/express": "^5.0.0",
+    "@types/supertest": "^6.0.3",
     "@vitest/coverage-v8": "^4.0.15",
     "@vitest/eslint-plugin": "^1.5.2",
     "eslint": "^9.39.1",
@@ -49,6 +50,7 @@
     "eslint-plugin-prettier": "^5.5.4",
     "jiti": "^2.6.1",
     "prettier": "^3.7.4",
+    "supertest": "^7.1.4",
     "tslib": "2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.49.0",