@darksheep/express 2.1.0 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [2.1.2](https://github.com/DarkSheepSoftware/node-packages/compare/express-v2.1.1...express-v2.1.2) (2026-04-17)
+
+
+### 🩹 Fixes
+
+* **express:** make @darksheep/logger optional, always log errors ([#836](https://github.com/DarkSheepSoftware/node-packages/issues/836)) ([f29fef9](https://github.com/DarkSheepSoftware/node-packages/commit/f29fef9453b78ef03b6903bcc0b1ccd3af4e2baa))
+
+
+### 📚 Documentation
+
+* Update the READMEs ([#824](https://github.com/DarkSheepSoftware/node-packages/issues/824)) ([9d282b7](https://github.com/DarkSheepSoftware/node-packages/commit/9d282b724fe056ec275578088bf495985e22c25f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @darksheep/errors bumped from 1.2.0 to 1.2.1
+  * devDependencies
+    * @darksheep/json-schema bumped to 0.1.2
+    * @darksheep/logger bumped from 1.3.0 to 1.3.1
+  * peerDependencies
+    * @darksheep/json-schema bumped to 0.1.2
+    * @darksheep/logger bumped from >=1.0.10 to >=1.3.1
+
+## [2.1.1](https://github.com/DarkSheepSoftware/node-packages/compare/express-v2.1.0...express-v2.1.1) (2025-12-04)
+
+
+### 📚 Documentation
+
+* fix issue in example ([#797](https://github.com/DarkSheepSoftware/node-packages/issues/797)) ([c889a98](https://github.com/DarkSheepSoftware/node-packages/commit/c889a980ea4b6cbe970eac7627d8229becddbe83))
+
 ## [2.1.0](https://github.com/DarkSheepSoftware/node-packages/compare/express-v2.0.1...express-v2.1.0) (2025-10-09)
 
 

package/README.md

@@ -1,2 +1,109 @@
 # @darksheep/express
-Automatically log your express requests.
+Express middleware for the stuff you end up wiring up in every service.
+
+## Installation
+```sh
+yarn add @darksheep/express express
+```
+
+## Example
+```js
+import express from 'express';
+import {
+  createRequestIdMiddleware,
+  createRequestLoggerMiddleware,
+  errorHandlerMiddleware,
+  notFoundMiddleware,
+  HttpErrorHandler,
+} from '@darksheep/express';
+
+const app = express();
+
+app.use(createRequestIdMiddleware());
+app.use(createRequestLoggerMiddleware());
+
+// your routes here
+
+app.use(notFoundMiddleware);
+app.errorHandlers = [ HttpErrorHandler ];
+app.use(errorHandlerMiddleware);
+```
+
+## Detailed Docs
+
+### Middleware
+
+```js
+/**
+ * Adds a unique request ID to req.id and the X-Request-Id response header.
+ */
+createRequestIdMiddleware(options?)
+
+/**
+ * Logs each request. Requires @darksheep/logger.
+ */
+createRequestLoggerMiddleware(options?)
+
+/**
+ * Returns 404 JSON for any unmatched route.
+ */
+notFoundMiddleware
+
+/**
+ * Catches errors, sets the status code from error.statusCode, and returns JSON.
+ * Checks app.errorHandlers to format the error body.
+ */
+errorHandlerMiddleware
+```
+
+### Content type
+
+`createContentTypeMiddleware` checks the incoming `Content-Type` header and either continues or throws `UnsupportedMediaType`:
+
+```js
+import { createContentTypeMiddleware } from '@darksheep/express';
+
+// Only allow JSON bodies on this route
+app.post('/data', createContentTypeMiddleware('application/json'), (req, res) => {
+  res.json({ ok: true });
+});
+
+// Allow multiple content types
+app.post('/upload', createContentTypeMiddleware(['application/json', 'multipart/form-data']), handler);
+
+// Pass false to skip to the next route instead of throwing
+app.post('/maybe', createContentTypeMiddleware('application/json', false), jsonHandler);
+```
+
+`createContentTypeRouter` is a shorthand that builds a sub-router dispatching by `Content-Type`:
+
+```js
+import { createContentTypeRouter } from '@darksheep/express';
+
+app.post('/data', createContentTypeRouter({
+  'application/json': jsonHandler,
+  'multipart/form-data': formHandler,
+}));
+// Throws UnsupportedMediaType for anything else
+```
+
+### Error handlers
+`app.errorHandlers` is an array of `{ test, format }` objects. The first matching handler formats the error response.
+
+```js
+/**
+ * Handles @darksheep/errors HttpError instances.
+ * Returns the error name and message.
+ */
+HttpErrorHandler
+
+/**
+ * Handles @darksheep/json-schema validation errors.
+ */
+SchemaErrorHandler
+
+/**
+ * Handles Zod validation errors.
+ */
+ZodErrorHandler
+```

package/express.d.ts

@@ -1,11 +1,11 @@
 /* eslint @typescript-eslint/consistent-type-definitions: 0 */
-import { type Logger } from '@darksheep/logger';
+import type { Logger } from '@darksheep/logger';
 
-export type ApiError = {
+export interface ApiError {
   message?: string;
   name: string;
   path?: (number | string)[] | string;
-};
+}
 
 export type ErrorHandler<E extends Error = Error> = {
   format(error: E): ApiError[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksheep/express",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "express utilites and other bits",
   "license": "UNLICENCED",
   "type": "module",
@@ -22,16 +22,16 @@
     "test:watch": "node --watch --test src/**/*.test.js"
   },
   "dependencies": {
-    "@darksheep/errors": "1.2.0",
+    "@darksheep/errors": "1.2.1",
     "@darksheep/prune": "1.1.0",
     "on-finished": "2.4.1"
   },
   "devDependencies": {
     "@darksheep/json-schema": "",
-    "@darksheep/logger": "1.3.0",
+    "@darksheep/logger": "1.3.1",
     "@types/express": "~5.0.0",
     "@types/on-finished": "^2",
-    "express": "~5.1.0"
+    "express": "~5.2.0"
   },
   "peerDependencies": {
     "@darksheep/json-schema": "",

package/src/content-type/middleware.js

@@ -22,14 +22,15 @@ export function createContentTypeMiddleware(targetContentTypes, shouldThrow = tr
       provided != null &&
       contentTypes.has(provided)
     ) {
-      return next();
+      next();
+      return;
     }
 
     if (shouldThrow === true) {
       return unsupportedMediaType(request, response, next);
     }
 
-    return next('route');
+    next('route');
   };
 }
 

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

@@ -8,7 +8,9 @@
  * @property {Record<string, string> | undefined} headers - Additional headers to send.
  * @property {number} statusCode - The response status code.
  */
-/** @typedef {Error & HttpErrorExtra} HttpError */
+/**
+ * @typedef {Error & HttpErrorExtra} HttpError
+ */
 
 /** @type {ErrorHandler<HttpError>} */
 export const HttpErrorHandler = {

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

@@ -1,10 +1,11 @@
 /**
+ * @import * as JsonSchema from '@darksheep/json-schema';
  * @import { ErrorHandler } from '../../express.js';
  * @import { RequestSchemaError, ResponseSchemaError } from '@darksheep/json-schema';
  */
 
 /**
- * @type {import('@darksheep/json-schema')}
+ * @type {JsonSchema}
  */
 let schema;
 try {
@@ -33,8 +34,9 @@ export const SchemaErrorHandler = {
   format(error) {
     const base = HttpErrorHandler.format(error);
 
-    // @ts-ignore
-    base.push(...error.errors);
+    for (const child of error.errors) {
+      base.push(Object.assign(child, { name: child.keyword }));
+    }
 
     return base;
   },

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

@@ -8,7 +8,9 @@
  * @property {string} code - The zod error code text.
  * @property {string} path - The path to the error in zod.
  */
-/** @typedef {Error & { errors: ZodIssue[] }} ZodError */
+/**
+ * @typedef {Error & { errors: ZodIssue[] }} ZodError
+ */
 
 /** @type {ErrorHandler<ZodError>} */
 export const ZodErrorHandler = {

package/src/logger/filter.js

@@ -5,14 +5,20 @@ const fallbackFilters = [
   /^\/live(?:ness)?z?$/u,
 ];
 
-/** @typedef {string|RegExp} Filter */
+/**
+ * @typedef {string|RegExp} Filter
+ */
 
 /**
- * @param {string} requestPath - The path to test.
+ * @param {string | undefined | null} [requestPath] - The path to test.
  * @param {Filter[]} [filters] - A list of paths to filter out.
  * @returns {boolean}
  */
 export function shouldFilterOutRequest(requestPath, filters = fallbackFilters) {
+  if (requestPath == null) {
+    return false;
+  }
+
   for (const filter of filters) {
     if (filter instanceof RegExp && filter.test(requestPath)) {
       return true;

package/src/logger/middleware.js

@@ -1,18 +1,32 @@
 /**
  * @import { Socket } from 'node:net'
+ * @import { Logger } from '@darksheep/logger'
  * @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 './filter.js';
 
+async function getLogger() {
+  try {
+    const { Logger } = await import('@darksheep/logger');
+
+    return Logger;
+  } catch {
+    // optional peer dependency
+  }
+}
+
+const Logger = await getLogger();
+
 /** @type {WeakMap<Socket, number>} */
 const sockets = new WeakMap();
 
+const wrap = Logger?.wrap ?? ((_ctx, fn) => fn());
+
 /**
  * @param {Logger} logger - A callback that can be bound to the request.
  * @param {Filter[]} [filters] - A list of requests to not log.
@@ -25,24 +39,25 @@ export function createRequestLoggerMiddleware(
   return (request, response, next) => {
     request.logger = logger;
 
-    Logger.wrap({
+    wrap({
       request: request,
       trail: request.trail,
     }, () => {
-      const [ requestPath ] = request.originalUrl.split('?', 1);
-      if (
-        requestPath == null ||
-        shouldFilterOutRequest(requestPath, filters)
-      ) {
-        return next();
-      }
-
       const startBytesRead = sockets.get(request.socket) ?? 0;
       const startBytesWritten = request.socket.bytesWritten;
 
       const requestStartMs = Date.now();
       onFinished(response, (error) => {
         sockets.set(request.socket, request.socket.bytesRead);
+        const [ requestPath ] = request.originalUrl.split('?', 1);
+
+        if (
+          shouldFilterOutRequest(requestPath, filters) === true &&
+          response.statusCode < 400 &&
+          error == null
+        ) {
+          return;
+        }
 
         const message = `${request.method} ${requestPath} ${response.statusCode}`;
         const context = pruneShallow({
@@ -61,14 +76,16 @@ export function createRequestLoggerMiddleware(
         });
 
         if (response.statusCode < 400) {
-          return request.logger.info(message, context);
+          request.logger.info(message, context);
+          return;
         }
 
         if (response.statusCode < 500) {
-          return request.logger.warning(message, context);
+          request.logger.warning(message, context);
+          return;
         }
 
-        return request.logger.error(message, context);
+        request.logger.error(message, context);
       });
 
       next();

package/src/not-found/middleware.js

@@ -1,11 +1,17 @@
 /**
- * @import { Handler } from '../../express.js'
+ * @import { NextFunction } from 'express'
+ * @import { Request, Response } from '../../express.js'
  */
 import { NotFound } from '@darksheep/errors';
 
-/** @type {Handler} */
+/**
+ * @param {Request} request - The express request.
+ * @param {Response} _response - The express response.
+ * @param {NextFunction} next - The next handler.
+ * @returns {void}
+ */
 export function notFoundMiddleware(request, _response, next) {
-  return next(
+  next(
     new NotFound(`${request.method} ${request.originalUrl}`),
   );
 }

package/src/request-id/middleware.js

@@ -29,6 +29,6 @@ export function createRequestIdMiddleware(headerName) {
   return (request, response, next) => {
     request.trail ??= getTrail(request, headerName);
     response.trail = request.trail;
-    return next();
+    next();
   };
 }

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

@@ -4,5 +4,5 @@
  * @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;
+export function unsupportedMediaType(req: import("express-serve-static-core").Request<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>, res: import("express-serve-static-core").Response<any, Record<string, any>, number>, next: import("express-serve-static-core").NextFunction): unknown;
 import type { Handler } from '../../express.js';

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

@@ -7,7 +7,9 @@
  * @property {Record<string, string> | undefined} headers - Additional headers to send.
  * @property {number} statusCode - The response status code.
  */
-/** @typedef {Error & HttpErrorExtra} HttpError */
+/**
+ * @typedef {Error & HttpErrorExtra} HttpError
+ */
 /** @type {ErrorHandler<HttpError>} */
 export const HttpErrorHandler: ErrorHandler<HttpError>;
 export type HttpErrorExtra = {

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

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

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

@@ -1 +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;
+export function errorHandlerMiddleware(err: any, req: import("express-serve-static-core").Request<import("express-serve-static-core").ParamsDictionary, any, any, import("qs").ParsedQs, Record<string, any>>, res: import("express-serve-static-core").Response<any, Record<string, any>, number>, next: import("express-serve-static-core").NextFunction): unknown;

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

@@ -7,7 +7,9 @@
  * @property {string} code - The zod error code text.
  * @property {string} path - The path to the error in zod.
  */
-/** @typedef {Error & { errors: ZodIssue[] }} ZodError */
+/**
+ * @typedef {Error & { errors: ZodIssue[] }} ZodError
+ */
 /** @type {ErrorHandler<ZodError>} */
 export const ZodErrorHandler: ErrorHandler<ZodError>;
 export type ZodIssue = {

package/types/logger/filter.d.ts

@@ -1,8 +1,10 @@
-/** @typedef {string|RegExp} Filter */
 /**
- * @param {string} requestPath - The path to test.
+ * @typedef {string|RegExp} Filter
+ */
+/**
+ * @param {string | undefined | null} [requestPath] - The path to test.
  * @param {Filter[]} [filters] - A list of paths to filter out.
  * @returns {boolean}
  */
-export function shouldFilterOutRequest(requestPath: string, filters?: Filter[]): boolean;
+export function shouldFilterOutRequest(requestPath?: string | undefined | null, filters?: Filter[]): boolean;
 export type Filter = string | RegExp;

package/types/logger/middleware.d.ts

@@ -4,6 +4,8 @@
  * @returns {Handler}
  */
 export function createRequestLoggerMiddleware(logger: Logger, filters?: Filter[]): Handler;
-import { Logger } from '@darksheep/logger';
+declare const Logger: typeof Logger | undefined;
+import type { Logger } from '@darksheep/logger';
 import type { Filter } from './filter.js';
 import type { Handler } from '../../express.js';
+export {};

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

@@ -1 +1,10 @@
-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;
+/**
+ * @param {Request} request - The express request.
+ * @param {Response} _response - The express response.
+ * @param {NextFunction} next - The next handler.
+ * @returns {void}
+ */
+export function notFoundMiddleware(request: Request, _response: Response, next: NextFunction): void;
+import type { Request } from '../../express.js';
+import type { Response } from '../../express.js';
+import type { NextFunction } from 'express';