@nmvuong92/fluxe 0.8.0 → 0.9.1

package/README.md

@@ -47,6 +47,7 @@ npm run test:all           # typecheck + 144 unit + integration (selftest2) —
 app/        ← DEV sở hữu (sửa thoải mái) — Contract Plane
   cells/        trang/feature (route + loader + view + action/head/layout/guard)
   layouts/      layout dùng chung (nested)
+  server.ts     server entry — Express/Hono/Nest mount fluxe (mặc định Express)
   backend.ts    TẦNG DATA của bạn: interface domain + chọn driver (memory/sqlite/postgres)
   profiles.ts   profile resolve render mode (static/island) per môi trường
   contract.ts   schema → codegen types TS
@@ -64,6 +65,7 @@ inject qua `makeServer(…, { backend })`. Engine không bao giờ import ngư
 
 ## Tính năng (tất cả TDD + chạy thật)
 
+- **Server** — chạy zero-config (`makeServer`, node:http) HOẶC nhúng vào **Express/Hono/Nest** qua adapter (`@nmvuong92/fluxe/express|hono|nest`)
 - **Render** — static (0 JS) · island hydrate · SPA nav (Inertia) · static-prerender · API mode `?json=1`
 - **Routing** — động `[param]` → `ctx.input` · **nested layouts** · SEO (head/canonical/OG/JSON-LD per cell, `/sitemap.xml`, `/robots.txt`)
 - **Bảo mật (đầy đủ)** — input validation (Zod) · auth password **scrypt** · **RBAC** · **CSRF** double-submit · **rate-limit** token-bucket · error handling không-leak + structured

package/lib/adapters/express.d.ts

@@ -0,0 +1,3 @@
+import type { RequestHandler } from "express";
+import { createHandler } from "../server_factory.ts";
+export declare function fluxe(...args: Parameters<typeof createHandler>): RequestHandler;

package/lib/adapters/express.js

@@ -0,0 +1,7 @@
+import { createHandler } from "../server_factory.js";
+/* Mount fluxe như middleware (đặt SAU các route riêng của bạn — fluxe là catch-all):
+ *   app.use(fluxe(manifest, cells, layouts, { backend }));  */
+export function fluxe(...args) {
+    const handler = createHandler(...args);
+    return (req, res, next) => { handler(req, res).catch(next); };
+}

package/lib/adapters/hono.d.ts

@@ -0,0 +1,3 @@
+import type { MiddlewareHandler } from "hono";
+import { createHandler } from "../server_factory.ts";
+export declare function fluxe(...args: Parameters<typeof createHandler>): MiddlewareHandler;

package/lib/adapters/hono.js

@@ -0,0 +1,48 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Adapter Hono (chạy trên Node qua @hono/node-server). `hono` + `@hono/node-server` là peerDependency.
+ * Hono yêu cầu handler trả về Web `Response`; còn createHandler ghi vào node res. Ta dùng một
+ * "capture shim": chạy handler vào res đệm (buffer) rồi dựng Response chuẩn → Hono ghi sạch,
+ * không đụng nội bộ node-server. (Đánh đổi: buffer toàn response thay vì stream — chấp nhận được
+ * cho lớp adapter; muốn stream thì dùng makeServer/Express.) */
+import { Writable } from "node:stream";
+import { createHandler } from "../server_factory.js";
+class CaptureRes extends Writable {
+    statusCode = 200;
+    headersSent = false;
+    headers = {};
+    chunks = [];
+    writeHead(status, headers) {
+        this.statusCode = status;
+        if (headers)
+            for (const k of Object.keys(headers))
+                this.headers[k.toLowerCase()] = headers[k];
+        this.headersSent = true;
+        return this;
+    }
+    setHeader(k, v) { this.headers[k.toLowerCase()] = v; return this; }
+    getHeader(k) { return this.headers[k.toLowerCase()]; }
+    _write(chunk, _enc, cb) { this.chunks.push(Buffer.from(chunk)); cb(); }
+}
+/* Mount fluxe như catch-all (đặt SAU route Hono riêng của bạn):
+ *   app.use("*", fluxe(manifest, cells, layouts, { backend }));
+ *   serve({ fetch: app.fetch, port: 5180 });   // từ @hono/node-server  */
+export function fluxe(...args) {
+    const handler = createHandler(...args);
+    return async (c) => {
+        const { incoming } = c.env;
+        const res = new CaptureRes();
+        const finished = new Promise((resolve) => res.on("finish", resolve));
+        await handler(incoming, res);
+        await finished;
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(res.headers)) {
+            if (Array.isArray(v))
+                v.forEach((x) => headers.append(k, String(x)));
+            else
+                headers.set(k, String(v));
+        }
+        const body = Buffer.concat(res.chunks);
+        return new Response(body.length ? body : null, { status: res.statusCode, headers });
+    };
+}

package/lib/adapters/nest.d.ts

@@ -0,0 +1,3 @@
+import type { NestMiddleware } from "@nestjs/common";
+import { createHandler } from "../server_factory.ts";
+export declare function fluxeMiddleware(...args: Parameters<typeof createHandler>): NestMiddleware["use"];

package/lib/adapters/nest.js

@@ -0,0 +1,9 @@
+import { createHandler } from "../server_factory.js";
+/* Functional middleware — mount global (khuyên dùng, catch-all đặt sau route Nest):
+ *   const app = await NestFactory.create(AppModule);
+ *   app.use(fluxeMiddleware(manifest, cells, layouts, { backend }));
+ * (hoặc consumer.apply(...).forRoutes("{*splat}") trong module — Nest 11 dùng wildcard mới). */
+export function fluxeMiddleware(...args) {
+    const handler = createHandler(...args);
+    return (req, res, next) => { handler(req, res).catch(next); };
+}

package/lib/core/cli.js

@@ -47,7 +47,7 @@ export const COMMANDS = {
     },
     dev: {
         desc: "Sync + resolve + build client + chạy server",
-        shell: (a) => `${SYNC} && tsx scripts/resolve.ts ${p(a)} && ${ESBUILD} && tsx src/server.tsx`,
+        shell: (a) => `${SYNC} && tsx scripts/resolve.ts ${p(a)} && ${ESBUILD} && tsx app/server.ts`,
     },
     test: {
         desc: "Sync + typecheck + unit + integration",

package/lib/index.d.ts

@@ -18,4 +18,4 @@ export * from "./storage/types.ts";
 export { createMemoryStorage } from "./storage/memory.ts";
 export { createLocalStorage } from "./storage/local.ts";
 export { createS3Storage } from "./storage/s3.ts";
-export { makeServer } from "./server_factory.ts";
+export { makeServer, createHandler, type NodeHandler, type MakeServerOpts } from "./server_factory.ts";

package/lib/index.js

@@ -22,5 +22,5 @@ export * from "./storage/types.js"; // Storage, PutResult, GetResult, safeKey, m
 export { createMemoryStorage } from "./storage/memory.js";
 export { createLocalStorage } from "./storage/local.js";
 export { createS3Storage } from "./storage/s3.js"; // adapter tham chiếu (cần @aws-sdk/client-s3)
-export { makeServer } from "./server_factory.js";
+export { makeServer, createHandler } from "./server_factory.js";
 // Backend = USER-OWNED (app/backend.ts) — engine KHÔNG ship driver/domain data nào.

package/lib/server_factory.d.ts

@@ -11,10 +11,13 @@ type LayoutMap = Record<string, LayoutEntry>;
 import { type I18n } from "./core/i18n.ts";
 import { type Storage } from "./storage/types.ts";
 import { type FluxeConfig } from "./core/config.ts";
-export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: {
+export interface MakeServerOpts {
     i18n?: I18n;
     storage?: Storage;
     config?: FluxeConfig;
     backend?: unknown;
-}): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
+}
+export type NodeHandler = (req: http.IncomingMessage, res: http.ServerResponse) => Promise<unknown>;
+export declare function createHandler(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: MakeServerOpts): NodeHandler;
+export declare function makeServer(manifest: ResolutionManifest, cells: CellDef<any, any>[], layouts?: LayoutMap, opts?: MakeServerOpts): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 export {};

package/lib/server_factory.js

@@ -74,7 +74,9 @@ function renderBodyToString(node) {
         });
     });
 }
-export function makeServer(manifest, cells, layouts = {}, opts = {}) {
+/* createHandler — lõi request framework-agnostic: trả về handler Node (req,res).
+ * Dùng trực tiếp cho adapter Express/Hono/Nest; makeServer chỉ bọc bằng http.createServer. */
+export function createHandler(manifest, cells, layouts = {}, opts = {}) {
     const i18n = opts.i18n;
     const storage = opts.storage;
     const config = opts.config ?? loadConfig(); // default ← ENV (FLUXE_*) ← override
@@ -109,7 +111,7 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     const recorder = createRecorder(); // request log — chạy mỗi request → eager (luôn dùng)
     const renderCache = createRenderCache({ maxKeys: config.renderCache.maxKeys }); // FLUXE_RENDERCACHE_MAX_KEYS
     let clientJs; // ý A: đọc dist/client.js 1 lần (zero-copy: tái dùng buffer)
-    return http.createServer(async (req, res) => {
+    return async (req, res) => {
         const url = new URL(req.url, "http://localhost");
         const start = Date.now();
         res.on("finish", () => recorder.record({ method: req.method ?? "?", path: url.pathname, status: res.statusCode, ms: Date.now() - start, ts: start }));
@@ -351,5 +353,9 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
             // Action (rpc) luôn nhận lỗi dạng JSON.
             sendError(res, wantsJson || url.pathname.startsWith("/__action/"), err);
         }
-    });
+    };
+}
+/* makeServer — đường zero-config: bọc createHandler bằng http.createServer (giữ API cũ). */
+export function makeServer(manifest, cells, layouts = {}, opts = {}) {
+    return http.createServer(createHandler(manifest, cells, layouts, opts));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmvuong92/fluxe",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "fluxe — khung fullstack tối giản, một runtime TS (RCA: Resolved Cell Architecture).",
   "license": "Apache-2.0",
   "author": "nmvuong92",
@@ -30,9 +30,17 @@
       "types": "./lib/core/jobs.d.ts",
       "default": "./lib/core/jobs.js"
     },
-    "./sqlite": {
-      "types": "./lib/backends/sqlite.d.ts",
-      "default": "./lib/backends/sqlite.js"
+    "./express": {
+      "types": "./lib/adapters/express.d.ts",
+      "default": "./lib/adapters/express.js"
+    },
+    "./hono": {
+      "types": "./lib/adapters/hono.d.ts",
+      "default": "./lib/adapters/hono.js"
+    },
+    "./nest": {
+      "types": "./lib/adapters/nest.d.ts",
+      "default": "./lib/adapters/nest.js"
     }
   },
   "files": [
@@ -48,8 +56,8 @@
     "typecheck": "tsc --noEmit",
     "sync": "tsx scripts/sync.ts",
     "build:client": "npm run sync && esbuild src/client.tsx --bundle --format=esm --outfile=dist/client.js --jsx=automatic --loader:.tsx=tsx",
-    "dev": "npm run build:client && tsx src/server.tsx",
-    "dev:remote": "npm run build:client && FLUXE_BACKEND=remote tsx src/server.tsx",
+    "dev": "npm run build:client && tsx app/server.ts",
+    "dev:node": "npm run build:client && tsx src/server.tsx",
     "test": "tsx src/selftest2.ts",
     "test:unit": "node --experimental-sqlite --import tsx --test '{src,app}/**/*.test.ts'",
     "test:cells": "node --experimental-sqlite --import tsx --test 'app/cells/**/*.test.ts'",
@@ -67,16 +75,47 @@
   },
   "peerDependencies": {
     "react": "^18 || ^19",
-    "react-dom": "^18 || ^19"
+    "react-dom": "^18 || ^19",
+    "express": "^4 || ^5",
+    "hono": "^4",
+    "@hono/node-server": "^1 || ^2",
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/core": "^10 || ^11"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "hono": {
+      "optional": true
+    },
+    "@hono/node-server": {
+      "optional": true
+    },
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "typescript": "^5",
-    "tsx": "^4",
+    "@hono/node-server": "^2.0.6",
+    "@nestjs/common": "^11.1.27",
+    "@nestjs/core": "^11.1.27",
+    "@nestjs/platform-express": "^11.1.27",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20",
+    "@types/react": "^18",
+    "@types/react-dom": "^18",
     "esbuild": "^0.23",
+    "express": "^5.2.1",
+    "hono": "^4.12.27",
     "react": "^18",
     "react-dom": "^18",
-    "@types/node": "^20",
-    "@types/react": "^18",
-    "@types/react-dom": "^18"
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "tsx": "^4",
+    "typescript": "^5"
   }
 }