@api-envelope/express

Express middleware that adds res.ok() and res.fail() helpers for sending standardized API Envelope responses.

Table of contents

• Why use this
• Install
• Quick start
• Configuration — custom codes
• Type-safe custom codes
• Things to know
• API reference
• FAQ
• License

Why use this

Instead of hand-writing res.status(404).json({ success: false, ... }) in every route — and inevitably drifting on field names between them — res.ok() / res.fail() give every route in your Express app the exact same response shape, with the HTTP status resolved automatically from a code you choose.

Install

npm install @api-envelope/express

Requires express in your project (peer dependency). @api-envelope/core is installed automatically.

Quick start

import express from "express";
import useApiEnvelope from "@api-envelope/express";
import "@api-envelope/express"; // brings in the res.ok()/res.fail() type augmentation

const app = express();

app.use(useApiEnvelope());

app.get("/users/:id", (req, res) => {
  const user = { id: req.params.id, name: "Ada" };
  return res.ok({ code: "OK", data: user });
});

app.get("/users/:id/missing", (req, res) => {
  return res.fail({ code: "NOT_FOUND", message: "User does not exist" });
});

res.ok() sends 200 { success: true, code: "OK", status: 200, message: "...", data: {...} }. res.fail() sends 404 { success: false, code: "NOT_FOUND", status: 404, message: "User does not exist" }.

Register the middleware once, before any routes that call res.ok() / res.fail().

Configuration — custom codes

app.use(
  useApiEnvelope({
    codes: [
      { code: "USER_NOT_FOUND", status: 404 },
      { code: "INVALID_TOKEN", status: 401 },
    ],
  }),
);

app.get("/users/:id", (req, res) => {
  if (!userExists) {
    return res.fail({ code: "USER_NOT_FOUND" });
  }
  return res.ok({ code: "OK", data: user });
});

Built-in codes (OK, SUCCESS, CREATED, NOT_FOUND, ...) are always available — options.codes only needs to list codes specific to your app. See @api-envelope/core for the full default list.

Type-safe custom codes

import type { DefaultCode } from "@api-envelope/express";

type AppCode = DefaultCode | "USER_NOT_FOUND";

app.get("/users/:id", (req, res) => {
  return res.fail<AppCode>({ code: "USER_NOT_FOUND" }); // autocompleted & checked
});

Things to know

• Register before your routes. res.ok/res.fail don't exist until the middleware from useApiEnvelope() has run for that request.
• One instance per useApiEnvelope() call. Calling it more than once (e.g. per sub-router) creates separate code registries — custom codes registered on one don't apply to another.
• The .d.ts augmentation is types only. Importing @api-envelope/express gives TypeScript the shape of res.ok/res.fail; you still need app.use(useApiEnvelope()) for them to exist at runtime.
• Custom codes can override defaults. Registering { code: "OK", status: 201 } changes what "OK" resolves to for that instance.

API reference

useApiEnvelope(options?)

Returns an Express RequestHandler. options.codes is an optional array of { code, status } pairs registered on top of the built-in defaults.

res.ok({ code, data, message? })

Sends the success envelope with the matching HTTP status already set.

res.fail({ code, message? })

Sends the failure envelope with the matching HTTP status already set.

Both throw if code hasn't been registered — check for typos in custom codes, or make sure options.codes was passed to useApiEnvelope().

FAQ

Do I need to call res.status() myself? No — res.ok()/res.fail() set it for you based on the resolved code.

Can I still use res.json() directly in some routes? Yes. The middleware only adds two extra methods; it doesn't remove or wrap any existing Express Response methods.

What if I forget to register the middleware? res.ok/res.fail will be undefined at runtime and calling them will throw a TypeError, even though TypeScript sees them as valid (since the .d.ts augmentation only describes the shape, not the runtime wiring).

Does this work with express.Router() sub-routers? Yes — apply app.use(useApiEnvelope()) on the main app (or on a specific router) and any handler downstream of it gets res.ok/res.fail.

License

MIT © 2026 ltimsina

Copyright (c) [2026] [ltimsina]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

See also

• @api-envelope/core — shared types and the code registry these helpers build on.