@monlite/core 1.3.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)

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 });