expressentials 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gautam Suthar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# expressentials
+
+Essential Express.js helpers — status codes, errors, logging, validation, and more.
+
+```ts
+import { status, NotFound, errorHandler, requestId } from "expressentials";
+
+app.use(requestId());
+app.use(errorHandler());
+
+app.get("/users/:id", (req, res) => {
+  throw new NotFound("User not found");
+});
+```
+
+## Install
+
+```sh
+npm install expressentials
+```
+
+Requires `express` as a peer dependency.
+
+## Features
+
+| Module | Description |
+|--------|-------------|
+| [status](./FEATURES.md#status--http-status-code-constants) | HTTP status code constants (`status.ok` → `200`) |
+| [message](./FEATURES.md#message--human-readable-status-messages) | Human-readable messages (`message.created` → `"Created successfully"`) |
+| [ApiError](./FEATURES.md#apierror--base-error-class) | Base error class with HTTP status codes |
+| [Http Errors](./FEATURES.md#predefined-error-classes) | `NotFound`, `BadRequest`, `Forbidden`, etc. |
+| [errorHandler](./FEATURES.md#errorhandler--express-error-handling-middleware) | Express error-handling middleware |
+| [requestId](./FEATURES.md#requestid--request-id-middleware) | Request ID middleware (UUID, configurable header) |
+| [requestContext](./FEATURES.md#requestcontext--request-scoped-logger--asynclocalstorage) | Request-scoped logger + AsyncLocalStorage context |
+| [httpLogger](./FEATURES.md#httplogger--http-request-logging-middleware) | Auto-log requests with method, path, status, duration |
+| [validate](./FEATURES.md#validate--request-validation-middleware-schema-adapter) | Request validation (Zod/Yup/ArkType adapter) |
+| [asyncHandler](./FEATURES.md#asynchandler--async-route-handler-wrapper) | Async route handler wrapper |
+| [timeout](./FEATURES.md#timeout--request-timeout-middleware) | Request timeout middleware (504 Gateway Timeout) |
+| [healthCheck](./FEATURES.md#healthcheck--health-endpoint-helper) | Health check endpoint |
+| [Logger](./FEATURES.md#logger--structured-json-logger) | Structured JSON logger |
+| [Context](./FEATURES.md#context--asynclocalstorage-accessors) | AsyncLocalStorage accessors (`getLogger`, `getRequestId`) |
+
+See [FEATURES.md](./FEATURES.md) for full documentation with all options and usage examples.
+
+## Quick start
+
+```ts
+import express from "express";
+import {
+  requestId,
+  requestContext,
+  httpLogger,
+  validate,
+  asyncHandler,
+  errorHandler,
+  NotFound,
+} from "expressentials";
+import { z } from "zod";
+
+const app = express();
+
+app.use(express.json());
+app.use(requestId());
+app.use(requestContext());
+app.use(httpLogger({ skip: (req) => req.url === "/health" }));
+
+const createUserSchema = z.object({
+  name: z.string(),
+  email: z.string().email(),
+});
+
+app.post(
+  "/users",
+  validate({ body: createUserSchema }),
+  asyncHandler(async (req, res) => {
+    req.log.info({ email: req.body.email }, "Creating user");
+    // ...
+    res.status(201).json({ id: "abc" });
+  }),
+);
+
+app.get("/health", (_req, res) => {
+  res.json({ status: "ok" });
+});
+
+app.use("*", () => {
+  throw new NotFound("Route not found");
+});
+
+app.use(errorHandler());
+
+app.listen(3000);
+```
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `npm run build` | Build with tsup (ESM + CJS + types) |
+| `npm run dev` | Watch mode |
+| `npm test` | Run tests |
+| `npm run typecheck` | TypeScript check |
+| `npm run format` | Check formatting with Prettier |
+| `npm run format:fix` | Fix formatting |
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, guidelines, and project structure.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md). By participating, you agree to uphold its terms.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,530 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  BadRequest: () => BadRequest,
+  Conflict: () => Conflict,
+  Forbidden: () => Forbidden,
+  GatewayTimeout: () => GatewayTimeout,
+  InternalServerError: () => InternalServerError,
+  Logger: () => Logger,
+  NotFound: () => NotFound,
+  ServiceUnavailable: () => ServiceUnavailable,
+  TooManyRequests: () => TooManyRequests,
+  Unauthorized: () => Unauthorized,
+  ValidationError: () => ValidationError,
+  asyncHandler: () => asyncHandler,
+  createLogger: () => createLogger,
+  errorHandler: () => errorHandler,
+  getLogger: () => getLogger,
+  getRequestContext: () => getRequestContext,
+  getRequestId: () => getRequestId,
+  healthCheck: () => healthCheck,
+  httpLogger: () => httpLogger,
+  message: () => message,
+  requestContext: () => requestContext,
+  requestId: () => requestId,
+  runWithContext: () => runWithContext,
+  status: () => status,
+  timeout: () => timeout,
+  validate: () => validate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/status/index.ts
+var status = {
+  // 1xx Informational
+  continue: 100,
+  switchingProtocols: 101,
+  processing: 102,
+  earlyHints: 103,
+  // 2xx Success
+  ok: 200,
+  created: 201,
+  accepted: 202,
+  nonAuthoritativeInformation: 203,
+  noContent: 204,
+  resetContent: 205,
+  partialContent: 206,
+  // 3xx Redirection
+  multipleChoices: 300,
+  movedPermanently: 301,
+  found: 302,
+  seeOther: 303,
+  notModified: 304,
+  useProxy: 305,
+  temporaryRedirect: 307,
+  permanentRedirect: 308,
+  // 4xx Client Error
+  badRequest: 400,
+  unauthorized: 401,
+  paymentRequired: 402,
+  forbidden: 403,
+  notFound: 404,
+  methodNotAllowed: 405,
+  notAcceptable: 406,
+  proxyAuthenticationRequired: 407,
+  requestTimeout: 408,
+  conflict: 409,
+  gone: 410,
+  lengthRequired: 411,
+  preconditionFailed: 412,
+  payloadTooLarge: 413,
+  uriTooLong: 414,
+  unsupportedMediaType: 415,
+  rangeNotSatisfiable: 416,
+  expectationFailed: 417,
+  imATeapot: 418,
+  unprocessableEntity: 422,
+  tooEarly: 425,
+  upgradeRequired: 426,
+  preconditionRequired: 428,
+  tooManyRequests: 429,
+  requestHeaderFieldsTooLarge: 431,
+  unavailableForLegalReasons: 451,
+  // 5xx Server Error
+  internalServerError: 500,
+  notImplemented: 501,
+  badGateway: 502,
+  serviceUnavailable: 503,
+  gatewayTimeout: 504,
+  httpVersionNotSupported: 505,
+  insufficientStorage: 507,
+  loopDetected: 508,
+  notExtended: 510,
+  networkAuthenticationRequired: 511
+};
+
+// src/message/index.ts
+var message = {
+  // 1xx Informational
+  continue: "Continue",
+  switchingProtocols: "Switching Protocols",
+  processing: "Processing request",
+  earlyHints: "Early hints available",
+  // 2xx Success
+  ok: "Success",
+  created: "Created successfully",
+  accepted: "Request accepted",
+  nonAuthoritativeInformation: "Non-authoritative information",
+  noContent: "No content",
+  resetContent: "Reset content",
+  partialContent: "Partial content",
+  // 3xx Redirection
+  multipleChoices: "Multiple redirect options available",
+  movedPermanently: "Resource moved permanently",
+  found: "Resource found elsewhere",
+  seeOther: "See other resource",
+  notModified: "Resource not modified",
+  useProxy: "Use proxy to access resource",
+  temporaryRedirect: "Resource temporarily moved",
+  permanentRedirect: "Resource permanently moved",
+  // 4xx Client Error
+  badRequest: "Invalid request",
+  unauthorized: "Authentication required",
+  paymentRequired: "Payment required",
+  forbidden: "You don't have permission to access this resource",
+  notFound: "Resource not found",
+  methodNotAllowed: "Method not allowed for this resource",
+  notAcceptable: "Requested format not available",
+  proxyAuthenticationRequired: "Proxy authentication required",
+  requestTimeout: "Request timed out",
+  conflict: "Resource conflict detected",
+  gone: "Resource no longer available",
+  lengthRequired: "Content length header is required",
+  preconditionFailed: "Request precondition failed",
+  payloadTooLarge: "Request payload exceeds size limit",
+  uriTooLong: "Request URI exceeds length limit",
+  unsupportedMediaType: "Unsupported media type",
+  rangeNotSatisfiable: "Requested range is not available",
+  expectationFailed: "Request expectation could not be met",
+  imATeapot: "I'm a teapot",
+  unprocessableEntity: "Unable to process request entity",
+  tooEarly: "Request sent too early, retry later",
+  upgradeRequired: "Protocol upgrade required",
+  preconditionRequired: "Precondition header is required",
+  tooManyRequests: "Too many requests, please slow down",
+  requestHeaderFieldsTooLarge: "Request headers exceed size limit",
+  unavailableForLegalReasons: "Resource unavailable for legal reasons",
+  // 5xx Server Error
+  internalServerError: "Something went wrong on our end",
+  notImplemented: "Feature not yet implemented",
+  badGateway: "Bad gateway response from upstream",
+  serviceUnavailable: "Service temporarily unavailable, try again later",
+  gatewayTimeout: "Upstream server timed out",
+  httpVersionNotSupported: "HTTP version not supported by server",
+  insufficientStorage: "Server has insufficient storage",
+  loopDetected: "Infinite request loop detected",
+  notExtended: "Server cannot fulfill extended request",
+  networkAuthenticationRequired: "Network authentication required"
+};
+
+// src/errors/api-error.ts
+var ApiError = class _ApiError extends Error {
+  constructor(statusCode, message2, details) {
+    super(message2 ??= getDefaultMessage(statusCode));
+    this.statusCode = statusCode;
+    this.details = details;
+    this.name = "ApiError";
+  }
+  statusCode;
+  details;
+  static notFound(message2) {
+    return new _ApiError(status.notFound, message2);
+  }
+  static badRequest(message2) {
+    return new _ApiError(status.badRequest, message2);
+  }
+  static unauthorized(message2) {
+    return new _ApiError(status.unauthorized, message2);
+  }
+  static forbidden(message2) {
+    return new _ApiError(status.forbidden, message2);
+  }
+  static conflict(message2) {
+    return new _ApiError(status.conflict, message2);
+  }
+  static internalServerError(message2) {
+    return new _ApiError(status.internalServerError, message2);
+  }
+  static serviceUnavailable(message2) {
+    return new _ApiError(status.serviceUnavailable, message2);
+  }
+  static tooManyRequests(message2) {
+    return new _ApiError(status.tooManyRequests, message2);
+  }
+};
+function getDefaultMessage(code) {
+  const entry = Object.entries(status).find(([, v]) => v === code);
+  if (!entry) return "Error";
+  return message[entry[0]];
+}
+
+// src/errors/http-error.ts
+var NotFound = class extends ApiError {
+  constructor(message2) {
+    super(404, message2);
+  }
+};
+var BadRequest = class extends ApiError {
+  constructor(message2) {
+    super(400, message2);
+  }
+};
+var Unauthorized = class extends ApiError {
+  constructor(message2) {
+    super(401, message2);
+  }
+};
+var Forbidden = class extends ApiError {
+  constructor(message2) {
+    super(403, message2);
+  }
+};
+var Conflict = class extends ApiError {
+  constructor(message2) {
+    super(409, message2);
+  }
+};
+var InternalServerError = class extends ApiError {
+  constructor(message2) {
+    super(500, message2);
+  }
+};
+var ServiceUnavailable = class extends ApiError {
+  constructor(message2) {
+    super(503, message2);
+  }
+};
+var TooManyRequests = class extends ApiError {
+  constructor(message2) {
+    super(429, message2);
+  }
+};
+var ValidationError = class extends ApiError {
+  constructor(message2, details) {
+    super(422, message2 ?? "Validation failed", details);
+  }
+};
+var GatewayTimeout = class extends ApiError {
+  constructor(message2) {
+    super(504, message2);
+  }
+};
+
+// src/logger/index.ts
+var levelPriority = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+var defaultDestination = (entry) => {
+  console.log(JSON.stringify(entry));
+};
+var Logger = class _Logger {
+  level;
+  destination;
+  bindings;
+  constructor(options = {}, bindings = {}) {
+    this.level = options.level ?? "info";
+    this.destination = options.destination ?? defaultDestination;
+    this.bindings = bindings;
+  }
+  shouldLog(level) {
+    return levelPriority[level] >= levelPriority[this.level];
+  }
+  log(level, ...args) {
+    if (!this.shouldLog(level)) return;
+    let message2;
+    let meta = {};
+    if (args.length === 1) {
+      message2 = String(args[0]);
+    } else if (typeof args[0] === "object" && args[0] !== null) {
+      meta = { ...args[0] };
+      message2 = String(args[1]);
+    } else {
+      message2 = String(args[0]);
+      if (args[1] !== void 0) {
+        meta = args[1];
+      }
+    }
+    this.destination({
+      level,
+      ...this.bindings,
+      ...meta,
+      ...message2 ? { message: message2 } : {}
+    });
+  }
+  debug(...args) {
+    this.log("debug", ...args);
+  }
+  info(...args) {
+    this.log("info", ...args);
+  }
+  warn(...args) {
+    this.log("warn", ...args);
+  }
+  error(...args) {
+    this.log("error", ...args);
+  }
+  child(bindings) {
+    return new _Logger(
+      { level: this.level, destination: this.destination },
+      { ...this.bindings, ...bindings }
+    );
+  }
+};
+function createLogger(options) {
+  return new Logger(options);
+}
+
+// src/context/index.ts
+var import_node_async_hooks = require("async_hooks");
+var storage = new import_node_async_hooks.AsyncLocalStorage();
+function getRequestContext() {
+  return storage.getStore();
+}
+function getLogger() {
+  return storage.getStore()?.log;
+}
+function getRequestId() {
+  return storage.getStore()?.requestId;
+}
+function runWithContext(context, fn) {
+  storage.run(context, fn);
+}
+
+// src/middleware/error-handler.ts
+function errorHandler(options = {}) {
+  const log = options.log ?? true;
+  return (err, _req, res, _next) => {
+    if (err instanceof ApiError) {
+      res.status(err.statusCode).json({
+        error: {
+          message: err.message,
+          statusCode: err.statusCode,
+          ...err.details !== void 0 && { details: err.details }
+        }
+      });
+      return;
+    }
+    if (log) {
+      console.error(err);
+    }
+    res.status(500).json({
+      error: {
+        message: message.internalServerError,
+        statusCode: 500
+      }
+    });
+  };
+}
+
+// src/middleware/request-id.ts
+var import_node_crypto = __toESM(require("crypto"), 1);
+function requestId(options = {}) {
+  const {
+    header = "x-request-id",
+    generator = import_node_crypto.default.randomUUID,
+    respectExisting = true
+  } = options;
+  return (req, res, next) => {
+    const existing = req.get(header);
+    const id = existing && respectExisting ? existing : generator();
+    req.requestId = id;
+    res.setHeader(header, id);
+    next();
+  };
+}
+
+// src/middleware/request-context.ts
+function requestContext(options = {}) {
+  const logger = options.logger ?? new Logger();
+  return (req, _res, next) => {
+    const scoped = logger.child({ requestId: req.requestId });
+    req.log = scoped;
+    runWithContext({ requestId: req.requestId, log: scoped }, () => {
+      next();
+    });
+  };
+}
+
+// src/middleware/http-logger.ts
+function httpLogger(options = {}) {
+  const { skip } = options;
+  return (req, res, next) => {
+    if (skip?.(req, res)) {
+      next();
+      return;
+    }
+    const start = Date.now();
+    res.on("finish", () => {
+      req.log.info({
+        method: req.method,
+        path: req.originalUrl ?? req.url,
+        status: res.statusCode,
+        durationMs: Date.now() - start
+      });
+    });
+    next();
+  };
+}
+
+// src/middleware/validate.ts
+function defaultFormatter(error) {
+  if (error && typeof error === "object" && "issues" in error && Array.isArray(error.issues)) {
+    return error.issues;
+  }
+  if (error instanceof Error) {
+    return [{ path: [], message: error.message }];
+  }
+  return [{ path: [], message: String(error) }];
+}
+function validate(schemas, options = {}) {
+  const formatError = options.formatError ?? defaultFormatter;
+  return (req, _res, next) => {
+    try {
+      if (schemas.body) req.body = schemas.body.parse(req.body);
+      if (schemas.params) req.params = schemas.params.parse(req.params);
+      if (schemas.query) req.query = schemas.query.parse(req.query);
+      next();
+    } catch (err) {
+      next(new ValidationError("Validation failed", formatError(err)));
+    }
+  };
+}
+
+// src/middleware/async-handler.ts
+function asyncHandler(fn) {
+  return (req, res, next) => {
+    Promise.resolve(fn(req, res, next)).catch(next);
+  };
+}
+
+// src/middleware/timeout.ts
+function timeout(ms, options = {}) {
+  return (req, _res, next) => {
+    const timer = setTimeout(() => {
+      next(new GatewayTimeout(options.message ?? "Request timed out"));
+    }, ms);
+    const done = () => clearTimeout(timer);
+    _res.on("finish", done);
+    _res.on("close", done);
+    next();
+  };
+}
+
+// src/middleware/health-check.ts
+function healthCheck(options = {}) {
+  const getUptime = options.uptime ?? (() => process.uptime());
+  const getTimestamp = options.timestamp ?? (() => (/* @__PURE__ */ new Date()).toISOString());
+  return (_req, res, _next) => {
+    res.json({
+      status: "ok",
+      uptime: getUptime(),
+      timestamp: getTimestamp(),
+      ...options.checks?.() ?? {}
+    });
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  BadRequest,
+  Conflict,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  Logger,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  ValidationError,
+  asyncHandler,
+  createLogger,
+  errorHandler,
+  getLogger,
+  getRequestContext,
+  getRequestId,
+  healthCheck,
+  httpLogger,
+  message,
+  requestContext,
+  requestId,
+  runWithContext,
+  status,
+  timeout,
+  validate
+});
+//# sourceMappingURL=index.cjs.map