@monlite/core 0.3.0 → 0.6.0

package/README.md

@@ -1,12 +1,7 @@
 # 🌙 monlite
 
-> An embedded document database for TypeScript apps.
-> MongoDB-like API. Prisma-like DX. SQLite under the hood. Zero config.
-
-monlite is a local-first document database that lives inside your app as a
-single `.db` file. No server to run, no schema to define, no migrations to
-manage. You get the flexibility of MongoDB, the familiarity of a Prisma-style
-API, and the reliability of SQLite — all in one `npm install`.
+> Your app's local database. A MongoDB-like API and Prisma-style DX in a single
+> file. Zero config, zero migrations, zero server.
 
 ```ts
 import { createDb } from "@monlite/core";
@@ -18,7 +13,36 @@ await users.create({ data: { name: "Ali", age: 28 } });
 await users.findMany({ where: { age: { gte: 18 } } });
 ```
 
-That's it. No setup. No config. Your data is in `app.db`.
+That's the whole setup. Your data is in `app.db`.
+
+---
+
+## Mental model (read this first)
+
+monlite is **one database with one query API.** You never have to choose "SQL or
+NoSQL." You only choose, per collection, **where each field is stored:**
+
+- **Document mode** (default) — the whole document is stored as JSON. Flexible
+  and schema-free, like MongoDB.
+- **Structured mode** (`db.collection(name, { schema })`) — the fields you
+  declare become real SQL columns (typed, indexed, joinable). Anything else
+  overflows into JSON automatically.
+
+> **A schema changes the _storage_, never the _syntax_.**
+> `create`, `find`, `where`, `orderBy`, `groupBy` are identical in both modes and
+> return identical results — structured mode is just faster and SQL-native underneath.
+
+Raw SQL is the one optional place SQL becomes visible: the `$queryRaw` escape
+hatch, for joins/CTEs/window functions the document API doesn't cover.
+
+| You decide… | Document (default) | Structured (`{ schema }`) |
+| --- | --- | --- |
+| **How you query** | `find` / `where` / `orderBy` / `groupBy` | **identical** |
+| **Where a field lives** | JSON `data` blob | a native column (declared) — the rest overflow to JSON |
+| **Pick it when** | the shape is unknown or varies per record | the shape is stable and you want joins, FKs, reporting, or fast native indexes |
+
+You can mix both in the same `.db`, and move a collection from document to
+structured later without changing a single query.
 
 ---
 
@@ -57,6 +81,20 @@ If your data is structured and you already know your schema, plain SQLite adds
 nothing on top of monlite — use it directly. monlite earns its keep when your
 documents are dynamic, schema-free, or mirror a cloud NoSQL store.
 
+### How monlite compares
+
+| | monlite | MongoDB | better-sqlite3 | Prisma + SQLite |
+|---|---|---|---|---|
+| Schema-free documents | ✅ | ✅ | ⚠️ manual JSON | ❌ |
+| Native typed columns | ✅ (opt-in) | ❌ | ✅ | ✅ |
+| Same API for both | ✅ | — | — | — |
+| Raw SQL escape hatch | ✅ | ❌ | ✅ | ✅ (`$queryRaw`) |
+| No server / single file | ✅ | ❌ | ✅ | ✅ |
+| No migrations / codegen | ✅ | ✅ | ✅ | ❌ |
+| Aggregation API | ✅ | ✅ | ⚠️ manual | ⚠️ limited |
+| Local-first sync | ✅ (`@monlite/sync`) | ⚠️ Atlas/Realm | ❌ | ❌ |
+| Runtime dependencies | **0** (Node 22.5+) | server | 1 (native) | several |
+
 ---
 
 ## Setup
@@ -124,6 +162,9 @@ await users.createMany({ data: [{ name: "Sara" }, { name: "Omar" }] });
 // read
 await users.findById("…");                                  // doc | null
 await users.findFirst({ where: { name: "Ali" } });          // doc | null
+await users.findUnique({ where: { email: "a@x.com" } });    // alias of findFirst
+await users.findFirstOrThrow({ where: { name: "Ali" } });   // throws if missing
+await users.exists({ role: "admin" });                      // boolean
 await users.findMany({
   where: { age: { gte: 18 } },
   orderBy: { age: "desc" },
@@ -167,10 +208,11 @@ where: { age: { gt: 18 } }               // gt, gte, lt, lte
 where: { role: { in: ["admin", "editor"] } }
 where: { role: { notIn: ["guest"] } }
 
-// String (case-sensitive; wildcards are matched literally)
+// String (case-sensitive by default; wildcards are matched literally)
 where: { name: { contains: "li" } }
 where: { name: { startsWith: "A" } }
 where: { name: { endsWith: "i" } }
+where: { name: { contains: "ALI", mode: "insensitive" } }  // case-insensitive (ASCII)
 
 // Arrays
 where: { tags: { contains: "admin" } }   // element membership
@@ -277,6 +319,108 @@ await users.distinct("tags");                        // ["a", "b", "c"]
 
 ---
 
+## Structured collections (native SQL columns)
+
+By default a collection is **document mode** — schema-free, every field stored
+as JSON. Pass a `schema` to make it a **structured collection**: the declared
+fields become real, typed SQL columns (fast, indexable, joinable, constrainable)
+and any *other* fields overflow into a JSON column. **The CRUD/query API is
+identical** — `find`, `where`, `orderBy`, `groupBy`, `distinct`, updates. As the
+[mental model](#mental-model-read-this-first) says: a schema changes the storage,
+not the syntax.
+
+```ts
+const orders = db.collection("orders", {
+  schema: {
+    user_id: { type: "TEXT", index: true, references: "users(_id)" },
+    amount: "REAL",
+    status: { type: "TEXT", notNull: true, default: "pending" },
+    meta: "JSON",            // objects/arrays, transparently (de)serialized
+  },
+});
+
+// Same API as document collections — but `amount`/`status` are real columns:
+await orders.create({ data: { user_id: "u1", amount: 100, status: "paid", note: "rush" } });
+await orders.findMany({ where: { amount: { gte: 50 }, status: "paid" } });
+await orders.groupBy({ by: ["status"], _sum: { amount: true } });
+
+// Undeclared fields (like `note`) still work — they overflow into JSON.
+await orders.findMany({ where: { note: { contains: "rush" } } });
+```
+
+Because the columns are native, they join, constrain, and index like any SQL
+table — including from the raw SQL hatch with no `json_extract`:
+
+```ts
+await db.$queryRaw`
+  SELECT u.name, SUM(o.amount) AS revenue
+  FROM users u JOIN orders o ON o.user_id = u._id
+  GROUP BY u._id
+`;
+```
+
+Column types: `"TEXT" | "INTEGER" | "REAL" | "BLOB" | "JSON"`. A full column
+definition supports `index`, `unique`, `notNull`, `default`, and `references`.
+
+### Do I have to care: JSON vs native columns?
+
+- **For correctness — no.** Both modes return identical results through the same API.
+- **For performance & SQL interop — a little.** Native columns + native indexes are
+  faster and join/constrain cleanly; JSON is for when the shape is unknown or varies.
+
+monlite never hides which is which:
+
+```ts
+orders.mode;             // "structured" | "document"
+await db.$schema("orders"); // physical columns: [{ name, type, notNull, primaryKey }, …]
+createDb("./app.db", { verbose: (sql) => console.log(sql) }); // see json_extract vs bare columns
+```
+
+> **Rule of thumb:** unknown/flexible shape → document (JSON); known/stable shape
+> with heavy joins, reporting, or external SQL tooling → structured (native columns).
+
+> Note: structured collections are not yet covered by `@monlite/sync` (document
+> collections are) — that's planned follow-up work.
+
+---
+
+## Sync & local-first
+
+The companion package [`@monlite/sync`](https://www.npmjs.com/package/@monlite/sync)
+replicates a local monlite database with a remote source of truth — MongoDB
+first — so apps can work offline and converge when reconnected.
+
+Opt in with `{ sync: true }` (adds a change feed + tombstones + versioning; zero
+overhead when off), then drive an engine:
+
+```ts
+import { createDb } from "@monlite/core";
+import { sync, MongoAdapter } from "@monlite/sync";
+import { MongoClient } from "mongodb";
+
+const db = createDb("./app.db", { sync: true });
+const mongo = new MongoClient(uri);
+await mongo.connect();
+
+const engine = sync(db, {
+  adapter: new MongoAdapter({ client: mongo, db: "app" }),
+  collections: "*",
+  mode: "two-way",   // "pull" | "push" | "two-way"
+  conflict: "lww",   // or a custom resolver
+  interval: 5000,
+});
+
+await engine.start();
+```
+
+Pull / push / two-way replication, last-write-wins (or custom) conflict
+resolution, and pluggable adapters (`MongoAdapter`, `MonliteAdapter` for
+monlite-to-monlite, `MemoryAdapter` for tests). monlite's ObjectId-compatible
+`_id`s map 1:1 to Mongo `_id`s. See the
+[`@monlite/sync` README](https://www.npmjs.com/package/@monlite/sync) for details.
+
+---
+
 ## SQL escape hatch
 
 When you need full SQL power — complex joins, analytics, cross-collection