@monlite/core 1.2.0 → 1.4.0

package/README.md

@@ -317,6 +317,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)
@@ -459,9 +481,10 @@ 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
+resolution, and pluggable adapters (`MongoAdapter`, `PostgresAdapter`,
+`MySqlAdapter`, `MonliteAdapter` for monlite-to-monlite, `MemoryAdapter` for
+tests) — keep local monlite as the embedded runtime and a server DB as the cloud
+of record. See the
 [`@monlite/sync` README](https://www.npmjs.com/package/@monlite/sync) for details.
 
 ---
@@ -600,13 +623,14 @@ Redis/Mongo/Qdrant replacement. For scale, keep the real services and
 
 ## Drivers & zero dependencies
 
-monlite talks to SQLite through a tiny driver adapter, so it runs on two
+monlite talks to SQLite through a tiny driver adapter, so it runs on
 interchangeable backends:
 
 | Backend | When it's used | Notes |
 |---|---|---|
 | **`node:sqlite`** | Built into Node **22.5+** | **Zero dependencies.** Still flagged experimental by Node, so it prints a one-time `ExperimentalWarning`. |
 | **`better-sqlite3`** | When the package is installed | Battle-tested native driver. Works on Node 18/20/22, no warning. Install it yourself: `npm i better-sqlite3`. |
+| **WASM (browser)** | Via [`@monlite/wasm`](https://www.npmjs.com/package/@monlite/wasm) | Runs monlite **in the browser** on SQLite-WASM (sql.js); pass `driver: wasmDriver(SQL)`. Snapshot persistence to IndexedDB/OPFS. |
 
 By default (`driver: "auto"`) monlite uses `better-sqlite3` if it's installed,
 otherwise falls back to the built-in `node:sqlite`. Force one explicitly:

package/dist/index.cjs

@@ -1153,7 +1153,56 @@ 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);
+    if (!args.lookup) return this.findManyCore(args);
+    const specs = Array.isArray(args.lookup) ? args.lookup : [args.lookup];
+    let rows = this.findManyCore({
+      ...args,
+      select: void 0,
+      lookup: void 0
+    });
+    for (const spec of specs) rows = await this.applyLookup(rows, spec);
+    if (args.select) {
+      rows = rows.map((r) => {
+        const projected = project(r, args.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 });
@@ -1615,7 +1664,11 @@ function loadNodeSqlite() {
     return null;
   }
 }
+function isDriverInstance(d) {
+  return typeof d === "object" && d !== null && typeof d.prepare === "function" && typeof d.exec === "function";
+}
 function createDriver(filename, options = {}) {
+  if (isDriverInstance(options.driver)) return options.driver;
   const choice = options.driver ?? "auto";
   if (options.encryption) {
     if (choice === "node:sqlite") {