npm - @nmvuong92/fluxe - Versions diffs - 0.1.0 - Mend

@nmvuong92/fluxe 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (90) hide show

package/README.md +88 -0
package/lib/backends/http.d.ts +2 -0
package/lib/backends/http.js +32 -0
package/lib/backends/memory.d.ts +2 -0
package/lib/backends/memory.js +21 -0
package/lib/backends/postgres.d.ts +7 -0
package/lib/backends/postgres.js +28 -0
package/lib/backends/sqlite.d.ts +2 -0
package/lib/backends/sqlite.js +27 -0
package/lib/backends/types.d.ts +11 -0
package/lib/backends/types.js +7 -0
package/lib/core/auth.d.ts +12 -0
package/lib/core/auth.js +54 -0
package/lib/core/broker.d.ts +7 -0
package/lib/core/broker.js +27 -0
package/lib/core/chaos.d.ts +5 -0
package/lib/core/chaos.js +11 -0
package/lib/core/cli.d.ts +6 -0
package/lib/core/cli.js +54 -0
package/lib/core/client.d.ts +33 -0
package/lib/core/client.js +108 -0
package/lib/core/codegen.d.ts +7 -0
package/lib/core/codegen.js +28 -0
package/lib/core/engine.d.ts +28 -0
package/lib/core/engine.js +1 -0
package/lib/core/env.d.ts +2 -0
package/lib/core/env.js +10 -0
package/lib/core/errors.d.ts +19 -0
package/lib/core/errors.js +39 -0
package/lib/core/etag.d.ts +2 -0
package/lib/core/etag.js +11 -0
package/lib/core/jobs.d.ts +27 -0
package/lib/core/jobs.js +54 -0
package/lib/core/layouts.d.ts +5 -0
package/lib/core/layouts.js +17 -0
package/lib/core/nav.d.ts +29 -0
package/lib/core/nav.js +53 -0
package/lib/core/observe.d.ts +12 -0
package/lib/core/observe.js +24 -0
package/lib/core/panel.d.ts +3 -0
package/lib/core/panel.js +46 -0
package/lib/core/presence.d.ts +6 -0
package/lib/core/presence.js +33 -0
package/lib/core/ratelimit.d.ts +13 -0
package/lib/core/ratelimit.js +32 -0
package/lib/core/rendercache.d.ts +15 -0
package/lib/core/rendercache.js +39 -0
package/lib/core/resolver.d.ts +37 -0
package/lib/core/resolver.js +42 -0
package/lib/core/router.d.ts +6 -0
package/lib/core/router.js +41 -0
package/lib/core/seo.d.ts +10 -0
package/lib/core/seo.js +27 -0
package/lib/core/testing.d.ts +9 -0
package/lib/core/testing.js +38 -0
package/lib/core/validate.d.ts +4 -0
package/lib/core/validate.js +17 -0
package/lib/core/wiring.d.ts +8 -0
package/lib/core/wiring.js +33 -0
package/lib/hot/search.d.ts +9 -0
package/lib/hot/search.js +16 -0
package/lib/index.d.ts +20 -0
package/lib/index.js +22 -0
package/lib/react/DebugBar.d.ts +3 -0
package/lib/react/DebugBar.js +57 -0
package/lib/react/Link.d.ts +12 -0
package/lib/react/Link.js +11 -0
package/lib/react/Nav.d.ts +8 -0
package/lib/react/Nav.js +7 -0
package/lib/react/ThemeToggle.d.ts +1 -0
package/lib/react/ThemeToggle.js +6 -0
package/lib/react/index.d.ts +10 -0
package/lib/react/index.js +11 -0
package/lib/react/mutation.d.ts +5 -0
package/lib/react/mutation.js +30 -0
package/lib/react/nav-client.d.ts +10 -0
package/lib/react/nav-client.js +76 -0
package/lib/react/query.d.ts +9 -0
package/lib/react/query.js +62 -0
package/lib/react/repro.d.ts +4 -0
package/lib/react/repro.js +19 -0
package/lib/react/shell.d.ts +1 -0
package/lib/react/shell.js +13 -0
package/lib/react/store.d.ts +28 -0
package/lib/react/store.js +31 -0
package/lib/react/theme.d.ts +6 -0
package/lib/react/theme.js +29 -0
package/lib/server_factory.d.ts +12 -0
package/lib/server_factory.js +293 -0
package/package.json +33 -0

package/lib/core/errors.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+export declare class FluxeError extends Error {
+    code: string;
+    status: number;
+    details?: unknown;
+    constructor(code: string, message: string, status?: number, details?: unknown);
+}
+export interface ErrorPayload {
+    status: number;
+    code: string;
+    message: string;
+    errorId?: string;
+    detail?: string;
+    details?: unknown;
+}
+export declare function toErrorPayload(err: unknown, opts: {
+    dev: boolean;
+    errorId: string;
+}): ErrorPayload;
+export declare function renderErrorPage(p: ErrorPayload): string;

package/lib/core/errors.js ADDED Viewed

@@ -0,0 +1,39 @@
+/* Error handling (tenet T5 / Trục 4q):
+ * - FluxeError = domain error (giá trị có kiểu) → map status/code/message an toàn.
+ * - Lỗi khác = unexpected → 500 generic + errorId; detail chỉ ở dev (không leak prod). */
+export class FluxeError extends Error {
+    code;
+    status;
+    details; // vd: danh sách lỗi field (validation)
+    constructor(code, message, status = 400, details) {
+        super(message);
+        this.name = "FluxeError";
+        this.code = code;
+        this.status = status;
+        this.details = details;
+    }
+}
+export function toErrorPayload(err, opts) {
+    if (err instanceof FluxeError) {
+        const p = { status: err.status, code: err.code, message: err.message };
+        if (err.details !== undefined)
+            p.details = err.details;
+        return p;
+    }
+    const e = err;
+    const p = { status: 500, code: "internal", message: "Internal Server Error", errorId: opts.errorId };
+    if (opts.dev)
+        p.detail = e?.stack ?? String(err);
+    return p;
+}
+function esc(s) {
+    return String(s)
+        .replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+export function renderErrorPage(p) {
+    const id = p.errorId ? `<p style="color:#888">error id: ${esc(p.errorId)}</p>` : "";
+    const detail = p.detail ? `<pre style="background:#1a1a2e;color:#e8e8f0;padding:1rem;overflow:auto;border-radius:6px">${esc(p.detail)}</pre>` : "";
+    return `<!doctype html><html lang="vi"><head><meta charset="utf-8"><title>${p.status} ${esc(p.code)}</title></head>` +
+        `<body style="font:14px/1.5 ui-sans-serif,system-ui;margin:3rem;max-width:720px">` +
+        `<h1>${p.status} — ${esc(p.code)}</h1><p>${esc(p.message)}</p>${id}${detail}</body></html>`;
+}

package/lib/core/etag.d.ts ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ export declare function etagOf(body: string): string;
2	+ export declare function etagMatches(ifNoneMatch: string \| undefined, etag: string): boolean;

package/lib/core/etag.js ADDED Viewed

@@ -0,0 +1,11 @@
+import { createHash } from "node:crypto";
+/* Render cache — ETag/304: hash body, client gửi If-None-Match → 304 nếu không đổi
+ * (không gửi lại body). Dùng cho JSON props (SPA nav refetch nhiều). */
+export function etagOf(body) {
+    return `"${createHash("sha1").update(body).digest("base64url").slice(0, 27)}"`;
+}
+export function etagMatches(ifNoneMatch, etag) {
+    if (!ifNoneMatch)
+        return false;
+    return ifNoneMatch.split(",").map((s) => s.trim()).includes(etag);
+}

package/lib/core/jobs.d.ts ADDED Viewed

@@ -0,0 +1,27 @@
+export interface Job {
+    id: number;
+    type: string;
+    payload: any;
+    status: "pending" | "done" | "dead";
+    attempts: number;
+}
+export type JobHandler = (payload: any) => Promise<void>;
+export interface Queue {
+    enqueue(type: string, payload: unknown): Job;
+    pending(): number;
+    dead(): number;
+    processNext(handlers: Record<string, JobHandler>, opts?: {
+        maxAttempts?: number;
+    }): Promise<Job | null>;
+}
+export declare function drain(queue: Queue, handlers: Record<string, JobHandler>, opts?: {
+    maxAttempts?: number;
+}): Promise<number>;
+export declare function createQueue(path?: string): {
+    enqueue(type: string, payload: unknown): Job;
+    pending: () => number;
+    dead: () => number;
+    processNext(handlers: Record<string, JobHandler>, opts?: {
+        maxAttempts?: number;
+    }): Promise<Job | null>;
+};

package/lib/core/jobs.js ADDED Viewed

@@ -0,0 +1,54 @@
+import { DatabaseSync } from "node:sqlite";
+/* Worker: xử lý cạn job pending (retry → dead-letter bao bọc nên luôn kết thúc). */
+export async function drain(queue, handlers, opts) {
+    let n = 0;
+    while (await queue.processNext(handlers, opts))
+        n++;
+    return n;
+}
+export function createQueue(path = ":memory:") {
+    const db = new DatabaseSync(path);
+    db.exec(`CREATE TABLE IF NOT EXISTS jobs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    type TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'pending',
+    attempts INTEGER NOT NULL DEFAULT 0,
+    last_error TEXT
+  )`);
+    const toJob = (r) => ({
+        id: r.id, type: r.type, payload: JSON.parse(r.payload), status: r.status, attempts: r.attempts,
+    });
+    const countByStatus = (s) => db.prepare("SELECT COUNT(*) c FROM jobs WHERE status = ?").get(s).c;
+    return {
+        enqueue(type, payload) {
+            const info = db.prepare("INSERT INTO jobs (type, payload) VALUES (?, ?)").run(type, JSON.stringify(payload));
+            return toJob(db.prepare("SELECT * FROM jobs WHERE id = ?").get(info.lastInsertRowid));
+        },
+        pending: () => countByStatus("pending"),
+        dead: () => countByStatus("dead"),
+        // Claim 1 job pending (id nhỏ nhất), chạy handler; lỗi → attempts++ , dead nếu cạn retry.
+        async processNext(handlers, opts = {}) {
+            const max = opts.maxAttempts ?? 3;
+            const row = db.prepare("SELECT * FROM jobs WHERE status = 'pending' ORDER BY id LIMIT 1").get();
+            if (!row)
+                return null;
+            const job = toJob(row);
+            try {
+                const handler = handlers[job.type];
+                if (!handler)
+                    throw new Error(`không có handler cho type '${job.type}'`);
+                await handler(job.payload);
+                db.prepare("UPDATE jobs SET status = 'done' WHERE id = ?").run(job.id);
+                return { ...job, status: "done" };
+            }
+            catch (e) {
+                const attempts = job.attempts + 1;
+                const dead = attempts >= max;
+                db.prepare("UPDATE jobs SET attempts = ?, status = ?, last_error = ? WHERE id = ?")
+                    .run(attempts, dead ? "dead" : "pending", String(e?.message ?? e), job.id);
+                return { ...job, attempts, status: dead ? "dead" : "pending" };
+            }
+        },
+    };
+}

package/lib/core/layouts.d.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export interface LayoutMeta {
+    id: string;
+    parent?: string;
+}
+export declare function layoutChain(layoutId: string | undefined, layouts: Record<string, LayoutMeta>): string[];

package/lib/core/layouts.js ADDED Viewed

@@ -0,0 +1,17 @@
+/* Nested layouts — phần thuần: giải chuỗi layout từ cell lên root.
+ * Trả về thứ tự INNER→OUTER để render bọc dần (outermost cuối cùng bọc ngoài). */
+export function layoutChain(layoutId, layouts) {
+    const chain = [];
+    const seen = new Set();
+    let cur = layoutId;
+    while (cur) {
+        if (seen.has(cur))
+            throw new Error(`layout vòng lặp: ${cur}`);
+        if (!layouts[cur])
+            throw new Error(`layout không tồn tại: ${cur}`);
+        seen.add(cur);
+        chain.push(cur); // inner trước
+        cur = layouts[cur].parent;
+    }
+    return chain; // [inner, …, outer]
+}

package/lib/core/nav.d.ts ADDED Viewed

@@ -0,0 +1,29 @@
+export interface PageProps {
+    cell: string;
+    data: unknown;
+    layout?: string;
+}
+interface ClickLike {
+    button: number;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    defaultPrevented: boolean;
+}
+interface AnchorLike {
+    href: string;
+    target?: string;
+    origin: string;
+    download?: boolean;
+}
+export declare function shouldIntercept(e: ClickLike, a: AnchorLike): boolean;
+export interface PrefetchCache {
+    has(url: string): boolean;
+    peek(url: string): PageProps | undefined;
+    load(url: string, fetcher: (u: string) => Promise<PageProps>): Promise<PageProps>;
+    clear(url?: string): void;
+    size(): number;
+}
+export declare function createPrefetchCache(): PrefetchCache;
+export {};

package/lib/core/nav.js ADDED Viewed

@@ -0,0 +1,53 @@
+/* Resolved Navigation — phần THUẦN (testable, không DOM/fetch).
+ * shouldIntercept: có nên chặn click để SPA-nav không. createPrefetchCache: cache props
+ * theo URL + dedup in-flight (prefetch on hover → nav cảm giác tức thì). */
+/* Chỉ chặn để SPA-nav khi: chuột trái, không phím bổ trợ, cùng origin, không _blank/download.
+ * Còn lại → để browser điều hướng thường (progressive enhancement: JS tắt vẫn chạy <a>). */
+export function shouldIntercept(e, a) {
+    if (e.defaultPrevented)
+        return false;
+    if (e.button !== 0)
+        return false;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+        return false;
+    if (a.download)
+        return false;
+    if (a.target && a.target !== "" && a.target !== "_self")
+        return false;
+    let u;
+    try {
+        u = new URL(a.href, a.origin);
+    }
+    catch {
+        return false;
+    }
+    if (u.origin !== a.origin)
+        return false; // external
+    return true;
+}
+export function createPrefetchCache() {
+    const done = new Map();
+    const inflight = new Map();
+    return {
+        has: (url) => done.has(url),
+        peek: (url) => done.get(url),
+        load(url, fetcher) {
+            const cached = done.get(url);
+            if (cached)
+                return Promise.resolve(cached);
+            let p = inflight.get(url);
+            if (!p) {
+                p = fetcher(url).then((r) => { done.set(url, r); inflight.delete(url); return r; }, (e) => { inflight.delete(url); throw e; });
+                inflight.set(url, p);
+            }
+            return p;
+        },
+        clear(url) {
+            if (url)
+                done.delete(url);
+            else
+                done.clear();
+        },
+        size: () => done.size,
+    };
+}

package/lib/core/observe.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+export interface ReqLog {
+    method: string;
+    path: string;
+    status: number;
+    ms: number;
+    ts: number;
+}
+export interface Recorder {
+    record(e: ReqLog): void;
+    recent(n?: number): ReqLog[];
+}
+export declare function createRecorder(max?: number): Recorder;

package/lib/core/observe.js ADDED Viewed

@@ -0,0 +1,24 @@
+/* Observability — request log Ring Buffer CIRCULAR (#17).
+ * Trước: push + shift (shift O(n) mỗi record khi đầy). Giờ: mảng vòng + con trỏ ghi →
+ * record O(1) (không dời mảng). recent O(n) chỉ trên số phần tử yêu cầu. */
+export function createRecorder(max = 200) {
+    const buf = new Array(max);
+    let writeIdx = 0; // vị trí ghi tiếp theo
+    let size = 0;
+    return {
+        record(e) {
+            buf[writeIdx] = e;
+            writeIdx = (writeIdx + 1) % max;
+            if (size < max)
+                size++;
+        },
+        recent(n = 50) {
+            const count = Math.min(n, size);
+            const out = [];
+            for (let i = 0; i < count; i++) {
+                out.push(buf[(writeIdx - 1 - i + max * 2) % max]); // lùi từ mới nhất
+            }
+            return out; // newest-first
+        },
+    };
+}

package/lib/core/panel.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import type { ResolutionManifest } from "./resolver.ts";
+import type { ReqLog } from "./observe.ts";
+export declare function renderResolutionPanel(m: ResolutionManifest, requests?: ReqLog[]): string;

package/lib/core/panel.js ADDED Viewed

@@ -0,0 +1,46 @@
+const esc = (s) => String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+/* Dashboard fluxe (Trục 4j): RCA Resolution (mỗi cell giải trục nào) + Recent requests
+ * (observe: timing/status). String builder thuần, testable. */
+export function renderResolutionPanel(m, requests = []) {
+    const rows = Object.values(m.cells).map((c) => `
+      <tr>
+        <td><code>${c.id}</code></td>
+        <td><code>${c.route}</code></td>
+        <td>${c.render.mode}</td>
+        <td>${c.render.shipClientJs ? "✓ JS" : "0 JS"}</td>
+        <td><span class="badge ${c.backend.language}">${c.backend.language}</span></td>
+        <td>${c.backend.transport}</td>
+        <td>${c.backend.endpoint ?? "—"}</td>
+      </tr>`).join("");
+    return `<!doctype html><html lang="vi"><head><meta charset="utf-8"><title>fluxe — RCA Resolution</title>
+<style>
+  body{font:14px/1.5 ui-sans-serif,system-ui;margin:2rem;background:#0f0f1a;color:#e8e8f0}
+  h1{font-size:1.3rem;margin:0 0 .2rem}
+  .sub{color:#8a8aa0;margin-bottom:1.5rem}
+  table{border-collapse:collapse;width:100%;max-width:920px}
+  th,td{text-align:left;padding:.5rem .75rem;border-bottom:1px solid #2a2a40}
+  th{color:#8a8aa0;font-weight:600;font-size:.78rem;text-transform:uppercase;letter-spacing:.04em}
+  code{background:#1a1a2e;padding:.1rem .35rem;border-radius:4px;color:#a0a0ff}
+  .badge{display:inline-block;padding:.1rem .55rem;border-radius:99px;font-size:.78rem}
+  .go{background:#00add833;color:#5fd3f0}.rust{background:#dea58433;color:#e8b48f}.memory{background:#7c7cff33;color:#a0a0ff}
+</style></head>
+<body>
+  <h1>RCA Resolution</h1>
+  <div class="sub">profile <b>${m.profile}</b> · default backend <b>${m.backend.language}</b> (${m.backend.transport})</div>
+  <table>
+    <thead><tr><th>cell</th><th>route</th><th>render</th><th>JS</th><th>backend</th><th>transport</th><th>endpoint</th></tr></thead>
+    <tbody>${rows}
+    </tbody>
+  </table>
+  <p class="sub" style="margin-top:1.5rem">Đọc từ <code>.fluxe/resolution.json</code> — mỗi cell được Resolution Plane giải độc lập.</p>
+  ${requests.length ? `
+  <h1 style="font-size:1.1rem;margin:2rem 0 .2rem">Recent requests</h1>
+  <div class="sub">${requests.length} request gần nhất (observe)</div>
+  <table>
+    <thead><tr><th>method</th><th>path</th><th>status</th><th>ms</th></tr></thead>
+    <tbody>${requests.map((r) => `
+      <tr><td>${esc(r.method)}</td><td><code>${esc(r.path)}</code></td><td>${r.status}</td><td>${r.ms}ms</td></tr>`).join("")}
+    </tbody>
+  </table>` : ""}
+</body></html>`;
+}

package/lib/core/presence.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+export interface Presence {
+    join(topic: string, id: string): () => void;
+    members(topic: string): string[];
+    count(topic: string): number;
+}
+export declare function createPresence(): Presence;

package/lib/core/presence.js ADDED Viewed

@@ -0,0 +1,33 @@
+/* Presence — ai đang online per topic (Trục 4g). Refcount theo id để chịu multi-tab/
+ * nhiều kết nối cùng user. Bản 1-node; distributed: chia sẻ qua NATS/Redis (gắn 4d). */
+export function createPresence() {
+    const topics = new Map(); // topic → (id → số kết nối)
+    return {
+        join(topic, id) {
+            let m = topics.get(topic);
+            if (!m) {
+                m = new Map();
+                topics.set(topic, m);
+            }
+            m.set(id, (m.get(id) ?? 0) + 1);
+            return () => {
+                const mm = topics.get(topic);
+                if (!mm)
+                    return;
+                const n = (mm.get(id) ?? 0) - 1;
+                if (n <= 0)
+                    mm.delete(id);
+                else
+                    mm.set(id, n);
+                if (mm.size === 0)
+                    topics.delete(topic);
+            };
+        },
+        members(topic) {
+            return [...(topics.get(topic)?.keys() ?? [])];
+        },
+        count(topic) {
+            return topics.get(topic)?.size ?? 0;
+        },
+    };
+}

package/lib/core/ratelimit.d.ts ADDED Viewed

@@ -0,0 +1,13 @@
+export interface RateLimiter {
+    take(key: string): {
+        ok: boolean;
+        retryAfter: number;
+    };
+    size(): number;
+}
+export declare function createRateLimiter(opts: {
+    capacity: number;
+    refillPerSec: number;
+    now?: () => number;
+    maxKeys?: number;
+}): RateLimiter;

package/lib/core/ratelimit.js ADDED Viewed

@@ -0,0 +1,32 @@
+/* Rate limiting (6b.F) — token bucket per key (vd IP/user/route). Thuần, clock injected.
+ * Bucket bound bằng LRU (maxKeys) → CHỐNG RÒ RAM khi nhiều IP (kẻ tấn công nhiều nguồn).
+ * Bản 1-node; distributed: chia sẻ bucket qua Redis (gắn 4d), cùng interface. */
+export function createRateLimiter(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const max = opts.maxKeys ?? 100_000;
+    // Map giữ thứ tự chèn → dùng làm LRU: chạm key = delete+set (đẩy về cuối).
+    const buckets = new Map();
+    return {
+        take(key) {
+            const t = now();
+            let b = buckets.get(key);
+            if (b) {
+                buckets.delete(key); // chạm → đưa về cuối (recently used)
+            }
+            else {
+                b = { tokens: opts.capacity, last: t };
+                if (buckets.size >= max)
+                    buckets.delete(buckets.keys().next().value); // evict LRU (đầu)
+            }
+            buckets.set(key, b);
+            b.tokens = Math.min(opts.capacity, b.tokens + ((t - b.last) / 1000) * opts.refillPerSec);
+            b.last = t;
+            if (b.tokens >= 1) {
+                b.tokens -= 1;
+                return { ok: true, retryAfter: 0 };
+            }
+            return { ok: false, retryAfter: Math.ceil((1 - b.tokens) / opts.refillPerSec) };
+        },
+        size: () => buckets.size,
+    };
+}

package/lib/core/rendercache.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+export interface RenderEntry {
+    etag: string;
+    buf: Buffer;
+}
+export interface RenderCache {
+    /** Lấy entry theo key (đánh dấu vừa dùng — LRU). undefined nếu chưa có. */
+    get(key: string): RenderEntry | undefined;
+    /** Lưu/ghi đè entry; evict key cũ nhất nếu vượt maxKeys. */
+    set(key: string, entry: RenderEntry): void;
+    /** Số entry hiện giữ (≤ maxKeys) — cho test/quan sát. */
+    size(): number;
+}
+export declare function createRenderCache(opts?: {
+    maxKeys?: number;
+}): RenderCache;

package/lib/core/rendercache.js ADDED Viewed

@@ -0,0 +1,39 @@
+/* ============================================================
+ * Render cache — memoize HTML đã render của cell static, key theo route.
+ *
+ * Tối ưu "zero-copy kiểu Node": render React 1 lần → giữ Buffer → mọi request
+ * sau ghi LẠI đúng buffer đó (res.end), bỏ qua renderToPipeableStream (đắt ~1 lõi).
+ *
+ * Behavior-preserving: mỗi entry gắn `etag` của data sinh ra nó. Caller chỉ dùng
+ * buffer khi etag khớp data hiện tại → data đổi ⇒ miss ⇒ render lại (không trả HTML cũ).
+ *
+ * Bound bộ nhớ bằng LRU (route động như /hello/[name] có không gian key vô hạn —
+ * không bound sẽ rò RAM). DSA: Hash Table + danh sách LRU, get/set O(1).
+ * ============================================================ */
+export function createRenderCache(opts = {}) {
+    const maxKeys = opts.maxKeys ?? 256;
+    // Map giữ thứ tự chèn → key đầu tiên = ít-dùng-gần-đây nhất (LRU).
+    const m = new Map();
+    return {
+        get(key) {
+            const e = m.get(key);
+            if (e === undefined)
+                return undefined;
+            m.delete(key); // chạm vào → đẩy lên "mới dùng" (cuối Map)
+            m.set(key, e);
+            return e;
+        },
+        set(key, entry) {
+            if (m.has(key))
+                m.delete(key);
+            m.set(key, entry);
+            while (m.size > maxKeys) {
+                const oldest = m.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                m.delete(oldest);
+            }
+        },
+        size: () => m.size,
+    };
+}

package/lib/core/resolver.d.ts ADDED Viewed

@@ -0,0 +1,37 @@
+export type RenderMode = "static" | "island";
+export type BackendKind = "memory" | "go" | "rust";
+export interface CellDecl {
+    id: string;
+    route: string;
+    hydration?: RenderMode;
+}
+export interface ResolutionProfile {
+    name: string;
+    backend: BackendKind;
+    endpoints?: {
+        go?: string;
+        rust?: string;
+    };
+    cellBackends?: Record<string, BackendKind>;
+}
+export interface BackendResolution {
+    language: BackendKind;
+    transport: "in-process" | "http";
+    endpoint?: string;
+}
+export interface CellResolution {
+    id: string;
+    route: string;
+    render: {
+        mode: RenderMode;
+        shipClientJs: boolean;
+    };
+    backend: BackendResolution;
+}
+export interface ResolutionManifest {
+    version: 1;
+    profile: string;
+    backend: BackendResolution;
+    cells: Record<string, CellResolution>;
+}
+export declare function resolve(cells: CellDecl[], profile: ResolutionProfile): ResolutionManifest;

package/lib/core/resolver.js ADDED Viewed

@@ -0,0 +1,42 @@
+const ALLOWED = ["memory", "go", "rust"];
+// Giải một BackendKind → BackendResolution (validate endpoint nếu http). Dùng chung
+// cho default app-level lẫn override per-cell.
+function resolveBackend(kind, profile) {
+    if (!ALLOWED.includes(kind)) {
+        throw new Error(`profile "${profile.name}": backend không hợp lệ: ${kind}`);
+    }
+    if (kind === "memory")
+        return { language: "memory", transport: "in-process" };
+    const endpoint = profile.endpoints?.[kind];
+    if (!endpoint) {
+        throw new Error(`profile "${profile.name}": backend "${kind}" cần endpoints.${kind}`);
+    }
+    return { language: kind, transport: "http", endpoint };
+}
+export function resolve(cells, profile) {
+    const ids = new Set(cells.map((c) => c.id));
+    for (const id of Object.keys(profile.cellBackends ?? {})) {
+        if (!ids.has(id)) {
+            throw new Error(`profile "${profile.name}": cellBackends trỏ cell không tồn tại: ${id}`);
+        }
+    }
+    const backend = resolveBackend(profile.backend, profile); // default app-level
+    const out = {};
+    const seenRoutes = new Set();
+    for (const c of cells) {
+        if (out[c.id])
+            throw new Error(`cell id trùng: ${c.id}`);
+        if (seenRoutes.has(c.route))
+            throw new Error(`route trùng: ${c.route}`);
+        seenRoutes.add(c.route);
+        const kind = profile.cellBackends?.[c.id] ?? profile.backend;
+        const mode = c.hydration ?? "island"; // default island
+        out[c.id] = {
+            id: c.id,
+            route: c.route,
+            render: { mode, shipClientJs: mode === "island" },
+            backend: resolveBackend(kind, profile),
+        };
+    }
+    return { version: 1, profile: profile.name, backend, cells: out };
+}

package/lib/core/router.d.ts ADDED Viewed

@@ -0,0 +1,6 @@
+import type { CellDef } from "./engine";
+export interface RouteMatch {
+    cell: CellDef<any, any>;
+    params: Record<string, string>;
+}
+export declare function makeRouter(cells: CellDef<any, any>[]): (pathname: string) => RouteMatch | null;

package/lib/core/router.js ADDED Viewed

@@ -0,0 +1,41 @@
+const ESC = /[.*+?^${}()|[\]\\]/g;
+function compile(cell) {
+    const paramNames = [];
+    let isStatic = true;
+    const parts = cell.route.split("/").map((seg) => {
+        const m = seg.match(/^\[(.+)\]$/);
+        if (m) {
+            isStatic = false;
+            paramNames.push(m[1]);
+            return "([^/]+)";
+        }
+        return seg.replace(ESC, "\\$&");
+    });
+    return { isStatic, compiled: { cell, regex: new RegExp("^" + parts.join("/") + "$"), paramNames } };
+}
+// Trả về matcher: static exact (Map, O(1)) trước, dynamic param sau (precedence).
+export function makeRouter(cells) {
+    const staticMap = new Map();
+    const dynamic = [];
+    for (const cell of cells) {
+        const { isStatic, compiled } = compile(cell);
+        if (isStatic)
+            staticMap.set(cell.route, cell);
+        else
+            dynamic.push(compiled);
+    }
+    return (pathname) => {
+        const s = staticMap.get(pathname);
+        if (s)
+            return { cell: s, params: {} };
+        for (const d of dynamic) {
+            const m = d.regex.exec(pathname);
+            if (m) {
+                const params = {};
+                d.paramNames.forEach((n, i) => (params[n] = decodeURIComponent(m[i + 1])));
+                return { cell: d.cell, params };
+            }
+        }
+        return null;
+    };
+}

package/lib/core/seo.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+export interface HeadMeta {
+    title?: string;
+    description?: string;
+    canonical?: string;
+    og?: Record<string, string>;
+    jsonLd?: unknown;
+}
+export declare function renderHead(meta: HeadMeta): string;
+export declare function renderSitemap(routes: string[], baseUrl: string): string;
+export declare function renderRobots(baseUrl: string): string;