@extk/expressive 0.1.0

package/dist/index.mjs

@@ -0,0 +1,499 @@
+// src/expressive.ts
+import express from "express";
+import helmet from "helmet";
+import morgan from "morgan";
+import qs from "qs";
+import swaggerUi from "swagger-ui-express";
+
+// src/swagger.ts
+var buildSwaggerBuilder = (swaggerDoc) => {
+  return {
+    swaggerBuilder: () => {
+      return {
+        withInfo(info) {
+          swaggerDoc.info = info;
+          return this;
+        },
+        withServers(servers) {
+          swaggerDoc.servers = servers;
+          return this;
+        },
+        withSecuritySchemes(schemes) {
+          swaggerDoc.components.securitySchemes = schemes;
+          return this;
+        },
+        withSchemas(schemas) {
+          swaggerDoc.components.schemas = schemas;
+          return this;
+        },
+        withDefaultSecurity(globalAuthMethods) {
+          swaggerDoc.security = globalAuthMethods;
+          return this;
+        },
+        get() {
+          return swaggerDoc;
+        }
+      };
+    }
+  };
+};
+var securitySchemes = {
+  BasicAuth: () => ({
+    type: "http",
+    scheme: "basic"
+  }),
+  BearerAuth: () => ({
+    type: "http",
+    scheme: "bearer"
+  }),
+  ApiKeyAuth: (headerName) => ({
+    type: "apiKey",
+    in: "header",
+    name: headerName
+  }),
+  OpenID: (openIdConnectUrl) => ({
+    type: "openIdConnect",
+    openIdConnectUrl
+  }),
+  OAuth2: (authorizationUrl, tokenUrl, scopes) => ({
+    type: "oauth2",
+    flows: {
+      authorizationCode: {
+        authorizationUrl,
+        tokenUrl,
+        scopes
+      }
+    }
+  })
+};
+var securityRegistry = {};
+var security = (name) => {
+  if (!securityRegistry[name]) {
+    securityRegistry[name] = { [name]: [] };
+  }
+  return securityRegistry[name];
+};
+function jsonSchema(schema) {
+  return {
+    content: {
+      "application/json": {
+        schema
+      }
+    }
+  };
+}
+function jsonSchemaRef(name) {
+  return jsonSchema({ $ref: `#/components/schemas/${name}` });
+}
+function param(inP, id, schema, required = true, description = "", name) {
+  return {
+    in: inP,
+    name: name ?? id,
+    desciption: description,
+    required,
+    schema
+  };
+}
+function pathParam(id, schema, required = true, description = "", name) {
+  return param("path", id, schema, required, description, name);
+}
+function queryParam(id, schema, required = true, description = "", name) {
+  return param("query", id, schema, required, description, name);
+}
+function headerParam(id, schema, required = true, description = "", name) {
+  return param("headers", id, schema, required, description, name);
+}
+function convertExpressPath(path2) {
+  return path2.replace(/:([a-zA-Z0-9_*]+)/g, "{$1}");
+}
+function tryParsePathParameters(path2) {
+  const matches = path2.match(/(?<={)[^}]+(?=})/g);
+  if (!matches) {
+    return [];
+  }
+  return matches.map((pp) => pathParam(pp, { type: "string" }));
+}
+var SWG = {
+  param,
+  pathParam,
+  queryParam,
+  headerParam,
+  jsonSchema,
+  jsonSchemaRef,
+  security,
+  securitySchemes
+};
+
+// src/expressive.ts
+function buildExpressive(container, swaggerDoc) {
+  return {
+    expressiveServer(configs) {
+      const { options } = configs;
+      const app = configs.app ?? express();
+      app.use(helmet(options?.helmet ?? {}));
+      app.set("query parser", function(str) {
+        return qs.parse(str, { decoder(s) {
+          return decodeURIComponent(s);
+        } });
+      });
+      app.use(morgan(
+        options?.morgan?.format ?? ":req[x-real-ip] :method :url :status :res[content-length] - :response-time ms",
+        options?.morgan?.options ?? { stream: { write(message) {
+          container.logger.info(message.trim());
+        } } }
+      ));
+      app.use(configs.swagger.path, swaggerUi.serve, swaggerUi.setup(configs.swagger.doc));
+      return app;
+    },
+    expressiveRouter(configs) {
+      const router = express.Router();
+      return {
+        router,
+        addRoute(context, ...handlers) {
+          router[context.method](context.path, ...handlers);
+          const {
+            pathOverride,
+            pathParameters,
+            headerParameters,
+            queryParameters,
+            ...pathItemConfig
+          } = context.oapi || {};
+          const route = pathOverride ?? convertExpressPath(context.path);
+          const pathItem = {
+            // -- defaults --
+            responses: {},
+            // has to be defined or else responses are not documented... ¯\_(ツ)_/¯
+            // -- group defaults --
+            ...configs?.oapi || {},
+            // -- overrides --
+            ...pathItemConfig || {},
+            parameters: [
+              // ...(contract.pathParameters || []),
+              ...headerParameters || [],
+              ...queryParameters || []
+            ]
+          };
+          if (pathParameters?.length) {
+            pathItem.parameters.push(...pathParameters);
+          } else {
+            pathItem.parameters.push(...tryParsePathParameters(route));
+          }
+          swaggerDoc.paths[route] = {
+            [context.method]: pathItem
+          };
+          return router;
+        }
+      };
+    }
+  };
+}
+
+// src/env.ts
+import dotenv from "dotenv";
+dotenv.config();
+function isDev() {
+  return getEnvVar("ENV") === "dev";
+}
+function isProd() {
+  return getEnvVar("ENV") === "prod";
+}
+function getEnvVar(configName) {
+  const config = process.env[configName];
+  if (!config) {
+    throw new Error(`Missing config '${configName}'`);
+  }
+  return config;
+}
+
+// src/errors.ts
+var ApiError = class extends Error {
+  code;
+  httpStatusCode;
+  data;
+  constructor(message, httpStatusCode, errorCode) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = errorCode;
+    this.httpStatusCode = httpStatusCode;
+  }
+  setData(data) {
+    this.data = data;
+    return this;
+  }
+};
+var NotFoundError = class extends ApiError {
+  constructor(message = "Resource not found") {
+    super(message, 404, "NOT_FOUND");
+  }
+};
+var DuplicateError = class extends ApiError {
+  constructor(message = "Duplicate entry") {
+    super(message, 409, "DUPLICATE_ENTRY");
+  }
+};
+var BadRequestError = class extends ApiError {
+  constructor(message = "Bad request") {
+    super(message, 400, "BAD_REQUEST");
+  }
+};
+var SchemaValidationError = class extends ApiError {
+  constructor(message = "Failed to validate Schema") {
+    super(message, 400, "SCHEMA_VALIDATION_ERROR");
+  }
+};
+var FileTooBigError = class extends ApiError {
+  constructor() {
+    super("File too big", 400, "FILE_TOO_BIG");
+  }
+};
+var InvalidFileTypeError = class extends ApiError {
+  constructor() {
+    super("Invalid file type", 400, "INVALID_FILE_TYPE");
+  }
+};
+var InvalidCredentialsError = class extends ApiError {
+  constructor() {
+    super("Invalid credentials", 401, "INVALID_CREDENTIALS");
+  }
+};
+var InternalError = class extends ApiError {
+  constructor() {
+    super("Internal error", 500, "INTERNAL_ERROR");
+  }
+};
+var TooManyRequestsError = class extends ApiError {
+  constructor(message = "Too many requests") {
+    super(message, 429, "TOO_MANY_REQUESTS");
+  }
+};
+var ForbiddenError = class extends ApiError {
+  constructor(message = "Action not allowed") {
+    super(message, 403, "FORBIDDEN");
+  }
+};
+var TokenExpiredError = class extends ApiError {
+  constructor(message = "Token Expired") {
+    super(message, 401, "TOKEN_EXPIRED");
+  }
+};
+var UserUnauthorizedError = class extends ApiError {
+  constructor(message = "User unauthorized") {
+    super(message, 401, "USER_UNAUTHORIZED");
+  }
+};
+
+// src/response/ApiErrorResponse.ts
+var ApiErrorResponse = class {
+  status = "error";
+  message;
+  errorCode;
+  errors;
+  constructor(message, errorCode, errors) {
+    this.message = message;
+    this.errorCode = errorCode;
+    this.errors = errors;
+  }
+};
+
+// src/common.ts
+import path from "path";
+function parsePositiveInteger(v, defaultValue, max) {
+  const value = Number(v);
+  return Number.isInteger(value) && value > 0 && (!max || value <= max) ? value : defaultValue;
+}
+function parseIdOrFail(v) {
+  const value = Number(v);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new ApiError("Invalid Id", 400, "INVALID_ID");
+  }
+  return value;
+}
+function slugify(text) {
+  return text.toString().normalize("NFKD").toLowerCase().trim().replace(/[\s\n_+.]/g, "-").replace(/--+/g, "-");
+}
+function getTmpDir() {
+  return path.resolve("tmp");
+}
+function getTmpPath(...steps) {
+  return path.join(getTmpDir(), ...steps);
+}
+function parseDefaultPagination(query) {
+  const limit = parsePositiveInteger(query.limit, 50, 100);
+  const page = parsePositiveInteger(query.page, 1, 1e3);
+  const offset = (page - 1) * limit;
+  return { limit, offset };
+}
+function createReqSnapshot(req) {
+  return {
+    query: req.query,
+    path: req.path,
+    method: req.method,
+    userId: req?.user?.id
+  };
+}
+
+// src/middleware/errorHandlerMiddleware.ts
+var buildErrorHandlerMiddleware = (container) => {
+  const { logger, alertHandler } = container;
+  return {
+    getErrorHandlerMiddleware: (errorMapper) => {
+      return async (err, req, res, _next) => {
+        let finalError;
+        const customMappedError = errorMapper && errorMapper(err);
+        if (customMappedError) {
+          finalError = customMappedError;
+          logger.error("%s\n%o", finalError.message, finalError.data);
+        } else if (err.name === "SyntaxError" && err.type === "entity.parse.failed") {
+          logger.error("%s", err);
+          finalError = new BadRequestError("Invalid json format");
+        } else if (err instanceof ApiError) {
+          logger.error("%s", err);
+          finalError = err;
+        } else {
+          logger.error("Error: %s", err);
+          if (err.cause) {
+            logger.error("Cause: %s", err.cause);
+          }
+          if (alertHandler) {
+            alertHandler(err, createReqSnapshot(req));
+          }
+          finalError = new InternalError();
+          if (!isProd()) {
+            finalError.data = { name: err.name, message: err.message, stack: err.stack, cause: err.cause };
+          }
+        }
+        res.status(finalError.httpStatusCode).json(new ApiErrorResponse(finalError.message, finalError.code, finalError.data));
+      };
+    }
+  };
+};
+
+// src/middleware/notFoundMiddleware.ts
+var notFoundMiddleware = (_req, res, _next) => {
+  res.status(404).send("\xAF\\_(\u30C4)_/\xAF").end();
+};
+
+// src/logger.ts
+import winston from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+var loggerRegistry = {};
+var defaultFormat = winston.format.combine(
+  winston.format.timestamp({ format: "DD/MM/YYYY HH:mm:ss" }),
+  winston.format.splat(),
+  // String interpolation splat for %d %s-style messages.
+  winston.format.errors({ stack: true }),
+  winston.format.printf(({ level, message, timestamp, stack }) => `${timestamp}[${level.toUpperCase()}]: ${stack || message}`)
+);
+var consoleTransport = new winston.transports.Console({
+  handleExceptions: true
+});
+var createFileLogger = (filename) => {
+  const logger = winston.createLogger({
+    format: defaultFormat,
+    transports: [
+      new DailyRotateFile({
+        level: "debug",
+        filename: `./logs/${filename}-%DATE%.log`,
+        handleExceptions: true,
+        // exitOnError: false, // do not exit on handled exceptions
+        datePattern: "YYYY-MM-DD",
+        zippedArchive: true,
+        auditFile: "./logs/audit.json",
+        maxSize: "20m",
+        maxFiles: isProd() ? "30d" : "1d"
+        // format: defaultFormat,
+        // the nested 'format' field causes issues with logging errors;
+        // use the 'format' field on logger, instead of transport;
+      })
+    ]
+  });
+  if (isDev()) {
+    logger.add(consoleTransport);
+  }
+  return logger;
+};
+var createLogger = winston.createLogger;
+var getDefaultFileLogger = (name = "app") => {
+  if (!loggerRegistry[name]) {
+    loggerRegistry[name] = createFileLogger(name.toString());
+  }
+  return loggerRegistry[name];
+};
+var getDefaultConsoleLogger = (name = "console") => {
+  if (!loggerRegistry[name]) {
+    loggerRegistry[name] = winston.createLogger({
+      format: defaultFormat,
+      transports: [
+        consoleTransport
+      ]
+    });
+  }
+  return loggerRegistry[name];
+};
+
+// src/response/ApiResponse.ts
+var ApiResponse = class {
+  status = "ok";
+  result;
+  constructor(result) {
+    this.result = result;
+  }
+};
+
+// src/index.ts
+function bootstrap(container) {
+  const swaggerDoc = {
+    openapi: "3.1.0",
+    // TODO
+    info: {},
+    paths: {},
+    components: {}
+  };
+  return {
+    ...buildExpressive(container, swaggerDoc),
+    ...buildSwaggerBuilder(swaggerDoc),
+    ...buildErrorHandlerMiddleware(container),
+    notFoundMiddleware,
+    silently: (fn, reqSnapshot) => {
+      fn().catch((e) => {
+        if (container.alertHandler && e instanceof Error) {
+          container.alertHandler(e, reqSnapshot);
+        } else {
+          container.logger.error(e);
+        }
+      });
+    }
+  };
+}
+export {
+  ApiError,
+  ApiErrorResponse,
+  ApiResponse,
+  BadRequestError,
+  DuplicateError,
+  FileTooBigError,
+  ForbiddenError,
+  InternalError,
+  InvalidCredentialsError,
+  InvalidFileTypeError,
+  NotFoundError,
+  SWG,
+  SchemaValidationError,
+  TokenExpiredError,
+  TooManyRequestsError,
+  UserUnauthorizedError,
+  bootstrap,
+  createLogger,
+  createReqSnapshot,
+  getDefaultConsoleLogger,
+  getDefaultFileLogger,
+  getEnvVar,
+  getTmpDir,
+  getTmpPath,
+  isDev,
+  isProd,
+  parseDefaultPagination,
+  parseIdOrFail,
+  parsePositiveInteger,
+  slugify
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+    "name": "@extk/expressive",
+    "version": "0.1.0",
+    "type": "commonjs",
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js"
+        }
+    },
+    "engines": {
+        "node": ">=22.0.0 <23.0.0"
+    },
+    "scripts": {
+        "build": "tsup",
+        "test": "node --import=tsx --test 'test/**/*.test.ts'",
+        "lint": "eslint ./"
+    },
+    "devDependencies": {
+        "@extk/eslint-config": "^0.2.0",
+        "@types/chance": "^1.1.7",
+        "@types/express": "^5.0.1",
+        "@types/morgan": "^1.9.9",
+        "@types/node": "^20.9.3",
+        "@types/swagger-ui-express": "^4.1.8",
+        "chance": "^1.1.13",
+        "eslint": "^9.36.0",
+        "tsup": "^8.5.0",
+        "tsx": "^4.20.3",
+        "typescript": "^5.9.2"
+    },
+    "peerDependencies": {
+        "express": "^5.1.0"
+    },
+    "dependencies": {
+        "dotenv": "^17.1.0",
+        "helmet": "^8.0.0",
+        "morgan": "^1.10.0",
+        "swagger-ui-express": "^5.0.1",
+        "winston": "^3.11.0",
+        "winston-daily-rotate-file": "^5.0.0"
+    },
+    "author": "",
+    "license": "ISC",
+    "description": ""
+}