@darksheep/express 2.1.1 → 2.1.2

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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)
 
 

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.2",
   "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.3.1",
     "@types/express": "~5.0.0",
     "@types/on-finished": "^2",
     "express": "~5.2.0"

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,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,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

@@ -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.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;
+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/middleware.d.ts

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

@@ -2,9 +2,9 @@
  * @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 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 {};