@monlite/core 1.3.0 → 2.0.0

package/README.md

@@ -137,6 +137,17 @@ interface User {
 const users = db.collection<User>("users");
 ```
 
+When you type a collection, queries are **type-checked** (since 2.0): `where`/
+`orderBy` reject unknown fields, and `select` **narrows the return type** to the
+fields you ask for. Prefer schema-free? Use `db.collection("users")` (untyped) —
+it accepts any field, exactly as before.
+
+```ts
+const u = await users.findMany({ select: { name: true } });
+u[0].name; // string  ✅      u[0].age // ✗ not selected
+await users.findMany({ where: { naem: "x" } }); // ✗ 'naem' is not a field
+```
+
 Every stored document gains three system fields:
 
 | Field | Type | Notes |
@@ -317,6 +328,28 @@ await users.distinct("age", { role: "admin" });     // [28, 31]
 await users.distinct("tags");                        // ["a", "b", "c"]
 ```
 
+### Joins (`$lookup` / `$unwind`)
+
+Pull in related documents from another collection with a `lookup` on `findMany`
+— a left join, run as **two queries (no N+1)**, in either storage mode:
+
+```ts
+// Attach each user's orders as an array ($lookup):
+await db.collection("users").findMany({
+  lookup: { from: "orders", localField: "_id", foreignField: "user_id", as: "orders" },
+});
+// → [{ _id: "u1", name: "Ali", orders: [ {…}, {…} ] }, …]
+
+// Flatten to one row per match with `unwind` ($unwind); use "preserve" to keep
+// rows that have no match (left-outer):
+await db.collection("orders").findMany({
+  lookup: { from: "users", localField: "user_id", foreignField: "_id", as: "user", unwind: true },
+});
+// → [{ _id: "o1", user_id: "u1", user: { _id: "u1", name: "Ali" } }, …]
+```
+
+Pass an array of specs to join several collections at once.
+
 ---
 
 ## Live queries (reactivity)
@@ -597,6 +630,10 @@ These target **local / edge / desktop** runtimes — not a distributed cloud-sca
 Redis/Mongo/Qdrant replacement. For scale, keep the real services and
 [`@monlite/sync`](https://www.npmjs.com/package/@monlite/sync) to them.
 
+**Building an Electron app?** [`@monlite/electron`](https://www.npmjs.com/package/@monlite/electron)
+keeps the database in the main process and shares it with renderer windows over
+IPC, with cross-window reactivity.
+
 ---
 
 ## Drivers & zero dependencies
@@ -686,8 +723,28 @@ future-proofing.
 ## Examples
 
 Runnable demos live in [`examples/`](examples/): a notes app (CRUD + full-text
-search + live queries), AI-agent memory (vector + hybrid search), and local-first
-sync. `cd examples && npm install && node notes.mjs`.
+search + live queries), AI-agent memory (vector + hybrid search), local-first
+sync, the cache/queue/cron harness, `$lookup`/`$unwind` joins, and the WASM
+browser backend. `cd examples && npm install && node notes.mjs`.
+
+## Guides
+
+- [Schema & migrations](docs/guides/migrations.md) — auto-additive changes and
+  `$migrate()` for drop/rename/type-change.
+- [Custom adapters & drivers](docs/guides/custom-adapter.md) — add a sync backend
+  or a new SQLite binding/environment.
+- [Migrating to 2.0](docs/guides/v2-migration.md) — the typed-query / select
+  changes (types only; runtime unchanged).
+
+## Studio (inspector)
+
+Browse a database in your browser — collections, documents, filter queries:
+
+```bash
+npx @monlite/studio app.db
+```
+
+See [`@monlite/studio`](https://www.npmjs.com/package/@monlite/studio).
 
 ## Benchmarks
 
@@ -697,6 +754,12 @@ ops/sec, roughly 2× the raw-driver overhead for the full document API, and it
 **stays flat on indexed reads where JSON-file stores degrade** (lowdb point reads
 are ~15× slower at 10k docs).
 
+## On-disk format (cross-language)
+
+A monlite database is **just a SQLite file** with documented conventions, so any
+language with a SQLite library can read/write it — no port required. The contract
+is in [`docs/FORMAT.md`](docs/FORMAT.md).
+
 ---
 
 ## License

package/dist/index.cjs

@@ -1153,7 +1153,59 @@ var Collection = class {
     return this.db.prepare(`SELECT 1 FROM "${this.name}" WHERE ${clause} LIMIT 1`).get(...params) != null;
   }
   async findMany(args = {}) {
-    return this.findManyCore(args);
+    const a = args;
+    if (!a.lookup) {
+      return this.findManyCore(a);
+    }
+    const specs = Array.isArray(a.lookup) ? a.lookup : [a.lookup];
+    let rows = this.findManyCore({
+      ...a,
+      select: void 0,
+      lookup: void 0
+    });
+    for (const spec of specs) rows = await this.applyLookup(rows, spec);
+    if (a.select) {
+      rows = rows.map((r) => {
+        const projected = project(r, a.select);
+        for (const spec of specs) projected[spec.as] = r[spec.as];
+        return projected;
+      });
+    }
+    return rows;
+  }
+  /** Resolve one `$lookup` spec against already-fetched rows (2 queries, no N+1). */
+  async applyLookup(rows, spec) {
+    const localValues = [
+      ...new Set(
+        rows.map((r) => r[spec.localField]).filter((v) => v !== void 0 && v !== null)
+      )
+    ];
+    const foreign = localValues.length ? await this.mon.collection(spec.from).findMany({
+      where: { [spec.foreignField]: { in: localValues } }
+    }) : [];
+    const byKey = /* @__PURE__ */ new Map();
+    for (const f of foreign) {
+      const key = f[spec.foreignField];
+      const list = byKey.get(key);
+      if (list) list.push(f);
+      else byKey.set(key, [f]);
+    }
+    if (spec.unwind) {
+      const out = [];
+      for (const r of rows) {
+        const matches = byKey.get(r[spec.localField]) ?? [];
+        if (matches.length === 0) {
+          if (spec.unwind === "preserve") out.push({ ...r, [spec.as]: null });
+        } else {
+          for (const m of matches) out.push({ ...r, [spec.as]: m });
+        }
+      }
+      return out;
+    }
+    return rows.map((r) => ({
+      ...r,
+      [spec.as]: byKey.get(r[spec.localField]) ?? []
+    }));
   }
   async findFirst(args = {}) {
     const rows = await this.findMany({ ...args, take: 1 });