@nmvuong92/fluxe 0.3.0 → 0.4.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/index.d.ts

@@ -5,6 +5,7 @@ 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/i18n.ts";
 export * from "./core/seo.ts";
 export * from "./core/broker.ts";

package/lib/index.js

@@ -9,6 +9,7 @@ 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/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

@@ -23,6 +23,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 +93,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;
@@ -115,10 +117,10 @@ export function makeServer(manifest, cells, layouts = {}, opts = {}) {
     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 actionLimit = createRateLimiter(config.rateLimit); // per-IP cho action (FLUXE_RATELIMIT_*)
     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)
+    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");

package/package.json

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