@seip/bluebird-js 0.1.1 → 0.1.4

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 (49) hide show
  1. package/.vscode/extensions.json +7 -0
  2. package/.vscode/settings.json +10 -0
  3. package/AGENTS.md +124 -64
  4. package/README.md +236 -103
  5. package/app/routes/web.js +47 -55
  6. package/app/views/about.jsx +98 -0
  7. package/app/views/components/Header.jsx +42 -0
  8. package/app/views/components/LiveCounter.jsx +67 -0
  9. package/app/views/dashboard.jsx +300 -0
  10. package/app/views/index.jsx +123 -0
  11. package/app/views/layouts/main/view.jsx +201 -0
  12. package/app/views/legal/terms.html +29 -19
  13. package/app/views/login.jsx +141 -0
  14. package/core/actions.d.ts +4 -0
  15. package/core/actions.js +329 -0
  16. package/core/app.js +129 -22
  17. package/core/auth.js +1 -1
  18. package/core/cli/doctor.js +3 -4
  19. package/core/cli/init.js +153 -6
  20. package/core/cli/migrate.js +418 -145
  21. package/core/cli/view.js +76 -11
  22. package/core/config.js +35 -5
  23. package/core/csrf.js +1 -1
  24. package/core/database.js +52 -17
  25. package/core/debug.js +1 -1
  26. package/core/html.d.ts +54 -42
  27. package/core/html.js +473 -217
  28. package/core/index.d.ts +187 -85
  29. package/core/jsx.d.ts +38 -0
  30. package/core/jsx.js +1180 -0
  31. package/core/model.js +282 -61
  32. package/core/queue.js +7 -4
  33. package/core/render-cache.js +212 -212
  34. package/core/render.d.ts +20 -2
  35. package/core/render.js +320 -43
  36. package/core/upload.js +7 -1
  37. package/core/validate.js +1 -1
  38. package/core/view-loader.js +341 -19
  39. package/core/vite.js +1 -1
  40. package/package.json +9 -3
  41. package/public/js/bluebird-client.js +2313 -1049
  42. package/public/js/tailwind.js +8 -0
  43. package/app/views/about.js +0 -63
  44. package/app/views/dashboard.js +0 -147
  45. package/app/views/index.js +0 -80
  46. package/app/views/layouts/main/view.js +0 -81
  47. package/app/views/login.js +0 -80
  48. package/public/css/bluebird.min.css +0 -2
  49. package/public/js/bluebird.min.js +0 -1073
@@ -0,0 +1,7 @@
1
+ {
2
+ "recommendations": [
3
+ "Tobermory.es6-string-html",
4
+ "bradlc.vscode-tailwindcss"
5
+ ]
6
+ }
7
+
@@ -0,0 +1,10 @@
1
+ {
2
+ "emmet.includeLanguages": {
3
+ "javascript": "html",
4
+ "javascriptreact": "html"
5
+ },
6
+ "files.associations": {
7
+ "*.jsx": "javascriptreact"
8
+ }
9
+ }
10
+
package/AGENTS.md CHANGED
@@ -119,6 +119,20 @@ const postWithAuthor = await Post.find(10, { belongsTo: User });
119
119
  const page = await User.paginate({ where: { role: "user" }, page: 1, limit: 10 });
120
120
  await User.update(userId, { name: "Alice Smith" });
121
121
 
122
+ const totalUsers = await User.count({ role: "user" });
123
+ const exists = await User.exists({ email: "alice@example.com" });
124
+
125
+ const matching = await User.all({
126
+ where: {
127
+ id: [1, 2, 3],
128
+ role: { $ne: "banned" },
129
+ views: { $gt: 100 },
130
+ },
131
+ });
132
+
133
+ const userRecord = await User.firstOrCreate({ email: "john@example.com" }, { name: "John Doe" });
134
+ const updatedRecord = await User.updateOrCreate({ email: "john@example.com" }, { name: "Johnathan" });
135
+
122
136
  await User.delete(userId);
123
137
  await User.delete(userId, { force: true });
124
138
  await User.delete(userId, { cascade: [Post] });
@@ -306,18 +320,46 @@ For complete deployment details including Nginx reverse proxy configuration and
306
320
 
307
321
  Bluebird supports running embedded inside Electron or Tauri desktop applications where the application bundle (`.asar`) is read-only:
308
322
 
309
- - Automatically routes SQLite database files, `logs/`, and `app/cache/` to a writable OS user data directory (`Config.userDataDir()`), copying initial bundled SQLite databases on first run.
310
- - Binds strictly to `127.0.0.1` with dynamic port allocation (`port: 0`) via `await app.runDesktop()`.
323
+ - **Base Directory Resolution (`appPath`)**: Accepts `appPath: electronApp.getAppPath()` (or `Config.setAppDir()`) to ensure views (`app/views/`) and static assets (`public/`) resolve accurately regardless of shortcut launch locations (`process.cwd()`).
324
+ - **Writable User Data (`userDataPath`)**: Automatically routes SQLite database files, `logs/`, `app/cache/`, and file uploads (`Upload.storage()`) to `Config.userDataDir()` (`electronApp.getPath("userData")`), copying bundled initial SQLite template databases from `appPath`, `process.resourcesPath`, or `.asar.unpacked` on first launch.
325
+ - **Dynamic Port & LAN / QR Access**:
326
+ - By default, binds to `127.0.0.1` with dynamic port allocation (`port: 0`) via `await app.runDesktop()`.
327
+ - When `{ allowLan: true }` is enabled, binds to `0.0.0.0` and returns `{ server, port, url, lanUrl, lanIp }` ready for mobile QR code access on local WiFi.
328
+ - **Uploads & Static Serving**:
329
+ - In desktop mode, `Upload.storage()` writes to `userDataDir/uploads` and `App` automatically mounts `/uploads` to serve uploaded files statically without read-only filesystem errors.
330
+ - **Clean Shutdown & WAL Checkpoint**:
331
+ - Invoking `await app.close()` (e.g. in Electron `app.on("before-quit")`) automatically checkpoints SQLite WAL (`PRAGMA wal_checkpoint(TRUNCATE)`), closes open database handles via `Database.closeAll()`, and frees Windows file locks cleanly.
332
+ - **Packaging with electron-builder**:
333
+ - Recommended `electron-builder` configuration in `package.json`:
334
+ ```json
335
+ "build": {
336
+ "asar": true,
337
+ "asarUnpack": ["app/views/**/*", "database/**/*"]
338
+ }
339
+ ```
311
340
 
312
341
  ```javascript
342
+ import App from "@seip/bluebird-js/core/app.js";
343
+ import { app as electronApp, BrowserWindow } from "electron";
344
+ import routerApi from "./app/routes/api.js";
345
+ import routerWeb from "./app/routes/web.js";
346
+
313
347
  const app = new App({
314
348
  desktop: true,
349
+ appPath: electronApp.getAppPath(),
315
350
  userDataPath: electronApp.getPath("userData"),
316
351
  routes: [routerWeb, routerApi],
317
352
  });
318
353
 
319
- const { url, port } = await app.runDesktop();
320
- mainWindow.loadURL(url);
354
+ electronApp.whenReady().then(async () => {
355
+ const { url, port, lanUrl, lanIp } = await app.runDesktop({ allowLan: true });
356
+ const mainWindow = new BrowserWindow({ width: 1200, height: 800 });
357
+ mainWindow.loadURL(url);
358
+
359
+ electronApp.on("before-quit", async () => {
360
+ await app.close();
361
+ });
362
+ });
321
363
  ```
322
364
 
323
365
  ## 14. Developer Tooling CLI
@@ -328,10 +370,9 @@ npx bluebird-js make:model <Name> # BaseModel scaffolding
328
370
  npx bluebird-js make:route <name> # REST route scaffolding
329
371
  npx bluebird-js make:route <name> --auth # Authenticated REST route scaffolding
330
372
  npx bluebird-js make:view <name> # HTML or EJS template scaffolding
331
- npx bluebird-js make:migration <name> # Blank SQL migration
332
- npx bluebird-js make:migration --model <Model> # Auto DDL migration from Model schema
333
- npx bluebird-js make:migration --all # Batch generate migrations for all models
334
- npx bluebird-js migrate # Applies pending migrations
373
+ npx bluebird-js make:migration [name] # Smart auto-migration from app/models/
374
+ npx bluebird-js make:migration --model <Model> # Auto DDL migration for specific Model schema
375
+ npx bluebird-js migrate [--yes] # Executes pending migrations with auto-detection
335
376
  npx bluebird-js migrate:status # Displays applied batches
336
377
  npx bluebird-js migrate:rollback # Reverts latest batch
337
378
  npx bluebird-js make:seed <name> # Database seed file creation
@@ -355,66 +396,85 @@ await Queue.dispatch("sendWelcomeEmail", { email: "user@example.com" });
355
396
  await Queue.work();
356
397
  ```
357
398
 
358
- ## 16. Pure JavaScript Views, Layouts, Vanilla Scripts & View Transitions
359
-
360
- Bluebird provides a modern, zero-build view architecture uniting database-driven server-rendered HTML with pure ESM JavaScript views, shared layouts, simple inline vanilla scripts, and instant View Transitions SPA navigation:
361
-
362
- - **Zero-Build JavaScript Views (`html\`...\``)**: Located as flat files in `app/views/<name>.js` (e.g. `app/views/about.js`, `app/views/dashboard.js`, `app/views/login.js`). Views export a default rendering function using `html` tagged templates from `@seip/bluebird-js/core/html.js`. All interpolated variables `${val}` are strictly HTML-escaped automatically to prevent XSS. Explicit trusted markup uses `html.raw(markup)`.
363
- - **Shared Layouts (`app/views/layouts/main/view.js` or `app/views/layouts/main.js`)**:
364
- - Exported via `export const layout = "main"` on any view (defaults to `"main"`). Layout receives `{ body, head, ctx, data }`.
399
+ ## 16. React JSX SSR, Auto-Routes, Client Islands & View Transitions
400
+
401
+ Bluebird provides a modern, zero-build view architecture uniting database-driven server-rendered HTML with native React JSX (`.jsx`) and JavaScript (`.js`) views, declarative file-based Auto-Routes, shared layouts, Tailwind CSS v4, `<Client>` / `<Island>` components with anti-CLS skeletons, and instant View Transitions SPA navigation:
402
+
403
+ - **Built-In Tailwind CSS v4 & Inter Font**:
404
+ - `public/js/tailwind.js` and Google Fonts `Inter` are loaded by default in the main layout (`app/views/layouts/main/view.jsx`).
405
+ - Zero build steps, zero transpilation, pure modern utilities out of the box with dark mode synchronization.
406
+ - **Native Zero-Build React JSX SSR (`app/views/*.jsx`)**:
407
+ - Powered by `core/jsx.js` and Node 22.18+ native `module.registerHooks()`. Compiles `.jsx` modules in memory with **zero temporary files on disk** and **zero external npm dependencies** required.
408
+ - Supports `async` Server Components, Fragments (`<>...</>`), spread props, `style` objects, automatic XSS escaping, and mixed `html\`...\`` templates.
409
+ - **Declarative Auto-Routes from Views (`ViewLoader.discoverRoutes()` / `Render.autoRoutes()`)**:
410
+ - Automatically scans `app/views/` (ignoring `layouts/`, `components/`, `partials/`, `islands/`, and `/api`) and mounts GET routes when `App` starts.
411
+ - Export route settings directly from any view file:
412
+ - `export const route = "/login"` (or inferred automatically from filename; `false` disables auto-routing)
413
+ - `export const cache = 300` (applies `Render.cache(300)` automatically)
414
+ - `export const layout = "main"` (uses `app/views/layouts/main/view.jsx`)
415
+ - `export const middlewares = [Auth.protect({ redirect: "/login" })]`
416
+ - `export const seo = true` (registers route in `/sitemap.xml` and `/robots.txt`)
417
+ - Disable auto-discovery if desired via `new App({ noAutoDiscoverRoutes: true })`.
418
+ - **Client Components & Anti-Accordion Skeletons (`<Client>` / `<Island>`)**:
419
+ - Everything renders as pure SSR by default (0 KB client JS).
420
+ - For client-side interactivity (`useEffect`, `useState`, or native DOM logic), use `<Client>` or `<Island>` from `@seip/bluebird-js/core/jsx.js`.
421
+ - Pass `skeleton={...}`, `minHeight`, and `minWidth` to lock container dimensions before hydration and prevent layout shift ("accordion" effect), plus `persistent={true}` to preserve state across View Transitions.
422
+ - Supports zero-build declarative client components with standard hooks (`useState`, `useEffect`, `useRef`, `html` tagged templates) via `component={LiveCounter}` (`LiveCounter.jsx`), inline functions via `client={(el, props) => { ... }}`, and full React Islands (`npx bluebird-js add react-islands`).
423
+ - **Native Server Actions (`core/actions.js` & `export const actions = { ... }`)**:
424
+ - Next.js-style Server Actions executed on the server with automatic CSRF verification (`_csrf` cookie + `X-CSRF-Token` header), payload byte limit guards (`maxBytes`, default 64KB), prototype-pollution & depth/key sanitization (`sanitizeActionPayload`), and optional `Validator` schema checks.
425
+ - Triggered from the client via `await Bluebird.action("syncCount", { count: 10 })` or declarative `data-action="syncCount"` attributes on buttons/forms.
426
+ - **Shared Layouts (`app/views/layouts/main/view.jsx`)**:
427
+ - Exported via `export const layout = "main"` on any view (defaults to `"main"`). Layout receives `{ body, children, head, ctx, data }`.
365
428
  - When requested with `X-Bluebird-Partial: 1`, layouts are automatically bypassed for fast partial swaps.
366
429
  - Elements with `data-bb-outlet="true"` enable layout outlet swapping so navigation between pages sharing the same layout preserves header, menus, and media playback uninterrupted.
367
- - **Vanilla Inline Scripts (`<script>`)**:
368
- - Zero heavy frontend dependencies. Write plain native JavaScript directly in `<script>` tags inside `html\`...\`` (or using the optional `script` tagged template helper from `@seip/bluebird-js/core/html.js` for safe serialization).
369
- - Scripts inside `[data-bb-outlet]` re-execute automatically upon View Transitions navigation.
370
- - **Dev Live Reload**:
371
- - During development (`debug: true` or `node --watch`), Bluebird automatically reloads connected browser tabs via native Server-Sent Events (`/_bb/dev-reload`) on server restart. Zero browser plugins required.
372
- - **Raw Static HTML (`Render.html`)**:
373
- - For unparsed static files (terms of service, legal disclaimers, offline pages): `Render.html(res, "legal/terms.html", { ttl: 86400 })`. Bypasses template execution completely with zero server overhead.
374
- - **Fragment & Route Caching (`cached` & `Render.cache`)**:
375
- - Cache heavy fragments inside dynamic pages with `await cached("stats:summary", 60, async () => StatsCard(await Stats.summary()))`.
376
- - **Client Router (`public/js/bluebird-client.js`)**:
377
- - Native `document.startViewTransition()` page navigation.
378
- - Outlet-aware swaps via `[data-bb-outlet]` without layout flickering.
379
- - Preserved elements via `data-persist="true"`.
380
-
381
- ```javascript
382
- // app/views/dashboard.js
383
- import { html } from "@seip/bluebird-js/core/html.js";
430
+ - **Comprehensive Built-In Client UI Kit (`public/js/bluebird-client.js`)**:
431
+ - `toast({ title, description, type, position, duration })`
432
+ - `snackbar({ message, type, duration })`
433
+ - `bluebird('drawer', { id, action: 'open'|'close'|'toggle' })`
434
+ - `new ResponsiveDataTable(containerId, options)`
435
+ - `bluebird('command')` palette (`Ctrl+K`), `bluebird('tab')`, `bluebird('popover')`, `bluebird('carousel')`
436
+ - Declarative forms via `form[data-bb-form="true"]`: submits via `fetch`, auto-injects CSRF tokens, and follows `X-Bluebird-Redirect`.
437
+ - Native `document.startViewTransition()` page navigation with preserved elements via `data-persist="true"`.
438
+
439
+ ```jsx
440
+ // app/views/dashboard.jsx
441
+ import Auth from "@seip/bluebird-js/core/auth.js";
442
+ import Actions from "@seip/bluebird-js/core/actions.js";
443
+ import { Client } from "@seip/bluebird-js/core/jsx.js";
444
+ import Header from "./components/Header.jsx";
445
+ import LiveCounter from "./components/LiveCounter.js";
384
446
 
447
+ export const route = "/dashboard";
385
448
  export const layout = "main";
386
- export const head = (data) => ({ title: `Dashboard — ${data.user.name}` });
387
-
388
- export default function DashboardView({ user, metrics }) {
389
- const initial = metrics?.unread || 0;
390
-
391
- return html`
392
- <section class="dashboard-grid">
393
- <h1>Welcome back, ${user.name}</h1>
394
-
395
- <div class="card">
396
- <button id="btnDec" class="btn-sm">-</button>
397
- <span id="counter" class="font-bold">${initial}</span>
398
- <button id="btnInc" class="btn-sm">+</button>
399
- </div>
400
- </section>
401
-
402
- <!-- Native vanilla inline script: simple, readable, fast -->
403
- <script>
404
- (() => {
405
- let count = ${initial};
406
- const el = document.getElementById("counter");
407
- document.getElementById("btnInc")?.addEventListener("click", () => {
408
- count++;
409
- if (el) el.textContent = count;
410
- });
411
- document.getElementById("btnDec")?.addEventListener("click", () => {
412
- if (count > 0) count--;
413
- if (el) el.textContent = count;
414
- });
415
- })();
416
- </script>
417
- `;
449
+ export const middlewares = [Auth.protect({ redirect: "/login" })];
450
+ export const seo = false;
451
+ export const head = (data) => ({ title: `Dashboard — ${data.user?.name}` });
452
+
453
+ export const actions = {
454
+ syncCount: Actions.define(
455
+ {
456
+ maxBytes: "16kb",
457
+ schema: { count: { required: true, number: true } },
458
+ },
459
+ async ({ body, user }) => {
460
+ return { syncedCount: Number(body.count), updatedBy: user?.email };
461
+ }
462
+ ),
463
+ };
464
+
465
+ export default async function DashboardView({ user, syncedCount = 7 }) {
466
+ return (
467
+ <>
468
+ <Header title="Dashboard" user={user} count={syncedCount} />
469
+ <Client
470
+ component={LiveCounter}
471
+ props={{ initial: syncedCount }}
472
+ persistent={true}
473
+ minHeight={56}
474
+ skeleton={<div className="h-14 animate-pulse bg-slate-900 rounded-xl" />}
475
+ />
476
+ </>
477
+ );
418
478
  }
419
479
  ```
420
480