@darksheep/express 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [2.0.0](https://github.com/DarkSheepSoftware/node-packages/compare/express-v1.0.1...express-v2.0.0) (2025-07-19)
+
+
+### ⚠ BREAKING CHANGES
+
+* Rework express package into multiple middleware functions ([#698](https://github.com/DarkSheepSoftware/node-packages/issues/698))
+
+### 🌟 Features
+
+* Add notFoundMiddleware and errorHandlerMiddleware ([#700](https://github.com/DarkSheepSoftware/node-packages/issues/700)) ([9a46f01](https://github.com/DarkSheepSoftware/node-packages/commit/9a46f018f7295611aa3baf09ea823334eebfa232))
+* Rework express package into multiple middleware functions ([#698](https://github.com/DarkSheepSoftware/node-packages/issues/698)) ([5a5a234](https://github.com/DarkSheepSoftware/node-packages/commit/5a5a2343d823b5233b25dfbbf15bb8d9bf82bf4d))
+
+## [1.0.1](https://github.com/DarkSheepSoftware/node-packages/compare/express-v1.0.0...express-v1.0.1) (2025-04-19)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @darksheep/logger bumped from 1.1.0 to 1.2.0
+  * peerDependencies
+    * @darksheep/logger bumped from ~1.0.10 to ~1.2.0
+
 ## 1.0.0 (2025-03-25)
 
 

package/express.d.ts

@@ -0,0 +1,38 @@
+/* eslint @typescript-eslint/consistent-type-definitions: 0 */
+import { type Logger } from '@darksheep/logger';
+
+export type ApiError = {
+  message?: string;
+  name: string;
+  path?: (number | string)[] | string;
+};
+
+export type ErrorHandler<E extends Error = Error> = {
+  format(error: E): ApiError[];
+  test(error: unknown): error is E;
+};
+
+declare global {
+  namespace Express {
+    interface Application {
+      errorHandlers: ErrorHandler[];
+    }
+
+    interface Request {
+      logger: Logger;
+      trail: string;
+    }
+
+    interface Response {
+      trail: string;
+    }
+  }
+}
+
+export {
+  type ErrorRequestHandler,
+  type Handler,
+  type Request,
+  type Response,
+// eslint-disable-next-line n/no-missing-import -- not sure why :sad:
+} from 'express';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksheep/express",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "express utilites and other bits",
   "license": "UNLICENCED",
   "type": "module",
@@ -13,6 +13,7 @@
   "files": [
     "src",
     "types",
+    "express.d.ts",
     "!*.test.*"
   ],
   "scripts": {
@@ -21,19 +22,30 @@
     "test:watch": "node --watch --test src/**/*.test.js"
   },
   "dependencies": {
+    "@darksheep/errors": "1.1.1",
     "@darksheep/prune": "1.0.4",
     "on-finished": "2.4.1"
   },
   "devDependencies": {
-    "@darksheep/logger": "1.1.0",
+    "@darksheep/json-schema": "",
+    "@darksheep/logger": "1.2.0",
     "@types/express": "~5.0.0",
     "@types/on-finished": "^2",
-    "express": "~4.21.2"
+    "express": "~5.1.0"
   },
   "peerDependencies": {
+    "@darksheep/json-schema": "",
     "@darksheep/logger": "~1.0.10",
     "express": "~4.21.2 || ~5"
   },
+  "peerDependenciesMeta": {
+    "@darksheep/json-schema": {
+      "optional": true
+    },
+    "@darksheep/logger": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": "^20.13.1 || ^22.2.0"
   }

package/src/content-type/middleware.js

@@ -0,0 +1,45 @@
+/**
+ * @import { Handler } from '../../express.js'
+ */
+
+import { UnsupportedMediaType } from '@darksheep/errors';
+
+/**
+ * @param {string | string[]} targetContentTypes - The permitted content types.
+ * @param {boolean} [shouldThrow] - Should the middleware throw an error.
+ * @returns {Handler}
+ */
+export function createContentTypeMiddleware(targetContentTypes, shouldThrow = true) {
+  const contentTypes = new Set(
+    typeof targetContentTypes === 'string'
+      ? [ targetContentTypes ]
+      : targetContentTypes,
+  );
+
+  return (request, response, next) => {
+    const provided = request.headers['content-type']?.split(';').at(0);
+    if (
+      provided != null &&
+      contentTypes.has(provided)
+    ) {
+      return next();
+    }
+
+    if (shouldThrow === true) {
+      return unsupportedMediaType(request, response, next);
+    }
+
+    return next('route');
+  };
+}
+
+/** @type {Handler} */
+export function unsupportedMediaType(request) {
+  const { method } = request;
+  const url = request.originalUrl.split('?').at(0) ?? '/';
+  const contentType = request.headers['content-type'];
+
+  throw new UnsupportedMediaType(
+    `Unsupported content-type at ${method} ${url}: ${contentType}`,
+  );
+}

package/src/content-type/router.js

@@ -0,0 +1,27 @@
+/**
+ * @import { Handler } from '../../express.js'
+ */
+
+import { Router } from 'express';
+
+import { createContentTypeMiddleware, unsupportedMediaType } from './middleware.js';
+
+/**
+ * @param {Record<string, Handler | Handler[]>} contentTypeRoutes - An object containing the contentType and routes.
+ * @returns {Router}
+ */
+export function createContentTypeRouter(contentTypeRoutes) {
+  const router = Router({ strict: true });
+
+  for (const [ contentType, route ] of Object.entries(contentTypeRoutes)) {
+    router.all(
+      /^/u,
+      createContentTypeMiddleware(contentType, false),
+      ...(Array.isArray(route) ? route : [ route ]),
+    );
+  }
+
+  router.use(unsupportedMediaType);
+
+  return router;
+}

package/src/error-handler/http.handler.js

@@ -0,0 +1,63 @@
+/**
+ * @import { ErrorHandler } from '../../express.js';
+ */
+
+/**
+ * @typedef HttpErrorExtra
+ * @property {boolean} expose - Should the error message be sent to the client.
+ * @property {Record<string, string> | undefined} headers - Additional headers to send.
+ * @property {number} statusCode - The response status code.
+ */
+/** @typedef {Error & HttpErrorExtra} HttpError */
+
+/** @type {ErrorHandler<HttpError>} */
+export const HttpErrorHandler = {
+  /**
+   * @param {unknown} error - The possible http error.
+   * @returns {error is HttpError}
+   */
+  test(error) {
+    return (
+      error instanceof Error &&
+      'expose' in error &&
+      'statusCode' in error &&
+      typeof error.expose === 'boolean' &&
+      typeof error.statusCode === 'number' &&
+      (
+        (
+          'headers' in error === false
+        ) ||
+        (
+          'headers' in error === true &&
+          error.headers != null &&
+          typeof error.headers === 'object' &&
+          Object.values(error.headers).every(
+            (header) => typeof header === 'string',
+          )
+        ) || (
+          'headers' in error === true &&
+          error.headers == null
+        )
+      )
+    );
+  },
+  format(error) {
+    // eslint-disable-next-line n/no-process-env
+    if (process.env.NODE_ENV === 'devlopment') {
+      return [ {
+        message: error.message,
+        name: error.name,
+        stack: error.stack,
+      } ];
+    }
+
+    if (error.expose === false) {
+      return [ { name: error.name } ];
+    }
+
+    return [ {
+      message: error.message,
+      name: error.name,
+    } ];
+  },
+};

package/src/error-handler/json-schema.handler.js

@@ -0,0 +1,41 @@
+/**
+ * @import { ErrorHandler } from '../../express.js';
+ * @import { RequestSchemaError, ResponseSchemaError } from '@darksheep/json-schema';
+ */
+
+/**
+ * @type {import('@darksheep/json-schema')}
+ */
+let schema;
+try {
+  schema = await import('@darksheep/json-schema');
+} catch {
+
+}
+
+import { HttpErrorHandler } from './http.handler.js';
+
+/** @type {ErrorHandler<RequestSchemaError | ResponseSchemaError>} */
+export const SchemaErrorHandler = {
+  /**
+   * @param {unknown} error - The possible http error.
+   * @returns {error is RequestSchemaError | ResponseSchemaError}
+   */
+  test(error) {
+    return (
+      schema != null &&
+      (
+        error instanceof schema.RequestSchemaError ||
+        error instanceof schema.ResponseSchemaError
+      )
+    );
+  },
+  format(error) {
+    const base = HttpErrorHandler.format(error);
+
+    // @ts-ignore
+    base.push(...error.errors);
+
+    return base;
+  },
+};

package/src/error-handler/middleware.js

@@ -0,0 +1,38 @@
+/**
+ * @import {
+ *   ErrorRequestHandler,
+ * } from '../../express.js'
+ */
+
+/** @type {ErrorRequestHandler} */
+export function errorHandlerMiddleware(error, request, response, _next) {
+  response.locals.error = error;
+
+  if ('headers' in error) {
+    response.header(error.headers);
+  }
+
+  response.status(
+    (
+      'statusCode' in error &&
+      typeof error.statusCode === 'number'
+    )
+      ? error.statusCode
+      : 500,
+  );
+
+  for (const { format, test } of request.app.errorHandlers ?? []) {
+    if (test(error)) {
+      response.json({
+        errors: format(error),
+        statusCode: response.statusCode,
+      });
+      return;
+    }
+  }
+
+  response.json({
+    errors: [ { name: 'InternalServerError' } ],
+    statusCode: response.statusCode,
+  });
+}

package/src/error-handler/zod.handler.js

@@ -0,0 +1,48 @@
+/**
+ * @import { ErrorHandler } from '../../express.js';
+ */
+
+/**
+ * @typedef ZodIssue
+ * @property {string} message - The error message for the path.
+ * @property {string} code - The zod error code text.
+ * @property {string} path - The path to the error in zod.
+ */
+/** @typedef {Error & { errors: ZodIssue[] }} ZodError */
+
+/** @type {ErrorHandler<ZodError>} */
+export const ZodErrorHandler = {
+  /**
+   * @param {unknown} error - The possible http error.
+   * @returns {error is ZodError}
+   */
+  test(error) {
+    return (
+      error instanceof Error &&
+      'errors' in error &&
+      Array.isArray(error.errors) &&
+      error.errors.every((issue) => (
+        issue != null &&
+        'message' in issue &&
+        'code' in issue &&
+        'path' in issue &&
+        typeof issue.message === 'string' &&
+        typeof issue.code === 'string' &&
+        typeof issue.path === 'string'
+      ))
+    );
+  },
+  format(error) {
+    return [
+      {
+        message: error.message,
+        name: error.name,
+      },
+      ...error.errors.map((issue) => ({
+        message: issue.message,
+        name: issue.code,
+        path: issue.path,
+      })),
+    ];
+  },
+};

package/src/index.js

@@ -1 +1,11 @@
-export { createRequestLogger } from './request-logger.js';
+export { createContentTypeMiddleware } from './content-type/middleware.js';
+export { createContentTypeRouter } from './content-type/router.js';
+export { createRequestLoggerMiddleware } from './logger/middleware.js';
+export { createRequestIdMiddleware } from './request-id/middleware.js';
+
+export { errorHandlerMiddleware } from './error-handler/middleware.js';
+export { notFoundMiddleware } from './not-found/middleware.js';
+
+export { HttpErrorHandler } from './error-handler/http.handler.js';
+export { SchemaErrorHandler } from './error-handler/json-schema.handler.js';
+export { ZodErrorHandler } from './error-handler/zod.handler.js';

package/src/{request-logger.js → logger/middleware.js}

@@ -1,42 +1,33 @@
 /**
  * @import { Socket } from 'node:net'
- * @import { Handler } from './express.js'
- * @import { Filter } from './should-filter.js'
+ * @import { Handler } from '../../express.js'
+ * @import { Filter } from './filter.js'
  */
 
 import { Logger } from '@darksheep/logger';
 import { pruneShallow } from '@darksheep/prune';
 import onFinished from 'on-finished';
 
-import { shouldFilterOutRequest } from './should-filter.js';
+import { shouldFilterOutRequest } from './filter.js';
 
 /** @type {WeakMap<Socket, number>} */
 const sockets = new WeakMap();
 
-import { randomUUID } from 'node:crypto';
-
 /**
  * @param {Logger} logger - A callback that can be bound to the request.
  * @param {Filter[]} [filters] - A list of requests to not log.
- * @param {string} [headerName] - The name of a header to include in the response with the trail.
  * @returns {Handler}
  */
-export function createRequestLogger(
+export function createRequestLoggerMiddleware(
   logger,
   filters,
-  headerName = 'X-Request-Id',
 ) {
   return (request, response, next) => {
-    request.id ??= (
-      request.header(headerName) ??
-      request.id ??
-      randomUUID()
-    );
-    request.logger = logger.trail(request.id);
+    request.logger = logger;
 
     Logger.wrap({
       request: request,
-      trail: request.id,
+      trail: request.trail,
     }, () => {
       const [ requestPath ] = request.originalUrl.split('?', 1);
       if (
@@ -57,6 +48,7 @@ export function createRequestLogger(
         const context = pruneShallow({
           duration: Date.now() - requestStartMs,
           error: error,
+          cause: response.locals.error,
 
           request: request,
           response: response,

package/src/not-found/middleware.js

@@ -0,0 +1,11 @@
+/**
+ * @import { Handler } from '../../express.js'
+ */
+import { NotFound } from '@darksheep/errors';
+
+/** @type {Handler} */
+export function notFoundMiddleware(request, _response, next) {
+  return next(
+    new NotFound(`${request.method} ${request.originalUrl}`),
+  );
+}

package/src/request-id/middleware.js

@@ -0,0 +1,34 @@
+/**
+ * @import { Handler, Request } from '../../express.js'
+ */
+import { randomUUID } from 'node:crypto';
+
+/**
+ * @param {Request} request - The express request.
+ * @param {string} [headerName] - The name of the header used in correlation.
+ * @returns {string}
+ */
+export function getTrail(request, headerName = 'X-Request-Id') {
+  if (typeof request.trail === 'string') {
+    return request.trail;
+  }
+
+  const header = request.header(headerName);
+  if (typeof header === 'string') {
+    return header;
+  }
+
+  return randomUUID();
+}
+
+/**
+ * @param {string} [headerName] - The name of a header to include in the response with the trail.
+ * @returns {Handler}
+ */
+export function createRequestIdMiddleware(headerName) {
+  return (request, response, next) => {
+    request.trail ??= getTrail(request, headerName);
+    response.trail = request.trail;
+    return next();
+  };
+}

package/types/content-type/middleware.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @param {string | string[]} targetContentTypes - The permitted content types.
+ * @param {boolean} [shouldThrow] - Should the middleware throw an error.
+ * @returns {Handler}
+ */
+export function createContentTypeMiddleware(targetContentTypes: string | string[], shouldThrow?: boolean): Handler;
+export function unsupportedMediaType(req: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").Request<import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").ParamsDictionary, any, any, import(".store/@types-qs-npm-6.14.0-e27d9ca044/package").ParsedQs, Record<string, any>>, res: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").Response<any, Record<string, any>, number>, next: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").NextFunction): unknown;
+import type { Handler } from '../../express.js';

package/types/content-type/router.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {Record<string, Handler | Handler[]>} contentTypeRoutes - An object containing the contentType and routes.
+ * @returns {Router}
+ */
+export function createContentTypeRouter(contentTypeRoutes: Record<string, Handler | Handler[]>): Router;
+import type { Handler } from '../../express.js';
+import { Router } from 'express';

package/types/error-handler/http.handler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @import { ErrorHandler } from '../../express.js';
+ */
+/**
+ * @typedef HttpErrorExtra
+ * @property {boolean} expose - Should the error message be sent to the client.
+ * @property {Record<string, string> | undefined} headers - Additional headers to send.
+ * @property {number} statusCode - The response status code.
+ */
+/** @typedef {Error & HttpErrorExtra} HttpError */
+/** @type {ErrorHandler<HttpError>} */
+export const HttpErrorHandler: ErrorHandler<HttpError>;
+export type HttpErrorExtra = {
+    /**
+     * - Should the error message be sent to the client.
+     */
+    expose: boolean;
+    /**
+     * - Additional headers to send.
+     */
+    headers: Record<string, string> | undefined;
+    /**
+     * - The response status code.
+     */
+    statusCode: number;
+};
+export type HttpError = Error & HttpErrorExtra;
+import type { ErrorHandler } from '../../express.js';

package/types/error-handler/json-schema.handler.d.ts

@@ -0,0 +1,5 @@
+/** @type {ErrorHandler<RequestSchemaError | ResponseSchemaError>} */
+export const SchemaErrorHandler: ErrorHandler<RequestSchemaError | ResponseSchemaError>;
+import type { RequestSchemaError } from '@darksheep/json-schema';
+import type { ResponseSchemaError } from '@darksheep/json-schema';
+import type { ErrorHandler } from '../../express.js';

package/types/error-handler/middleware.d.ts

@@ -0,0 +1 @@
+export function errorHandlerMiddleware(err: any, req: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").Request<import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").ParamsDictionary, any, any, import(".store/@types-qs-npm-6.14.0-e27d9ca044/package").ParsedQs, Record<string, any>>, res: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").Response<any, Record<string, any>, number>, next: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").NextFunction): unknown;

package/types/error-handler/zod.handler.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @import { ErrorHandler } from '../../express.js';
+ */
+/**
+ * @typedef ZodIssue
+ * @property {string} message - The error message for the path.
+ * @property {string} code - The zod error code text.
+ * @property {string} path - The path to the error in zod.
+ */
+/** @typedef {Error & { errors: ZodIssue[] }} ZodError */
+/** @type {ErrorHandler<ZodError>} */
+export const ZodErrorHandler: ErrorHandler<ZodError>;
+export type ZodIssue = {
+    /**
+     * - The error message for the path.
+     */
+    message: string;
+    /**
+     * - The zod error code text.
+     */
+    code: string;
+    /**
+     * - The path to the error in zod.
+     */
+    path: string;
+};
+export type ZodError = Error & {
+    errors: ZodIssue[];
+};
+import type { ErrorHandler } from '../../express.js';

package/types/index.d.ts

@@ -1 +1,9 @@
-export { createRequestLogger } from "./request-logger.js";
+export { createContentTypeMiddleware } from "./content-type/middleware.js";
+export { createContentTypeRouter } from "./content-type/router.js";
+export { createRequestLoggerMiddleware } from "./logger/middleware.js";
+export { createRequestIdMiddleware } from "./request-id/middleware.js";
+export { errorHandlerMiddleware } from "./error-handler/middleware.js";
+export { notFoundMiddleware } from "./not-found/middleware.js";
+export { HttpErrorHandler } from "./error-handler/http.handler.js";
+export { SchemaErrorHandler } from "./error-handler/json-schema.handler.js";
+export { ZodErrorHandler } from "./error-handler/zod.handler.js";

package/types/logger/middleware.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @param {Logger} logger - A callback that can be bound to the request.
+ * @param {Filter[]} [filters] - A list of requests to not log.
+ * @returns {Handler}
+ */
+export function createRequestLoggerMiddleware(logger: Logger, filters?: Filter[]): Handler;
+import { Logger } from '@darksheep/logger';
+import type { Filter } from './filter.js';
+import type { Handler } from '../../express.js';

package/types/not-found/middleware.d.ts

@@ -0,0 +1 @@
+export function notFoundMiddleware(req: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").Request<import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").ParamsDictionary, any, any, import(".store/@types-qs-npm-6.14.0-e27d9ca044/package").ParsedQs, Record<string, any>>, res: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").Response<any, Record<string, any>, number>, next: import(".store/@types-express-serve-static-core-npm-5.0.7-4a816a369e/package").NextFunction): unknown;

package/types/request-id/middleware.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @param {Request} request - The express request.
+ * @param {string} [headerName] - The name of the header used in correlation.
+ * @returns {string}
+ */
+export function getTrail(request: Request, headerName?: string): string;
+/**
+ * @param {string} [headerName] - The name of a header to include in the response with the trail.
+ * @returns {Handler}
+ */
+export function createRequestIdMiddleware(headerName?: string): Handler;
+import type { Request } from '../../express.js';
+import type { Handler } from '../../express.js';

package/src/express.d.ts

@@ -1,18 +0,0 @@
-/* eslint @typescript-eslint/consistent-type-definitions: 0, n/no-missing-import: 0 */
-
-import { type Logger } from '@darksheep/logger';
-
-declare global {
-  namespace Express {
-    interface Request {
-      id: string;
-      logger: Logger;
-    }
-  }
-}
-
-export {
-  type Handler,
-  type Request,
-  type Response,
-} from 'express';

package/src/get-trail.js

@@ -1,29 +0,0 @@
-/**
- * @import { Request } from './express.js'
- * @import { Logger } from '@darksheep/logger'
- */
-import { randomUUID } from 'node:crypto';
-
-/**
- * @param {Request} request - The express request.
- * @param {Logger} logger - The root logger.
- * @param {string} headerName - The name of the header used in correlation.
- * @returns {string}
- */
-export function getTrail(request, logger, headerName) {
-  const loggerTrail = logger.get('trail');
-  if (typeof loggerTrail === 'string') {
-    return loggerTrail;
-  }
-
-  const header = request.header(headerName);
-  if (typeof header === 'string') {
-    return header;
-  }
-
-  if (typeof request.id === 'string') {
-    return request.id;
-  }
-
-  return randomUUID();
-}

package/types/request-logger.d.ts

@@ -1,10 +0,0 @@
-/**
- * @param {Logger} logger - A callback that can be bound to the request.
- * @param {Filter[]} [filters] - A list of requests to not log.
- * @param {string} [headerName] - The name of a header to include in the response with the trail.
- * @returns {Handler}
- */
-export function createRequestLogger(logger: Logger, filters?: Filter[], headerName?: string): Handler;
-import { Logger } from '@darksheep/logger';
-import type { Filter } from './should-filter.js';
-import type { Handler } from './express.js';