transit-kit 0.1.0

package/dist/server/server.d.ts

@@ -0,0 +1,21 @@
+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 { Logger } from "./utils/logging";
+export interface ServerOptions {
+    inDevMode?: boolean;
+    port?: number;
+    logger?: Logger | boolean;
+}
+export interface Server {
+    _expressApp: Application;
+    _logger: Logger | boolean;
+    start: () => void;
+    registerApiEndpoint: (endpoint: {
+        endpointHandler: ApiEndpointHandler;
+        endpointDefinition: ApiEndpointDefinition<string, HttpMethod, z.ZodType, z.ZodType, {}>;
+    }) => void;
+}
+export declare function createServer(options: ServerOptions): Server;

package/dist/server/server.js

@@ -0,0 +1,43 @@
+import cookieParser from "cookie-parser";
+import express from "express";
+import { buildApiEndpointHandler } from "./handlers/api/createApiHandler";
+import { buildRequestLogger, buildResponseLogger } from "./middleware/logging";
+import { buildBodyValidatorMiddleware, buildQueryValidatorMiddleware, } from "./middleware/validation";
+import { NoOpLogger } from "./utils/logging";
+import { hasNoValue, hasValue } from "./utils/typeGuards";
+export function createServer(options) {
+    const { port = 3000, inDevMode = false } = options;
+    const logger = options.logger === true
+        ? console
+        : options.logger === false || hasNoValue(options.logger)
+            ? NoOpLogger
+            : options.logger;
+    const app = express();
+    app.use(express.json());
+    app.use(express.urlencoded({ extended: true }));
+    app.use(cookieParser());
+    app.use(buildRequestLogger(logger, inDevMode));
+    app.use(buildResponseLogger(logger, inDevMode));
+    return {
+        _expressApp: app,
+        _logger: logger,
+        start: () => {
+            app.listen(port);
+        },
+        registerApiEndpoint: ({ endpointDefinition, endpointHandler }) => {
+            registerApiEndpoint(app, endpointDefinition, endpointHandler);
+        },
+    };
+}
+function registerApiEndpoint(expressApp, endpointDefinition, endpointHandler) {
+    const handlerStack = [
+        hasValue(endpointDefinition.querySchema)
+            ? buildQueryValidatorMiddleware(endpointDefinition.querySchema)
+            : null,
+        hasValue(endpointDefinition.requestBodySchema)
+            ? buildBodyValidatorMiddleware(endpointDefinition.requestBodySchema)
+            : null,
+        buildApiEndpointHandler(endpointHandler),
+    ].filter(hasValue);
+    expressApp[endpointDefinition.method](endpointDefinition.path, handlerStack);
+}

package/dist/server/utils/funcs.d.ts

@@ -0,0 +1 @@
+export declare function isEmpty<T>(array: Array<T>): boolean;

package/dist/server/utils/funcs.js

@@ -0,0 +1,3 @@
+export function isEmpty(array) {
+    return array.length === 0;
+}

package/dist/server/utils/logging.d.ts

@@ -0,0 +1,3 @@
+export type Logger = Pick<Console, "log" | "info" | "error" | "warn">;
+export declare const NoOpLogger: Logger;
+export declare const DefaultLogger: Logger;

package/dist/server/utils/logging.js

@@ -0,0 +1,7 @@
+export const NoOpLogger = {
+    log: () => { },
+    info: () => { },
+    error: () => { },
+    warn: () => { },
+};
+export const DefaultLogger = console;

package/dist/server/utils/typeGuards.d.ts

@@ -0,0 +1,2 @@
+export declare function hasValue<T>(value: T | undefined | null): value is T;
+export declare function hasNoValue<T>(value: T | undefined | null): value is undefined | null;

package/dist/server/utils/typeGuards.js

@@ -0,0 +1,6 @@
+export function hasValue(value) {
+    return value !== undefined && value !== null;
+}
+export function hasNoValue(value) {
+    return value === undefined || value === null;
+}

package/dist/server/utils/types.d.ts

@@ -0,0 +1,3 @@
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/dist/server/utils/types.js

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

package/eslint-configs/eslint.base.config.js

@@ -0,0 +1,30 @@
+import { globalIgnores } from "eslint/config";
+import { config } from "typescript-eslint";
+
+import eslintJS from "@eslint/js";
+import prettierEslint from "eslint-plugin-prettier/recommended";
+import eslintTS from "typescript-eslint";
+
+export default config(
+  globalIgnores([
+    "*.config.{mjs|js|ts}",
+    "coverage",
+    "dist",
+    "generated",
+    "node_modules",
+  ]),
+  eslintJS.configs.recommended,
+  eslintTS.configs.recommended,
+  {
+    rules: {
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        {
+          argsIgnorePattern: "^_",
+          destructuredArrayIgnorePattern: "^_",
+        },
+      ],
+    },
+  },
+  prettierEslint,
+);

package/eslint-configs/eslint.node.config.js

@@ -0,0 +1,23 @@
+import globals from "globals";
+import { config } from "typescript-eslint";
+
+import baseConfig from "./eslint.base.config.js";
+
+export default config(baseConfig, {
+  files: ["**/*.ts"],
+  languageOptions: {
+    globals: {
+      ...globals.node,
+    },
+  },
+  rules: {
+    "@typescript-eslint/no-empty-object-type": "off",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        argsIgnorePattern: "^_",
+        varsIgnorePattern: "^_",
+      },
+    ],
+  },
+});

package/eslint-configs/eslint.test.config.js

@@ -0,0 +1,15 @@
+import eslintVitest from "@vitest/eslint-plugin";
+import globals from "globals";
+import { config } from "typescript-eslint";
+
+export default config(eslintVitest.configs.recommended, {
+  files: ["**/*.spec.ts"],
+  languageOptions: {
+    globals: {
+      ...globals.vitest,
+    },
+  },
+  rules: {
+    "vitest/expect-expect": "off",
+  },
+});

package/eslint.config.ts

@@ -0,0 +1,6 @@
+import { config } from "typescript-eslint";
+
+import nodeConfig from "./eslint-configs/eslint.node.config";
+import testConfig from "./eslint-configs/eslint.test.config";
+
+export default config(nodeConfig, testConfig);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "transit-kit",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": "https://github.com/D4rkr34lm/declarative-server",
+  "exports": {
+    "./server": {
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.js",
+      "types": "./dist/server/server.d.ts"
+    }
+  },
+  "bin": "./dist/cli/cli.js",
+  "scripts": {
+    "lint": "eslint",
+    "test": "vitest",
+    "build": "rm -rf ./dist && tsc"
+  },
+  "devDependencies": {
+    "@types/cookie-parser": "^1.4.9",
+    "@types/express": "^5.0.0",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/eslint-plugin": "^1.5.2",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jiti": "^2.6.1",
+    "prettier": "^3.7.4",
+    "tslib": "2.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.49.0",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^4.0.15"
+  },
+  "dependencies": {
+    "colors": "^1.4.0",
+    "commander": "^14.0.2",
+    "cookie-parser": "^1.4.7",
+    "express": "^4.21.1",
+    "express-async-handler": "^1.2.0",
+    "glob": "^13.0.0",
+    "openapi-types": "^12.1.3",
+    "zod": "^4.1.13"
+  }
+}

package/prettier.config.js

@@ -0,0 +1,14 @@
+/**
+ * @see https://prettier.io/docs/configuration
+ * @type {import("prettier").Config}
+ */
+const config = {
+  trailingComma: "all",
+  tabWidth: 2,
+  semi: true,
+  singleQuote: false,
+  printWidth: 80,
+  endOfLine: "lf",
+};
+
+export default config;

package/src/cli/cli.ts

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import fs from "fs";
+import { generateOpenApiDoc } from "./generateOpenApi";
+
+const program = new Command();
+
+program
+  .name("transit-kit")
+  .description("CLI of the transitKit backend framework")
+
+  .version("1.0.0");
+
+program
+  .command("generate-openapi")
+  .option(
+    "-o, --output <path>",
+
+    "Output path for the generated OpenAPI document",
+    "openapi.json",
+  )
+  .option(
+    "-t, --target <path>",
+    "Target path to search for endpoint definitions",
+    ".",
+  )
+  .action(async (options) => {
+    const { output, target } = options;
+
+    const generatedDoc = await generateOpenApiDoc(target);
+
+    fs.writeFileSync(output, JSON.stringify(generatedDoc, null, 2), {
+      encoding: "utf-8",
+    });
+    console.log(`OpenAPI document generated at: ${output}`);
+  });
+
+program.parse();

package/src/cli/generateOpenApi.ts

@@ -0,0 +1,217 @@
+import { glob } from "glob";
+import path from "path";
+import z from "zod";
+import { HttpMethod } from "../server/constants/HttpMethods";
+import { ApiEndpointDefinition } from "../server/handlers/api/EndpointDefinition";
+import { GenericResponseSchemaMap } from "../server/handlers/api/responses";
+import { hasNoValue, hasValue } from "../server/utils/typeGuards";
+
+import { ZodType } from "zod";
+
+import { OpenAPIV3 } from "openapi-types";
+import { isJsonResponseSchema } from "../server/handlers/api/responses/jsonResponse";
+
+async function findEndpointDefinitions(targetPath: string) {
+  const files = await glob("**/*.ts", {
+    cwd: path.resolve(process.cwd(), targetPath),
+    ignore: ["**/node_modules/**", "**/*.spec.ts"],
+  });
+
+  const definitions = await Promise.all(
+    files.map(async (file) => {
+      const absolutePath = path.resolve(file);
+      const fileUrl = path.toNamespacedPath(absolutePath).startsWith("/")
+        ? `file://${absolutePath}`
+        : `file:///${absolutePath}`;
+
+      try {
+        const module = await import(fileUrl);
+        if (module.default) {
+          const def = module.default.__API_ENDPOINT_DEFINITION__ as
+            | ApiEndpointDefinition<
+                string,
+                HttpMethod,
+                z.ZodType | undefined,
+                z.ZodType | undefined,
+                GenericResponseSchemaMap
+              >
+            | undefined;
+
+          if (hasNoValue(def)) {
+            return null;
+          }
+
+          return def;
+        } else {
+          return null;
+        }
+      } catch (error) {
+        console.error(`Error importing ${file}:`, error);
+        return null;
+      }
+    }),
+  );
+
+  return definitions.filter(hasValue);
+}
+
+function extractPathAndParameters(path: string): {
+  openApiPath: string;
+  parameters: OpenAPIV3.ParameterObject[];
+} {
+  const parameters: OpenAPIV3.ParameterObject[] =
+    path.match(/:([a-zA-Z0-9_]+)/g)?.map((param) => {
+      return {
+        name: param.substring(1),
+        in: "path",
+        required: true,
+        schema: { type: "string" },
+        description: `Path parameter ${param}`,
+      };
+    }) ?? [];
+
+  const openApiPath = path.replace(/:([a-zA-Z0-9_]+)/g, (_, paramName) => {
+    return `{${paramName}}`;
+  });
+
+  return { openApiPath, parameters };
+}
+
+function extractQueryParameters(
+  querySchema: ZodType,
+): OpenAPIV3.ParameterObject[] {
+  const querySchemaObject = z.toJSONSchema(querySchema);
+
+  if (querySchemaObject.properties) {
+    return Object.entries(querySchemaObject.properties).map(
+      ([name, schema]) => ({
+        name: name,
+        in: "query",
+        required: querySchemaObject.required?.includes(name) || false,
+        schema: schema as OpenAPIV3.SchemaObject,
+      }),
+    );
+  } else {
+    return [];
+  }
+}
+
+function translateToOpenAPIPathItem(
+  definition: ApiEndpointDefinition<
+    string,
+    HttpMethod,
+    ZodType | undefined,
+    ZodType | undefined,
+    GenericResponseSchemaMap
+  >,
+): [string, OpenAPIV3.PathItemObject] {
+  const {
+    meta,
+    path,
+    method,
+    requestBodySchema,
+    querySchema,
+    responseSchemas,
+  } = definition;
+
+  // 1. Path and Parameter extraction
+  const { openApiPath, parameters: pathParameters } =
+    extractPathAndParameters(path);
+
+  const queryParameters = hasValue(querySchema)
+    ? extractQueryParameters(querySchema)
+    : [];
+
+  const operationParameters = [...pathParameters, ...queryParameters];
+
+  const requestBody = hasValue(requestBodySchema)
+    ? {
+        requestBody: {
+          description: `${meta.name} Request Body`,
+          required: true,
+          content: {
+            "application/json": {
+              schema: z.toJSONSchema(
+                requestBodySchema,
+              ) as OpenAPIV3.SchemaObject, // Type assertion
+            },
+          },
+        },
+      }
+    : {};
+
+  // 4. Response Schema Translation
+  const responses = Object.entries(responseSchemas)
+    .map(([statusCode, responseDef]) => {
+      if (isJsonResponseSchema(responseDef)) {
+        const zodSchema = responseDef.dataSchema as ZodType;
+        const responseSchema = z.toJSONSchema(zodSchema);
+
+        return {
+          [statusCode]: {
+            description: `Response for status code ${statusCode}`,
+            content: {
+              [responseDef.dataType]: {
+                schema: responseSchema as OpenAPIV3.SchemaObject,
+              },
+            },
+          } as OpenAPIV3.ResponseObject,
+        };
+      } else {
+        return {
+          [statusCode]: {
+            description: `Response for status code ${statusCode}`,
+          } as OpenAPIV3.ResponseObject,
+        };
+      }
+    })
+    .reduce((acc, resp) => {
+      return { ...acc, ...resp };
+    }, {});
+
+  const operation: OpenAPIV3.OperationObject = {
+    operationId: meta.name,
+    summary: meta.description,
+    tags: [meta.group],
+    description: meta.description,
+    parameters: operationParameters,
+    ...requestBody,
+    responses,
+  };
+
+  const pathItem: OpenAPIV3.PathItemObject = {
+    [method.toLowerCase()]: operation,
+  };
+
+  return [openApiPath, pathItem];
+}
+
+export async function generateOpenApiDoc(targetPath: string) {
+  const definitions = await findEndpointDefinitions(targetPath);
+
+  const paths = definitions.reduce<OpenAPIV3.PathsObject>((acc, def) => {
+    const [openApiPath, pathItem] = translateToOpenAPIPathItem(def);
+
+    if (acc[openApiPath]) {
+      acc[openApiPath] = {
+        ...acc[openApiPath],
+        ...pathItem,
+      };
+    } else {
+      acc[openApiPath] = pathItem;
+    }
+
+    return acc;
+  }, {});
+
+  const openApiDocument: OpenAPIV3.Document = {
+    openapi: "3.0.0",
+    info: {
+      title: "Generated API",
+      version: "1.0.0",
+    },
+    paths: paths,
+  };
+
+  return openApiDocument;
+}

package/src/server/constants/HttpMethods.ts

@@ -0,0 +1,11 @@
+export const HttpMethods = {
+  get: "get",
+  post: "post",
+  put: "put",
+  delete: "delete",
+  patch: "patch",
+  head: "head",
+  options: "options",
+} as const;
+
+export type HttpMethod = (typeof HttpMethods)[keyof typeof HttpMethods];

package/src/server/constants/HttpStatusCodes.ts

@@ -0,0 +1,46 @@
+export const SuccessStatusCodes = {
+  Ok_200: 200,
+  Created_201: 201,
+  NoContent_204: 204,
+} as const;
+
+export type SuccessStatusCode =
+  (typeof SuccessStatusCodes)[keyof typeof SuccessStatusCodes];
+
+export const ClientErrorStatusCodes = {
+  BadRequest_400: 400,
+  Unauthorized_401: 401,
+  Forbidden_403: 403,
+  NotFound_404: 404,
+  Conflict_409: 409,
+} as const;
+
+export type ClientErrorStatusCode =
+  (typeof ClientErrorStatusCodes)[keyof typeof ClientErrorStatusCodes];
+
+export const ServerErrorStatusCodes = {
+  InternalServerError_500: 500,
+  NotImplemented_501: 501,
+  BadGateway_502: 502,
+  ServiceUnavailable_503: 503,
+} as const;
+
+export const ErrorStatusCodes = {
+  ...ClientErrorStatusCodes,
+  ...ServerErrorStatusCodes,
+} as const;
+
+export type ErrorStatusCode =
+  (typeof ErrorStatusCodes)[keyof typeof ErrorStatusCodes];
+
+export type ServerErrorStatusCode =
+  (typeof ServerErrorStatusCodes)[keyof typeof ServerErrorStatusCodes];
+
+export const HttpStatusCodes = {
+  ...SuccessStatusCodes,
+  ...ClientErrorStatusCodes,
+  ...ServerErrorStatusCodes,
+} as const;
+
+export type HttpStatusCode =
+  (typeof HttpStatusCodes)[keyof typeof HttpStatusCodes];

package/src/server/handlers/api/EndpointDefinition.ts

@@ -0,0 +1,24 @@
+import z from "zod";
+import { HttpMethod } from "../../constants/HttpMethods";
+import { GenericResponseSchemaMap } from "./responses/index";
+
+export interface ApiEndpointMeta {
+  name: string;
+  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,
+> = {
+  meta: ApiEndpointMeta;
+  path: Path;
+  method: Method;
+  requestBodySchema?: RequestBody;
+  querySchema?: Query;
+  responseSchemas: ResponseMap;
+};

package/src/server/handlers/api/EndpointHandler.ts

@@ -0,0 +1,24 @@
+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
+  | {
+      code: (typeof HttpStatusCodes)["InternalServerError_500"];
+    }
+>;