@objectstack/express 4.0.4 → 4.1.0

package/README.md

@@ -1,22 +1,81 @@
 # @objectstack/express
 
-The official Express adapter for ObjectStack.
+> Express adapter for ObjectStack — mounts the auto-generated REST API and route dispatcher onto an Express app.
 
-## Features
-- Standalone Express router integration
-- Full Auth/GraphQL/Metadata/Data/Storage routes
-- AuthPlugin service support with Web Request conversion
-- Middleware mode for attaching kernel to requests
+[![npm](https://img.shields.io/npm/v/@objectstack/express.svg)](https://www.npmjs.com/package/@objectstack/express)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-## Usage
+## Overview
+
+Wraps `HttpDispatcher` from `@objectstack/runtime` as an Express `Router` (or request middleware). All ObjectStack routes — CRUD, batch, metadata, discovery, auth, storage, GraphQL — are handled by a catch-all that delegates to the dispatcher, so new protocol routes work automatically without adapter updates.
+
+## Installation
+
+```bash
+pnpm add @objectstack/express express
+```
+
+## Quick Start
 
 ```typescript
 import express from 'express';
 import { createExpressRouter } from '@objectstack/express';
+import { kernel } from './my-kernel';
 
 const app = express();
 app.use(express.json());
 app.use('/api', createExpressRouter({ kernel }));
-
 app.listen(3000);
 ```
+
+### Middleware mode
+
+```typescript
+import { objectStackMiddleware } from '@objectstack/express';
+
+app.use(objectStackMiddleware(kernel));
+```
+
+## Key Exports
+
+| Export | Kind | Description |
+|:---|:---|:---|
+| `createExpressRouter(options)` | function | Returns a mounted `Router` with all ObjectStack dispatchers. |
+| `objectStackMiddleware(kernel)` | function | Per-request middleware (use for custom routing/prefix). |
+| `ExpressAdapterOptions` | interface | `{ kernel: ObjectKernel, prefix?: string }`. |
+
+## Configuration
+
+| Option | Type | Default | Notes |
+|:---|:---|:---|:---|
+| `kernel` | `ObjectKernel` | — | Bootstrapped kernel from `@objectstack/core`. |
+| `prefix` | `string` | `'/api'` | Base path for the mounted router. |
+
+## Middleware order
+
+`express.json()` (or an equivalent body parser) MUST be registered **before** the ObjectStack router. Auth cookies require `cookie-parser` if you use cookie sessions. The adapter sets response headers directly; do not wrap with compression middleware that rewrites JSON bodies before the router.
+
+## When to use
+
+- ✅ Adding ObjectStack to an existing Express app.
+- ✅ Node.js deployments without edge runtime constraints.
+
+## When not to use
+
+- ❌ Edge / Workers — use [`@objectstack/hono`](../hono) instead.
+- ❌ Next.js App Router — use [`@objectstack/nextjs`](../nextjs).
+
+## Related Packages
+
+- [`@objectstack/runtime`](../../runtime) — provides `HttpDispatcher`.
+- [`@objectstack/rest`](../../rest) — route registration used by the dispatcher.
+- [`@objectstack/core`](../../core) — kernel.
+
+## Links
+
+- 📖 Docs: <https://objectstack.ai/docs>
+- 📚 API Reference: <https://objectstack.ai/docs/references>
+
+## License
+
+Apache-2.0 © ObjectStack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/express",
-  "version": "4.0.4",
+  "version": "4.1.0",
   "license": "Apache-2.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,14 +13,40 @@
   },
   "peerDependencies": {
     "express": "^5.1.0",
-    "@objectstack/runtime": "^4.0.4"
+    "@objectstack/runtime": "^4.1.0"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",
     "express": "^5.2.1",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4",
-    "@objectstack/runtime": "4.0.4"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7",
+    "@objectstack/runtime": "4.1.0"
+  },
+  "description": "Express adapter for ObjectStack — mounts the generated REST API onto an Express app.",
+  "keywords": [
+    "objectstack",
+    "express",
+    "adapter",
+    "rest",
+    "node"
+  ],
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/adapters/express"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
   },
   "scripts": {
     "build": "tsup --config ../../../tsup.config.ts",

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @objectstack/express@4.0.4 build /home/runner/work/framework/framework/packages/adapters/express
-> tsup --config ../../../tsup.config.ts
-
-CLI Building entry: src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/framework/framework/tsup.config.ts
-CLI Target: es2020
-CLI Cleaning output folder
-ESM Build start
-CJS Build start
-CJS dist/index.js     5.80 KB
-CJS dist/index.js.map 10.64 KB
-CJS ⚡️ Build success in 59ms
-ESM dist/index.mjs     4.72 KB
-ESM dist/index.mjs.map 10.59 KB
-ESM ⚡️ Build success in 60ms
-DTS Build start
-DTS ⚡️ Build success in 13153ms
-DTS dist/index.d.mts 1.18 KB
-DTS dist/index.d.ts  1.18 KB

package/CHANGELOG.md

@@ -1,194 +0,0 @@
-# @objectstack/express
-
-## 4.0.4
-
-### Patch Changes
-
-- @objectstack/runtime@4.0.4
-
-## 4.0.3
-
-### Patch Changes
-
-- @objectstack/runtime@4.0.3
-
-## 4.0.2
-
-### Patch Changes
-
-- @objectstack/runtime@4.0.2
-
-## 4.0.0
-
-### Patch Changes
-
-- f08ffc3: Fix discovery API endpoint routing and protocol consistency.
-
-  **Discovery route standardization:**
-
-  - All adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit) now mount the discovery endpoint at `{prefix}/discovery` instead of `{prefix}` root.
-  - `.well-known/objectstack` redirects now point to `{prefix}/discovery`.
-  - Client `connect()` fallback URL changed from `/api/v1` to `/api/v1/discovery`.
-  - Runtime dispatcher handles both `/discovery` (standard) and `/` (legacy) for backward compatibility.
-
-  **Schema & route alignment:**
-
-  - Added `storage` (service: `file-storage`) and `feed` (service: `data`) routes to `DEFAULT_DISPATCHER_ROUTES`.
-  - Added `feed` and `discovery` fields to `ApiRoutesSchema`.
-  - Unified `GetDiscoveryResponseSchema` with `DiscoverySchema` as single source of truth.
-  - Client `getRoute('feed')` fallback updated from `/api/v1/data` to `/api/v1/feed`.
-
-  **Type safety:**
-
-  - Extracted `ApiRouteType` from `ApiRoutes` keys for type-safe client route resolution.
-  - Removed `as any` type casting in client route access.
-
-- Updated dependencies [f08ffc3]
-- Updated dependencies [e0b0a78]
-  - @objectstack/runtime@4.0.0
-
-## 3.3.1
-
-### Patch Changes
-
-- @objectstack/runtime@3.3.1
-
-## 3.3.0
-
-### Patch Changes
-
-- @objectstack/runtime@3.3.0
-
-## 3.2.9
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.9
-
-## 3.2.8
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.8
-
-## 3.2.8
-
-### Patch Changes
-
-- fix: unified catch-all dispatch pattern — `createExpressRouter()` now delegates all non-framework-specific routes to `HttpDispatcher.dispatch()`, automatically supporting packages, analytics, automation, i18n, ui, openapi, custom endpoints, and any future routes
-- Only auth (service check), storage (file upload), GraphQL (raw result), and discovery (response wrapper) remain as explicit routes
-
-## 3.2.7
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.7
-
-## 3.2.6
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.6
-
-## 3.2.5
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.5
-
-## 3.2.4
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.4
-
-## 3.2.3
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.3
-
-## 3.2.2
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.2
-
-## 3.2.1
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.1
-
-## 3.2.0
-
-### Patch Changes
-
-- @objectstack/runtime@3.2.0
-
-## 3.1.1
-
-### Patch Changes
-
-- @objectstack/runtime@3.1.1
-
-## 3.1.0
-
-### Patch Changes
-
-- @objectstack/runtime@3.1.0
-
-## 3.0.11
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.11
-
-## 3.0.10
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.10
-
-## 3.0.9
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.9
-
-## 3.0.8
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.8
-
-## 3.0.7
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.7
-
-## 3.0.6
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.6
-
-## 3.0.5
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.5
-
-## 3.0.4
-
-### Patch Changes
-
-- @objectstack/runtime@3.0.4
-
-## 3.0.3
-
-### Patch Changes
-
-- Updated dependencies [c7267f6]
-  - @objectstack/runtime@3.0.3

package/src/__mocks__/runtime.ts

@@ -1,4 +0,0 @@
-// Stub for @objectstack/runtime - replaced by vi.mock in tests
-export const HttpDispatcher = class {};
-export type ObjectKernel = any;
-export type HttpDispatcherResult = any;

package/src/express.test.ts

@@ -1,84 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-
-// Mock dispatcher instance
-const mockDispatcher = {
-  getDiscoveryInfo: vi.fn().mockReturnValue({ version: '1.0', endpoints: [] }),
-  handleAuth: vi.fn().mockResolvedValue({ handled: true, response: { body: { ok: true }, status: 200 } }),
-  handleGraphQL: vi.fn().mockResolvedValue({ data: {} }),
-  handleStorage: vi.fn().mockResolvedValue({ handled: true, response: { body: {}, status: 200 } }),
-  dispatch: vi.fn().mockResolvedValue({ handled: true, response: { body: { success: true }, status: 200 } }),
-};
-
-vi.mock('@objectstack/runtime', () => {
-  return {
-    HttpDispatcher: function HttpDispatcher() {
-      return mockDispatcher;
-    },
-  };
-});
-
-import { createExpressRouter, objectStackMiddleware } from './index';
-
-const mockKernel = { name: 'test-kernel' } as any;
-
-function createMockRes() {
-  const res: any = {
-    _status: 200,
-    _body: null,
-    _headers: {} as Record<string, string>,
-    _redirectUrl: null as string | null,
-    status(code: number) { res._status = code; return res; },
-    json(body: any) { res._body = body; return res; },
-    send(body: any) { res._body = body; return res; },
-    set(k: string, v: string) { res._headers[k] = v; return res; },
-    redirect(url: string) { res._redirectUrl = url; return res; },
-  };
-  return res;
-}
-
-function createMockReq(overrides: any = {}) {
-  return {
-    method: 'GET',
-    path: '/',
-    url: '/',
-    originalUrl: '/',
-    body: {},
-    query: {},
-    headers: {},
-    params: {},
-    protocol: 'http',
-    get: (key: string) => key === 'host' ? 'localhost' : undefined,
-    ...overrides,
-  };
-}
-
-describe('createExpressRouter', () => {
-  let router: any;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    router = createExpressRouter({ kernel: mockKernel });
-  });
-
-  it('returns a router with registered routes', () => {
-    expect(router).toBeDefined();
-    expect(router.stack).toBeDefined();
-    expect(router.stack.length).toBeGreaterThan(0);
-  });
-});
-
-describe('objectStackMiddleware', () => {
-  it('attaches kernel to request', () => {
-    const middleware = objectStackMiddleware(mockKernel);
-    const req: any = {};
-    const res = createMockRes();
-    const next = vi.fn();
-
-    middleware(req, res, next);
-
-    expect(req.objectStack).toBe(mockKernel);
-    expect(next).toHaveBeenCalled();
-  });
-});

package/src/index.ts

@@ -1,188 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { type Router, type Request, type Response, type NextFunction, Router as createRouter } from 'express';
-import { type ObjectKernel, HttpDispatcher, HttpDispatcherResult } from '@objectstack/runtime';
-
-export interface ExpressAdapterOptions {
-  kernel: ObjectKernel;
-  prefix?: string;
-}
-
-/**
- * Auth service interface with handleRequest method
- */
-interface AuthService {
-  handleRequest(request: globalThis.Request): Promise<globalThis.Response>;
-}
-
-/**
- * Creates an Express Router with all ObjectStack route dispatchers.
- *
- * Only routes that need framework-specific handling (auth service, storage
- * file upload, GraphQL raw result, discovery wrapper) are registered explicitly.
- * All other routes are handled by a catch-all that delegates to
- * `HttpDispatcher.dispatch()`, making the adapter automatically support
- * new routes added to the dispatcher.
- *
- * @example
- * ```ts
- * import express from 'express';
- * import { createExpressRouter } from '@objectstack/express';
- *
- * const app = express();
- * app.use('/api', createExpressRouter({ kernel }));
- * app.listen(3000);
- * ```
- */
-export function createExpressRouter(options: ExpressAdapterOptions): Router {
-  const router = createRouter();
-  const dispatcher = new HttpDispatcher(options.kernel);
-  const prefix = options.prefix || '/api';
-
-  const sendResult = (result: HttpDispatcherResult, res: Response) => {
-    if (result.handled) {
-      if (result.response) {
-        if (result.response.headers) {
-          Object.entries(result.response.headers).forEach(([k, v]) => res.set(k, v as string));
-        }
-        return res.status(result.response.status).json(result.response.body);
-      }
-      if (result.result) {
-        const response = result.result;
-        if (response.type === 'redirect' && response.url) {
-          return res.redirect(response.url);
-        }
-        if (response.type === 'stream' && response.stream) {
-          if (response.headers) {
-            Object.entries(response.headers).forEach(([k, v]) => res.set(k, v as string));
-          }
-          response.stream.pipe(res);
-          return;
-        }
-        return res.status(200).json(response);
-      }
-    }
-    return res.status(404).json({ success: false, error: { message: 'Not Found', code: 404 } });
-  };
-
-  const errorResponse = (err: any, res: Response) => {
-    return res.status(err.statusCode || 500).json({
-      success: false,
-      error: {
-        message: err.message || 'Internal Server Error',
-        code: err.statusCode || 500,
-      },
-    });
-  };
-
-  // ─── Explicit routes (framework-specific handling required) ────────────────
-
-  // --- Discovery ---
-  router.get('/discovery', async (_req: Request, res: Response) => {
-    res.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
-  });
-
-  // --- Auth (needs auth service integration) ---
-  router.all('/auth/{*path}', async (req: Request, res: Response) => {
-    try {
-      const path = (req.params as any).path;
-      const method = req.method;
-
-      // Try AuthPlugin service first (prefer async to support factory-based services)
-      let authService: AuthService | null = null;
-      try {
-        if (typeof options.kernel.getServiceAsync === 'function') {
-          authService = await options.kernel.getServiceAsync<AuthService>('auth');
-        } else if (typeof options.kernel.getService === 'function') {
-          authService = options.kernel.getService<AuthService>('auth');
-        }
-      } catch {
-        // Service not registered — fall through to dispatcher
-        authService = null;
-      }
-
-      if (authService && typeof authService.handleRequest === 'function') {
-        const protocol = req.protocol || 'http';
-        const host = req.get?.('host') || req.headers?.host || 'localhost';
-        const url = `${protocol}://${host}${req.originalUrl || req.url}`;
-        const headers = new Headers();
-        if (req.headers) {
-          Object.entries(req.headers).forEach(([k, v]) => {
-            if (typeof v === 'string') headers.set(k, v);
-            else if (Array.isArray(v)) headers.set(k, v.join(', '));
-          });
-        }
-        const init: RequestInit = { method, headers };
-        if (method !== 'GET' && method !== 'HEAD' && req.body) {
-          init.body = JSON.stringify(req.body);
-          if (!headers.has('content-type')) {
-            headers.set('content-type', 'application/json');
-          }
-        }
-        const webRequest = new Request(url, init);
-        const response = await authService.handleRequest(webRequest);
-        res.status(response.status);
-        response.headers.forEach((v: string, k: string) => res.set(k, v));
-        const text = await response.text();
-        return res.send(text);
-      }
-
-      // Fallback to dispatcher
-      const body = method === 'GET' || method === 'HEAD' ? {} : req.body || {};
-      const result = await dispatcher.handleAuth(path, method, body, { request: req, response: res });
-      return sendResult(result, res);
-    } catch (err: any) {
-      return errorResponse(err, res);
-    }
-  });
-
-  // --- GraphQL (returns raw result, not HttpDispatcherResult) ---
-  router.post('/graphql', async (req: Request, res: Response) => {
-    try {
-      const result = await dispatcher.handleGraphQL(req.body, { request: req });
-      return res.json(result);
-    } catch (err: any) {
-      return errorResponse(err, res);
-    }
-  });
-
-  // --- Storage (needs file upload handling) ---
-  router.all('/storage/{*path}', async (req: Request, res: Response) => {
-    try {
-      const subPath = '/' + (req.params as any).path;
-      const method = req.method;
-      const file = (req as any).file || (req as any).files?.file;
-      const result = await dispatcher.handleStorage(subPath, method, file, { request: req });
-      return sendResult(result, res);
-    } catch (err: any) {
-      return errorResponse(err, res);
-    }
-  });
-
-  // ─── Catch-all: delegate to dispatcher.dispatch() ─────────────────────────
-  // Handles meta, data, packages, analytics, automation, i18n, ui, openapi,
-  // custom API endpoints, and any future routes added to HttpDispatcher.
-  router.all('/{*path}', async (req: Request, res: Response) => {
-    try {
-      const subPath = '/' + (req.params as any).path;
-      const method = req.method;
-      const body = (method === 'POST' || method === 'PUT' || method === 'PATCH') ? req.body : undefined;
-      const result = await dispatcher.dispatch(method, subPath, body, req.query, { request: req, response: res }, prefix);
-      return sendResult(result, res);
-    } catch (err: any) {
-      return errorResponse(err, res);
-    }
-  });
-
-  return router;
-}
-
-/**
- * Middleware that attaches the ObjectStack kernel to the request.
- */
-export function objectStackMiddleware(kernel: ObjectKernel) {
-  return (req: Request, _res: Response, next: NextFunction) => {
-    (req as any).objectStack = kernel;
-    next();
-  };
-}

package/tsconfig.json

@@ -1,26 +0,0 @@
-{
-  "extends": "../../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "lib": [
-      "ES2020",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "src/**/*"
-  ],
-  "exclude": [
-    "node_modules",
-    "dist"
-  ]
-}

package/vitest.config.ts

@@ -1,16 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { defineConfig } from 'vitest/config';
-import path from 'node:path';
-
-export default defineConfig({
-  test: {
-    globals: true,
-    environment: 'node',
-  },
-  resolve: {
-    alias: {
-      '@objectstack/runtime': path.resolve(__dirname, 'src/__mocks__/runtime.ts'),
-    },
-  },
-});