@nuraly/lumenjs 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # LumenJS
 
-A full-stack web framework for [Lit](https://lit.dev/) web components. File-based routing, server loaders, SSR with hydration, nested layouts, API routes, and a Vite-powered dev server.
+A full-stack web framework for [Lit](https://lit.dev/) web components. File-based routing, server loaders, real-time subscriptions (SSE), SSR with hydration, nested layouts, API routes, and a Vite-powered dev server.
 
 ## Quick Start
 
@@ -49,9 +49,7 @@ Pages are Lit components in the `pages/` directory. The file path determines the
 ```typescript
 // pages/index.ts
 import { LitElement, html, css } from 'lit';
-import { customElement } from 'lit/decorators.js';
 
-@customElement('page-index')
 export class PageIndex extends LitElement {
   static styles = css`:host { display: block; }`;
 
@@ -61,6 +59,8 @@ export class PageIndex extends LitElement {
 }
 ```
 
+The custom element tag name is derived automatically from the file path — no `@customElement` decorator needed.
+
 ### Routing
 
 | File | URL | Tag |
@@ -85,9 +85,9 @@ export async function loader({ params, headers, query, url }) {
   return { post };
 }
 
-@customElement('page-blog-slug')
 export class BlogPost extends LitElement {
-  @property({ type: Object }) loaderData: any = {};
+  static properties = { loaderData: { type: Object } };
+  loaderData: any = {};
 
   render() {
     return html`<h1>${this.loaderData.post?.title}</h1>`;
@@ -105,6 +105,7 @@ Loaders run server-side on initial load (SSR) and are fetched via `/__nk_loader/
 | `query` | `Record<string, string>` | Query string parameters |
 | `url` | `string` | Request pathname |
 | `headers` | `Record<string, any>` | Request headers |
+| `locale` | `string` | Current locale (when i18n is configured) |
 
 ### Redirects
 
@@ -116,13 +117,75 @@ export async function loader({ headers }) {
 }
 ```
 
+## Live Data (subscribe)
+
+Export a `subscribe()` function from any page or layout to push real-time data to the client over Server-Sent Events (SSE).
+
+```typescript
+// pages/dashboard.ts
+export async function loader() {
+  return { orders: await db.orders.findAll() };
+}
+
+export function subscribe({ push }) {
+  const stream = db.orders.watch();
+  stream.on('change', (change) => push({ type: 'order-update', data: change }));
+  return () => stream.close();
+}
+
+export class PageDashboard extends LitElement {
+  static properties = { loaderData: { type: Object }, liveData: { type: Object } };
+  loaderData: any = {};
+  liveData: any = null;
+
+  render() {
+    return html`
+      <h1>Orders (${this.loaderData.orders?.length})</h1>
+      ${this.liveData ? html`<p>Update: ${this.liveData.type}</p>` : ''}
+    `;
+  }
+}
+```
+
+The `subscribe()` function is a persistent server-side process tied to the page lifecycle:
+
+1. User opens page → framework opens SSE connection to `/__nk_subscribe/<path>`
+2. Server calls `subscribe()` — function keeps running (DB watchers, intervals, etc.)
+3. Call `push(data)` whenever you want → delivered to client → updates `liveData` property
+4. User navigates away → connection closes → cleanup function runs
+
+Like `loader()`, `subscribe()` is stripped from client bundles automatically.
+
+### Subscribe Context
+
+| Property | Type | Description |
+|---|---|---|
+| `params` | `Record<string, string>` | Dynamic route parameters |
+| `headers` | `Record<string, any>` | Request headers |
+| `locale` | `string` | Current locale (when i18n is configured) |
+| `push` | `(data: any) => void` | Send SSE event to client (JSON-serialized) |
+
+Return a cleanup function that is called when the client disconnects.
+
+### Layout Subscribe
+
+Layouts can also export `subscribe()` for global live data (notifications, presence, etc.):
+
+```typescript
+// pages/_layout.ts
+export function subscribe({ push }) {
+  const ws = new WebSocket('wss://notifications.example.com');
+  ws.on('message', (msg) => push(JSON.parse(msg)));
+  return () => ws.close();
+}
+```
+
 ## Nested Layouts
 
 Create `_layout.ts` in any directory to wrap all pages in that directory and its subdirectories.
 
 ```typescript
 // pages/_layout.ts
-@customElement('layout-root')
 export class RootLayout extends LitElement {
   render() {
     return html`
@@ -146,9 +209,9 @@ export async function loader({ headers }) {
   return { user };
 }
 
-@customElement('layout-dashboard')
 export class DashboardLayout extends LitElement {
-  @property({ type: Object }) loaderData: any = {};
+  static properties = { loaderData: { type: Object } };
+  loaderData: any = {};
 
   render() {
     return html`
@@ -223,6 +286,80 @@ Pages with loaders are automatically server-rendered using `@lit-labs/ssr`:
 
 Pages without loaders render client-side only (SPA mode). If SSR fails, LumenJS falls back gracefully to client-side rendering.
 
+## Internationalization (i18n)
+
+LumenJS has built-in i18n support with URL-prefix-based locale routing.
+
+### Setup
+
+1. Add i18n config to `lumenjs.config.ts`:
+
+```typescript
+export default {
+  title: 'My App',
+  i18n: {
+    locales: ['en', 'fr'],
+    defaultLocale: 'en',
+    prefixDefault: false, // / instead of /en/
+  },
+};
+```
+
+2. Create translation files in `locales/`:
+
+```
+my-app/
+├── locales/
+│   ├── en.json    # { "home.title": "Welcome", "nav.docs": "Docs" }
+│   └── fr.json    # { "home.title": "Bienvenue", "nav.docs": "Documentation" }
+├── pages/
+└── lumenjs.config.ts
+```
+
+### Usage
+
+```typescript
+import { t, getLocale, setLocale } from '@lumenjs/i18n';
+
+export class PageIndex extends LitElement {
+  render() {
+    return html`<h1>${t('home.title')}</h1>`;
+  }
+}
+```
+
+### API
+
+| Function | Description |
+|---|---|
+| `t(key)` | Returns the translated string for the key, or the key itself if not found |
+| `getLocale()` | Returns the current locale string |
+| `setLocale(locale)` | Switches locale — sets cookie, navigates to the localized URL |
+
+### Locale Resolution
+
+Locale is resolved in this order:
+
+1. URL prefix: `/fr/about` → locale `fr`, pathname `/about`
+2. Cookie `nk-locale` (set on explicit locale switch)
+3. `Accept-Language` header (SSR)
+4. Config `defaultLocale`
+
+### URL Routing
+
+With `prefixDefault: false`, the default locale uses clean URLs:
+
+| URL | Locale | Page |
+|---|---|---|
+| `/about` | `en` (default) | `pages/about.ts` |
+| `/fr/about` | `fr` | `pages/about.ts` |
+
+Routes are locale-agnostic — you don't need separate pages per locale. The router strips the locale prefix before matching and prepends it during navigation.
+
+### SSR
+
+Translations are server-rendered. The `<html lang="...">` attribute is set dynamically, and translations are inlined in the response for hydration without flash of untranslated content.
+
 ## Integrations
 
 ### Tailwind CSS

package/dist/build/build.js

@@ -65,12 +65,12 @@ export async function buildProject(options) {
     // Collect server entry points (pages with loaders + layouts with loaders + API routes)
     const serverEntries = {};
     for (const entry of pageEntries) {
-        if (entry.hasLoader) {
+        if (entry.hasLoader || entry.hasSubscribe) {
             serverEntries[`pages/${entry.name}`] = entry.filePath;
         }
     }
     for (const entry of layoutEntries) {
-        if (entry.hasLoader) {
+        if (entry.hasLoader || entry.hasSubscribe) {
             const entryName = entry.dir ? `layouts/${entry.dir}/_layout` : 'layouts/_layout';
             serverEntries[entryName] = entry.filePath;
         }
@@ -124,6 +124,7 @@ export async function buildProject(options) {
                             'os', 'fs', 'path', 'url', 'util', 'crypto', 'http', 'https', 'net',
                             'stream', 'zlib', 'events', 'buffer', 'querystring', 'child_process',
                             'worker_threads', 'cluster', 'dns', 'tls', 'assert', 'constants',
+                            'better-sqlite3',
                         ],
                     },
                 },
@@ -163,8 +164,9 @@ export async function buildProject(options) {
             const relPath = path.relative(pagesDir, e.filePath).replace(/\\/g, '/');
             return {
                 path: e.routePath,
-                module: e.hasLoader ? `pages/${e.name}.js` : '',
+                module: (e.hasLoader || e.hasSubscribe) ? `pages/${e.name}.js` : '',
                 hasLoader: e.hasLoader,
+                hasSubscribe: e.hasSubscribe,
                 tagName: filePathToTagName(relPath),
                 ...(routeLayouts.length > 0 ? { layouts: routeLayouts } : {}),
             };
@@ -173,11 +175,13 @@ export async function buildProject(options) {
             path: `/api/${e.routePath}`,
             module: `api/${e.name}.js`,
             hasLoader: false,
+            hasSubscribe: false,
         })),
         layouts: layoutEntries.map(e => ({
             dir: e.dir,
-            module: e.hasLoader ? (e.dir ? `layouts/${e.dir}/_layout.js` : 'layouts/_layout.js') : '',
+            module: (e.hasLoader || e.hasSubscribe) ? (e.dir ? `layouts/${e.dir}/_layout.js` : 'layouts/_layout.js') : '',
             hasLoader: e.hasLoader,
+            hasSubscribe: e.hasSubscribe,
         })),
         ...(i18nConfig ? { i18n: i18nConfig } : {}),
     };

package/dist/build/scan.d.ts

@@ -3,11 +3,13 @@ export interface PageEntry {
     filePath: string;
     routePath: string;
     hasLoader: boolean;
+    hasSubscribe: boolean;
 }
 export interface LayoutEntry {
     dir: string;
     filePath: string;
     hasLoader: boolean;
+    hasSubscribe: boolean;
 }
 export interface ApiEntry {
     name: string;

package/dist/build/scan.js

@@ -1,6 +1,6 @@
 import fs from 'fs';
 import path from 'path';
-import { fileHasLoader, filePathToRoute } from '../shared/utils.js';
+import { fileHasLoader, fileHasSubscribe, filePathToRoute } from '../shared/utils.js';
 export function scanPages(pagesDir) {
     if (!fs.existsSync(pagesDir))
         return [];
@@ -54,7 +54,8 @@ function walkDir(baseDir, relativePath, entries, pagesDir) {
             const name = entryRelative.replace(/\.(ts|js)$/, '').replace(/\\/g, '/');
             const routePath = filePathToRoute(entryRelative);
             const hasLoader = fileHasLoader(filePath);
-            entries.push({ name, filePath, routePath, hasLoader });
+            const hasSubscribe = fileHasSubscribe(filePath);
+            entries.push({ name, filePath, routePath, hasLoader, hasSubscribe });
         }
     }
 }
@@ -65,7 +66,7 @@ function walkForLayouts(baseDir, relativePath, entries) {
         if (entry.isFile() && /^_layout\.(ts|js)$/.test(entry.name)) {
             const filePath = path.join(fullDir, entry.name);
             const dir = relativePath.replace(/\\/g, '/');
-            entries.push({ dir, filePath, hasLoader: fileHasLoader(filePath) });
+            entries.push({ dir, filePath, hasLoader: fileHasLoader(filePath), hasSubscribe: fileHasSubscribe(filePath) });
         }
         if (entry.isDirectory()) {
             walkForLayouts(baseDir, path.join(relativePath, entry.name), entries);

package/dist/build/serve-loaders.d.ts

@@ -1,4 +1,6 @@
 import http from 'http';
 import type { BuildManifest } from '../shared/types.js';
 export declare function handleLayoutLoaderRequest(manifest: BuildManifest, serverDir: string, queryString: string | undefined, headers: http.IncomingHttpHeaders, res: http.ServerResponse): Promise<void>;
+export declare function handleLayoutSubscribeRequest(manifest: BuildManifest, serverDir: string, queryString: string | undefined, headers: http.IncomingHttpHeaders, res: http.ServerResponse): Promise<void>;
+export declare function handleSubscribeRequest(manifest: BuildManifest, serverDir: string, pagesDir: string, pathname: string, queryString: string | undefined, headers: http.IncomingHttpHeaders, res: http.ServerResponse): Promise<void>;
 export declare function handleLoaderRequest(manifest: BuildManifest, serverDir: string, pagesDir: string, pathname: string, queryString: string | undefined, headers: http.IncomingHttpHeaders, res: http.ServerResponse): Promise<void>;

package/dist/build/serve-loaders.js

@@ -56,6 +56,116 @@ export async function handleLayoutLoaderRequest(manifest, serverDir, queryString
         res.end(JSON.stringify({ error: message }));
     }
 }
+export async function handleLayoutSubscribeRequest(manifest, serverDir, queryString, headers, res) {
+    const query = {};
+    if (queryString) {
+        for (const pair of queryString.split('&')) {
+            const [key, val] = pair.split('=');
+            query[decodeURIComponent(key)] = decodeURIComponent(val || '');
+        }
+    }
+    const dir = query.__dir || '';
+    const layout = (manifest.layouts || []).find(l => l.dir === dir);
+    if (!layout || !layout.hasSubscribe || !layout.module) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    const modulePath = path.join(serverDir, layout.module);
+    if (!fs.existsSync(modulePath)) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    try {
+        const mod = await import(modulePath);
+        if (!mod.subscribe || typeof mod.subscribe !== 'function') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+        });
+        const locale = query.__locale;
+        const push = (data) => {
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        };
+        const cleanup = mod.subscribe({ params: {}, push, headers, locale });
+        res.on('close', () => {
+            if (typeof cleanup === 'function')
+                cleanup();
+        });
+    }
+    catch (err) {
+        console.error(`[LumenJS] Layout subscribe error for dir=${dir}:`, err);
+        if (!res.headersSent) {
+            res.writeHead(500);
+            res.end();
+        }
+    }
+}
+export async function handleSubscribeRequest(manifest, serverDir, pagesDir, pathname, queryString, headers, res) {
+    const pagePath = pathname.replace('/__nk_subscribe', '') || '/';
+    const query = {};
+    if (queryString) {
+        for (const pair of queryString.split('&')) {
+            const [key, val] = pair.split('=');
+            query[decodeURIComponent(key)] = decodeURIComponent(val || '');
+        }
+    }
+    let params = {};
+    if (query.__params) {
+        try {
+            params = JSON.parse(query.__params);
+        }
+        catch { /* ignore */ }
+        delete query.__params;
+    }
+    const matched = matchRoute(manifest.routes.filter(r => r.hasSubscribe), pagePath);
+    if (!matched || !matched.route.module) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    const modulePath = path.join(serverDir, matched.route.module);
+    if (!fs.existsSync(modulePath)) {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    try {
+        const mod = await import(modulePath);
+        if (!mod.subscribe || typeof mod.subscribe !== 'function') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+        });
+        const locale = query.__locale;
+        const push = (data) => {
+            res.write(`data: ${JSON.stringify(data)}\n\n`);
+        };
+        const cleanup = mod.subscribe({ params: matched.params, push, headers, locale });
+        res.on('close', () => {
+            if (typeof cleanup === 'function')
+                cleanup();
+        });
+    }
+    catch (err) {
+        console.error(`[LumenJS] Subscribe error for ${pagePath}:`, err);
+        if (!res.headersSent) {
+            res.writeHead(500);
+            res.end();
+        }
+    }
+}
 export async function handleLoaderRequest(manifest, serverDir, pagesDir, pathname, queryString, headers, res) {
     const pagePath = pathname.replace('/__nk_loader', '') || '/';
     // Parse query params

package/dist/build/serve.js

@@ -5,13 +5,15 @@ import { readProjectConfig } from '../dev-server/config.js';
 import { installDomShims } from '../shared/dom-shims.js';
 import { serveStaticFile, sendCompressed } from './serve-static.js';
 import { handleApiRoute } from './serve-api.js';
-import { handleLoaderRequest, handleLayoutLoaderRequest } from './serve-loaders.js';
+import { handleLoaderRequest, handleLayoutLoaderRequest, handleSubscribeRequest, handleLayoutSubscribeRequest } from './serve-loaders.js';
 import { handlePageRoute } from './serve-ssr.js';
 import { renderErrorPage } from './error-page.js';
 import { handleI18nRequest } from './serve-i18n.js';
 import { resolveLocale } from '../dev-server/middleware/locale.js';
+import { setProjectDir } from '../db/context.js';
 export async function serveProject(options) {
     const { projectDir } = options;
+    setProjectDir(projectDir);
     const port = options.port || 3000;
     const outDir = path.join(projectDir, '.lumenjs');
     const clientDir = path.join(outDir, 'client');
@@ -62,12 +64,22 @@ export async function serveProject(options) {
                 handleI18nRequest(localesDir, manifest.i18n.locales, pathname, req, res);
                 return;
             }
-            // 4. Layout loader endpoint
+            // 4. Layout subscribe endpoint (SSE)
+            if (pathname === '/__nk_subscribe/__layout/' || pathname === '/__nk_subscribe/__layout') {
+                await handleLayoutSubscribeRequest(manifest, serverDir, queryString, req.headers, res);
+                return;
+            }
+            // 5. Subscribe endpoint (SSE)
+            if (pathname.startsWith('/__nk_subscribe/')) {
+                await handleSubscribeRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res);
+                return;
+            }
+            // 6. Layout loader endpoint
             if (pathname === '/__nk_loader/__layout/' || pathname === '/__nk_loader/__layout') {
                 await handleLayoutLoaderRequest(manifest, serverDir, queryString, req.headers, res);
                 return;
             }
-            // 5. Loader endpoint for client-side navigation
+            // 7. Loader endpoint for client-side navigation
             if (pathname.startsWith('/__nk_loader/')) {
                 await handleLoaderRequest(manifest, serverDir, pagesDir, pathname, queryString, req.headers, res);
                 return;

package/dist/db/context.d.ts

@@ -0,0 +1,2 @@
+export declare function setProjectDir(dir: string): void;
+export declare function getProjectDir(): string;

package/dist/db/context.js

@@ -0,0 +1,9 @@
+let _projectDir = null;
+export function setProjectDir(dir) {
+    _projectDir = dir;
+}
+export function getProjectDir() {
+    if (!_projectDir)
+        throw new Error('[LumenJS] Project directory not set');
+    return _projectDir;
+}

package/dist/db/index.d.ts

@@ -0,0 +1,19 @@
+import Database from 'better-sqlite3';
+export declare class LumenDb {
+    private db;
+    constructor(db: Database.Database);
+    /** SELECT multiple rows */
+    all<T = any>(sql: string, ...params: any[]): T[];
+    /** SELECT single row */
+    get<T = any>(sql: string, ...params: any[]): T | undefined;
+    /** INSERT/UPDATE/DELETE */
+    run(sql: string, ...params: any[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    /** Multi-statement DDL */
+    exec(sql: string): void;
+    /** Access the underlying better-sqlite3 instance */
+    get raw(): Database.Database;
+}
+export declare function useDb(): LumenDb;

package/dist/db/index.js

@@ -0,0 +1,79 @@
+import path from 'path';
+import fs from 'fs';
+import Database from 'better-sqlite3';
+import { getProjectDir } from './context.js';
+import { readProjectConfig } from '../dev-server/config.js';
+export class LumenDb {
+    constructor(db) {
+        this.db = db;
+    }
+    /** SELECT multiple rows */
+    all(sql, ...params) {
+        return this.db.prepare(sql).all(...params);
+    }
+    /** SELECT single row */
+    get(sql, ...params) {
+        return this.db.prepare(sql).get(...params);
+    }
+    /** INSERT/UPDATE/DELETE */
+    run(sql, ...params) {
+        const result = this.db.prepare(sql).run(...params);
+        return { changes: result.changes, lastInsertRowid: result.lastInsertRowid };
+    }
+    /** Multi-statement DDL */
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    /** Access the underlying better-sqlite3 instance */
+    get raw() {
+        return this.db;
+    }
+}
+let _instance = null;
+export function useDb() {
+    if (_instance)
+        return _instance;
+    const projectDir = getProjectDir();
+    const config = readProjectConfig(projectDir);
+    const dbRelPath = config.db?.path || 'data/db.sqlite';
+    const dbPath = path.resolve(projectDir, dbRelPath);
+    // Auto-create directory
+    const dbDir = path.dirname(dbPath);
+    if (!fs.existsSync(dbDir)) {
+        fs.mkdirSync(dbDir, { recursive: true });
+    }
+    const db = new Database(dbPath);
+    db.pragma('journal_mode = WAL');
+    db.pragma('foreign_keys = ON');
+    _instance = new LumenDb(db);
+    // Run pending migrations
+    runMigrations(db, projectDir);
+    return _instance;
+}
+function runMigrations(db, projectDir) {
+    const migrationsDir = path.join(projectDir, 'data', 'migrations');
+    if (!fs.existsSync(migrationsDir))
+        return;
+    // Ensure tracking table exists
+    db.exec(`CREATE TABLE IF NOT EXISTS _lumen_migrations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+  )`);
+    const applied = new Set(db.prepare('SELECT name FROM _lumen_migrations').all()
+        .map((row) => row.name));
+    const files = fs.readdirSync(migrationsDir)
+        .filter(f => f.endsWith('.sql'))
+        .sort();
+    for (const file of files) {
+        if (applied.has(file))
+            continue;
+        const sql = fs.readFileSync(path.join(migrationsDir, file), 'utf-8');
+        const migrate = db.transaction(() => {
+            db.exec(sql);
+            db.prepare('INSERT INTO _lumen_migrations (name) VALUES (?)').run(file);
+        });
+        migrate();
+        console.log(`[LumenJS] Applied migration: ${file}`);
+    }
+}

package/dist/dev-server/config.d.ts

@@ -7,6 +7,9 @@ export interface ProjectConfig {
     title: string;
     integrations: string[];
     i18n?: I18nConfig;
+    db?: {
+        path?: string;
+    };
 }
 /**
  * Reads the project config from lumenjs.config.ts.

package/dist/dev-server/config.js

@@ -52,7 +52,21 @@ export function readProjectConfig(projectDir) {
         }
         catch { /* ignore */ }
     }
-    return { title, integrations, ...(i18n ? { i18n } : {}) };
+    // Parse db config
+    let db;
+    if (fs.existsSync(configPath)) {
+        try {
+            const configContent = fs.readFileSync(configPath, 'utf-8');
+            const dbMatch = configContent.match(/db\s*:\s*\{([\s\S]*?)\}/);
+            if (dbMatch) {
+                const block = dbMatch[1];
+                const pathMatch = block.match(/path\s*:\s*['"]([^'"]+)['"]/);
+                db = pathMatch ? { path: pathMatch[1] } : {};
+            }
+        }
+        catch { /* ignore */ }
+    }
+    return { title, integrations, ...(i18n ? { i18n } : {}), ...(db ? { db } : {}) };
 }
 /**
  * Reads the project title from lumenjs.config.ts (or returns default).

package/dist/dev-server/plugins/vite-plugin-loaders.d.ts

@@ -12,7 +12,6 @@ import { Plugin } from 'vite';
  *     return { item: data, timestamp: Date.now() };
  *   }
  *
- *   @customElement('page-item')
  *   export class PageItem extends LitElement {
  *     @property({ type: Object }) loaderData = {};
  *     render() {