transit-kit 0.1.0

package/src/server/handlers/api/HandlerFormDefinition.spec.ts

@@ -0,0 +1,120 @@
+import { Request } from "express";
+import { describe, expectTypeOf, it } from "vitest";
+import z from "zod";
+import { HandlerForDefinition } from "./HandlerFromDefinition";
+
+describe("HandlerFromDefinition", () => {
+  it("can infer handler responses correctly (Empty)", () => {
+    type Handler = HandlerForDefinition<
+      "/test",
+      undefined,
+      undefined,
+      {
+        200: {};
+      }
+    >;
+
+    type Expected = (
+      request: Request<
+        undefined,
+        unknown,
+        undefined,
+        undefined,
+        Record<string, unknown>
+      >,
+    ) => Promise<
+      | {
+          code: 200;
+        }
+      | {
+          code: 500;
+        }
+    >;
+
+    expectTypeOf<Handler>().toEqualTypeOf<Expected>();
+  });
+
+  it("can infer handler responses correctly (Json)", () => {
+    const _data = z.object({
+      a: z.number(),
+    });
+
+    type Handler = HandlerForDefinition<
+      "/test",
+      undefined,
+      undefined,
+      {
+        200: {
+          dataType: "application/json";
+          dataSchema: typeof _data;
+        };
+      }
+    >;
+
+    type Expected = (
+      request: Request<
+        undefined,
+        unknown,
+        undefined,
+        undefined,
+        Record<string, unknown>
+      >,
+    ) => Promise<
+      | {
+          code: 200;
+          dataType: "application/json";
+          json: {
+            a: number;
+          };
+        }
+      | {
+          code: 500;
+        }
+    >;
+
+    expectTypeOf<Handler>().toEqualTypeOf<Expected>();
+  });
+
+  it("can infer handler responses correctly (Multiple)", () => {
+    const _data = z.object({
+      a: z.number(),
+    });
+
+    type Handler = HandlerForDefinition<
+      "/test",
+      undefined,
+      undefined,
+      {
+        200: {
+          dataType: "application/json";
+          dataSchema: typeof _data;
+        };
+        400: {};
+      }
+    >;
+
+    type Expected = (
+      request: Request<
+        undefined,
+        unknown,
+        undefined,
+        undefined,
+        Record<string, unknown>
+      >,
+    ) => Promise<
+      | {
+          code: 200;
+          dataType: "application/json";
+          json: {
+            a: number;
+          };
+        }
+      | { code: 400 }
+      | {
+          code: 500;
+        }
+    >;
+
+    expectTypeOf<Handler>().toEqualTypeOf<Expected>();
+  });
+});

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

@@ -0,0 +1,33 @@
+import z from "zod";
+import { HttpStatusCode } from "../../constants/HttpStatusCodes";
+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 {
+  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]
+  >
+>;

package/src/server/handlers/api/PathParameters.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expectTypeOf, it } from "vitest";
+import { ExtractPathParams } from "./PathParameters";
+
+describe("ExtractPathParameters", () => {
+  it("can infer the parameter types of a path", () => {
+    type Path = "/test/path/with/:testId";
+    type ParamObject = ExtractPathParams<Path>;
+
+    expectTypeOf<ParamObject>().toEqualTypeOf<{ testId: string }>();
+  });
+
+  it("can infer multiple params", () => {
+    type Path = "/test/path/with/:testId/and/:otherId";
+    type ParamObject = ExtractPathParams<Path>;
+
+    expectTypeOf<ParamObject>().toEqualTypeOf<{
+      testId: string;
+      otherId: string;
+    }>();
+  });
+
+  it("can infer correctly if no param is present", () => {
+    type Path = "/test/path/without";
+    type ParamObject = ExtractPathParams<Path>;
+
+    expectTypeOf<ParamObject>().toEqualTypeOf<undefined>();
+  });
+});

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

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

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

@@ -0,0 +1,44 @@
+import { Request, Response } from "express";
+import expressAsyncHandler from "express-async-handler";
+import z from "zod";
+import { HttpMethod } from "../../constants/HttpMethods";
+import { ApiEndpointDefinition } from "./EndpointDefinition";
+import { ApiEndpointHandler } from "./EndpointHandler";
+import { HandlerForDefinition } from "./HandlerFromDefinition";
+import { GenericResponseSchemaMap } from "./responses";
+import { isJsonResponse } from "./responses/jsonResponse";
+
+export 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>,
+) {
+  return {
+    __API_ENDPOINT_DEFINITION__: definition,
+    definition,
+    handler,
+  };
+}
+
+export function buildApiEndpointHandler(handler: ApiEndpointHandler) {
+  return expressAsyncHandler(async (request: Request, response: Response) => {
+    const result = await handler(request);
+
+    if (isJsonResponse(result)) {
+      response.status(result.code).json(result.json);
+    } else {
+      response.status(result.code).send();
+    }
+  });
+}

package/src/server/handlers/api/responses/emptyResponse.ts

@@ -0,0 +1,12 @@
+import { HttpStatusCode } from "../../../constants/HttpStatusCodes";
+
+export interface EmptyResponseSchema {}
+
+export interface EmptyResponse<Code extends HttpStatusCode = HttpStatusCode> {
+  code: Code;
+}
+
+export type EmptyResponseSchemaToResponseType<
+  Code extends HttpStatusCode,
+  _ extends EmptyResponseSchema,
+> = EmptyResponse<Code>;

package/src/server/handlers/api/responses/index.ts

@@ -0,0 +1,15 @@
+import {
+  ClientErrorStatusCode,
+  SuccessStatusCode,
+} from "../../../constants/HttpStatusCodes";
+import { EmptyResponse, EmptyResponseSchema } from "./emptyResponse";
+import { JsonResponse, JsonResponseSchema } from "./jsonResponse";
+
+export type GenericResponseSchemaMap = {
+  [K in SuccessStatusCode | ClientErrorStatusCode]?:
+    | EmptyResponseSchema
+    | JsonResponseSchema
+    | undefined;
+};
+
+export type GenericResponse = EmptyResponse | JsonResponse;

package/src/server/handlers/api/responses/jsonResponse.ts

@@ -0,0 +1,44 @@
+import z from "zod";
+import { HttpStatusCode } from "../../../constants/HttpStatusCodes";
+import { hasValue } from "../../../utils/typeGuards";
+
+export interface JsonResponseSchema<DataSchema extends z.ZodType = z.ZodType> {
+  dataType: "application/json";
+  dataSchema: DataSchema;
+}
+
+export interface JsonResponse<
+  Code extends HttpStatusCode = HttpStatusCode,
+  Data = unknown,
+> {
+  code: Code;
+  dataType: "application/json";
+  json: Data;
+}
+
+export type JsonResponseSchemaToResponseType<
+  Code extends HttpStatusCode,
+  Schema extends JsonResponseSchema,
+> =
+  Schema extends JsonResponseSchema<infer DataSchema>
+    ? JsonResponse<Code, z.infer<DataSchema>>
+    : never;
+
+export function isJsonResponseSchema(
+  value: unknown,
+): value is JsonResponseSchema {
+  return (
+    typeof value === "object" &&
+    hasValue(value) &&
+    "dataType" in value &&
+    value.dataType === "application/json"
+  );
+}
+export function isJsonResponse(value: unknown): value is JsonResponse {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "dataType" in value &&
+    value.dataType === "application/json"
+  );
+}

package/src/server/index.ts

@@ -0,0 +1,4 @@
+export { createApiEndpointHandler } from "./handlers/api/createApiHandler";
+export { createServer, type Server, type ServerOptions } from "./server";
+
+export default {};

package/src/server/middleware/logging.ts

@@ -0,0 +1,41 @@
+import colors from "colors/safe";
+import { NextFunction, Request, Response } from "express";
+import { Logger } from "../utils/logging";
+
+export function buildRequestLogger(logger: Logger, isInDevMode: boolean) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    logger.info(
+      `[Request] ${colors.cyan(req.method)} - ${colors.cyan(req.path)}`,
+    );
+
+    if (isInDevMode) {
+      logger.info(`[Request - Dev] Headers: ${JSON.stringify(req.headers)}`);
+      logger.info(`[Request - Dev] Query: ${JSON.stringify(req.query)}`);
+      logger.info(`[Request - Dev] Body: ${JSON.stringify(req.body)}`);
+    }
+
+    next();
+  };
+}
+
+export function buildResponseLogger(logger: Logger, isInDevMode: boolean) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const originalSend = res.send;
+
+    res.json = function (body: unknown): Response {
+      logger.info(
+        `[Response] ${colors.cyan(req.method)} - ${colors.cyan(
+          req.path,
+        )} - Status: ${res.statusCode > 299 && res.statusCode < 599 ? colors.red(res.statusCode.toString()) : colors.green(res.statusCode.toString())}`,
+      );
+
+      if (isInDevMode) {
+        logger.info(`[Response - Dev] Body: ${JSON.stringify(body)}`);
+      }
+
+      return originalSend.call(this, body);
+    };
+
+    next();
+  };
+}

package/src/server/middleware/validation.ts

@@ -0,0 +1,35 @@
+import { NextFunction, Request, Response } from "express";
+import { ZodType } from "zod";
+import { HttpStatusCodes } from "../constants/HttpStatusCodes";
+
+export function buildBodyValidatorMiddleware<Schema extends ZodType>(
+  schema: Schema,
+) {
+  return (request: Request, response: Response, next: NextFunction) => {
+    const validationResult = schema.safeParse(request.body);
+    if (!validationResult.success) {
+      response.status(HttpStatusCodes.BadRequest_400).json({
+        message: `Body invalid`,
+        error: validationResult.error,
+      });
+      return;
+    }
+    next();
+  };
+}
+
+export function buildQueryValidatorMiddleware<Schema extends ZodType>(
+  schema: Schema,
+) {
+  return (request: Request, response: Response, next: NextFunction) => {
+    const validationResult = schema.safeParse(request.query);
+    if (!validationResult.success) {
+      response.status(HttpStatusCodes.BadRequest_400).json({
+        message: `Query parameters invalid`,
+        error: validationResult.error,
+      });
+      return;
+    }
+    next();
+  };
+}

package/src/server/server.ts

@@ -0,0 +1,90 @@
+import cookieParser from "cookie-parser";
+import express, { Application } from "express";
+import z from "zod";
+import { HttpMethod } from "./constants/HttpMethods";
+import { buildApiEndpointHandler } from "./handlers/api/createApiHandler";
+import { ApiEndpointDefinition } from "./handlers/api/EndpointDefinition";
+import { ApiEndpointHandler } from "./handlers/api/EndpointHandler";
+import { buildRequestLogger, buildResponseLogger } from "./middleware/logging";
+import {
+  buildBodyValidatorMiddleware,
+  buildQueryValidatorMiddleware,
+} from "./middleware/validation";
+import { Logger, NoOpLogger } from "./utils/logging";
+import { hasNoValue, hasValue } from "./utils/typeGuards";
+
+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 function createServer(options: ServerOptions): Server {
+  const { port = 3000, inDevMode = false } = options;
+
+  const logger: 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: Application,
+  endpointDefinition: ApiEndpointDefinition<
+    string,
+    HttpMethod,
+    z.ZodType,
+    z.ZodType,
+    {}
+  >,
+  endpointHandler: ApiEndpointHandler,
+) {
+  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/src/server/utils/funcs.ts

@@ -0,0 +1,3 @@
+export function isEmpty<T>(array: Array<T>): boolean {
+  return array.length === 0;
+}

package/src/server/utils/logging.ts

@@ -0,0 +1,10 @@
+export type Logger = Pick<Console, "log" | "info" | "error" | "warn">;
+
+export const NoOpLogger: Logger = {
+  log: () => {},
+  info: () => {},
+  error: () => {},
+  warn: () => {},
+};
+
+export const DefaultLogger: Logger = console;

package/src/server/utils/typeGuards.ts

@@ -0,0 +1,9 @@
+export function hasValue<T>(value: T | undefined | null): value is T {
+  return value !== undefined && value !== null;
+}
+
+export function hasNoValue<T>(
+  value: T | undefined | null,
+): value is undefined | null {
+  return value === undefined || value === null;
+}

package/src/server/utils/types.ts

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

package/transitKit.code-workspace

@@ -0,0 +1,36 @@
+{
+  "folders": [
+    {
+      "path": "."
+    },
+  ],
+  "settings": {
+    "editor.tokenColorCustomizations": {
+      "[*Dark*]": {
+        "textMateRules": [
+          {
+            "scope": "keyword.control",
+            "settings": {
+              "foreground": "#C586C0"
+            }
+          }
+        ]
+      }
+    },
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit",
+      "source.organizeImports": "explicit"
+    },
+    "eslint.validate": [
+      "javascript",
+      "typescript",
+      "vue",
+      "vue-html"
+    ],
+    "cSpell.words": [
+      "neverthrow",
+      "VITE"
+    ],
+    "typescript.tsdk": "node_modules/typescript/lib",
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "module": "ESNext",
+    "target": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "outDir": "./dist"
+  },
+  "include": [
+    "./src/**/*",
+  ],
+}

package/vitest.config.ts

@@ -0,0 +1,22 @@
+import { loadEnv } from "vite";
+import tsconfigPaths from "vite-tsconfig-paths";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  root: "./src",
+  test: {
+    env: loadEnv("", ".", ""),
+    globals: true,
+    environment: "node",
+    coverage: {
+      provider: "v8",
+      reporter: ["html-spa", "text"],
+      include: ["*"],
+      reportsDirectory: "../coverage",
+      enabled: true,
+      cleanOnRerun: true,
+    },
+  },
+  define: {},
+  plugins: [tsconfigPaths()],
+});