@superfunctions/http-express 0.1.0

package/README.md

@@ -0,0 +1,195 @@
+# @superfunctions/http-express
+
+Express adapter for [@superfunctions/http](../http) - Use framework-agnostic routers with Express.
+
+## Installation
+
+```bash
+npm install @superfunctions/http @superfunctions/http-express express
+```
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import { createRouter } from '@superfunctions/http';
+import { toExpressRouter } from '@superfunctions/http-express';
+
+// Define your router (framework-agnostic)
+const apiRouter = createRouter({
+  routes: [
+    {
+      method: 'GET',
+      path: '/users/:id',
+      handler: async (req, ctx) => {
+        return Response.json({ id: ctx.params.id });
+      },
+    },
+  ],
+});
+
+// Use with Express
+const app = express();
+app.use(express.json()); // Important: Add body parser
+app.use('/api', toExpressRouter(apiRouter));
+app.listen(3000);
+```
+
+## API
+
+### `toExpressRouter(router)`
+
+Converts a `@superfunctions/http` router to an Express Router.
+
+**Parameters:**
+- `router`: Router instance from `@superfunctions/http`
+
+**Returns:** `express.Router`
+
+**Example:**
+```typescript
+import { toExpressRouter } from '@superfunctions/http-express';
+
+const expressRouter = toExpressRouter(myRouter);
+app.use('/api', expressRouter);
+```
+
+### `toExpressHandler(router)`
+
+Converts a `@superfunctions/http` router to an Express RequestHandler (single middleware function).
+
+**Parameters:**
+- `router`: Router instance from `@superfunctions/http`
+
+**Returns:** `express.RequestHandler`
+
+**Example:**
+```typescript
+import { toExpressHandler } from '@superfunctions/http-express';
+
+const handler = toExpressHandler(myRouter);
+app.use('/api', handler);
+```
+
+## Usage Examples
+
+### With Middleware
+
+```typescript
+import { createRouter } from '@superfunctions/http';
+import { toExpressRouter } from '@superfunctions/http-express';
+
+const router = createRouter({
+  middleware: [
+    async (req, ctx, next) => {
+      // Auth middleware
+      const token = req.headers.get('Authorization');
+      if (!token) {
+        return Response.json({ error: 'Unauthorized' }, { status: 401 });
+      }
+      return next();
+    },
+  ],
+  routes: [
+    {
+      method: 'GET',
+      path: '/protected',
+      handler: async () => Response.json({ data: 'secret' }),
+    },
+  ],
+});
+
+app.use('/api', toExpressRouter(router));
+```
+
+### With Custom Context
+
+```typescript
+interface AppContext {
+  db: Database;
+}
+
+const router = createRouter<AppContext>({
+  context: { db: myDatabase },
+  routes: [
+    {
+      method: 'GET',
+      path: '/users',
+      handler: async (req, ctx) => {
+        const users = await ctx.db.findMany({ model: 'users' });
+        return Response.json(users);
+      },
+    },
+  ],
+});
+
+app.use('/api', toExpressRouter(router));
+```
+
+### Multiple Routers
+
+```typescript
+const usersRouter = createRouter({ routes: [/* user routes */] });
+const postsRouter = createRouter({ routes: [/* post routes */] });
+
+app.use('/api/users', toExpressRouter(usersRouter));
+app.use('/api/posts', toExpressRouter(postsRouter));
+```
+
+## Important Notes
+
+### Body Parsing
+
+You must add Express body parsing middleware before using the adapter:
+
+```typescript
+app.use(express.json()); // For JSON bodies
+app.use(express.urlencoded({ extended: true })); // For form data
+```
+
+### Error Handling
+
+The adapter automatically handles errors from your route handlers. You can add Express error middleware for additional handling:
+
+```typescript
+app.use((err, req, res, next) => {
+  console.error('Express error:', err);
+  res.status(500).json({ error: 'Server error' });
+});
+```
+
+### Route Paths
+
+Routes are registered relative to the mount point:
+
+```typescript
+const router = createRouter({
+  routes: [
+    { method: 'GET', path: '/hello', handler: () => Response.json({ msg: 'hi' }) }
+  ]
+});
+
+// Route accessible at: /api/hello
+app.use('/api', toExpressRouter(router));
+```
+
+## TypeScript
+
+Full TypeScript support with proper types:
+
+```typescript
+import type { Router } from '@superfunctions/http';
+import type { Express, Router as ExpressRouter } from 'express';
+
+const myRouter: Router = createRouter({ routes: [...] });
+const expressRouter: ExpressRouter = toExpressRouter(myRouter);
+```
+
+## Compatibility
+
+- Express 4.x ✅
+- Express 5.x ✅
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Express adapter for @superfunctions/http
+ */
+import type { Router } from '@superfunctions/http';
+import express from 'express';
+/**
+ * Convert a @superfunctions/http Router to an Express Router
+ */
+export declare function toExpressRouter(router: Router): express.Router;
+/**
+ * Convert a @superfunctions/http Router to an Express RequestHandler
+ * This is useful for mounting at a specific path with a catch-all
+ */
+export declare function toExpressHandler(router: Router): express.RequestHandler;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CA2B9D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,CAexB"}

package/dist/adapter.js

@@ -0,0 +1,112 @@
+/**
+ * Express adapter for @superfunctions/http
+ */
+import express from 'express';
+/**
+ * Convert a @superfunctions/http Router to an Express Router
+ */
+export function toExpressRouter(router) {
+    const expressRouter = express.Router();
+    // Get all routes from the router
+    const routes = router.getRoutes();
+    // Register each route with Express
+    for (const route of routes) {
+        const method = route.method.toLowerCase();
+        expressRouter[method](route.path, async (req, res, next) => {
+            try {
+                // Convert Express Request to Web Standard Request
+                const webRequest = await convertToWebRequest(req);
+                // Handle with router
+                const webResponse = await router.handle(webRequest);
+                // Convert Web Response to Express Response
+                await convertToExpressResponse(webResponse, res);
+            }
+            catch (error) {
+                next(error);
+            }
+        });
+    }
+    return expressRouter;
+}
+/**
+ * Convert a @superfunctions/http Router to an Express RequestHandler
+ * This is useful for mounting at a specific path with a catch-all
+ */
+export function toExpressHandler(router) {
+    return async (req, res, next) => {
+        try {
+            // Convert Express Request to Web Standard Request
+            const webRequest = await convertToWebRequest(req);
+            // Handle with router
+            const webResponse = await router.handle(webRequest);
+            // Convert Web Response to Express Response
+            await convertToExpressResponse(webResponse, res);
+        }
+        catch (error) {
+            next(error);
+        }
+    };
+}
+/**
+ * Convert Express Request to Web Standard Request
+ */
+async function convertToWebRequest(req) {
+    // Build full URL
+    // Use req.url (not originalUrl) to get path relative to router mount point
+    const protocol = req.protocol;
+    const host = req.get('host') || 'localhost';
+    const url = `${protocol}://${host}${req.url}`;
+    // Convert headers
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(req.headers)) {
+        if (value) {
+            if (Array.isArray(value)) {
+                value.forEach((v) => headers.append(key, v));
+            }
+            else {
+                headers.set(key, value);
+            }
+        }
+    }
+    // Handle body
+    let body = null;
+    if (req.method !== 'GET' && req.method !== 'HEAD') {
+        // If body is already parsed (e.g., by express.json() middleware)
+        if (req.body && Object.keys(req.body).length > 0) {
+            body = JSON.stringify(req.body);
+            // Ensure Content-Type is set
+            if (!headers.has('Content-Type')) {
+                headers.set('Content-Type', 'application/json');
+            }
+        }
+    }
+    return new Request(url, {
+        method: req.method,
+        headers,
+        body,
+    });
+}
+/**
+ * Convert Web Standard Response to Express Response
+ */
+async function convertToExpressResponse(webResponse, expressResponse) {
+    // Set status
+    expressResponse.status(webResponse.status);
+    // Set status text if available
+    if (webResponse.statusText) {
+        expressResponse.statusMessage = webResponse.statusText;
+    }
+    // Set headers
+    webResponse.headers.forEach((value, key) => {
+        expressResponse.setHeader(key, value);
+    });
+    // Send body
+    if (webResponse.body) {
+        const text = await webResponse.text();
+        expressResponse.send(text);
+    }
+    else {
+        expressResponse.end();
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @superfunctions/http-express - Express adapter
+ */
+export { toExpressRouter, toExpressHandler } from './adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * @superfunctions/http-express - Express adapter
+ */
+export { toExpressRouter, toExpressHandler } from './adapter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@superfunctions/http-express",
+  "version": "0.1.0",
+  "description": "Express adapter for @superfunctions/http",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "lint": "echo 'lint not configured'",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@superfunctions/http": "^0.1.0",
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@superfunctions/http": "^0.1.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.0.0",
+    "@types/supertest": "^6.0.2",
+    "express": "^4.21.2",
+    "supertest": "^7.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "http",
+    "express",
+    "adapter",
+    "router",
+    "superfunctions"
+  ],
+  "author": "21n",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/21nCo/super-functions/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/super-functions.git",
+    "directory": "packages/http-express"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}