@zudojs/middleware 1.0.2 → 1.1.0

package/README.md

@@ -183,6 +183,40 @@ const timed = withTiming("db-lookup", lookup, {
 });
 ```
 
+## Guard responses
+
+A middleware that refuses a request — authentication, authorization, tenant
+resolution — answers with `createGuardResponse()` instead of calling `next()`:
+
+```typescript
+import { createGuardResponse, isGuardResponse } from "@zudojs/middleware";
+
+const requireApiKey = async (context, next) => {
+  if (!context.request.getHeader("x-api-key")) {
+    return createGuardResponse({
+      status: 401,
+      body: { error: "Unauthorized" },
+      headers: { "www-authenticate": "ApiKey" },
+    });
+  }
+  return next();
+};
+```
+
+`@zudojs/http` sends a guard response with its own status, headers and body
+(a structured body as JSON, with `content-type: application/json` unless you
+set one). It is the contract lower-tier packages use: `@zudojs/permissions`'
+`authorize()` and `@zudojs/tenancy`'s middleware return one for every 401,
+403 and 404, without depending on `@zudojs/http`.
+
+Only the brand counts. The object carries the registered symbol
+`GUARD_RESPONSE` (`Symbol.for("zudojs.middleware.guardResponse")`), which JSON
+cannot carry, so data that happens to have a `status` key is never mistaken
+for a response, and `isGuardResponse()` is `false` for any plain
+`{ status, body, headers }` object. The result is frozen; `status` must be an
+integer in 100–599 (`RangeError` otherwise) and header values strings
+(`TypeError`).
+
 ## Errors
 
 All errors extend `MiddlewareError`, which is the class owned by

package/dist/index.d.ts

@@ -14,4 +14,5 @@ export * from "./middlewareCore/index.js";
 export * from "./middlewarePipeline/index.js";
 export * from "./middlewareUtils/index.js";
 export * from "./middlewareErrors/index.js";
+export * from "./middlewareResponse/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -14,4 +14,5 @@ export * from "./middlewareCore/index.js";
 export * from "./middlewarePipeline/index.js";
 export * from "./middlewareUtils/index.js";
 export * from "./middlewareErrors/index.js";
+export * from "./middlewareResponse/index.js";
 //# sourceMappingURL=index.js.map

package/dist/middlewareResponse/guardResponse.factory.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Creation and detection of guard responses.
+ *
+ * @module middlewareResponse/guardResponse.factory
+ */
+import { type GuardResponse, type GuardResponseInit } from "./guardResponse.type.js";
+/**
+ * Create a response a middleware returns to answer the request itself.
+ *
+ * Use it for a refusal — 400, 401, 403, 404, 423, 429 — so the transport
+ * sends that status. A plain `{ status, body, headers }` object is not
+ * recognised as a response: it is ordinary data.
+ *
+ * @param init - Status, optional body and headers.
+ * @returns A frozen, branded response.
+ * @throws {RangeError} If `status` is not an integer in 100–599.
+ * @throws {TypeError} If a header value is not a string.
+ *
+ * @example
+ * ```ts
+ * return createGuardResponse({ status: 403, body: { error: "Forbidden" } });
+ * ```
+ */
+export declare function createGuardResponse(init: GuardResponseInit): GuardResponse;
+/**
+ * Whether a value is a {@link GuardResponse}.
+ *
+ * Only the brand counts. An object with `status`, `body` and `headers` keys
+ * but no brand is not a guard response, so JSON data is never mistaken for
+ * one.
+ */
+export declare function isGuardResponse(value: unknown): value is GuardResponse;
+//# sourceMappingURL=guardResponse.factory.d.ts.map

package/dist/middlewareResponse/guardResponse.factory.js

@@ -0,0 +1,72 @@
+/**
+ * Creation and detection of guard responses.
+ *
+ * @module middlewareResponse/guardResponse.factory
+ */
+import { GUARD_RESPONSE, } from "./guardResponse.type.js";
+const JSON_CONTENT_TYPE = "application/json; charset=utf-8";
+function isStatus(value) {
+    return (typeof value === "number" &&
+        Number.isInteger(value) &&
+        value >= 100 &&
+        value <= 599);
+}
+function isRawBody(body) {
+    return typeof body === "string" || body instanceof Uint8Array;
+}
+function normalizeHeaders(headers, body) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (typeof value !== "string") {
+            throw new TypeError(`Guard response header "${name}" must be a string.`);
+        }
+        result[name.toLowerCase()] = value;
+    }
+    if (body !== undefined && !isRawBody(body) && !result["content-type"]) {
+        result["content-type"] = JSON_CONTENT_TYPE;
+    }
+    return Object.freeze(result);
+}
+/**
+ * Create a response a middleware returns to answer the request itself.
+ *
+ * Use it for a refusal — 400, 401, 403, 404, 423, 429 — so the transport
+ * sends that status. A plain `{ status, body, headers }` object is not
+ * recognised as a response: it is ordinary data.
+ *
+ * @param init - Status, optional body and headers.
+ * @returns A frozen, branded response.
+ * @throws {RangeError} If `status` is not an integer in 100–599.
+ * @throws {TypeError} If a header value is not a string.
+ *
+ * @example
+ * ```ts
+ * return createGuardResponse({ status: 403, body: { error: "Forbidden" } });
+ * ```
+ */
+export function createGuardResponse(init) {
+    if (!isStatus(init.status)) {
+        throw new RangeError(`Guard response status must be an integer in 100-599, got ${String(init.status)}.`);
+    }
+    return Object.freeze({
+        [GUARD_RESPONSE]: true,
+        status: init.status,
+        body: init.body,
+        headers: normalizeHeaders(init.headers, init.body),
+    });
+}
+/**
+ * Whether a value is a {@link GuardResponse}.
+ *
+ * Only the brand counts. An object with `status`, `body` and `headers` keys
+ * but no brand is not a guard response, so JSON data is never mistaken for
+ * one.
+ */
+export function isGuardResponse(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value[GUARD_RESPONSE] ===
+            true &&
+        isStatus(value.status));
+}
+//# sourceMappingURL=guardResponse.factory.js.map

package/dist/middlewareResponse/guardResponse.type.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The guard response contract: how a middleware that refuses a request tells
+ * the transport which status, headers and body to answer with.
+ *
+ * @module middlewareResponse/guardResponse.type
+ */
+/**
+ * Brand carried by every {@link GuardResponse}.
+ *
+ * A registered symbol (`Symbol.for`), so two copies of this package in one
+ * process still agree on it. JSON cannot carry a symbol, so request data can
+ * never forge the brand: a plain object that merely has a `status` key is not
+ * a guard response.
+ */
+export declare const GUARD_RESPONSE: unique symbol;
+/**
+ * A response a middleware returns instead of calling `next()`.
+ *
+ * Created with {@link createGuardResponse}. `@zudojs/http` turns one into a
+ * real response with this status, these headers and this body; any other
+ * returned object keeps its previous meaning.
+ */
+export interface GuardResponse {
+    /** Marks the object as a guard response. */
+    readonly [GUARD_RESPONSE]: true;
+    /** HTTP status code, an integer in 100–599. */
+    readonly status: number;
+    /** Response body. Serialized as JSON unless it is a string or bytes. */
+    readonly body: unknown;
+    /** Response headers, keyed by lower-case name. */
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** Input to {@link createGuardResponse}. */
+export interface GuardResponseInit {
+    /** HTTP status code, an integer in 100–599. */
+    readonly status: number;
+    /** Response body. Omit for an empty body. */
+    readonly body?: unknown;
+    /**
+     * Response headers. A JSON body gets `content-type: application/json`
+     * unless one is given here.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=guardResponse.type.d.ts.map

package/dist/middlewareResponse/guardResponse.type.js

@@ -0,0 +1,16 @@
+/**
+ * The guard response contract: how a middleware that refuses a request tells
+ * the transport which status, headers and body to answer with.
+ *
+ * @module middlewareResponse/guardResponse.type
+ */
+/**
+ * Brand carried by every {@link GuardResponse}.
+ *
+ * A registered symbol (`Symbol.for`), so two copies of this package in one
+ * process still agree on it. JSON cannot carry a symbol, so request data can
+ * never forge the brand: a plain object that merely has a `status` key is not
+ * a guard response.
+ */
+export const GUARD_RESPONSE = Symbol.for("zudojs.middleware.guardResponse");
+//# sourceMappingURL=guardResponse.type.js.map

package/dist/middlewareResponse/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Guard responses: the contract a middleware uses to answer a request itself
+ * (a 401, 403, 404 …) instead of calling `next()`, and that `@zudojs/http`
+ * honours.
+ *
+ * @module middlewareResponse
+ */
+export { GUARD_RESPONSE, type GuardResponse, type GuardResponseInit, } from "./guardResponse.type.js";
+export { createGuardResponse, isGuardResponse, } from "./guardResponse.factory.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/middlewareResponse/index.js

@@ -0,0 +1,10 @@
+/**
+ * Guard responses: the contract a middleware uses to answer a request itself
+ * (a 401, 403, 404 …) instead of calling `next()`, and that `@zudojs/http`
+ * honours.
+ *
+ * @module middlewareResponse
+ */
+export { GUARD_RESPONSE, } from "./guardResponse.type.js";
+export { createGuardResponse, isGuardResponse, } from "./guardResponse.factory.js";
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/middleware",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "Composable middleware pipeline with composition, timing, error handling, and context propagation.",
   "license": "MIT",
   "author": {
@@ -25,14 +25,14 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0"
+    "@zudojs/errors": "1.3.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -43,7 +43,7 @@
     "pipeline",
     "composition"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-middleware",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },