Extending the Express API

req  ->  app.request   ->  express.request   ->  http.IncomingMessage.prototype
res  ->  app.response  ->  express.response  ->  http.ServerResponse.prototype

// src/express-extensions.js
import express from 'express';

const MOBILE_PATTERN = /Mobi|Android|iPhone|iPad/i;

/**
 * Install the Bookshelf extensions on one application.
 * @param {import('express').Application} app
 */
export function extendBookshelfApi(app) {
  // req.isMobile: a boolean computed from the User-Agent header.
  Object.defineProperty(app.request, 'isMobile', {
    configurable: true,
    enumerable: false,
    get() {
      // `this` is the current request, so a regular function is required here.
      return MOBILE_PATTERN.test(this.get('user-agent') ?? '');
    },
  });

  // req.requestedPageSize: the validated ?pageSize= value, capped at 100.
  Object.defineProperty(app.request, 'requestedPageSize', {
    configurable: true,
    enumerable: false,
    get() {
      const raw = Number.parseInt(String(this.query.pageSize ?? ''), 10);
      if (!Number.isInteger(raw) || raw < 1) return 20;
      return Math.min(raw, 100);
    },
  });

  // res.ok(data) and res.created(data, location): response helpers.
  app.response.ok = function ok(data) {
    return this.status(200).json({ data });
  };

  app.response.created = function created(data, location) {
    if (location) this.location(location);
    return this.status(201).json({ data });
  };
}

// src/server.js
import express from 'express';
import { extendBookshelfApi } from './express-extensions.js';

const app = express();
extendBookshelfApi(app);

const books = [{ id: 1, title: 'Dune' }];

app.get('/books', (req, res) => {
  const size = req.requestedPageSize;
  res.ok({ items: books.slice(0, size), mobile: req.isMobile });
});

app.post('/books', express.json(), (req, res) => {
  const book = { id: books.length + 1, title: String(req.body?.title ?? 'Untitled') };
  books.push(book);
  res.created(book, `/books/${book.id}`);
});

app.listen(3000, () => {
  console.log('Bookshelf API listening on port 3000');
});

// src/response-envelope.js
import express from 'express';

const originalJson = express.response.json;

/**
 * Wrap every res.json() of one application in a { data, meta } envelope,
 * unless the body is already an error or already an envelope.
 * @param {import('express').Application} app
 */
export function wrapJsonInEnvelope(app) {
  app.response.json = function json(body) {
    const alreadyShaped =
      body !== null &&
      typeof body === 'object' &&
      ('data' in body || 'type' in body || 'errors' in body);

    const payload = alreadyShaped
      ? body
      : { data: body, meta: { generatedAt: new Date().toISOString() } };

    // Delegate to the original so that ETag, Content-Type, JSON spaces,
    // the replacer and the escaping settings all keep working.
    return originalJson.call(this, payload);
  };
}

// src/server.js (excerpt)
import express from 'express';
import { wrapJsonInEnvelope } from './response-envelope.js';

const app = express();
wrapJsonInEnvelope(app);

app.get('/books/:id', (req, res) => {
  res.json({ id: Number(req.params.id), title: 'Dune' });
});

// src/admin-prototypes.js
import { Router } from 'express';

/**
 * A router whose requests and responses carry extra admin-only members.
 * @param {import('express').Application} app
 */
export function createAdminRouter(app) {
  const adminRequest = Object.create(app.request, {
    isAdmin: {
      configurable: true,
      get() {
        return this.get('x-admin-token') === 'replace-with-a-real-check';
      },
    },
  });

  const adminResponse = Object.create(app.response, {
    audit: {
      configurable: true,
      value: function audit(action) {
        this.set('x-audit-action', action);
        return this;
      },
    },
  });

  const router = Router();

  router.use((req, res, next) => {
    Object.setPrototypeOf(req, adminRequest);
    Object.setPrototypeOf(res, adminResponse);
    next();
  });

  router.delete('/books/:id', (req, res) => {
    if (!req.isAdmin) return res.status(403).json({ error: 'forbidden' });
    return res.audit('book.delete').status(204).end();
  });

  return router;
}

// src/settings.js
import process from 'node:process';

/**
 * Store the Bookshelf configuration in the application settings.
 * @param {import('express').Application} app
 */
export function configureSettings(app) {
  app.set('bookshelf.name', 'Bookshelf API');
  app.set('bookshelf.maxPageSize', Number(process.env.MAX_PAGE_SIZE ?? 100));
  app.set('bookshelf.catalogue', new Map());

  // Feature flags read like Express's own booleans.
  if (process.env.ENABLE_EXPERIMENTAL_SEARCH === 'true') {
    app.enable('bookshelf.experimentalSearch');
  } else {
    app.disable('bookshelf.experimentalSearch');
  }

  // Built-in settings sit in the same store.
  app.disable('x-powered-by');
  app.set('json spaces', process.env.NODE_ENV === 'production' ? 0 : 2);
}

// src/server.js (excerpt)
import express from 'express';
import { configureSettings } from './settings.js';

const app = express();
configureSettings(app);

app.get('/search', (req, res) => {
  if (!req.app.enabled('bookshelf.experimentalSearch')) {
    return res.status(404).json({ error: 'search is not available' });
  }
  const limit = Math.min(Number(req.query.limit ?? 20), req.app.get('bookshelf.maxPageSize'));
  return res.json({ limit });
});

// src/admin-app.js
import express from 'express';

export function createAdminApp() {
  const admin = express();

  admin.on('mount', (parent) => {
    // parent is the application that mounted this one.
    console.log('Admin mounted in', parent.get('bookshelf.name'));
  });

  admin.get('/', (req, res) => {
    res.json({ name: req.app.get('bookshelf.name'), mountpath: req.app.mountpath });
  });

  return admin;
}

// src/request-context.js
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';

export const requestContext = new AsyncLocalStorage();

/**
 * Attach per-request state without touching any prototype.
 */
export function requestContextMiddleware(req, res, next) {
  const requestId = req.get('x-request-id') ?? randomUUID();
  res.set('x-request-id', requestId);
  res.locals.requestId = requestId;

  // A per-response helper: only this response gets it, and only after this middleware.
  res.locals.ok = (data) => res.status(200).json({ data, requestId });

  requestContext.run({ requestId }, next);
}

/** Read the request id from any function called during the request. */
export function currentRequestId() {
  return requestContext.getStore()?.requestId;
}

// src/server.js (excerpt)
import express from 'express';
import { requestContextMiddleware, currentRequestId } from './request-context.js';

const app = express();

app.locals.siteName = 'Bookshelf';
app.use(requestContextMiddleware);

app.get('/books/:id', (req, res) => {
  console.log('Serving book for request', currentRequestId());
  res.locals.ok({ id: Number(req.params.id) });
});

// src/types/express-extensions.d.ts
// The file must be a module (it has an import or export) for `declare global` to work.
export {};

declare global {
  namespace Express {
    interface Request {
      /** True when the User-Agent looks like a mobile browser. */
      readonly isMobile: boolean;
      /** The validated pageSize query value, between 1 and 100. */
      readonly requestedPageSize: number;
    }

    interface Response {
      ok(data: unknown): this;
      created(data: unknown, location?: string): this;
    }

    // Typed res.locals and app.locals.
    interface Locals {
      requestId?: string;
      siteName?: string;
    }
  }
}

// src/express-extensions.ts
import type { Application, Request, Response } from 'express';

const MOBILE_PATTERN = /Mobi|Android|iPhone|iPad/i;

export function extendBookshelfApi(app: Application): void {
  Object.defineProperty(app.request, 'isMobile', {
    configurable: true,
    get(this: Request): boolean {
      return MOBILE_PATTERN.test(this.get('user-agent') ?? '');
    },
  });

  Object.defineProperty(app.request, 'requestedPageSize', {
    configurable: true,
    get(this: Request): number {
      const raw = Number.parseInt(String(this.query.pageSize ?? ''), 10);
      return Number.isInteger(raw) && raw > 0 ? Math.min(raw, 100) : 20;
    },
  });

  app.response.ok = function ok(this: Response, data: unknown) {
    return this.status(200).json({ data });
  };

  app.response.created = function created(this: Response, data: unknown, location?: string) {
    if (location) this.location(location);
    return this.status(201).json({ data });
  };
}

// src/server.ts
import express from 'express';
import { extendBookshelfApi } from './express-extensions.js';

const app = express();
extendBookshelfApi(app);

app.get('/books', (req, res) => {
  // req.requestedPageSize and res.ok are fully typed through the merged interfaces.
  res.ok({ pageSize: req.requestedPageSize, mobile: req.isMobile });
});

app.listen(3000);

// test/express-extensions.test.js
import assert from 'node:assert/strict';
import { once } from 'node:events';
import { test } from 'node:test';
import express from 'express';
import { extendBookshelfApi } from '../src/express-extensions.js';

test('req.requestedPageSize caps the value at 100', async () => {
  const app = express();
  extendBookshelfApi(app);
  app.get('/size', (req, res) => res.ok({ size: req.requestedPageSize }));

  const server = app.listen(0);
  await once(server, 'listening');
  try {
    const { port } = server.address();
    const response = await fetch(`http://127.0.0.1:${port}/size?pageSize=5000`);
    assert.equal(response.status, 200);
    assert.deepEqual(await response.json(), { data: { size: 100 } });
  } finally {
    server.close();
  }
});