@darksheep/express 2.1.1 → 2.1.4

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # Changelog
 
+## [2.1.4](https://github.com/DarkSheepSoftware/node-packages/compare/express-v2.1.3...express-v2.1.4) (2026-09-20)
+
+
+### 🩹 Fixes
+
+* **express:** correct JSDoc types that broke the prepack typecheck ([#1005](https://github.com/DarkSheepSoftware/node-packages/issues/1005)) ([d21cd6f](https://github.com/DarkSheepSoftware/node-packages/commit/d21cd6fffe02ad1ed13a0d67c6c19e32eeff5a85))
+
+## [2.1.3](https://github.com/DarkSheepSoftware/node-packages/compare/express-v2.1.2...express-v2.1.3) (2026-09-20)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @darksheep/logger bumped from 1.3.1 to 1.4.0
+  * peerDependencies
+    * @darksheep/logger bumped from >=1.0.10 to >=1.4.0
+
+## [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)
 
 

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,5 +1,5 @@
 /* eslint @typescript-eslint/consistent-type-definitions: 0 */
-import { type Logger } from '@darksheep/logger';
+import type { Logger } from '@darksheep/logger';
 
 export interface ApiError {
   message?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksheep/express",
-  "version": "2.1.1",
+  "version": "2.1.4",
   "description": "express utilites and other bits",
   "license": "UNLICENCED",
   "type": "module",
@@ -22,13 +22,13 @@
     "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.4.0",
     "@types/express": "~5.0.0",
     "@types/on-finished": "^2",
     "express": "~5.2.0"
@@ -48,5 +48,8 @@
   },
   "engines": {
     "node": "^20.13.1 || >=22.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/content-type/middleware.js

@@ -17,7 +17,7 @@ export function createContentTypeMiddleware(targetContentTypes, shouldThrow = tr
   );
 
   return (request, response, next) => {
-    const provided = request.headers['content-type']?.split(';').at(0);
+    const provided = request.headers['content-type']?.split(';', 1).at(0);
     if (
       provided != null &&
       contentTypes.has(provided)
@@ -35,9 +35,9 @@ export function createContentTypeMiddleware(targetContentTypes, shouldThrow = tr
 }
 
 /** @type {Handler} */
-export function unsupportedMediaType(request) {
+export function unsupportedMediaType(request, _response, _next) {
   const { method } = request;
-  const url = request.originalUrl.split('?').at(0) ?? '/';
+  const url = request.originalUrl.split('?', 1).at(0) ?? '/';
   const contentType = request.headers['content-type'];
 
   throw new UnsupportedMediaType(

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

@@ -5,7 +5,7 @@
  */
 
 /**
- * @type {JsonSchema}
+ * @type {typeof JsonSchema | undefined}
  */
 let schema;
 try {

package/src/error-handler/middleware.js

@@ -21,7 +21,8 @@ export function errorHandlerMiddleware(error, request, response, _next) {
       : 500,
   );
 
-  for (const { format, test } of request.app.errorHandlers ?? []) {
+  const errorHandlers = request.app.errorHandlers ?? [];
+  for (const { format, test } of errorHandlers) {
     if (test(error)) {
       response.json({
         errors: format(error),

package/src/logger/filter.js

@@ -10,11 +10,15 @@ const fallbackFilters = [
  */
 
 /**
- * @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,20 +1,34 @@
 /**
  * @import { Socket } from 'node:net'
+ * @import { Logger as LoggerType } 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 {LoggerType} logger - A callback that can be bound to the request.
  * @param {Filter[]} [filters] - A list of requests to not log.
  * @returns {Handler}
  */
@@ -25,25 +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)
-      ) {
-        next();
-        return;
-      }
-
       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({

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

@@ -1,8 +1,10 @@
+/**
+ * @import { Handler } from '../../express.js'
+ */
+import type { Handler } from '../../express.js';
 /**
  * @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.1.0-227fccbb7d/package").Request<import(".store/@types-express-serve-static-core-npm-5.1.0-227fccbb7d/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.1.0-227fccbb7d/package").Response<any, Record<string, any>, number>, next: import(".store/@types-express-serve-static-core-npm-5.1.0-227fccbb7d/package").NextFunction): unknown;
-import type { Handler } from '../../express.js';
+export declare function createContentTypeMiddleware(targetContentTypes: string | string[], shouldThrow?: boolean): Handler;

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

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

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

@@ -1,17 +1,7 @@
 /**
  * @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>;
+import type { ErrorHandler } from '../../express.js';
 export type HttpErrorExtra = {
     /**
      * - Should the error message be sent to the client.
@@ -27,4 +17,14 @@ export type HttpErrorExtra = {
     statusCode: number;
 };
 export type HttpError = Error & HttpErrorExtra;
-import type { 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 declare const HttpErrorHandler: ErrorHandler<HttpError>;

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

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

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

@@ -1 +1,6 @@
-export function errorHandlerMiddleware(err: any, req: import(".store/@types-express-serve-static-core-npm-5.1.0-227fccbb7d/package").Request<import(".store/@types-express-serve-static-core-npm-5.1.0-227fccbb7d/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.1.0-227fccbb7d/package").Response<any, Record<string, any>, number>, next: import(".store/@types-express-serve-static-core-npm-5.1.0-227fccbb7d/package").NextFunction): unknown;
+/**
+ * @import {
+ *   ErrorRequestHandler,
+ * } from '../../express.js'
+ */
+export {};

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

@@ -1,17 +1,7 @@
 /**
  * @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>;
+import type { ErrorHandler } from '../../express.js';
 export type ZodIssue = {
     /**
      * - The error message for the path.
@@ -29,4 +19,14 @@ export type ZodIssue = {
 export type ZodError = Error & {
     errors: ZodIssue[];
 };
-import type { 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 declare const ZodErrorHandler: ErrorHandler<ZodError>;

package/types/index.d.ts

@@ -1,9 +1,9 @@
-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";
+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/filter.d.ts

@@ -1,10 +1,10 @@
+export type Filter = string | RegExp;
 /**
  * @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: string, filters?: Filter[]): boolean;
-export type Filter = string | RegExp;
+export declare function shouldFilterOutRequest(requestPath?: string | undefined | null, filters?: Filter[]): boolean;

package/types/logger/middleware.d.ts

@@ -1,9 +1,15 @@
 /**
- * @param {Logger} logger - A callback that can be bound to the request.
+ * @import { Socket } from 'node:net'
+ * @import { Logger as LoggerType } from '@darksheep/logger'
+ * @import { Handler } from '../../express.js'
+ * @import { Filter } from './filter.js'
+ */
+import type { Logger as LoggerType } from '@darksheep/logger';
+import type { Handler } from '../../express.js';
+import type { Filter } from './filter.js';
+/**
+ * @param {LoggerType} 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';
+export declare function createRequestLoggerMiddleware(logger: LoggerType, filters?: Filter[]): Handler;

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

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

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

@@ -1,13 +1,12 @@
+import type { Handler, Request } from '../../express.js';
 /**
  * @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;
+export declare 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';
+export declare function createRequestIdMiddleware(headerName?: string): Handler;