@nmvuong92/fluxe 0.3.0 → 0.5.0

package/lib/core/cli.js

@@ -17,6 +17,10 @@ export const COMMANDS = {
         desc: "Auto-discovery: quét app/cells/* → app/app.ts (dev/resolve tự gọi)",
         shell: () => SYNC,
     },
+    config: {
+        desc: "In config đã giải (default ← ENV FLUXE_* ← override)",
+        shell: () => `tsx scripts/config.ts`,
+    },
     gen: {
         desc: "Codegen contract → types TS/Go/Rust (.fluxe/gen)",
         shell: () => `tsx scripts/codegen.ts`,

package/lib/core/config.d.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+declare const Schema: z.ZodObject<{
+    env: z.ZodEnum<["development", "production", "test"]>;
+    secret: z.ZodString;
+    port: z.ZodNumber;
+    defaultBackend: z.ZodEnum<["memory", "go", "rust"]>;
+    rateLimit: z.ZodObject<{
+        capacity: z.ZodNumber;
+        refillPerSec: z.ZodNumber;
+        maxKeys: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        capacity: number;
+        refillPerSec: number;
+        maxKeys: number;
+    }, {
+        capacity: number;
+        refillPerSec: number;
+        maxKeys: number;
+    }>;
+    renderCache: z.ZodObject<{
+        maxKeys: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        maxKeys: number;
+    }, {
+        maxKeys: number;
+    }>;
+    upload: z.ZodObject<{
+        maxBytes: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        maxBytes: number;
+    }, {
+        maxBytes: number;
+    }>;
+    i18n: z.ZodObject<{
+        defaultLocale: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        defaultLocale: string;
+    }, {
+        defaultLocale: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    env: "development" | "production" | "test";
+    secret: string;
+    port: number;
+    defaultBackend: "memory" | "go" | "rust";
+    rateLimit: {
+        capacity: number;
+        refillPerSec: number;
+        maxKeys: number;
+    };
+    renderCache: {
+        maxKeys: number;
+    };
+    upload: {
+        maxBytes: number;
+    };
+    i18n: {
+        defaultLocale: string;
+    };
+}, {
+    env: "development" | "production" | "test";
+    secret: string;
+    port: number;
+    defaultBackend: "memory" | "go" | "rust";
+    rateLimit: {
+        capacity: number;
+        refillPerSec: number;
+        maxKeys: number;
+    };
+    renderCache: {
+        maxKeys: number;
+    };
+    upload: {
+        maxBytes: number;
+    };
+    i18n: {
+        defaultLocale: string;
+    };
+}>;
+export type FluxeConfig = z.infer<typeof Schema>;
+type Src = Record<string, string | undefined>;
+export declare const ENV_KEYS: {
+    readonly NODE_ENV: "env";
+    readonly FLUXE_SECRET: "secret";
+    readonly "PORT (ho\u1EB7c FLUXE_PORT)": "port";
+    readonly FLUXE_BACKEND: "defaultBackend";
+    readonly FLUXE_RATELIMIT_CAPACITY: "rateLimit.capacity";
+    readonly FLUXE_RATELIMIT_REFILL: "rateLimit.refillPerSec";
+    readonly FLUXE_RATELIMIT_MAX_KEYS: "rateLimit.maxKeys";
+    readonly FLUXE_RENDERCACHE_MAX_KEYS: "renderCache.maxKeys";
+    readonly FLUXE_UPLOAD_MAX_BYTES: "upload.maxBytes";
+    readonly FLUXE_LOCALE_DEFAULT: "i18n.defaultLocale";
+};
+type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? Partial<T[K]> : T[K];
+};
+export declare function loadConfig(source?: Src, overrides?: DeepPartial<FluxeConfig>): FluxeConfig;
+export {};

package/lib/core/config.js

@@ -0,0 +1,66 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Config core — DEFAULT + override qua ENV (quy ước FLUXE_*), kiểu Laravel config().
+ * Một nguồn sự thật cho mọi tham số tinh chỉnh của engine. Thứ tự ưu tiên:
+ *   default  <  ENV (FLUXE_*)  <  override truyền tay.
+ * Mọi giá trị quan trọng ĐỀU expose ra ENV + tài liệu (xem docs/reference/configuration). */
+import { z } from "zod";
+const Schema = z.object({
+    env: z.enum(["development", "production", "test"]),
+    secret: z.string().min(8),
+    port: z.coerce.number().int().positive(),
+    defaultBackend: z.enum(["memory", "go", "rust"]),
+    rateLimit: z.object({
+        capacity: z.coerce.number().int().positive(),
+        refillPerSec: z.coerce.number().positive(),
+        maxKeys: z.coerce.number().int().positive(),
+    }),
+    renderCache: z.object({ maxKeys: z.coerce.number().int().positive() }),
+    upload: z.object({ maxBytes: z.coerce.number().int().positive() }),
+    i18n: z.object({ defaultLocale: z.string().min(2) }),
+});
+/* Bảng ENV — TÊN biến ↔ field. Dùng cho loadConfig + sinh tài liệu. */
+export const ENV_KEYS = {
+    "NODE_ENV": "env",
+    "FLUXE_SECRET": "secret",
+    "PORT (hoặc FLUXE_PORT)": "port",
+    "FLUXE_BACKEND": "defaultBackend",
+    "FLUXE_RATELIMIT_CAPACITY": "rateLimit.capacity",
+    "FLUXE_RATELIMIT_REFILL": "rateLimit.refillPerSec",
+    "FLUXE_RATELIMIT_MAX_KEYS": "rateLimit.maxKeys",
+    "FLUXE_RENDERCACHE_MAX_KEYS": "renderCache.maxKeys",
+    "FLUXE_UPLOAD_MAX_BYTES": "upload.maxBytes",
+    "FLUXE_LOCALE_DEFAULT": "i18n.defaultLocale",
+};
+const num = (s, k, d) => {
+    const v = s[k];
+    return v == null || v === "" ? d : Number(v);
+};
+function merge(base, o) {
+    return {
+        ...base,
+        ...o,
+        rateLimit: { ...base.rateLimit, ...o.rateLimit },
+        renderCache: { ...base.renderCache, ...o.renderCache },
+        upload: { ...base.upload, ...o.upload },
+        i18n: { ...base.i18n, ...o.i18n },
+    };
+}
+/* Giải config: default ← ENV (FLUXE_*) ← override. Validate Zod (sai → ném ngay, fail-fast). */
+export function loadConfig(source = process.env, overrides = {}) {
+    const fromEnv = {
+        env: source.NODE_ENV || "development",
+        secret: source.FLUXE_SECRET || "dev-secret-change-me",
+        port: num(source, "PORT", num(source, "FLUXE_PORT", 5180)),
+        defaultBackend: source.FLUXE_BACKEND || "memory",
+        rateLimit: {
+            capacity: num(source, "FLUXE_RATELIMIT_CAPACITY", 30),
+            refillPerSec: num(source, "FLUXE_RATELIMIT_REFILL", 10),
+            maxKeys: num(source, "FLUXE_RATELIMIT_MAX_KEYS", 5000),
+        },
+        renderCache: { maxKeys: num(source, "FLUXE_RENDERCACHE_MAX_KEYS", 256) },
+        upload: { maxBytes: num(source, "FLUXE_UPLOAD_MAX_BYTES", 10 * 1024 * 1024) },
+        i18n: { defaultLocale: source.FLUXE_LOCALE_DEFAULT || "en" },
+    };
+    return Schema.parse(merge(fromEnv, overrides));
+}

package/lib/core/container.d.ts

@@ -0,0 +1,9 @@
+export type Factory<T> = (c: Container) => T;
+export interface Container {
+    register<T>(token: string, factory: Factory<T>): Container;
+    override<T>(token: string, factory: Factory<T>): Container;
+    has(token: string): boolean;
+    get<T>(token: string): T;
+    resolved(): string[];
+}
+export declare function createContainer(): Container;

package/lib/core/container.js

@@ -0,0 +1,46 @@
+// Copyright (c) 2026 nmvuong92
+// SPDX-License-Identifier: Apache-2.0
+/* Resolved Container — DI lười (lazy singleton). Register factory = O(1), KHÔNG instantiate;
+ * get() tạo lần đầu rồi memoize. Factory tự c.get(dep) → DI + thứ tự init tự nhiên (DFS) +
+ * phát hiện vòng (cycle). resolved() liệt kê token đã tạo → "chỉ module dùng mới bootstrap".
+ * DSA: Map provider + Map instance (O(1)); Set "đang giải" (cycle, O(depth)). */
+export function createContainer() {
+    const providers = new Map();
+    const instances = new Map();
+    const resolving = new Set(); // DFS đang giải → bắt cycle
+    const c = {
+        register(token, factory) {
+            if (providers.has(token))
+                throw new Error(`Container: token '${token}' đã đăng ký (dùng override để ghi đè)`);
+            providers.set(token, factory);
+            return c;
+        },
+        override(token, factory) {
+            providers.set(token, factory);
+            instances.delete(token); // buộc tạo lại lần get sau
+            return c;
+        },
+        has: (token) => providers.has(token),
+        get(token) {
+            if (instances.has(token))
+                return instances.get(token); // memoized singleton
+            const f = providers.get(token);
+            if (!f)
+                throw new Error(`Container: chưa đăng ký token '${token}'`);
+            if (resolving.has(token)) {
+                throw new Error(`Container: phụ thuộc vòng (cycle) tại '${token}' — chuỗi: ${[...resolving, token].join(" → ")}`);
+            }
+            resolving.add(token);
+            try {
+                const inst = f(c); // factory có thể c.get(dep) → DI lười, thứ tự tự nhiên
+                instances.set(token, inst);
+                return inst;
+            }
+            finally {
+                resolving.delete(token);
+            }
+        },
+        resolved: () => [...instances.keys()],
+    };
+    return c;
+}

package/lib/index.d.ts

@@ -5,6 +5,8 @@ export * from "./core/resolver.ts";
 export * from "./core/wiring.ts";
 export * from "./core/auth.ts";
 export * from "./core/env.ts";
+export * from "./core/config.ts";
+export * from "./core/container.ts";
 export * from "./core/i18n.ts";
 export * from "./core/seo.ts";
 export * from "./core/broker.ts";

package/lib/index.js

@@ -9,6 +9,8 @@ export * from "./core/resolver.js"; // resolve, ResolutionProfile/Manifest, Cell
 export * from "./core/wiring.js"; // backendFromManifest, backendsFromManifest
 export * from "./core/auth.js"; // session HMAC, scrypt password, CSRF, RBAC
 export * from "./core/env.js"; // loadEnv
+export * from "./core/config.js"; // FluxeConfig, loadConfig (default ← ENV FLUXE_* ← override)
+export * from "./core/container.js"; // createContainer — Resolved Container (DI lười, chỉ-used-bootstrap)
 export * from "./core/i18n.js"; // createI18n, resolveLocale, translate, makeT, t(key, vars)
 export * from "./core/seo.js"; // renderHead, renderSitemap, renderRobots, HeadMeta
 export * from "./core/broker.js"; // pub/sub

package/lib/server_factory.d.ts

@@ -10,9 +10,10 @@ type LayoutEntry = LayoutMeta & {
 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?: {
     i18n?: I18n;
     storage?: Storage;
-    maxUpload?: number;
+    config?: FluxeConfig;
 }): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
 export {};

package/lib/server_factory.js

@@ -14,6 +14,7 @@ import { FluxeError, toErrorPayload, renderErrorPage } from "./core/errors.js";
 import { signSession, verifySession, parseCookie, hasRole, hashPassword, verifyPassword, newCsrfToken } from "./core/auth.js";
 import { validateInput } from "./core/validate.js";
 import { createBroker } from "./core/broker.js";
+import { createContainer } from "./core/container.js";
 import { createRateLimiter } from "./core/ratelimit.js";
 import { createRecorder } from "./core/observe.js";
 import { createPresence } from "./core/presence.js";
@@ -23,6 +24,7 @@ import { parseChaos } from "./core/chaos.js";
 import { resolveLocale, makeT } from "./core/i18n.js";
 import { parseMultipart, boundaryFromContentType } from "./core/multipart.js";
 import { makeKey } from "./storage/types.js";
+import { loadConfig } from "./core/config.js";
 import { createMemoryBackend } from "./backends/memory.js";
 import { createHttpBackend } from "./backends/http.js";
 // Build backend theo ngôn ngữ (cho live swap trong devtools).
@@ -92,7 +94,8 @@ function renderBodyToString(node) {
 export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     const i18n = opts.i18n;
     const storage = opts.storage;
-    const MAX_UPLOAD = opts.maxUpload ?? 10 * 1024 * 1024; // 10MB mặc định
+    const config = opts.config ?? loadConfig(); // default ← ENV (FLUXE_*) ← override
+    const MAX_UPLOAD = config.upload.maxBytes;
     const readBodyBuffer = (req) => new Promise((resolve, reject) => {
         const chunks = [];
         let size = 0;
@@ -114,11 +117,14 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     // Backend GIẢI per-cell từ manifest (Resolution Plane) — cell/frontend giữ nguyên.
     const backends = backendsFromManifest(manifest);
     const backendFor = (id) => backends.byCell.get(id) ?? backends.default;
-    const broker = createBroker(); // realtime pub/sub (Trục 4g, bản 1-node)
-    const actionLimit = createRateLimiter({ capacity: 30, refillPerSec: 10 }); // per-IP cho action
-    const recorder = createRecorder(); // request log (observability)
-    const presence = createPresence(); // ai đang online per topic (Trục 4g)
-    const renderCache = createRenderCache({ maxKeys: 256 }); // memoize HTML cell static (key route, gate etag)
+    // Resolved Container: service realtime đăng ký LƯỜI — chỉ tạo khi thật sự dùng (SSE/action).
+    // App không realtime → broker/presence KHÔNG bao giờ bootstrap. resolved() ở /_fluxe/stats.
+    const container = createContainer();
+    container.register("broker", () => createBroker());
+    container.register("presence", () => createPresence());
+    const actionLimit = createRateLimiter(config.rateLimit); // per-IP cho action (FLUXE_RATELIMIT_*)
+    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) => {
         const url = new URL(req.url, "http://localhost");
@@ -158,7 +164,7 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
                 const m = process.memoryUsage();
                 const c = process.cpuUsage();
                 res.writeHead(200, { "content-type": "application/json" });
-                return res.end(JSON.stringify({ rss: m.rss, heapUsed: m.heapUsed, cpuUser: c.user, cpuSystem: c.system, uptimeMs: Math.round(process.uptime() * 1000) }));
+                return res.end(JSON.stringify({ rss: m.rss, heapUsed: m.heapUsed, cpuUser: c.user, cpuSystem: c.system, uptimeMs: Math.round(process.uptime() * 1000), bootstrapped: container.resolved() }));
             }
             if (url.pathname === "/_fluxe/requests") {
                 // Observability: log request gần đây (timing/status). Prod: gate sau auth.
@@ -244,6 +250,9 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
                 const id = url.searchParams.get("id");
                 res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
                 res.write(`event: ready\ndata: {"topic":"${topic}"}\n\n`);
+                // Lần đầu có client SSE → broker + presence mới bootstrap (lazy qua container).
+                const broker = container.get("broker");
+                const presence = container.get("presence");
                 const offBroker = broker.subscribe(topic, (data) => res.write(`data: ${JSON.stringify(data)}\n\n`));
                 let offPresence = () => { };
                 if (id) {
@@ -299,7 +308,7 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
                 if (schema)
                     input = validateInput(schema, input); // sai → FluxeError 400 (caught)
                 const out = await fn({ input, backend, session });
-                broker.publish(cellId, { action: name, out }); // realtime: báo client khác
+                container.get("broker").publish(cellId, { action: name, out }); // realtime: báo client khác (broker lazy)
                 res.writeHead(200, { "content-type": "application/json", "x-fluxe-resolution": resolution, "x-fluxe-server-ms": String(Date.now() - t0) });
                 return res.end(JSON.stringify(out));
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nmvuong92/fluxe",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "fluxe — khung fullstack tối giản polyglot (RCA: Resolved Cell Architecture).",
   "license": "Apache-2.0",
   "author": "nmvuong92",