@basaltkit/express 1.2.0 → 1.3.0

package/README.md

@@ -1,3 +1,9 @@
+<p align="center">
+  <a href="https://basaltkit-docs.pages.dev">
+    <img src="https://basaltkit-docs.pages.dev/social-card.png" alt="Basalt" width="440">
+  </a>
+</p>
+
 # @basaltkit/express
 
 Basalt adapter for [Express](https://expressjs.com): the same typed routes, enrichers, and guards you'd use in Fastify or Hono, running on an Express server. You need it when you already use Express (or want its huge middleware ecosystem) and want Basalt's validation, per-request context, and standardized errors.

package/dist/index.d.ts

@@ -1,21 +1,24 @@
-import * as _basaltkit_core from '@basaltkit/core';
 import { Container } from '@basaltkit/core';
-import { BasaltRoute, RequestEnricher, RouteGuard } from '@basaltkit/http';
-import express, { Express } from 'express';
-
-declare const EXPRESS: _basaltkit_core.Token<express.Express>;
+import { type BasaltRoute, type RequestEnricher, type RouteGuard } from '@basaltkit/http';
+import { type Express } from 'express';
+export declare const EXPRESS: import("@basaltkit/core").Token<Express>;
 /** Mounts Basalt routes on an Express app (usable without the plugin). */
-declare function registerRoutes(app: Express, routes: BasaltRoute[], container?: Container, enrichers?: RequestEnricher[], guards?: RouteGuard[]): void;
-interface ExpressPluginOptions {
+export declare function registerRoutes(app: Express, routes: BasaltRoute[], container?: Container, enrichers?: RequestEnricher[], guards?: RouteGuard[]): void;
+export interface ExpressPluginOptions {
     routes?: BasaltRoute[];
     /** Bring your own Express app; otherwise one is created with `express.json()`. */
     app?: Express;
+    /**
+     * Serve the neutral JSON body (`NOT_FOUND_RESPONSE` from @basaltkit/http)
+     * for unmatched routes, identical across all adapters, instead of Express's
+     * HTML default. Default: true. Pass false to keep Express's own handling
+     * (e.g. when the app mounts its own catch-all after boot).
+     */
+    notFound?: boolean;
 }
 /**
  * Runs Basalt on Express. The same routes, enrichers, guards and edge plugins
  * you register for Fastify work unchanged — resolve `EXPRESS` for the app to
  * `listen()`.
  */
-declare function expressPlugin(options?: ExpressPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
-
-export { EXPRESS, type ExpressPluginOptions, expressPlugin, registerRoutes };
+export declare function expressPlugin(options?: ExpressPluginOptions): import("@basaltkit/core").BasaltPlugin<unknown>;

package/dist/index.js

@@ -1,154 +1,165 @@
-// src/index.ts
-import { createToken, definePlugin, ensureMetadata } from "@basaltkit/core";
-import {
-  HttpServerCollector,
-  HTTP_SERVER,
-  runRoute,
-  toErrorResponse,
-  isSseResponse,
-  sseProducerOf,
-  driveSse,
-  SSE_HEADERS
-} from "@basaltkit/http";
-import express from "express";
-var EXPRESS = createToken("express");
+import { Container, createToken, definePlugin, ensureMetadata } from '@basaltkit/core';
+import { NOT_FOUND_RESPONSE, HttpServerCollector, HTTP_SERVER, runRoute, toErrorResponse, isSseResponse, sseProducerOf, driveSse, SSE_HEADERS, } from '@basaltkit/http';
+import express, {} from 'express';
+export const EXPRESS = createToken('express');
 function toNeutralRequest(req) {
-  return {
-    method: req.method,
-    url: req.originalUrl,
-    headers: req.headers,
-    params: req.params,
-    query: req.query,
-    body: req.body,
-    ...req.ip ? { ip: req.ip } : {},
-    ...req.route?.path ? { routePattern: String(req.route.path) } : {},
-    raw: req
-  };
+    return {
+        method: req.method,
+        url: req.originalUrl,
+        headers: req.headers,
+        params: req.params,
+        query: req.query,
+        body: req.body,
+        ...(req.ip ? { ip: req.ip } : {}),
+        ...(req.route?.path ? { routePattern: String(req.route.path) } : {}),
+        raw: req,
+    };
 }
-var ExpressReply = class {
-  constructor(res) {
-    this.res = res;
-  }
-  res;
-  _status = 200;
-  _sent = false;
-  get sent() {
-    return this._sent;
-  }
-  get statusCode() {
-    return this._status;
-  }
-  get raw() {
-    return this.res;
-  }
-  code(status) {
-    this._status = status;
-    return this;
-  }
-  header(name, value) {
-    this.res.setHeader(name, value);
-    return this;
-  }
-  send(payload) {
-    this._sent = true;
-    this.res.status(this._status);
-    if (payload === void 0 || payload === null) this.res.end();
-    else if (typeof payload === "string") this.res.send(payload);
-    else this.res.json(payload);
-    return this;
-  }
-};
-function basaltHandler(definition, container, enrichers, guards) {
-  return async (req, res) => {
-    const reply = new ExpressReply(res);
-    try {
-      const result = await runRoute(definition, toNeutralRequest(req), reply, {
-        ...container ? { container } : {},
-        enrichers,
-        guards
-      });
-      if (isSseResponse(result)) {
-        res.writeHead(200, SSE_HEADERS);
-        await driveSse(sseProducerOf(result), {
-          write: (frame) => void res.write(frame),
-          end: () => res.end(),
-          onClose: (listener) => req.on("close", listener)
-        });
-        return;
-      }
-      if (!reply.sent) reply.send(result);
-    } catch (error) {
-      const { status, body } = toErrorResponse(error);
-      if (!res.headersSent) res.status(status).json(body);
+/** Neutral reply backed by an Express `res`. */
+class ExpressReply {
+    res;
+    _status = 200;
+    _sent = false;
+    constructor(res) {
+        this.res = res;
+    }
+    get sent() {
+        return this._sent;
+    }
+    get statusCode() {
+        return this._status;
+    }
+    get raw() {
+        return this.res;
+    }
+    code(status) {
+        this._status = status;
+        return this;
+    }
+    header(name, value) {
+        this.res.setHeader(name, value);
+        return this;
+    }
+    send(payload) {
+        this._sent = true;
+        this.res.status(this._status);
+        if (payload === undefined || payload === null)
+            this.res.end();
+        else if (typeof payload === 'string')
+            this.res.send(payload);
+        else
+            this.res.json(payload);
+        return this;
     }
-  };
-}
-function registerRoutes(app, routes, container, enrichers = [], guards = []) {
-  const router = app;
-  for (const definition of routes) {
-    router[definition.method.toLowerCase()](definition.url, basaltHandler(definition, container, enrichers, guards));
-  }
 }
-function expressPlugin(options = {}) {
-  const collector = new HttpServerCollector();
-  return definePlugin({
-    name: "basalt:express",
-    register({ container }) {
-      container.singleton(EXPRESS, () => {
-        const app = options.app ?? express();
-        app.use(express.json());
-        app.use(express.urlencoded({ extended: false }));
-        return app;
-      });
-      container.singleton(HTTP_SERVER, () => collector);
-    },
-    boot({ container, hooks }) {
-      const app = container.get(EXPRESS);
-      const routes = options.routes ?? [];
-      const metadata = ensureMetadata(container);
-      const enrichers = metadata.get("http:enrichers");
-      const guards = metadata.get("http:guards");
-      const router = app;
-      hooks.on("app:booted", () => {
-        if (collector.afterHooks.length) {
-          app.use((req, res, next) => {
-            const start = Date.now();
-            res.on("finish", () => {
-              void collector.runAfter(toNeutralRequest(req), new ExpressReply(res), res.statusCode, Date.now() - start);
+function basaltHandler(definition, container, enrichers, guards) {
+    return async (req, res) => {
+        const reply = new ExpressReply(res);
+        try {
+            const result = await runRoute(definition, toNeutralRequest(req), reply, {
+                ...(container ? { container } : {}),
+                enrichers,
+                guards,
             });
-            next();
-          });
+            if (isSseResponse(result)) {
+                res.writeHead(200, SSE_HEADERS);
+                await driveSse(sseProducerOf(result), {
+                    write: (frame) => void res.write(frame),
+                    end: () => res.end(),
+                    onClose: (listener) => req.on('close', listener),
+                });
+                return;
+            }
+            if (!reply.sent)
+                reply.send(result);
         }
-        app.use(async (req, res, next) => {
-          const reply = new ExpressReply(res);
-          if (await collector.runPre(toNeutralRequest(req), reply)) return;
-          next();
-        });
-        registerRoutes(app, routes, container, enrichers, guards);
-        for (const { method, url, handler } of collector.extraRoutes) {
-          router[method.toLowerCase()](url, async (req, res) => {
-            const reply = new ExpressReply(res);
-            const result = await handler({ request: toNeutralRequest(req), reply });
-            if (!reply.sent) reply.send(result);
-          });
+        catch (error) {
+            const { status, body } = toErrorResponse(error);
+            if (!res.headersSent)
+                res.status(status).json(body);
         }
-      });
-      for (const definition of routes) {
-        metadata.add("http:routes", {
-          method: definition.method,
-          url: definition.url,
-          meta: definition.meta ?? {},
-          body: definition.body,
-          query: definition.query,
-          params: definition.params,
-          response: definition.response
-        });
-      }
+    };
+}
+/** Mounts Basalt routes on an Express app (usable without the plugin). */
+export function registerRoutes(app, routes, container, enrichers = [], guards = []) {
+    const router = app;
+    for (const definition of routes) {
+        router[definition.method.toLowerCase()](definition.url, basaltHandler(definition, container, enrichers, guards));
     }
-  });
 }
-export {
-  EXPRESS,
-  expressPlugin,
-  registerRoutes
-};
+/**
+ * Runs Basalt on Express. The same routes, enrichers, guards and edge plugins
+ * you register for Fastify work unchanged — resolve `EXPRESS` for the app to
+ * `listen()`.
+ */
+export function expressPlugin(options = {}) {
+    const collector = new HttpServerCollector();
+    return definePlugin({
+        name: 'basalt:express',
+        register({ container }) {
+            container.singleton(EXPRESS, () => {
+                const app = options.app ?? express();
+                app.use(express.json());
+                // HTML forms and the SAML ACS binding post application/x-www-form-urlencoded.
+                app.use(express.urlencoded({ extended: false }));
+                return app;
+            });
+            container.singleton(HTTP_SERVER, () => collector);
+        },
+        boot({ container, hooks }) {
+            const app = container.get(EXPRESS);
+            const routes = options.routes ?? [];
+            const metadata = ensureMetadata(container);
+            const enrichers = metadata.get('http:enrichers');
+            const guards = metadata.get('http:guards');
+            const router = app;
+            // Mount everything once edge plugins have registered their hooks/routes,
+            // in the order Express needs: after-hooks → pre-hooks → routes.
+            hooks.on('app:booted', () => {
+                if (collector.afterHooks.length) {
+                    app.use((req, res, next) => {
+                        const start = Date.now();
+                        res.on('finish', () => {
+                            void collector.runAfter(toNeutralRequest(req), new ExpressReply(res), res.statusCode, Date.now() - start);
+                        });
+                        next();
+                    });
+                }
+                app.use(async (req, res, next) => {
+                    const reply = new ExpressReply(res);
+                    if (await collector.runPre(toNeutralRequest(req), reply))
+                        return;
+                    next();
+                });
+                registerRoutes(app, routes, container, enrichers, guards);
+                for (const { method, url, handler } of collector.extraRoutes) {
+                    router[method.toLowerCase()](url, async (req, res) => {
+                        const reply = new ExpressReply(res);
+                        const result = await handler({ request: toNeutralRequest(req), reply });
+                        if (!reply.sent)
+                            reply.send(result);
+                    });
+                }
+                // Mounted last, so anything unmatched gets the neutral JSON 404
+                // instead of Express's HTML default.
+                if (options.notFound !== false) {
+                    app.use((_req, res) => {
+                        if (!res.headersSent)
+                            res.status(404).json(NOT_FOUND_RESPONSE);
+                    });
+                }
+            });
+            for (const definition of routes) {
+                metadata.add('http:routes', {
+                    method: definition.method,
+                    url: definition.url,
+                    meta: definition.meta ?? {},
+                    body: definition.body,
+                    query: definition.query,
+                    params: definition.params,
+                    response: definition.response,
+                });
+            }
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/express",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Express adapter for Basalt: run the same typed routes, enrichers and guards on Express that you would on Fastify or Hono.",
   "license": "MIT",
   "type": "module",
@@ -14,20 +14,19 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/core": "^1.1.0",
-    "@basaltkit/http": "^1.7.0"
+    "@basaltkit/core": "^1.1.2",
+    "@basaltkit/http": "^1.10.0"
   },
   "peerDependencies": {
     "express": "^4.19.0 || ^5.0.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",
-    "@types/node": "^22.15.0",
+    "@types/node": "^26.3.0",
     "express": "^5.1.0",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "vitest": "^3.1.0",
-    "zod": "^3.24.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11",
+    "zod": "^3.24.0 || ^4.0.0",
     "@basaltkit/tsconfig": "^0.24.0"
   },
   "publishConfig": {
@@ -35,11 +34,11 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "url": "git+https://github.com/basaltkit/basalt.git",
     "directory": "packages/express"
   },
-  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/express#readme",
-  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "homepage": "https://github.com/basaltkit/basalt/tree/main/packages/express#readme",
+  "bugs": "https://github.com/basaltkit/basalt/issues",
   "keywords": [
     "basalt",
     "typescript",
@@ -48,7 +47,7 @@
     "adapter"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
+    "build": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }