@zodmon/core 0.10.0 → 0.12.0

package/dist/index.js

@@ -11,30 +11,24 @@ var $avg = (field) => ({
   __accum: true,
   expr: { $avg: field }
 });
-var $min = (field) => ({
-  __accum: true,
-  expr: { $min: field }
-});
-var $max = (field) => ({
-  __accum: true,
-  expr: { $max: field }
-});
-var $first = (field) => ({
-  __accum: true,
-  expr: { $first: field }
-});
-var $last = (field) => ({
-  __accum: true,
-  expr: { $last: field }
-});
-var $push = (field) => ({
-  __accum: true,
-  expr: { $push: field }
-});
-var $addToSet = (field) => ({
-  __accum: true,
-  expr: { $addToSet: field }
-});
+function $min(field) {
+  return { __accum: true, expr: { $min: field } };
+}
+function $max(field) {
+  return { __accum: true, expr: { $max: field } };
+}
+function $first(field) {
+  return { __accum: true, expr: { $first: field } };
+}
+function $last(field) {
+  return { __accum: true, expr: { $last: field } };
+}
+function $push(field) {
+  return { __accum: true, expr: { $push: field } };
+}
+function $addToSet(field) {
+  return { __accum: true, expr: { $addToSet: field } };
+}
 function createAccumulatorBuilder() {
   return {
     count: () => ({ __accum: true, expr: { $sum: 1 } }),
@@ -52,50 +46,84 @@ function createAccumulatorBuilder() {
     // biome-ignore lint/suspicious/noExplicitAny: Runtime implementation uses string field names and returns plain objects — TypeScript cannot verify that the runtime Accumulator objects match the generic AccumulatorBuilder<T> return types. Safe because type resolution happens at compile time via AccumulatorBuilder<T>, and runtime values are identical to what the standalone $min/$max/etc. produce.
   };
 }
+var isExpr = (v) => typeof v === "object" && v !== null && v.__expr === true;
 function createExpressionBuilder() {
-  const $2 = (field) => `$${field}`;
-  const val = (v) => typeof v === "number" ? v : `$${v}`;
+  const resolveArg = (arg) => {
+    if (typeof arg === "number") return arg;
+    if (isExpr(arg)) return arg.value;
+    return `$${arg}`;
+  };
+  const resolveExprVal = (v) => isExpr(v) ? v.value : v;
   const expr = (value) => ({ __expr: true, value });
   return {
     // Arithmetic
-    add: (field, value) => expr({ $add: [$2(field), val(value)] }),
-    subtract: (field, value) => expr({ $subtract: [$2(field), val(value)] }),
-    multiply: (field, value) => expr({ $multiply: [$2(field), val(value)] }),
-    divide: (field, value) => expr({ $divide: [$2(field), val(value)] }),
-    mod: (field, value) => expr({ $mod: [$2(field), val(value)] }),
-    abs: (field) => expr({ $abs: $2(field) }),
-    ceil: (field) => expr({ $ceil: $2(field) }),
-    floor: (field) => expr({ $floor: $2(field) }),
-    round: (field, place = 0) => expr({ $round: [$2(field), place] }),
+    add: (a, b) => expr({ $add: [resolveArg(a), resolveArg(b)] }),
+    subtract: (a, b) => expr({ $subtract: [resolveArg(a), resolveArg(b)] }),
+    multiply: (a, b) => expr({ $multiply: [resolveArg(a), resolveArg(b)] }),
+    divide: (a, b) => expr({ $divide: [resolveArg(a), resolveArg(b)] }),
+    mod: (a, b) => expr({ $mod: [resolveArg(a), resolveArg(b)] }),
+    abs: (field) => expr({ $abs: resolveArg(field) }),
+    ceil: (field) => expr({ $ceil: resolveArg(field) }),
+    floor: (field) => expr({ $floor: resolveArg(field) }),
+    round: (field, place = 0) => expr({ $round: [resolveArg(field), place] }),
     // String
     concat: (...parts) => {
       const resolved = parts.map((p) => {
-        if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(p)) return $2(p);
+        if (isExpr(p)) return p.value;
+        if (/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(p)) return `$${p}`;
         return p;
       });
       return expr({ $concat: resolved });
     },
-    toLower: (field) => expr({ $toLower: $2(field) }),
-    toUpper: (field) => expr({ $toUpper: $2(field) }),
-    trim: (field) => expr({ $trim: { input: $2(field) } }),
-    substr: (field, start, length) => expr({ $substrBytes: [$2(field), start, length] }),
-    // Comparison
-    eq: (field, value) => expr({ $eq: [$2(field), value] }),
-    gt: (field, value) => expr({ $gt: [$2(field), value] }),
-    gte: (field, value) => expr({ $gte: [$2(field), value] }),
-    lt: (field, value) => expr({ $lt: [$2(field), value] }),
-    lte: (field, value) => expr({ $lte: [$2(field), value] }),
-    ne: (field, value) => expr({ $ne: [$2(field), value] }),
+    toLower: (field) => expr({ $toLower: resolveArg(field) }),
+    toUpper: (field) => expr({ $toUpper: resolveArg(field) }),
+    trim: (field) => expr({ $trim: { input: resolveArg(field) } }),
+    substr: (field, start, length) => expr({ $substrBytes: [resolveArg(field), start, length] }),
+    // Comparison — single runtime implementation handles both overloads:
+    // field path  → resolveArg('name')       → '$name'
+    // expression  → resolveArg(expr.sub(...)) → { $subtract: [...] }
+    eq: (field, value) => expr({ $eq: [resolveArg(field), resolveExprVal(value)] }),
+    gt: (field, value) => expr({ $gt: [resolveArg(field), resolveExprVal(value)] }),
+    gte: (field, value) => expr({ $gte: [resolveArg(field), resolveExprVal(value)] }),
+    lt: (field, value) => expr({ $lt: [resolveArg(field), resolveExprVal(value)] }),
+    lte: (field, value) => expr({ $lte: [resolveArg(field), resolveExprVal(value)] }),
+    ne: (field, value) => expr({ $ne: [resolveArg(field), resolveExprVal(value)] }),
     // Date
-    year: (field) => expr({ $year: $2(field) }),
-    month: (field) => expr({ $month: $2(field) }),
-    dayOfMonth: (field) => expr({ $dayOfMonth: $2(field) }),
+    year: (field) => expr({ $year: resolveArg(field) }),
+    month: (field) => expr({ $month: resolveArg(field) }),
+    dayOfMonth: (field) => expr({ $dayOfMonth: resolveArg(field) }),
     // Array
-    size: (field) => expr({ $size: $2(field) }),
+    size: (field) => expr({ $size: resolveArg(field) }),
     // Conditional
-    cond: (condition, thenValue, elseValue) => expr({ $cond: [condition.value, thenValue, elseValue] }),
-    ifNull: (field, fallback) => expr({ $ifNull: [$2(field), fallback] })
-    // biome-ignore lint/suspicious/noExplicitAny: Runtime implementation uses string field names — TypeScript cannot verify generic ExpressionBuilder<T> return types match. Safe because type resolution happens at compile time.
+    cond: (condition, thenValue, elseValue) => expr({
+      $cond: [condition.value, resolveExprVal(thenValue), resolveExprVal(elseValue)]
+    }),
+    ifNull: (field, fallback) => expr({ $ifNull: [resolveArg(field), fallback] }),
+    // Date (extended)
+    dayOfWeek: (field) => expr({ $dayOfWeek: resolveArg(field) }),
+    dateToString: (field, format) => expr({ $dateToString: { format, date: resolveArg(field) } }),
+    // $$NOW is a MongoDB system variable string — not a Document, but valid anywhere
+    // an aggregation expression is expected. Cast is safe; the MongoDB driver accepts it.
+    now: () => ({ __expr: true, value: "$$NOW" }),
+    // String conversion
+    toString: (field) => expr({ $toString: resolveArg(field) }),
+    // Array (extended)
+    inArray: (value, array) => expr({ $in: [resolveArg(value), Array.isArray(array) ? array : resolveArg(array)] }),
+    arrayElemAt: (field, index2) => expr({ $arrayElemAt: [resolveArg(field), index2] }),
+    // Conditional (extended)
+    switch: (branches, fallback) => expr({
+      $switch: {
+        branches: branches.map((b) => ({
+          case: b.case.value,
+          // biome-ignore lint/suspicious/noThenProperty: MongoDB $switch branch object requires a `then` key
+          then: resolveExprVal(b.then)
+        })),
+        default: resolveExprVal(fallback)
+      }
+    }),
+    // Field reference
+    field: (name) => ({ __expr: true, value: `$${name}` })
+    // biome-ignore lint/suspicious/noExplicitAny: Runtime implementation uses resolveArg/resolveExprVal — TypeScript cannot verify generic ExpressionBuilder<T> return types match. Safe because type resolution happens at compile time via ExpressionBuilder<T>.
   };
 }
 
@@ -110,9 +138,9 @@ var ZodmonError = class extends Error {
   /** The underlying error that caused this error, if any. */
   cause;
   constructor(message, collection2, options) {
-    super(message);
+    super(message, options?.cause !== void 0 ? { cause: options.cause } : void 0);
     this.collection = collection2;
-    if (options?.cause) {
+    if (options?.cause !== void 0) {
       this.cause = options.cause;
     }
   }
@@ -371,10 +399,12 @@ var AggregatePipeline = class _AggregatePipeline {
   definition;
   nativeCollection;
   stages;
-  constructor(definition, nativeCollection, stages) {
+  session;
+  constructor(definition, nativeCollection, stages, session) {
     this.definition = definition;
     this.nativeCollection = nativeCollection;
     this.stages = stages;
+    this.session = session;
   }
   /**
    * Append an arbitrary aggregation stage to the pipeline (escape hatch).
@@ -405,10 +435,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   raw(stage) {
-    return new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      stage
-    ]);
+    return new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, stage],
+      this.session
+    );
   }
   /**
    * Execute the pipeline and return all results as an array.
@@ -424,7 +456,10 @@ var AggregatePipeline = class _AggregatePipeline {
    */
   async toArray() {
     try {
-      const cursor = this.nativeCollection.aggregate(this.stages);
+      const cursor = this.nativeCollection.aggregate(
+        this.stages,
+        this.session ? { session: this.session } : {}
+      );
       return await cursor.toArray();
     } catch (err) {
       wrapMongoError(err, this.definition.name);
@@ -444,7 +479,10 @@ var AggregatePipeline = class _AggregatePipeline {
    */
   async *[Symbol.asyncIterator]() {
     try {
-      const cursor = this.nativeCollection.aggregate(this.stages);
+      const cursor = this.nativeCollection.aggregate(
+        this.stages,
+        this.session ? { session: this.session } : {}
+      );
       for await (const doc of cursor) {
         yield doc;
       }
@@ -470,7 +508,10 @@ var AggregatePipeline = class _AggregatePipeline {
    */
   async explain() {
     try {
-      const cursor = this.nativeCollection.aggregate(this.stages);
+      const cursor = this.nativeCollection.aggregate(
+        this.stages,
+        this.session ? { session: this.session } : {}
+      );
       return await cursor.explain();
     } catch (err) {
       wrapMongoError(err, this.definition.name);
@@ -520,12 +561,30 @@ var AggregatePipeline = class _AggregatePipeline {
    *   .toArray()
    * // subset[0].role → 'engineer' | 'designer'
    * ```
+   *
+   * @example
+   * ```ts
+   * // Field-vs-field comparison via $expr callback
+   * const overRefunded = await orders.aggregate()
+   *   .match(
+   *     { status: 'completed' },
+   *     (expr) => expr.gt('totalAmount', expr.field('refundedAmount')),
+   *   )
+   *   .toArray()
+   * ```
    */
-  match(filter) {
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $match: filter }
-    ]);
+  match(filter, exprCb) {
+    const stage = { ...filter };
+    if (exprCb) {
+      const built = exprCb(createExpressionBuilder());
+      stage["$expr"] = built.value;
+    }
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $match: stage }],
+      this.session
+    );
     return pipeline;
   }
   /**
@@ -545,10 +604,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   sort(spec) {
-    return new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $sort: spec }
-    ]);
+    return new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $sort: spec }],
+      this.session
+    );
   }
   /**
    * Skip a number of documents in the pipeline.
@@ -569,10 +630,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   skip(n) {
-    return new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $skip: n }
-    ]);
+    return new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $skip: n }],
+      this.session
+    );
   }
   /**
    * Limit the number of documents passing through the pipeline.
@@ -592,10 +655,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   limit(n) {
-    return new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $limit: n }
-    ]);
+    return new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $limit: n }],
+      this.session
+    );
   }
   // ── Shape-transforming projection stages ─────────────────────────
   /**
@@ -617,10 +682,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   project(spec) {
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $project: spec }
-    ]);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $project: spec }],
+      this.session
+    );
     return pipeline;
   }
   /**
@@ -641,10 +708,12 @@ var AggregatePipeline = class _AggregatePipeline {
    */
   pick(...fields) {
     const spec = Object.fromEntries(fields.map((f) => [f, 1]));
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $project: spec }
-    ]);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $project: spec }],
+      this.session
+    );
     return pipeline;
   }
   /**
@@ -665,22 +734,41 @@ var AggregatePipeline = class _AggregatePipeline {
    */
   omit(...fields) {
     const spec = Object.fromEntries(fields.map((f) => [f, 0]));
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $project: spec }
-    ]);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $project: spec }],
+      this.session
+    );
     return pipeline;
   }
   groupBy(field, accumulators) {
     const resolved = typeof accumulators === "function" ? accumulators(createAccumulatorBuilder()) : accumulators;
-    const _id = Array.isArray(field) ? Object.fromEntries(field.map((f) => [f, `$${f}`])) : `$${field}`;
+    let _id;
+    if (field === null) {
+      _id = null;
+    } else if (Array.isArray(field)) {
+      const entries = field.map((f) => [f.replaceAll(".", "_"), `$${f}`]);
+      const keys = entries.map(([k]) => k);
+      const dupes = keys.filter((k, i) => keys.indexOf(k) !== i);
+      if (dupes.length > 0) {
+        throw new Error(
+          `Compound groupBy key collision: ${dupes.join(", ")}. Two or more fields produce the same _id key after dot-to-underscore conversion. Use raw() with explicit aliases instead.`
+        );
+      }
+      _id = Object.fromEntries(entries);
+    } else {
+      _id = `$${field}`;
+    }
     const accumExprs = Object.fromEntries(
       Object.entries(resolved).map(([key, acc]) => [key, acc.expr])
     );
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $group: { _id, ...accumExprs } }
-    ]);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $group: { _id, ...accumExprs } }],
+      this.session
+    );
     return pipeline;
   }
   // Implementation
@@ -692,10 +780,12 @@ var AggregatePipeline = class _AggregatePipeline {
         v && typeof v === "object" && "__expr" in v ? v.value : v
       ])
     );
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $addFields: stage }
-    ]);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $addFields: stage }],
+      this.session
+    );
     return pipeline;
   }
   // ── unwind stage ─────────────────────────────────────────────────
@@ -721,10 +811,12 @@ var AggregatePipeline = class _AggregatePipeline {
    */
   unwind(field, options) {
     const stage = options?.preserveEmpty ? { $unwind: { path: `$${field}`, preserveNullAndEmptyArrays: true } } : { $unwind: `$${field}` };
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      stage
-    ]);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, stage],
+      this.session
+    );
     return pipeline;
   }
   lookup(fieldOrFrom, options) {
@@ -772,7 +864,63 @@ var AggregatePipeline = class _AggregatePipeline {
         stages.push({ $unwind: { path: `$${asField}`, preserveNullAndEmptyArrays: true } });
       }
     }
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, stages);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      stages,
+      this.session
+    );
+    return pipeline;
+  }
+  // ── facet stage ──────────────────────────────────────────────────
+  /**
+   * Run multiple sub-pipelines on the same input documents in parallel.
+   *
+   * Each key in `spec` maps to a callback that receives a fresh `SubPipeline`
+   * starting from `TOutput`. The callback chains stages and returns the terminal
+   * pipeline. Zodmon extracts the accumulated stages at runtime to build the
+   * `$facet` document. The output type is fully inferred — no annotation needed.
+   *
+   * Sub-pipelines support all stage methods including `.raw()` for operators not
+   * yet first-class. Execution methods (`toArray`, `explain`) are not available
+   * inside branches.
+   *
+   * @param spec - An object mapping branch names to sub-pipeline builder callbacks.
+   * @returns A new pipeline whose output is one document with each branch name mapped to an array of results.
+   *
+   * @example
+   * ```ts
+   * const [report] = await aggregate(orders)
+   *   .facet({
+   *     byCategory: (sub) => sub
+   *       .groupBy('category', acc => ({ count: acc.count() }))
+   *       .sort({ count: -1 }),
+   *     totals: (sub) => sub
+   *       .groupBy(null, acc => ({ grandTotal: acc.sum('amount') })),
+   *   })
+   *   .toArray()
+   * // report.byCategory → { _id: 'electronics' | 'books' | 'clothing'; count: number }[]
+   * // report.totals     → { _id: null; grandTotal: number }[]
+   * ```
+   */
+  facet(spec) {
+    const branches = {};
+    for (const [key, cb] of Object.entries(spec)) {
+      const sub = new _AggregatePipeline(
+        this.definition,
+        this.nativeCollection,
+        [],
+        this.session
+        // biome-ignore lint/suspicious/noExplicitAny: sub must be cast to `any` so the concrete `AggregatePipeline<TDef, TOutput>` is accepted where `SubPipeline<TDef, TOutput>` (which lacks execution methods) is expected — safe at runtime because the pipeline instance always has the right shape
+      );
+      branches[key] = cb(sub).getStages();
+    }
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $facet: branches }],
+      this.session
+    );
     return pipeline;
   }
   // ── Convenience shortcuts ────────────────────────────────────────
@@ -793,11 +941,16 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   countBy(field) {
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $group: { _id: `$${field}`, count: { $sum: 1 } } },
-      { $sort: { count: -1 } }
-    ]);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [
+        ...this.stages,
+        { $group: { _id: `$${field}`, count: { $sum: 1 } } },
+        { $sort: { count: -1 } }
+      ],
+      this.session
+    );
     return pipeline;
   }
   /**
@@ -818,11 +971,16 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   sumBy(field, sumField) {
-    const pipeline = new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $group: { _id: `$${field}`, total: { $sum: `$${sumField}` } } },
-      { $sort: { total: -1 } }
-    ]);
+    const pipeline = new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [
+        ...this.stages,
+        { $group: { _id: `$${field}`, total: { $sum: `$${sumField}` } } },
+        { $sort: { total: -1 } }
+      ],
+      this.session
+    );
     return pipeline;
   }
   /**
@@ -842,10 +1000,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   sortBy(field, direction = "asc") {
-    return new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $sort: { [field]: direction === "desc" ? -1 : 1 } }
-    ]);
+    return new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $sort: { [field]: direction === "desc" ? -1 : 1 } }],
+      this.session
+    );
   }
   /**
    * Return the top N documents sorted by a field descending.
@@ -864,11 +1024,12 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   top(n, options) {
-    return new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $sort: { [options.by]: -1 } },
-      { $limit: n }
-    ]);
+    return new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $sort: { [options.by]: -1 } }, { $limit: n }],
+      this.session
+    );
   }
   /**
    * Return the bottom N documents sorted by a field ascending.
@@ -887,15 +1048,25 @@ var AggregatePipeline = class _AggregatePipeline {
    * ```
    */
   bottom(n, options) {
-    return new _AggregatePipeline(this.definition, this.nativeCollection, [
-      ...this.stages,
-      { $sort: { [options.by]: 1 } },
-      { $limit: n }
-    ]);
+    return new _AggregatePipeline(
+      this.definition,
+      this.nativeCollection,
+      [...this.stages, { $sort: { [options.by]: 1 } }, { $limit: n }],
+      this.session
+    );
+  }
+  /** @internal Used by facet() to extract branch stages. Not part of the public API. */
+  getStages() {
+    return this.stages;
   }
 };
 function aggregate(handle) {
-  return new AggregatePipeline(handle.definition, handle.native, []);
+  return new AggregatePipeline(
+    handle.definition,
+    handle.native,
+    [],
+    handle.session
+  );
 }
 
 // src/client/client.ts
@@ -1077,6 +1248,36 @@ async function syncIndexes(handle, options) {
   };
 }
 
+// src/transaction/transaction.ts
+var TransactionContext = class {
+  /** @internal */
+  session;
+  /** @internal */
+  constructor(session) {
+    this.session = session;
+  }
+  /**
+   * Bind a collection handle to this transaction's session.
+   *
+   * Returns a cloned handle whose CRUD operations automatically include
+   * the transaction session. The original handle is not modified.
+   *
+   * @param handle - An existing collection handle from `db.use()`.
+   * @returns A new handle bound to the transaction session.
+   *
+   * @example
+   * ```ts
+   * await db.transaction(async (tx) => {
+   *   const txUsers = tx.use(users)
+   *   await txUsers.insertOne({ name: 'Ada' })
+   * })
+   * ```
+   */
+  use(handle) {
+    return handle.withSession(this.session);
+  }
+};
+
 // src/crud/delete.ts
 import { z as z2 } from "zod";
 
@@ -1101,14 +1302,22 @@ var ZodmonValidationError = class extends ZodmonError {
 // src/crud/delete.ts
 async function deleteOne(handle, filter) {
   try {
-    return await handle.native.deleteOne(filter);
+    return await handle.native.deleteOne(
+      // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+      filter,
+      handle.session ? { session: handle.session } : {}
+    );
   } catch (err) {
     wrapMongoError(err, handle.definition.name);
   }
 }
 async function deleteMany(handle, filter) {
   try {
-    return await handle.native.deleteMany(filter);
+    return await handle.native.deleteMany(
+      // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+      filter,
+      handle.session ? { session: handle.session } : {}
+    );
   } catch (err) {
     wrapMongoError(err, handle.definition.name);
   }
@@ -1119,7 +1328,7 @@ async function findOneAndDelete(handle, filter, options) {
     result = await handle.native.findOneAndDelete(
       // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
       filter,
-      { includeResultMetadata: false }
+      handle.session ? { includeResultMetadata: false, session: handle.session } : { includeResultMetadata: false }
     );
   } catch (err) {
     wrapMongoError(err, handle.definition.name);
@@ -1130,7 +1339,8 @@ async function findOneAndDelete(handle, filter, options) {
     return result;
   }
   try {
-    return handle.definition.schema.parse(result);
+    const schema = mode === "strict" ? handle.definition.strictSchema : handle.definition.schema;
+    return schema.parse(result);
   } catch (err) {
     if (err instanceof z2.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err, result);
@@ -1140,7 +1350,7 @@ async function findOneAndDelete(handle, filter, options) {
 }
 
 // src/crud/find.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // src/errors/not-found.ts
 var ZodmonNotFoundError = class extends ZodmonError {
@@ -1177,7 +1387,7 @@ function checkUnindexedFields(definition, filter) {
 }
 
 // src/query/cursor.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 
 // src/crud/paginate.ts
 import { ObjectId } from "mongodb";
@@ -1240,11 +1450,313 @@ function resolveSortKeys(sortSpec) {
   return entries;
 }
 
+// src/populate/builder.ts
+var PopulateRefBuilder = class {
+  /**
+   * Declare a projection to apply when fetching the referenced documents.
+   *
+   * Supported: inclusion (`{ name: 1 }`), exclusion (`{ email: 0 }`), or
+   * `_id` suppression (`{ name: 1, _id: 0 }`).
+   *
+   * @param projection - MongoDB-style inclusion or exclusion projection.
+   * @returns A config object carrying the projection type for compile-time narrowing.
+   *
+   * @example
+   * ```ts
+   * (b) => b.project({ name: 1, email: 1 })
+   * (b) => b.project({ password: 0 })
+   * ```
+   */
+  project(projection) {
+    return { projection };
+  }
+};
+
+// src/populate/execute.ts
+import { z as z3 } from "zod";
+function unwrapRefSchema(schema) {
+  const def = schema._zod.def;
+  if (def && typeof def === "object") {
+    if ("innerType" in def && def.innerType instanceof z3.ZodType) {
+      return unwrapRefSchema(def.innerType);
+    }
+    if ("element" in def && def.element instanceof z3.ZodType) {
+      return unwrapRefSchema(def.element);
+    }
+  }
+  return schema;
+}
+function resolveRefField(shape, fieldName, collectionName) {
+  const fieldSchema = shape[fieldName];
+  if (!fieldSchema) {
+    throw new Error(
+      `[zodmon] populate: field '${fieldName}' does not exist on collection '${collectionName}'.`
+    );
+  }
+  const isArray = fieldSchema instanceof z3.ZodArray;
+  const inner = unwrapRefSchema(fieldSchema);
+  const ref = getRefMetadata(inner);
+  if (!ref) {
+    throw new Error(
+      `[zodmon] populate: field '${fieldName}' has no .ref() metadata. Only fields declared with .ref(Collection) can be populated.`
+    );
+  }
+  return { isArray, ref };
+}
+function resolvePopulateStep(definition, previousSteps, path, as, projection) {
+  const dotIndex = path.indexOf(".");
+  if (dotIndex === -1) {
+    const shape = definition.shape;
+    const { isArray: isArray2, ref: ref2 } = resolveRefField(shape, path, definition.name);
+    return {
+      originalPath: path,
+      leafField: path,
+      as,
+      parentOutputPath: void 0,
+      targetCollection: ref2.collection,
+      isArray: isArray2,
+      ...projection !== void 0 ? { projection } : {}
+    };
+  }
+  const parentPath = path.slice(0, dotIndex);
+  const leafField = path.slice(dotIndex + 1);
+  const parentStep = previousSteps.find((s) => s.as === parentPath);
+  if (!parentStep) {
+    throw new Error(
+      `[zodmon] populate: parent '${parentPath}' has not been populated. Populate '${parentPath}' before populating '${path}'.`
+    );
+  }
+  const parentShape = parentStep.targetCollection.shape;
+  const { isArray, ref } = resolveRefField(parentShape, leafField, parentStep.targetCollection.name);
+  return {
+    originalPath: path,
+    leafField,
+    as,
+    parentOutputPath: parentPath,
+    targetCollection: ref.collection,
+    isArray,
+    ...projection !== void 0 ? { projection } : {}
+  };
+}
+function expandValue(value) {
+  if (value == null) return [];
+  if (Array.isArray(value)) {
+    const result = [];
+    for (const item of value) {
+      if (item != null && typeof item === "object") {
+        result.push(item);
+      }
+    }
+    return result;
+  }
+  if (typeof value === "object") {
+    return [value];
+  }
+  return [];
+}
+function getNestedTargets(doc, path) {
+  const parts = path.split(".");
+  let targets = [doc];
+  for (const part of parts) {
+    targets = targets.flatMap((target) => expandValue(target[part]));
+  }
+  return targets;
+}
+function addUniqueId(value, idSet, idValues) {
+  const key = String(value);
+  if (!idSet.has(key)) {
+    idSet.add(key);
+    idValues.push(value);
+  }
+}
+function collectIds(targets, leafField) {
+  const idSet = /* @__PURE__ */ new Set();
+  const idValues = [];
+  for (const target of targets) {
+    const value = target[leafField];
+    if (value == null) continue;
+    if (Array.isArray(value)) {
+      for (const id of value) {
+        addUniqueId(id, idSet, idValues);
+      }
+    } else {
+      addUniqueId(value, idSet, idValues);
+    }
+  }
+  return idValues;
+}
+function resolvePopulatedValue(value, map) {
+  if (value == null) return value;
+  if (Array.isArray(value)) {
+    return value.map((id) => map.get(String(id))).filter((d) => d != null);
+  }
+  return map.get(String(value)) ?? null;
+}
+function mergePopulated(targets, step, map) {
+  for (const target of targets) {
+    const value = target[step.leafField];
+    const populated = resolvePopulatedValue(value, map);
+    if (step.as !== step.leafField) {
+      delete target[step.leafField];
+    }
+    target[step.as] = populated;
+  }
+}
+async function executePopulate(documents, steps, getCollection) {
+  for (const step of steps) {
+    const targets = step.parentOutputPath ? documents.flatMap((doc) => getNestedTargets(doc, step.parentOutputPath)) : documents;
+    const idValues = collectIds(targets, step.leafField);
+    if (idValues.length === 0) continue;
+    const col = getCollection(step.targetCollection.name);
+    const findOptions = step.projection !== void 0 ? { projection: step.projection } : {};
+    const fetched = await col.find({ _id: { $in: idValues } }, findOptions).toArray();
+    const map = /* @__PURE__ */ new Map();
+    for (const doc of fetched) {
+      map.set(String(doc._id), doc);
+    }
+    mergePopulated(targets, step, map);
+  }
+  return documents;
+}
+
+// src/populate/cursor.ts
+var PopulateCursor = class _PopulateCursor {
+  cursor;
+  definition;
+  steps;
+  nativeCollection;
+  /** @internal */
+  constructor(cursor, definition, steps, nativeCollection) {
+    this.cursor = cursor;
+    this.definition = definition;
+    this.steps = steps;
+    this.nativeCollection = nativeCollection;
+  }
+  // Implementation -- TypeScript cannot narrow overloaded generics in the
+  // implementation body, so param types are widened and the return is cast.
+  populate(field, asOrConfigure) {
+    let alias;
+    let projection;
+    if (typeof asOrConfigure === "function") {
+      alias = field.includes(".") ? field.split(".").pop() ?? field : field;
+      const config = asOrConfigure(new PopulateRefBuilder());
+      projection = config.projection;
+    } else {
+      alias = asOrConfigure ?? (field.includes(".") ? field.split(".").pop() ?? field : field);
+      projection = void 0;
+    }
+    const step = resolvePopulateStep(this.definition, this.steps, field, alias, projection);
+    const newSteps = [...this.steps, step];
+    return new _PopulateCursor(this.cursor, this.definition, newSteps, this.nativeCollection);
+  }
+  /**
+   * Execute the query and return all matching documents as a populated array.
+   *
+   * Fetches all documents from the underlying cursor, then applies populate
+   * steps in order using batch `$in` queries (no N+1 problem).
+   *
+   * @returns Array of populated documents.
+   *
+   * @example
+   * ```ts
+   * const posts = await db.use(Posts)
+   *   .find({})
+   *   .populate('authorId', 'author')
+   *   .toArray()
+   * ```
+   */
+  async toArray() {
+    const docs = await this.cursor.toArray();
+    if (this.steps.length === 0) return docs;
+    const populated = await executePopulate(
+      docs,
+      this.steps,
+      (name) => this.nativeCollection.db.collection(name)
+    );
+    return populated;
+  }
+  /**
+   * Async iterator for streaming populated documents.
+   *
+   * Fetches all documents first (populate requires the full batch for
+   * efficient `$in` queries), then yields results one at a time.
+   *
+   * @yields Populated documents one at a time.
+   *
+   * @example
+   * ```ts
+   * for await (const post of db.use(Posts).find({}).populate('authorId', 'author')) {
+   *   console.log(post.author.name)
+   * }
+   * ```
+   */
+  async *[Symbol.asyncIterator]() {
+    const results = await this.toArray();
+    for (const doc of results) {
+      yield doc;
+    }
+  }
+};
+function createPopulateCursor(cursor, definition, steps) {
+  const nativeCollection = cursor.nativeCollection;
+  return new PopulateCursor(cursor, definition, steps, nativeCollection);
+}
+
+// src/query/projection.ts
+function isIncludeValue(value) {
+  return value === 1 || value === true;
+}
+function isExcludeValue(value) {
+  return value === 0 || value === false;
+}
+function isInclusionProjection(projection) {
+  for (const key of Object.keys(projection)) {
+    if (key === "_id") continue;
+    const value = projection[key];
+    if (value !== void 0 && isIncludeValue(value)) return true;
+  }
+  return false;
+}
+function buildPickMask(projection, schemaKeys) {
+  const mask = {};
+  const idValue = projection._id;
+  if (!(idValue !== void 0 && isExcludeValue(idValue)) && schemaKeys.has("_id")) {
+    mask._id = true;
+  }
+  for (const key of Object.keys(projection)) {
+    if (key === "_id") continue;
+    const value = projection[key];
+    if (value !== void 0 && isIncludeValue(value) && schemaKeys.has(key)) {
+      mask[key] = true;
+    }
+  }
+  return mask;
+}
+function buildOmitMask(projection, schemaKeys) {
+  const mask = {};
+  for (const key of Object.keys(projection)) {
+    const value = projection[key];
+    if (value !== void 0 && isExcludeValue(value) && schemaKeys.has(key)) {
+      mask[key] = true;
+    }
+  }
+  return mask;
+}
+function deriveProjectedSchema(schema, projection) {
+  const schemaKeys = new Set(Object.keys(schema.shape));
+  if (isInclusionProjection(projection)) {
+    return schema.pick(buildPickMask(projection, schemaKeys));
+  }
+  return schema.omit(buildOmitMask(projection, schemaKeys));
+}
+
 // src/query/cursor.ts
 var TypedFindCursor = class {
   /** @internal */
   cursor;
   /** @internal */
+  definition;
+  /** @internal */
   schema;
   /** @internal */
   collectionName;
@@ -1256,16 +1768,23 @@ var TypedFindCursor = class {
   // biome-ignore lint/suspicious/noExplicitAny: TypedFilter is not assignable to MongoDB's Filter; stored opaquely for paginate
   filter;
   /** @internal */
+  session;
+  /** @internal */
   sortSpec;
   /** @internal */
-  constructor(cursor, definition, mode, nativeCollection, filter) {
+  projectedSchema;
+  /** @internal */
+  constructor(cursor, definition, mode, nativeCollection, filter, session) {
     this.cursor = cursor;
+    this.definition = definition;
     this.schema = definition.schema;
     this.collectionName = definition.name;
     this.mode = mode;
     this.nativeCollection = nativeCollection;
     this.filter = filter;
+    this.session = session;
     this.sortSpec = null;
+    this.projectedSchema = null;
   }
   /**
    * Set the sort order for the query.
@@ -1339,6 +1858,48 @@ var TypedFindCursor = class {
     this.cursor.hint(indexName);
     return this;
   }
+  /**
+   * Apply a projection to narrow the returned fields.
+   *
+   * Inclusion projections (`{ name: 1 }`) return only the specified fields
+   * plus `_id` (unless `_id: 0`). Exclusion projections (`{ email: 0 }`)
+   * return all fields except those excluded.
+   *
+   * The cursor's output type is narrowed at compile time. A derived Zod
+   * schema is built for runtime validation of the projected fields.
+   *
+   * Projects from the original document type, not from a previous projection.
+   * Calling `.project()` twice overrides the previous projection.
+   *
+   * @param spec - Type-safe projection document.
+   * @returns A new cursor with the narrowed output type.
+   *
+   * @example
+   * ```ts
+   * const names = await find(users, {})
+   *   .project({ name: 1 })
+   *   .sort({ name: 1 })
+   *   .toArray()
+   * // names[0].name   ✓
+   * // names[0].email  TS error
+   * ```
+   */
+  project(spec) {
+    this.cursor.project(spec);
+    this.projectedSchema = deriveProjectedSchema(
+      this.schema,
+      spec
+    );
+    return this;
+  }
+  // Implementation — creates a PopulateCursor and delegates the first populate call.
+  // No circular runtime dependency: populate/cursor.ts imports TypedFindCursor as a
+  // *type* only (erased at runtime), so the runtime import flows one way:
+  // query/cursor.ts → populate/cursor.ts.
+  populate(field, asOrConfigure) {
+    const popCursor = createPopulateCursor(this, this.definition, []);
+    return popCursor.populate(field, asOrConfigure);
+  }
   async paginate(opts) {
     const sortRecord = this.sortSpec ? this.sortSpec : null;
     const sortKeys2 = resolveSortKeys(sortRecord);
@@ -1355,8 +1916,11 @@ var TypedFindCursor = class {
     try {
       ;
       [total, raw2] = await Promise.all([
-        this.nativeCollection.countDocuments(this.filter),
-        this.nativeCollection.find(this.filter).sort(sort).skip((opts.page - 1) * opts.perPage).limit(opts.perPage).toArray()
+        this.nativeCollection.countDocuments(
+          this.filter,
+          this.session ? { session: this.session } : {}
+        ),
+        this.nativeCollection.find(this.filter, this.session ? { session: this.session } : void 0).sort(sort).skip((opts.page - 1) * opts.perPage).limit(opts.perPage).toArray()
       ]);
     } catch (err) {
       wrapMongoError(err, this.collectionName);
@@ -1386,7 +1950,7 @@ var TypedFindCursor = class {
     const effectiveSort = isBackward ? Object.fromEntries(sortKeys2.map(([f, d]) => [f, d === 1 ? -1 : 1])) : sort;
     let raw2;
     try {
-      raw2 = await this.nativeCollection.find(combinedFilter).sort(effectiveSort).limit(opts.limit + 1).toArray();
+      raw2 = await this.nativeCollection.find(combinedFilter, this.session ? { session: this.session } : void 0).sort(effectiveSort).limit(opts.limit + 1).toArray();
     } catch (err) {
       wrapMongoError(err, this.collectionName);
     }
@@ -1455,10 +2019,11 @@ var TypedFindCursor = class {
     if (this.mode === false || this.mode === "passthrough") {
       return raw2;
     }
+    const schema = this.projectedSchema ?? (this.mode === "strict" ? this.definition.strictSchema : this.schema);
     try {
-      return this.schema.parse(raw2);
+      return schema.parse(raw2);
     } catch (err) {
-      if (err instanceof z3.ZodError) {
+      if (err instanceof z4.ZodError) {
         throw new ZodmonValidationError(this.collectionName, err, raw2);
       }
       throw err;
@@ -1469,10 +2034,15 @@ var TypedFindCursor = class {
 // src/crud/find.ts
 async function findOne(handle, filter, options) {
   checkUnindexedFields(handle.definition, filter);
-  const findOptions = options?.project ? { projection: options.project } : void 0;
+  const project = options && "project" in options ? options.project : void 0;
+  const findOptions = project ? { projection: project } : void 0;
   let raw2;
   try {
-    raw2 = await handle.native.findOne(filter, findOptions);
+    raw2 = await handle.native.findOne(
+      // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+      filter,
+      handle.session ? { ...findOptions, session: handle.session } : findOptions
+    );
   } catch (err) {
     wrapMongoError(err, handle.definition.name);
   }
@@ -1481,10 +2051,14 @@ async function findOne(handle, filter, options) {
   if (mode === false || mode === "passthrough") {
     return raw2;
   }
+  const schema = project ? deriveProjectedSchema(
+    handle.definition.schema,
+    project
+  ) : mode === "strict" ? handle.definition.strictSchema : handle.definition.schema;
   try {
-    return handle.definition.schema.parse(raw2);
+    return schema.parse(raw2);
   } catch (err) {
-    if (err instanceof z4.ZodError) {
+    if (err instanceof z5.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err, raw2);
     }
     throw err;
@@ -1499,26 +2073,42 @@ async function findOneOrThrow(handle, filter, options) {
 }
 function find(handle, filter, options) {
   checkUnindexedFields(handle.definition, filter);
-  const raw2 = handle.native.find(filter);
+  const raw2 = handle.native.find(
+    // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+    filter,
+    handle.session ? { session: handle.session } : void 0
+  );
   const cursor = raw2;
   const mode = options?.validate !== void 0 ? options.validate : handle.definition.options.validation;
-  return new TypedFindCursor(cursor, handle.definition, mode, handle.native, filter);
+  const typedCursor = new TypedFindCursor(
+    cursor,
+    handle.definition,
+    mode,
+    handle.native,
+    filter,
+    handle.session
+  );
+  const project = options && "project" in options ? options.project : void 0;
+  if (project) {
+    return typedCursor.project(project);
+  }
+  return typedCursor;
 }
 
 // src/crud/insert.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 async function insertOne(handle, doc) {
   let parsed;
   try {
     parsed = handle.definition.schema.parse(doc);
   } catch (err) {
-    if (err instanceof z5.ZodError) {
+    if (err instanceof z6.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err, doc);
     }
     throw err;
   }
   try {
-    await handle.native.insertOne(parsed);
+    await handle.native.insertOne(parsed, handle.session ? { session: handle.session } : {});
   } catch (err) {
     wrapMongoError(err, handle.definition.name);
   }
@@ -1531,14 +2121,14 @@ async function insertMany(handle, docs) {
     try {
       parsed.push(handle.definition.schema.parse(doc));
     } catch (err) {
-      if (err instanceof z5.ZodError) {
+      if (err instanceof z6.ZodError) {
         throw new ZodmonValidationError(handle.definition.name, err, doc);
       }
       throw err;
     }
   }
   try {
-    await handle.native.insertMany(parsed);
+    await handle.native.insertMany(parsed, handle.session ? { session: handle.session } : {});
   } catch (err) {
     wrapMongoError(err, handle.definition.name);
   }
@@ -1546,17 +2136,29 @@ async function insertMany(handle, docs) {
 }
 
 // src/crud/update.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 async function updateOne(handle, filter, update, options) {
   try {
-    return await handle.native.updateOne(filter, update, options);
+    return await handle.native.updateOne(
+      // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+      filter,
+      // biome-ignore lint/suspicious/noExplicitAny: TypedUpdateFilter intersection type is not directly assignable to MongoDB's UpdateFilter
+      update,
+      handle.session ? { ...options, session: handle.session } : options
+    );
   } catch (err) {
     wrapMongoError(err, handle.definition.name);
   }
 }
 async function updateMany(handle, filter, update, options) {
   try {
-    return await handle.native.updateMany(filter, update, options);
+    return await handle.native.updateMany(
+      // biome-ignore lint/suspicious/noExplicitAny: TypedFilter intersection type is not directly assignable to MongoDB's Filter
+      filter,
+      // biome-ignore lint/suspicious/noExplicitAny: TypedUpdateFilter intersection type is not directly assignable to MongoDB's UpdateFilter
+      update,
+      handle.session ? { ...options, session: handle.session } : options
+    );
   } catch (err) {
     wrapMongoError(err, handle.definition.name);
   }
@@ -1569,6 +2171,9 @@ async function findOneAndUpdate(handle, filter, update, options) {
   if (options?.upsert !== void 0) {
     driverOptions["upsert"] = options.upsert;
   }
+  if (handle.session) {
+    driverOptions["session"] = handle.session;
+  }
   let result;
   try {
     result = await handle.native.findOneAndUpdate(
@@ -1588,24 +2193,165 @@ async function findOneAndUpdate(handle, filter, update, options) {
     return result;
   }
   try {
-    return handle.definition.schema.parse(result);
+    const schema = mode === "strict" ? handle.definition.strictSchema : handle.definition.schema;
+    return schema.parse(result);
   } catch (err) {
-    if (err instanceof z6.ZodError) {
+    if (err instanceof z7.ZodError) {
       throw new ZodmonValidationError(handle.definition.name, err, result);
     }
     throw err;
   }
 }
 
+// src/populate/query.ts
+var PopulateOneQuery = class _PopulateOneQuery {
+  handle;
+  filter;
+  options;
+  steps;
+  constructor(handle, filter, options, steps = []) {
+    this.handle = handle;
+    this.filter = filter;
+    this.options = options;
+    this.steps = steps;
+  }
+  // Implementation — TypeScript cannot narrow overloaded generics in the
+  // implementation body, so param types are widened and the return is cast.
+  populate(field, asOrConfigure) {
+    let alias;
+    let projection;
+    if (typeof asOrConfigure === "function") {
+      alias = field.includes(".") ? field.split(".").pop() ?? field : field;
+      const config = asOrConfigure(new PopulateRefBuilder());
+      projection = config.projection;
+    } else {
+      alias = asOrConfigure ?? (field.includes(".") ? field.split(".").pop() ?? field : field);
+      projection = void 0;
+    }
+    const step = resolvePopulateStep(this.handle.definition, this.steps, field, alias, projection);
+    const newSteps = [...this.steps, step];
+    return new _PopulateOneQuery(this.handle, this.filter, this.options, newSteps);
+  }
+  /**
+   * Attach fulfillment and rejection handlers to the query promise.
+   *
+   * Executes the base findOne query and applies populate steps if any.
+   * Returns `null` when no document matches the filter.
+   */
+  // biome-ignore lint/suspicious/noThenProperty: PromiseLike requires a then method
+  then(onfulfilled, onrejected) {
+    const promise = this.execute();
+    return promise.then(onfulfilled, onrejected);
+  }
+  async execute() {
+    const doc = await findOne(this.handle, this.filter, this.options);
+    if (!doc) return null;
+    if (this.steps.length === 0) return doc;
+    const populated = await executePopulate(
+      [doc],
+      this.steps,
+      (name) => this.handle.native.db.collection(name)
+    );
+    return populated[0] ?? null;
+  }
+};
+var PopulateOneOrThrowQuery = class _PopulateOneOrThrowQuery {
+  handle;
+  filter;
+  options;
+  steps;
+  constructor(handle, filter, options, steps = []) {
+    this.handle = handle;
+    this.filter = filter;
+    this.options = options;
+    this.steps = steps;
+  }
+  // Implementation — see PopulateOneQuery for reasoning on casts.
+  populate(field, asOrConfigure) {
+    let alias;
+    let projection;
+    if (typeof asOrConfigure === "function") {
+      alias = field.includes(".") ? field.split(".").pop() ?? field : field;
+      const config = asOrConfigure(new PopulateRefBuilder());
+      projection = config.projection;
+    } else {
+      alias = asOrConfigure ?? (field.includes(".") ? field.split(".").pop() ?? field : field);
+      projection = void 0;
+    }
+    const step = resolvePopulateStep(this.handle.definition, this.steps, field, alias, projection);
+    const newSteps = [...this.steps, step];
+    return new _PopulateOneOrThrowQuery(this.handle, this.filter, this.options, newSteps);
+  }
+  /**
+   * Attach fulfillment and rejection handlers to the query promise.
+   *
+   * Executes the base findOneOrThrow query and applies populate steps if any.
+   * Throws {@link ZodmonNotFoundError} when no document matches.
+   */
+  // biome-ignore lint/suspicious/noThenProperty: PromiseLike requires a then method
+  then(onfulfilled, onrejected) {
+    const promise = this.execute();
+    return promise.then(onfulfilled, onrejected);
+  }
+  async execute() {
+    const doc = await findOne(this.handle, this.filter, this.options);
+    if (!doc) {
+      throw new ZodmonNotFoundError(this.handle.definition.name, this.filter);
+    }
+    if (this.steps.length === 0) return doc;
+    const populated = await executePopulate(
+      [doc],
+      this.steps,
+      (name) => this.handle.native.db.collection(name)
+    );
+    const result = populated[0];
+    if (!result) {
+      throw new ZodmonNotFoundError(this.handle.definition.name, this.filter);
+    }
+    return result;
+  }
+};
+
 // src/client/handle.ts
-var CollectionHandle = class {
+var CollectionHandle = class _CollectionHandle {
   /** The collection definition containing schema, name, and index metadata. */
   definition;
   /** The underlying MongoDB driver collection, typed to the inferred document type. */
   native;
-  constructor(definition, native) {
+  /**
+   * The MongoDB client session bound to this handle, if any.
+   *
+   * When set, all CRUD and aggregation operations performed through this
+   * handle will include the session in their options, enabling transactional
+   * reads and writes. Undefined when no session is bound.
+   */
+  session;
+  constructor(definition, native, session) {
     this.definition = definition;
     this.native = native;
+    this.session = session;
+  }
+  /**
+   * Create a new handle bound to the given MongoDB client session.
+   *
+   * Returns a new {@link CollectionHandle} that shares the same collection
+   * definition and native driver collection, but passes `session` to every
+   * CRUD and aggregation operation. The original handle is not modified.
+   *
+   * @param session - The MongoDB `ClientSession` to bind.
+   * @returns A new handle with the session attached.
+   *
+   * @example
+   * ```ts
+   * const users = db.use(Users)
+   * await db.client.withSession(async (session) => {
+   *   const bound = users.withSession(session)
+   *   await bound.insertOne({ name: 'Ada' }) // uses session
+   * })
+   * ```
+   */
+  withSession(session) {
+    return new _CollectionHandle(this.definition, this.native, session);
   }
   /**
    * Insert a single document into the collection.
@@ -1651,70 +2397,18 @@ var CollectionHandle = class {
   async insertMany(docs) {
     return await insertMany(this, docs);
   }
-  /**
-   * Find a single document matching the filter.
-   *
-   * Queries MongoDB, then validates the fetched document against the collection's
-   * Zod schema. Validation mode is resolved from the per-query option, falling
-   * back to the collection-level default (which defaults to `'strict'`).
-   *
-   * @param filter - Type-safe filter to match documents.
-   * @param options - Optional projection and validation overrides.
-   * @returns The matched document, or `null` if no document matches.
-   * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
-   *
-   * @example
-   * ```ts
-   * const users = db.use(Users)
-   * const user = await users.findOne({ name: 'Ada' })
-   * if (user) console.log(user.role)
-   * ```
-   */
-  async findOne(filter, options) {
-    return await findOne(this, filter, options);
+  findOne(filter, options) {
+    if (options && "project" in options) {
+      return findOne(this, filter, options);
+    }
+    return new PopulateOneQuery(this, filter, options);
   }
-  /**
-   * Find a single document matching the filter, or throw if none exists.
-   *
-   * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
-   * instead of returning `null` when no document matches the filter.
-   *
-   * @param filter - Type-safe filter to match documents.
-   * @param options - Optional projection and validation overrides.
-   * @returns The matched document (never null).
-   * @throws {ZodmonNotFoundError} When no document matches the filter.
-   * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
-   *
-   * @example
-   * ```ts
-   * const users = db.use(Users)
-   * const user = await users.findOneOrThrow({ name: 'Ada' })
-   * console.log(user.role) // guaranteed non-null
-   * ```
-   */
-  async findOneOrThrow(filter, options) {
-    return await findOneOrThrow(this, filter, options);
+  findOneOrThrow(filter, options) {
+    if (options && "project" in options) {
+      return findOneOrThrow(this, filter, options);
+    }
+    return new PopulateOneOrThrowQuery(this, filter, options);
   }
-  /**
-   * Find all documents matching the filter, returning a chainable typed cursor.
-   *
-   * The cursor is lazy — no query is executed until a terminal method
-   * (`toArray`, `for await`) is called. Use `sort`, `skip`, and `limit`
-   * to shape the query before executing.
-   *
-   * @param filter - Type-safe filter to match documents.
-   * @param options - Optional validation overrides.
-   * @returns A typed cursor for chaining query modifiers.
-   *
-   * @example
-   * ```ts
-   * const users = db.use(Users)
-   * const admins = await users.find({ role: 'admin' })
-   *   .sort({ name: 1 })
-   *   .limit(10)
-   *   .toArray()
-   * ```
-   */
   find(filter, options) {
     return find(this, filter, options);
   }
@@ -1963,12 +2657,51 @@ var Database = class {
     return results;
   }
   /**
-   * Execute a function within a MongoDB transaction with auto-commit/rollback.
+   * Execute a function within a MongoDB transaction.
+   *
+   * Starts a client session and runs the callback inside
+   * `session.withTransaction()`. The driver handles commit on success,
+   * abort on error, and automatic retries for transient transaction errors.
+   *
+   * The return value of `fn` is forwarded as the return value of this method.
    *
-   * Stub — full implementation in TASK-106.
+   * @param fn - Async callback receiving a {@link TransactionContext}.
+   * @returns The value returned by `fn`.
+   *
+   * @example
+   * ```ts
+   * const user = await db.transaction(async (tx) => {
+   *   const txUsers = tx.use(users)
+   *   return await txUsers.insertOne({ name: 'Ada' })
+   * })
+   * ```
+   *
+   * @example
+   * ```ts
+   * // Rollback on error
+   * try {
+   *   await db.transaction(async (tx) => {
+   *     const txUsers = tx.use(users)
+   *     await txUsers.insertOne({ name: 'Ada' })
+   *     throw new Error('abort!')
+   *   })
+   * } catch (err) {
+   *   // insert was rolled back, err is the original error
+   * }
+   * ```
    */
-  transaction(_fn) {
-    throw new Error("Not implemented");
+  async transaction(fn) {
+    const session = this._client.startSession();
+    try {
+      let result;
+      await session.withTransaction(async () => {
+        const tx = new TransactionContext(session);
+        result = await fn(tx);
+      });
+      return result;
+    } finally {
+      await session.endSession();
+    }
   }
   /**
    * Close the underlying `MongoClient` connection. Safe to call even if
@@ -2001,10 +2734,10 @@ function createClient(uri, dbNameOrOptions, maybeOptions) {
 
 // src/collection/collection.ts
 import { ObjectId as ObjectId3 } from "mongodb";
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // src/schema/extensions.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 var indexMetadata = /* @__PURE__ */ new WeakMap();
 function getIndexMetadata(schema) {
   if (typeof schema !== "object" || schema === null) return void 0;
@@ -2012,7 +2745,7 @@ function getIndexMetadata(schema) {
 }
 var GUARD = /* @__PURE__ */ Symbol.for("zodmon_extensions");
 function installExtensions() {
-  const proto = z7.ZodType.prototype;
+  const proto = z8.ZodType.prototype;
   if (GUARD in proto) return;
   Object.defineProperty(proto, "index", {
     /**
@@ -2111,10 +2844,10 @@ installExtensions();
 
 // src/schema/object-id.ts
 import { ObjectId as ObjectId2 } from "mongodb";
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var OBJECT_ID_HEX = /^[a-f\d]{24}$/i;
 function objectId() {
-  return z8.custom((val) => {
+  return z9.custom((val) => {
     if (val instanceof ObjectId2) return true;
     return typeof val === "string" && OBJECT_ID_HEX.test(val);
   }, "Invalid ObjectId").transform((val) => val instanceof ObjectId2 ? val : ObjectId2.createFromHexString(val));
@@ -2133,7 +2866,8 @@ function extractFieldIndexes(shape) {
 }
 function collection(name, shape, options) {
   const resolvedShape = "_id" in shape ? shape : { _id: objectId().default(() => new ObjectId3()), ...shape };
-  const schema = z9.object(resolvedShape);
+  const schema = z10.object(resolvedShape);
+  const strictSchema = schema.strict();
   const fieldIndexes = extractFieldIndexes(shape);
   const { indexes: compoundIndexes, validation, ...rest } = options ?? {};
   return {
@@ -2143,6 +2877,7 @@ function collection(name, shape, options) {
     // not assignable to ZodObject<ResolvedShape<TShape>>. The cast is safe because
     // the runtime shape is correct — only the readonly modifier differs.
     schema,
+    strictSchema,
     shape,
     fieldIndexes,
     // Safe cast: compoundIndexes is TIndexes at runtime (or an empty array when
@@ -2281,6 +3016,11 @@ export {
   CollectionHandle,
   Database,
   IndexBuilder,
+  PopulateCursor,
+  PopulateOneOrThrowQuery,
+  PopulateOneQuery,
+  PopulateRefBuilder,
+  TransactionContext,
   TypedFindCursor,
   ZodmonAuthError,
   ZodmonBulkWriteError,
@@ -2300,8 +3040,11 @@ export {
   createAccumulatorBuilder,
   createClient,
   createExpressionBuilder,
+  createPopulateCursor,
   deleteMany,
   deleteOne,
+  deriveProjectedSchema,
+  executePopulate,
   extractComparableOptions,
   extractDbName,
   extractFieldIndexes,
@@ -2316,14 +3059,17 @@ export {
   index,
   insertMany,
   insertOne,
+  isInclusionProjection,
   isOid,
   objectId,
   oid,
   raw,
+  resolvePopulateStep,
   serializeIndexKey,
   syncIndexes,
   toCompoundIndexSpec,
   toFieldIndexSpec,
+  unwrapRefSchema,
   updateMany,
   updateOne,
   wrapMongoError