allez-orm 1.1.0 → 1.2.0

package/README.md

@@ -1,7 +1,471 @@
-# AllezORM
- browser SQLite ORM + schema generator.
-
-## Install
-
-    npm i allez-orm
-
+# AllezORM
+
+**Ship a real SQLite database — in the browser — in under five minutes.**
+Zero servers. Zero migrations. Zero "your data is gone because the user refreshed."
+
+> Built for the next era of software: client-first apps, AI-generated code,
+> and teams that ship faster than infrastructure can keep up.
+
+[![npm](https://img.shields.io/npm/v/allez-orm.svg)](https://www.npmjs.com/package/allez-orm)
+[![license](https://img.shields.io/badge/license-ISC-blue.svg)](LICENSE)
+[![tests](https://img.shields.io/badge/tests-67%20passing-brightgreen.svg)](#tests)
+[![node](https://img.shields.io/badge/node-%3E=18-success.svg)](package.json)
+
+---
+
+## Why this exists (read this part)
+
+You've felt all three of these. Recently.
+
+1. **Your "simple" app needs a real query layer in the browser**, and you're
+   one library choice away from `localStorage.setItem(JSON.stringify(...))`
+   creeping into production. Again.
+2. **Your AI agent confidently rewrote your schema** on Tuesday and you
+   didn't notice until staging. The spec said one thing. The code did
+   another. Nobody owned the diff.
+3. **You shipped a "client-side prototype"** that became the product, and
+   now you're trying to graft IndexedDB persistence, foreign keys, and
+   migrations onto something that was never designed for them.
+
+AllezORM is a small, sharp answer to all three.
+
+Open it, point it at a schema, and you have a real SQLite database
+running in the browser tab — persisted to IndexedDB on every write,
+queried with prepared statements, protected by inline foreign keys.
+The schema generator writes idiomatic, version-pinned files that your
+agents **cannot** silently drift away from. Because every file is
+anchored — by SHA-256 — back to the spec it came from.
+
+That's the whole pitch. The rest of this README shows you the receipts.
+
+---
+
+## What you get in 60 seconds
+
+```bash
+npm install allez-orm
+```
+
+```js
+// app.js
+import { AllezORM } from "allez-orm";
+import users from "./schemas/users.schema.js";
+import posts from "./schemas/posts.schema.js";
+
+const orm = await AllezORM.init({ dbName: "myapp.db", schemas: [users, posts] });
+
+// Real prepared statements. Real foreign keys. Real persistence.
+await orm.table("users").upsert({ id: 1, email: "a@b.co", display_name: "Ada" });
+await orm.table("posts").insert({ user_id: 1, title: "Hello world" });
+
+const recent = await orm.query(
+  "SELECT u.email, p.title FROM posts p JOIN users u ON u.id = p.user_id ORDER BY p.id DESC LIMIT 10"
+);
+```
+
+That's it. The database is alive in the tab. Refresh the page — it's still there.
+Open DevTools → Application → IndexedDB → `myapp.db`. The whole SQLite file is sitting there as a `Uint8Array`.
+
+No backend. No service worker. No build step. No "but does it work in Safari" anxiety.
+
+---
+
+## The five things that make it different
+
+### 1. **Spec-anchored schemas your agents can't silently break**
+
+Here's what a generated schema file looks like:
+
+```js
+// users.schema.js (generated by allez-orm)
+// DO NOT EDIT — regenerate by editing the spec, then running:
+//   allez-orm from-json ../spec.json
+// SPEC ../spec.json
+// SPEC_SHA256 0f1ab429adc01ddeaa093a4b18a87836547f437e1bc31f5d1babddf9935c47dc
+// TABLE_SHA256 531b42a728116ec1332467a5fb83b93f230afaf5ea75f4b4019ef2cf5d997adc
+const usersSchema = {
+  table: "users",
+  version: 1,
+  createSQL: `
+CREATE TABLE IF NOT EXISTS users (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  email TEXT UNIQUE NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  deleted_at TEXT
+);`
+};
+export default usersSchema;
+```
+
+Every generated file carries two cryptographic anchors back to the spec it came from.
+When an agent (or a junior dev, or future-you at 2am) opens this file, the very first
+thing they see is *"DO NOT EDIT — regenerate from the spec."*
+
+Don't trust the comment? Don't have to. Run drift detection:
+
+```bash
+$ allez-orm verify schemas.spec.json --dir=./schemas
+✔ verify: 4 table(s) match spec schemas.spec.json
+```
+
+Hand-edit a generated file:
+
+```bash
+$ allez-orm verify schemas.spec.json --dir=./schemas
+✗ Drift detected in 1 file(s):
+  - ./schemas/users.schema.js
+
+To resync, run:  allez-orm from-json schemas.spec.json --dir=./schemas -f
+```
+
+Wire that into CI. Wire it into your pre-commit hook. **Your agents do not get to
+quietly mutate your contract anymore.**
+
+You also get an `AGENTS.md` auto-emitted next to the schemas — picked up
+natively by Claude Code, Cursor, and every IDE that respects the convention —
+telling future agents exactly where the source of truth lives and how to
+regenerate.
+
+> This is the part Luca asked about. Now it ships.
+
+### 2. **A SQLite database in the browser, persisted, with FKs that actually enforce**
+
+This is not a Promise-flavored wrapper around `localStorage`. AllezORM runs
+**real SQLite via sql.js (WASM)** — the same engine in your phone, your browser, every
+plane in the air, and most cars sold this decade.
+
+- `PRAGMA foreign_keys = ON` — and stays on, even across saves. (We found and
+  fixed a subtle sql.js bug where `db.export()` resets connection PRAGMAs.
+  Now they don't.)
+- Prepared statements for every helper — no string concatenation, no
+  injection holes. SQL identifier validation rejects anything that
+  doesn't match `/^[A-Za-z_][A-Za-z0-9_]*$/`, and we test it against
+  the OWASP injection corpus.
+- Debounced auto-save to IndexedDB after every write. Configurable.
+- Versioned `onUpgrade(db, from, to)` hook per schema, so you can ship
+  v2 of your app and migrate users in-place.
+
+### 3. **A CLI that generates schemas the way you'd write them by hand**
+
+```bash
+# Ad-hoc — one table, fast:
+allez-orm create table users email:text!+ display_name:text! --stamps
+
+# Or declarative — the source-of-truth path:
+allez-orm from-json schemas.spec.json
+```
+
+Compact field syntax that fits in your head: `name:type` with flag suffixes
+(`!` = NOT NULL, `+` = UNIQUE, `->target` = inline foreign key, `--onDelete=`
+for every FK at once). One mental model. No DSL to memorize.
+
+Spec a referenced table that doesn't exist yet? The CLI auto-generates an
+ID-only stub for it so your DDL compiles immediately and you can fill it in later.
+
+### 4. **AllezORM Studio — a visual workbench for your in-browser DB**
+
+`npm run dev` opens [Studio](index.html): a clean, single-page workbench
+with searchable tables, sortable columns, a SQL scratchpad, and a
+**Create table** / **Add column** dialog that calls the CLI for you
+and live-reloads the ORM.
+
+It's the kind of tool you wish you had during the first week of a new
+project. Now you do.
+
+### 5. **Tested with the seriousness of a database**
+
+This repo currently ships with **67 automated tests across six suites**:
+
+| Suite | What it covers |
+|---|---|
+| [test-cli.mjs](tests/test-cli.mjs) | CLI smoke tests, force/overwrite, FK stubs |
+| [test-security.mjs](tests/test-security.mjs) | SQL identifier injection corpus, prepared-statement integration |
+| [test-spec-anchor.mjs](tests/test-spec-anchor.mjs) | Spec-anchor headers, AGENTS.md, drift detection |
+| [test-generator-thorough.mjs](tests/test-generator-thorough.mjs) | 21 edge-case generator scenarios, real sql.js compile-and-run, idempotency |
+| [test-fk-persistence.mjs](tests/test-fk-persistence.mjs) | Regression: FK pragma survives `db.export()` and repeated saves |
+| [test-e2e-studio.mjs](tests/test-e2e-studio.mjs) | Playwright E2E: full Studio flow including IndexedDB reload, FK violations |
+
+```bash
+npm test       # everything except the browser E2E
+npm run test:e2e  # browser E2E (requires playwright + chromium)
+npm run test:all  # both
+```
+
+---
+
+## Install
+
+```bash
+npm install allez-orm
+```
+
+You don't need a bundler. You don't need a framework. You don't need a server.
+The package is **pure ESM**, runs in browsers natively, and exposes a single
+default entry plus a CLI:
+
+- `import { AllezORM } from "allez-orm"` — the ORM
+- `npx allez-orm …` — the schema generator
+- `import "allez-orm/cli"` — programmatic CLI access
+
+WASM is loaded from [sql.js's CDN](https://sql.js.org) by default. Want to
+self-host the WASM? Pass `wasmLocateFile` to `AllezORM.init`.
+
+---
+
+## Quickstart: from zero to a real database in 5 commands
+
+```bash
+# 1. Init a project
+npm init -y && npm install allez-orm
+
+# 2. Generate a schema declaratively
+cat > schemas.spec.json <<'JSON'
+{
+  "outDir": "./schemas",
+  "defaultOnDelete": "cascade",
+  "tables": [
+    { "name": "users", "stamps": true,
+      "fields": [
+        { "name": "email", "type": "text", "unique": true, "notnull": true },
+        { "name": "display_name", "type": "text", "notnull": true }
+      ] },
+    { "name": "posts", "stamps": true,
+      "fields": [
+        { "name": "title", "type": "text", "notnull": true },
+        { "name": "user_id", "type": "integer", "fk": { "table": "users" } }
+      ] }
+  ]
+}
+JSON
+
+# 3. Generate the schema files (and AGENTS.md)
+npx allez-orm from-json schemas.spec.json
+
+# 4. Verify alignment any time you like
+npx allez-orm verify schemas.spec.json
+
+# 5. Use it from your app
+echo 'import { AllezORM } from "allez-orm";
+import users from "./schemas/users.schema.js";
+import posts from "./schemas/posts.schema.js";
+const orm = await AllezORM.init({ schemas: [users, posts] });
+await orm.table("users").upsert({ id: 1, email: "a@b.co", display_name: "Ada", created_at: new Date().toISOString(), updated_at: new Date().toISOString() });
+console.log(await orm.query("SELECT * FROM users"));
+' > app.mjs
+```
+
+You now have a typed, persistent, foreign-key-enforced database
+running in any modern browser, generated from a single source-of-truth file.
+
+---
+
+## The CLI
+
+```
+allez-orm create table <name> [fields...] [options]
+allez-orm from-json <config.json> [--dir=<outDir>] [-f|--force]
+allez-orm verify    <config.json> [--dir=<outDir>]
+allez-orm --print-json-schema
+```
+
+### Field syntax (CLI form)
+
+```
+col[:type][flags][->target]
+
+Examples:
+  email:text!+              email TEXT UNIQUE NOT NULL
+  user_id:integer->users    user_id INTEGER REFERENCES users(id)
+  parent_id:integer->nodes  self-referencing FK; no stub generated
+  body                      body TEXT  (type defaults to TEXT)
+```
+
+Flags: `!` = NOT NULL, `+` = UNIQUE.
+Type aliases (case-insensitive): `text|string`, `int|integer`, `real|float`, `numeric|number`, `blob`, `bool`.
+
+### Options
+
+| Flag | What it does |
+|---|---|
+| `--dir=<outDir>` | Output directory (defaults to `schemas_cli`, or `outDir` from spec) |
+| `--stamps` | Add `created_at` (NOT NULL), `updated_at` (NOT NULL), `deleted_at` (nullable) |
+| `--onDelete=<mode>` | Apply ON DELETE behavior to every FK: `cascade\|restrict\|setnull\|noaction` |
+| `-f, --force` | Overwrite existing files (also: `ALLEZ_FORCE=1`) |
+| `--help` | Show help |
+
+### `from-json` config shape
+
+Print the canonical JSON Schema:
+
+```bash
+npx allez-orm --print-json-schema
+```
+
+The config supports both **rich field objects** and **compact string tokens** in the same array — pick whichever fits the table:
+
+```json
+{
+  "tables": [
+    { "name": "items", "fields": ["sku:text!+", "qty:integer!"] },
+    { "name": "memberships", "fields": [
+      { "name": "user_id", "type": "integer", "fk": { "table": "users" } },
+      { "name": "org_id",  "type": "integer", "fk": { "table": "orgs"  } }
+    ]}
+  ]
+}
+```
+
+### `verify` — your CI safety net
+
+`verify` re-runs generation **in memory** and byte-compares against what's on disk.
+It exits non-zero on:
+
+- **Drift** — a generated file was hand-edited.
+- **Stale files** — the spec moved forward but files weren't regenerated.
+- **Missing files** — the spec references a table whose file isn't there.
+
+```yaml
+# .github/workflows/ci.yml
+- run: npx allez-orm verify schemas.spec.json
+```
+
+One line. No more 2am Slack messages about schema drift.
+
+---
+
+## The ORM API
+
+### Init
+
+```js
+const orm = await AllezORM.init({
+  dbName: "myapp.db",          // IndexedDB key; defaults to "allez.db"
+  autoSaveMs: 1500,            // debounce window for IndexedDB writes
+  wasmLocateFile: f => `/wasm/${f}`,  // self-host sql-wasm.wasm
+  schemas: [usersSchema, postsSchema]
+});
+```
+
+### Per-table helpers (parameterized, FK-aware)
+
+```js
+const users = orm.table("users");
+
+await users.insert({ email: "a@b.co", display_name: "Ada" });
+await users.upsert({ id: 1, email: "a@b.co", display_name: "Ada" });
+await users.update(1, { display_name: "Ada Lovelace" });
+await users.findById(1);                            // single row
+await users.searchLike("ada", ["display_name"]);    // LIKE %ada% across columns
+await users.deleteSoft(1);                          // sets deleted_at / deletedAt
+await users.remove(1);                              // hard delete
+```
+
+### Raw SQL — when you need it
+
+```js
+const rows = await orm.query("SELECT * FROM users WHERE id IN (?, ?)", [1, 2]);
+const one = await orm.get("SELECT * FROM users LIMIT 1");
+await orm.execute("UPDATE users SET display_name = ? WHERE id = ?", ["X", 1]);
+```
+
+### Schema versioning
+
+```js
+const usersSchema = {
+  table: "users",
+  version: 2,
+  createSQL: `CREATE TABLE IF NOT EXISTS users (...);`,
+  async onUpgrade(db, from, to) {
+    if (from < 2) db.exec(`ALTER TABLE users ADD COLUMN avatar_url TEXT`);
+  }
+};
+```
+
+### Manual save
+
+```js
+await orm.saveNow(); // force a write to IndexedDB right now
+```
+
+---
+
+## Security
+
+This package treats SQL identifiers as an attack surface. Every table and
+column name passed to the `table()` helpers goes through `safeIdent()`,
+which validates against a strict character class and rejects every
+payload in the OWASP injection corpus. You can audit the test for yourself
+at [tests/test-security.mjs](tests/test-security.mjs) (13 assertions).
+
+All values are bound via prepared statements. There is no string
+concatenation of user input into SQL anywhere in the runtime.
+
+If you find a security issue, please open a private advisory in the
+GitHub repo. We respond.
+
+---
+
+## What you avoid by using this
+
+This is the part that's hard to feel until you've been burned. So picture it:
+
+- **No "the IndexedDB schema is one thing, the SQL schema is another" debugging at midnight.** One file is the truth. One command verifies it.
+- **No agents quietly mutating your contract.** The header on every generated file is unmissable. The verify command is automatic.
+- **No `localStorage.setItem(JSON.stringify(...))`** sprawling across your codebase as you slowly reinvent indexes. The Studio is the indexed database you wanted on day one.
+- **No "we'll add a real backend later"** technical debt. You may discover you never need one. Plenty of apps don't.
+- **No surprise FK behavior.** We tested the pragma persistence so you don't have to.
+
+---
+
+## Roadmap & status
+
+AllezORM is **production-shape for client-only apps**: tests gate every
+release, the API surface is small and stable, and the schema generator's
+output format is now SHA-anchored (so we'll bump major if we ever change it).
+
+Coming soon:
+
+- WAL-style append journaling for crash-safe writes
+- Optional Web Worker mode for off-main-thread queries
+- An `allez-orm sync` command for two-way reconciliation with a remote SQL database (so the same schema works client-side and server-side)
+
+Want one of those sooner? Open an issue and say so.
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/AllezMarketing/allez-orm.git
+cd allez-orm
+npm install
+npm test           # unit + integration
+npx playwright install chromium
+npm run test:e2e   # browser E2E
+npm run dev        # launch Studio at http://localhost:5174
+```
+
+PRs that touch generator output **must** keep the existing schema files
+byte-stable (or bump version and update the SHA anchors deliberately).
+`npm test` will tell you immediately.
+
+---
+
+## License
+
+ISC © [Allez Marketing LLC](https://github.com/AllezMarketing)
+
+---
+
+## One last thing
+
+If you read this far, you already know what to do. The install is one
+command. The first table is one config. The verify is one CI line.
+
+The friction between you and a working database is **smaller than it has
+ever been.** Use the next ten minutes well.
+
+```bash
+npm install allez-orm
+```

package/allez-orm.mjs

@@ -282,6 +282,10 @@ export class AllezORM {
 
   async saveNow() {
     const data = this.db.export(); // Uint8Array
+    // sql.js's db.export() resets connection-scoped PRAGMAs (including
+    // foreign_keys) to 0. Re-enable FK enforcement so subsequent writes
+    // stay constraint-checked.
+    this.db.exec("PRAGMA foreign_keys = ON;");
     if (isBrowser) await idbSet(this.dbName, data);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allez-orm",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "AllezORM: lightweight browser SQLite ORM (sql.js) + schema generator CLI",
   "type": "module",
   "bin": {
@@ -34,8 +34,13 @@
     "test:cli": "node tests/test-cli.mjs",
     "ddl:audit": "node tools/ddl-audit.mjs",
     "test:security": "node tests/test-security.mjs",
-    "test": "node tests/test-cli.mjs && node tests/test-security.mjs && node tools/ddl-audit.mjs",
-    "prepublishOnly": "node tests/test-cli.mjs && node tests/test-security.mjs && node tools/ddl-audit.mjs"
+    "test:anchor": "node tests/test-spec-anchor.mjs",
+    "test:thorough": "node tests/test-generator-thorough.mjs",
+    "test:fk": "node tests/test-fk-persistence.mjs",
+    "test:e2e": "node tests/test-e2e-studio.mjs",
+    "test": "node tests/test-cli.mjs && node tests/test-security.mjs && node tests/test-spec-anchor.mjs && node tests/test-generator-thorough.mjs && node tests/test-fk-persistence.mjs && node tools/ddl-audit.mjs",
+    "test:all": "npm test && npm run test:e2e",
+    "prepublishOnly": "node tests/test-cli.mjs && node tests/test-security.mjs && node tests/test-spec-anchor.mjs && node tests/test-generator-thorough.mjs && node tests/test-fk-persistence.mjs && node tools/ddl-audit.mjs"
   },
   "files": [
     "allez-orm.mjs",
@@ -68,6 +73,7 @@
     "sql.js": "^1.13.0"
   },
   "devDependencies": {
+    "playwright": "^1.60.0",
     "serve": "^14.2.5"
   },
   "engines": {