@zodmon/core 0.11.0 → 0.12.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ObjectId, Document, DeleteResult, FindCursor, Collection, UpdateResult, MongoClientOptions } from 'mongodb';
+import { ObjectId, Document, DeleteResult, Collection, FindCursor, ClientSession, UpdateResult, MongoClientOptions } from 'mongodb';
 import { ZodPipe, ZodCustom, ZodTransform, z, ZodDefault } from 'zod';
 
 /**
@@ -260,6 +260,8 @@ type InferInsert<TDef extends {
 type CollectionDefinition<TName extends string = string, TShape extends z.core.$ZodShape = z.core.$ZodShape, TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]> = {
     readonly name: TName;
     readonly schema: z.ZodObject<ResolvedShape<TShape>>;
+    /** Strict validation variant that throws on unknown fields. */
+    readonly strictSchema: z.ZodObject<ResolvedShape<TShape>>;
     readonly shape: TShape;
     readonly fieldIndexes: FieldIndexDefinition[];
     readonly compoundIndexes: TIndexes;
@@ -431,6 +433,48 @@ declare module 'zod' {
  * ```
  */
 declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
+/**
+ * Peel Zod wrappers (ZodOptional, ZodNullable, ZodDefault, ZodArray)
+ * to reach the inner schema type. Used to detect RefMarker on wrapped
+ * fields like `objectId().ref(X).optional()` or `z.array(objectId().ref(X))`.
+ *
+ * Bounded by wrapper depth (1-3 layers) — no circular risk.
+ *
+ * @example
+ * ```ts
+ * // ZodOptional<ZodObjectId & RefMarker<typeof Users>> → ZodObjectId & RefMarker<typeof Users>
+ * type Inner = UnwrapRef<typeof schema>
+ * ```
+ */
+type UnwrapRef<T> = T extends z.ZodOptional<infer U> ? UnwrapRef<U> : T extends z.ZodNullable<infer U> ? UnwrapRef<U> : T extends z.ZodDefault<infer U> ? UnwrapRef<U> : T extends z.ZodArray<infer E> ? UnwrapRef<E> : T;
+/**
+ * Extract field names that carry `.ref()` metadata from a collection definition.
+ *
+ * Unwraps ZodArray, ZodOptional, ZodNullable, ZodDefault to detect refs on
+ * inner schemas. Works for bare refs, array refs, and optional refs.
+ *
+ * @example
+ * ```ts
+ * type PostRefs = RefFields<typeof Posts>
+ * //   ^? 'authorId' | 'categoryIds' | 'reviewerId'
+ * ```
+ */
+type RefFields<TDef extends AnyCollection> = {
+    [K in keyof TDef['shape'] & string]: UnwrapRef<TDef['shape'][K]> extends RefMarker ? K : never;
+}[keyof TDef['shape'] & string];
+/**
+ * Given a collection definition and a ref-bearing field key, extract
+ * the target collection type from the `RefMarker<TCollection>` phantom.
+ *
+ * Unwraps Zod wrappers to reach the inner RefMarker.
+ *
+ * @example
+ * ```ts
+ * type Target = ExtractRefCollection<typeof Posts, 'authorId'>
+ * //   ^? typeof Users
+ * ```
+ */
+type ExtractRefCollection<TDef extends AnyCollection, K extends RefFields<TDef>> = UnwrapRef<TDef['shape'][K]> extends RefMarker<infer TCol> ? TCol : never;
 
 /**
  * Branded wrapper for accumulator expressions used inside `groupBy`.
@@ -572,12 +616,26 @@ type FieldRefType<T, F extends string> = F extends `$${infer K}` ? DotPathValue<
 type GroupByResult<T, K extends DotPath<T>, TAccum extends Record<string, Accumulator>> = Prettify<{
     _id: DotPathValue<T, K & string>;
 } & InferAccumulators<TAccum>>;
+/**
+ * Replace dots with underscores in a string type.
+ *
+ * Used to sanitize dot-path keys for compound `groupBy` `_id` sub-documents,
+ * since MongoDB forbids dots in field names.
+ *
+ * @example
+ * ```ts
+ * type R = ReplaceDots<'address.city'>
+ * //   ^? 'address_city'
+ * ```
+ */
+type ReplaceDots<S extends string> = S extends `${infer A}.${infer B}` ? `${A}_${ReplaceDots<B>}` : S;
 /**
  * Output shape of a compound (multi-field) `groupBy` stage.
  *
  * The `_id` field is an object with one property per grouped field,
  * and the rest of the shape comes from the inferred accumulator types.
- * Supports dot-path keys for grouping by nested fields.
+ * Dot-path keys are sanitized (dots replaced with underscores) because
+ * MongoDB forbids dots in field names.
  *
  * @example
  * ```ts
@@ -585,14 +643,30 @@ type GroupByResult<T, K extends DotPath<T>, TAccum extends Record<string, Accumu
  * //   ^? { _id: { status: string; region: string }; count: number }
  *
  * type Nested = GroupByCompoundResult<Order, 'name' | 'address.city', { count: Accumulator<number> }>
- * //   ^? { _id: { name: string; 'address.city': string }; count: number }
+ * //   ^? { _id: { name: string; address_city: string }; count: number }
  * ```
  */
 type GroupByCompoundResult<T, K extends DotPath<T>, TAccum extends Record<string, Accumulator>> = Prettify<{
     _id: Prettify<{
-        [P in K & string]: DotPathValue<T, P>;
+        [P in K & string as ReplaceDots<P>]: DotPathValue<T, P>;
     }>;
 } & InferAccumulators<TAccum>>;
+/**
+ * Output shape of a null-key `groupBy` stage (global aggregation).
+ *
+ * When `groupBy(null, ...)` is used, MongoDB collapses all documents
+ * into a single group with `_id: null`. The rest of the shape comes
+ * from the inferred accumulator types.
+ *
+ * @example
+ * ```ts
+ * type Result = GroupByNullResult<{ total: Accumulator<number> }>
+ * //   ^? { _id: null; total: number }
+ * ```
+ */
+type GroupByNullResult<TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: null;
+} & InferAccumulators<TAccum>>;
 /**
  * Output shape after unwinding an array field.
  *
@@ -644,29 +718,6 @@ type NarrowFromFilter<T, F> = {
         $nin: ReadonlyArray<infer V extends T[K]>;
     } ? Exclude<T[K], V> : T[K] : T[K];
 };
-/**
- * Extract field keys from a collection definition whose schema fields
- * carry `RefMarker` (i.e. fields that have `.ref()` metadata).
- *
- * @example
- * ```ts
- * type EmpRefs = RefFields<typeof Employees> // → 'departmentId'
- * ```
- */
-type RefFields<TDef extends AnyCollection> = {
-    [K in keyof TDef['shape'] & string]: TDef['shape'][K] extends RefMarker ? K : never;
-}[keyof TDef['shape'] & string];
-/**
- * Given a collection definition and a ref-bearing field key, extract
- * the target collection type from the `RefMarker<TCollection>` phantom.
- *
- * @example
- * ```ts
- * type Target = ExtractRefCollection<typeof Employees, 'departmentId'>
- * // → typeof Departments
- * ```
- */
-type ExtractRefCollection<TDef extends AnyCollection, K extends RefFields<TDef>> = TDef['shape'][K] extends RefMarker<infer TCol> ? TCol : never;
 /**
  * Extract the collection name string literal from a collection definition.
  *
@@ -723,12 +774,44 @@ type InferExpression<T> = T extends Expression<infer R> ? R : unknown;
 type InferAddedFields<T extends Record<string, unknown>> = {
     [K in keyof T]: InferExpression<T[K]>;
 };
+/**
+ * Accepts either a dot-path field reference or a pre-built `Expression<R>`.
+ *
+ * Used throughout `ExpressionBuilder` to allow method inputs to be either a
+ * field name string (auto-prefixed with `$` at runtime) or the result of a
+ * previous expression call (embedded directly into the pipeline stage).
+ *
+ * @typeParam T - The current pipeline document type.
+ * @typeParam R - The runtime value type produced by this input.
+ *
+ * @example
+ * ```ts
+ * // Field path (common case)
+ * expr.round('salary', 2)
+ *
+ * // Composed expression
+ * expr.round(expr.multiply('salary', 0.1), 2)
+ * ```
+ */
+type FieldOrExpr<T, R = unknown> = DotPath<T> | Expression<R>;
+/**
+ * Extracts the element type from a readonly or mutable array type.
+ *
+ * @example
+ * ```ts
+ * type Item = ArrayElement<string[]>     // → string
+ * type Num  = ArrayElement<number[]>     // → number
+ * type N    = ArrayElement<string>       // → never
+ * ```
+ */
+type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
 /**
  * Typed expression factory passed to the `addFields` callback.
  *
- * Each method constrains field names to `keyof T & string`, providing
- * IDE autocomplete and compile-time validation. Return types resolve
- * to `Expression<R>` where `R` is the MongoDB operator's output type.
+ * Each method accepts either a `DotPath<T>` field name string (auto-prefixed
+ * with `$` at runtime) or the result of a previous expression call
+ * (`Expression<R>`, embedded directly). This enables arbitrarily deep
+ * expression composition without `.raw()`.
  *
  * @typeParam T - The current pipeline output document type.
  *
@@ -736,65 +819,181 @@ type InferAddedFields<T extends Record<string, unknown>> = {
  * ```ts
  * employees.aggregate()
  *   .addFields(expr => ({
- *     hireYear: expr.year('hiredAt'),     // Expression<number>
- *     fullName: expr.concat('name', ' '), // Expression<string>
- *     isHighPay: expr.gte('salary', 100_000), // Expression<boolean>
+ *     hireYear: expr.year('hiredAt'),
+ *     bonus: expr.round(expr.multiply('salary', 0.1), 2),
+ *     profitMargin: expr.cond(
+ *       expr.eq('revenue', 0),
+ *       0,
+ *       expr.round(expr.divide(expr.subtract('revenue', 'cost'), 'revenue'), 4),
+ *     ),
  *   }))
  * ```
  */
 type ExpressionBuilder<T> = {
-    /** Add a numeric field and a value. Returns `Expression<number>`. */
-    add<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Subtract a value from a numeric field. Returns `Expression<number>`. */
-    subtract<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Multiply a numeric field by a value. Returns `Expression<number>`. */
-    multiply<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Divide a numeric field by a value. Returns `Expression<number>`. */
-    divide<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Modulo of a numeric field. Returns `Expression<number>`. */
-    mod<K extends keyof T & string>(field: K, value: number | (keyof T & string)): Expression<number>;
-    /** Absolute value of a numeric field. Returns `Expression<number>`. */
-    abs<K extends keyof T & string>(field: K): Expression<number>;
-    /** Ceiling of a numeric field. Returns `Expression<number>`. */
-    ceil<K extends keyof T & string>(field: K): Expression<number>;
-    /** Floor of a numeric field. Returns `Expression<number>`. */
-    floor<K extends keyof T & string>(field: K): Expression<number>;
-    /** Round a numeric field to N decimal places. Returns `Expression<number>`. */
-    round<K extends keyof T & string>(field: K, place?: number): Expression<number>;
-    /** Concatenate field values and literal strings. Returns `Expression<string>`. */
-    concat(...parts: Array<(keyof T & string) | string>): Expression<string>;
-    /** Convert a string field to lowercase. Returns `Expression<string>`. */
-    toLower<K extends keyof T & string>(field: K): Expression<string>;
-    /** Convert a string field to uppercase. Returns `Expression<string>`. */
-    toUpper<K extends keyof T & string>(field: K): Expression<string>;
-    /** Trim whitespace from a string field. Returns `Expression<string>`. */
-    trim<K extends keyof T & string>(field: K): Expression<string>;
-    /** Extract a substring from a string field. Returns `Expression<string>`. */
-    substr<K extends keyof T & string>(field: K, start: number, length: number): Expression<string>;
-    /** Test equality of a field against a value. Returns `Expression<boolean>`. */
-    eq<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is greater than a value. Returns `Expression<boolean>`. */
-    gt<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is greater than or equal to a value. Returns `Expression<boolean>`. */
-    gte<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is less than a value. Returns `Expression<boolean>`. */
-    lt<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is less than or equal to a value. Returns `Expression<boolean>`. */
-    lte<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Test if a field is not equal to a value. Returns `Expression<boolean>`. */
-    ne<K extends keyof T & string>(field: K, value: T[K]): Expression<boolean>;
-    /** Extract year from a date field. Returns `Expression<number>`. */
-    year<K extends keyof T & string>(field: K): Expression<number>;
-    /** Extract month (1-12) from a date field. Returns `Expression<number>`. */
-    month<K extends keyof T & string>(field: K): Expression<number>;
-    /** Extract day of month (1-31) from a date field. Returns `Expression<number>`. */
-    dayOfMonth<K extends keyof T & string>(field: K): Expression<number>;
-    /** Count elements in an array field. Returns `Expression<number>`. */
-    size<K extends keyof T & string>(field: K): Expression<number>;
-    /** Conditional expression. Returns `Expression<TThen | TElse>`. */
-    cond<TThen, TElse>(condition: Expression<boolean>, thenValue: TThen, elseValue: TElse): Expression<TThen | TElse>;
-    /** Replace null/missing field with a default. Returns `Expression<NonNullable<T[K]> | TDefault>`. */
-    ifNull<K extends keyof T & string, TDefault>(field: K, fallback: TDefault): Expression<NonNullable<T[K]> | TDefault>;
+    /** Add two numeric values. Returns `Expression<number>`. */
+    add(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Subtract `b` from `a`. Returns `Expression<number>`. */
+    subtract(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Multiply two numeric values. Returns `Expression<number>`. */
+    multiply(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Divide `a` by `b`. Returns `Expression<number>`. */
+    divide(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Modulo of `a` divided by `b`. Returns `Expression<number>`. */
+    mod(a: FieldOrExpr<T, number>, b: FieldOrExpr<T, number> | number): Expression<number>;
+    /** Absolute value of a numeric field or expression. Returns `Expression<number>`. */
+    abs(field: FieldOrExpr<T, number>): Expression<number>;
+    /** Ceiling (round up) of a numeric field or expression. Returns `Expression<number>`. */
+    ceil(field: FieldOrExpr<T, number>): Expression<number>;
+    /** Floor (round down) of a numeric field or expression. Returns `Expression<number>`. */
+    floor(field: FieldOrExpr<T, number>): Expression<number>;
+    /** Round to `place` decimal places (default 0). Returns `Expression<number>`. */
+    round(field: FieldOrExpr<T, number>, place?: number): Expression<number>;
+    /** Concatenate field values, literal strings, and string expressions. Returns `Expression<string>`. */
+    concat(...parts: Array<DotPath<T> | string | Expression<string>>): Expression<string>;
+    /** Convert a string field or expression to lowercase. Returns `Expression<string>`. */
+    toLower(field: FieldOrExpr<T, string>): Expression<string>;
+    /** Convert a string field or expression to uppercase. Returns `Expression<string>`. */
+    toUpper(field: FieldOrExpr<T, string>): Expression<string>;
+    /** Trim whitespace from a string field or expression. Returns `Expression<string>`. */
+    trim(field: FieldOrExpr<T, string>): Expression<string>;
+    /** Extract a byte-based substring. Returns `Expression<string>`. */
+    substr(field: FieldOrExpr<T, string>, start: number, length: number): Expression<string>;
+    /** Convert any value (number, date, ObjectId, etc.) to its string representation. Returns `Expression<string>`. */
+    toString(field: FieldOrExpr<T, unknown>): Expression<string>;
+    /** Test equality of a field against a value (type-safe value). Returns `Expression<boolean>`. */
+    eq<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test equality of a field against a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    eq(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test equality with a composed expression as the left-hand side. Returns `Expression<boolean>`. */
+    eq(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is greater than a value (type-safe). Returns `Expression<boolean>`. */
+    gt<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is greater than a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    gt(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is greater than a value. Returns `Expression<boolean>`. */
+    gt(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is greater than or equal to a value (type-safe). Returns `Expression<boolean>`. */
+    gte<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is greater than or equal to a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    gte(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is greater than or equal to a value. Returns `Expression<boolean>`. */
+    gte(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is less than a value (type-safe). Returns `Expression<boolean>`. */
+    lt<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is less than a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    lt(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is less than a value. Returns `Expression<boolean>`. */
+    lt(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is less than or equal to a value (type-safe). Returns `Expression<boolean>`. */
+    lte<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is less than or equal to a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    lte(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is less than or equal to a value. Returns `Expression<boolean>`. */
+    lte(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Test if a field is not equal to a value (type-safe). Returns `Expression<boolean>`. */
+    ne<F extends DotPath<T>>(field: F, value: DotPathValue<T, F>): Expression<boolean>;
+    /** Test if a field is not equal to a field reference expression (field-vs-field). Returns `Expression<boolean>`. */
+    ne(field: DotPath<T>, value: Expression<unknown>): Expression<boolean>;
+    /** Test if a composed expression is not equal to a value. Returns `Expression<boolean>`. */
+    ne(field: Expression<unknown>, value: unknown): Expression<boolean>;
+    /** Extract year from a date field or expression. Returns `Expression<number>`. */
+    year(field: FieldOrExpr<T, Date>): Expression<number>;
+    /** Extract month (1-12) from a date field or expression. Returns `Expression<number>`. */
+    month(field: FieldOrExpr<T, Date>): Expression<number>;
+    /** Extract day of month (1-31) from a date field or expression. Returns `Expression<number>`. */
+    dayOfMonth(field: FieldOrExpr<T, Date>): Expression<number>;
+    /** Extract day of week (1=Sunday … 7=Saturday) from a date field or expression. Returns `Expression<number>`. */
+    dayOfWeek(field: FieldOrExpr<T, Date>): Expression<number>;
+    /**
+     * Format a date field or expression as a string.
+     *
+     * Uses MongoDB format specifiers: `%Y` year, `%m` month (01-12), `%d` day (01-31), etc.
+     *
+     * @example
+     * ```ts
+     * expr.dateToString('createdAt', '%Y-%m')  // Expression<string>
+     * ```
+     */
+    dateToString(field: FieldOrExpr<T, Date>, format: string): Expression<string>;
+    /** Current timestamp at query start (`$$NOW`). Returns `Expression<Date>`. */
+    now(): Expression<Date>;
+    /** Count elements in an array field or expression. Returns `Expression<number>`. */
+    size(field: FieldOrExpr<T, unknown[]>): Expression<number>;
+    /**
+     * Check if a value is present in an array.
+     *
+     * Named `inArray` to distinguish from the filter-level `$in` operator.
+     * The second argument may be a field/expression producing an array, or a literal array.
+     *
+     * @example
+     * ```ts
+     * expr.inArray(expr.dayOfWeek('createdAt'), [1, 7])  // Expression<boolean>
+     * ```
+     */
+    inArray(value: FieldOrExpr<T, unknown>, array: FieldOrExpr<T, unknown[]> | ReadonlyArray<unknown>): Expression<boolean>;
+    /**
+     * Return the element at `index` from an array field (zero-based).
+     *
+     * When called with a typed field path, the element type is inferred from the schema.
+     * When called with a composed expression, the element type is `unknown`.
+     *
+     * @example
+     * ```ts
+     * // items: Item[] in schema → Expression<Item>
+     * expr.arrayElemAt('items', 0)
+     * ```
+     */
+    arrayElemAt<F extends DotPath<T>>(field: F, index: number): Expression<ArrayElement<DotPathValue<T, F>>>;
+    /** Return the element at `index` from an array expression. Returns `Expression<unknown>`. */
+    arrayElemAt(field: Expression<unknown[]>, index: number): Expression<unknown>;
+    /**
+     * Conditional expression: if `condition` is true return `thenValue`, else return `elseValue`.
+     *
+     * Both `thenValue` and `elseValue` accept literal values or composed `Expression<R>` results.
+     * Returns `Expression<TThen | TElse>`.
+     *
+     * @example
+     * ```ts
+     * expr.cond(expr.eq('revenue', 0), 0, expr.round(expr.divide('profit', 'revenue'), 4))
+     * ```
+     */
+    cond<TThen, TElse>(condition: Expression<boolean>, thenValue: TThen | Expression<TThen>, elseValue: TElse | Expression<TElse>): Expression<TThen | TElse>;
+    /** Replace null/missing field with a default. Returns `Expression<NonNullable<DotPathValue<T, F>> | TDefault>`. */
+    ifNull<F extends DotPath<T>, TDefault>(field: F, fallback: TDefault): Expression<NonNullable<DotPathValue<T, F>> | TDefault>;
+    /** Replace null/missing expression result with a default. Returns `Expression<NonNullable<R> | TDefault>`. */
+    ifNull<R, TDefault>(field: Expression<R>, fallback: TDefault): Expression<NonNullable<R> | TDefault>;
+    /**
+     * Multi-branch conditional. Evaluates `branches` in order and returns the first matching `then` value,
+     * or `fallback` if no branch matches.
+     *
+     * TypeScript infers `TThen` as the union of all `then` value types and the fallback type.
+     *
+     * @example
+     * ```ts
+     * expr.switch([
+     *   { case: expr.gte('spend', 10_000), then: 'VIP'    },
+     *   { case: expr.gte('spend', 5_000),  then: 'Gold'   },
+     * ], 'Bronze')
+     * // → Expression<'VIP' | 'Gold' | 'Bronze'>
+     * ```
+     */
+    switch<TThen>(branches: ReadonlyArray<{
+        case: Expression<boolean>;
+        then: TThen | Expression<TThen>;
+    }>, fallback: TThen | Expression<TThen>): Expression<TThen>;
+    /**
+     * Create a typed field reference for use as a comparison operand.
+     *
+     * Use when the right-hand side of a comparison should be a document
+     * field rather than a literal value (field-vs-field comparison).
+     *
+     * @example
+     * ```ts
+     * // Compare two fields in the same document
+     * .match({}, (expr) => expr.gt('totalAmount', expr.field('refundedAmount')))
+     * ```
+     */
+    field<F extends DotPath<T>>(name: F): Expression<DotPathValue<T, F>>;
 };
 
 /**
@@ -1030,19 +1229,20 @@ declare function createAccumulatorBuilder<T>(): AccumulatorBuilder<T>;
 /**
  * Create a typed expression builder for use inside `addFields` callbacks.
  *
- * The builder adds the `$` prefix to field names automatically and returns
- * properly typed `Expression<T>` values. Primarily used internally by
- * `AggregatePipeline.addFields` — most users interact with the builder via
- * the callback parameter rather than calling this directly.
+ * The builder accepts either a field name string (auto-prefixed with `$`) or a
+ * pre-built `Expression<R>` from another builder method, enabling composition.
+ * Primarily used internally by `AggregatePipeline.addFields` — most users
+ * interact with the builder via the callback parameter rather than calling
+ * this directly.
  *
  * @typeParam T - The current pipeline output document type.
  * @returns An `ExpressionBuilder<T>` with methods for each MongoDB expression operator.
  *
  * @example
  * ```ts
- * const expr = createExpressionBuilder<{ salary: number; name: string; hiredAt: Date }>()
- * expr.year('hiredAt')         // { __expr: true, value: { $year: '$hiredAt' } }
- * expr.multiply('salary', 0.9) // { __expr: true, value: { $multiply: ['$salary', 0.9] } }
+ * const expr = createExpressionBuilder<{ salary: number; hiredAt: Date }>()
+ * expr.year('hiredAt')                        // { __expr: true, value: { $year: '$hiredAt' } }
+ * expr.round(expr.multiply('salary', 0.1), 2) // { __expr: true, value: { $round: [{ $multiply: ['$salary', 0.1] }, 2] } }
  * ```
  */
 declare function createExpressionBuilder<T>(): ExpressionBuilder<T>;
@@ -1088,40 +1288,21 @@ type ComparisonOperators<V> = {
 } & (V extends string ? {
     $regex?: RegExp | string;
 } : unknown);
-/** Depth counter for limiting dot-notation recursion. Index = current depth, value = next depth. */
-type Prev = [never, 0, 1, 2];
 /**
- * Generates a union of all valid dot-separated paths for nested object fields in `T`.
+ * Dot-separated paths for nested fields, excluding top-level keys.
  *
- * Recursion is limited to 3 levels deep to prevent TypeScript compilation performance issues.
- * Only plain object fields are traversed — arrays, `Date`, `RegExp`, and `ObjectId` are
- * treated as leaf nodes and do not produce sub-paths.
+ * Filters out `keyof T & string` because top-level fields are already
+ * handled by slot (A) of {@link TypedFilter}. Keeping them separate
+ * preserves the intersection structure for lazy TypeScript evaluation.
  *
  * @example
  * ```ts
- * type User = { address: { city: string; geo: { lat: number; lng: number } } }
- *
- * // _DotPaths<User> = 'address.city' | 'address.geo' | 'address.geo.lat' | 'address.geo.lng'
+ * type User = { name: string; address: { city: string } }
+ * type Paths = DotSubPaths<User>
+ * //   ^? 'address.city'
  * ```
  */
-type _DotPaths<T, Depth extends number = 3> = Depth extends 0 ? never : {
-    [K in keyof T & string]: NonNullable<T[K]> extends ReadonlyArray<unknown> | Date | RegExp | ObjectId ? never : NonNullable<T[K]> extends Record<string, unknown> ? `${K}.${keyof NonNullable<T[K]> & string}` | `${K}.${_DotPaths<NonNullable<T[K]>, Prev[Depth]>}` : never;
-}[keyof T & string];
-/**
- * Resolves the value type at a dot-separated path `P` within type `T`.
- *
- * Splits `P` on the first `.` and recursively descends into `T`'s nested types.
- * Returns `never` if the path is invalid.
- *
- * @example
- * ```ts
- * type User = { address: { city: string; geo: { lat: number } } }
- *
- * // _DotPathType<User, 'address.city'> = string
- * // _DotPathType<User, 'address.geo.lat'> = number
- * ```
- */
-type _DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? Rest extends keyof NonNullable<T[K]> ? NonNullable<T[K]>[Rest] : _DotPathType<NonNullable<T[K]>, Rest> : never : P extends keyof T ? T[P] : never;
+type DotSubPaths<T> = Exclude<DotPath<T>, keyof T & string>;
 /**
  * Strict type-safe MongoDB filter query type.
  *
@@ -1132,7 +1313,7 @@ type _DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ?
  * Supports three forms of filter expressions:
  * - **Direct field values** (implicit `$eq`): `{ name: 'Alice' }`
  * - **Comparison operators**: `{ age: { $gt: 25 } }` or `{ age: $gt(25) }`
- * - **Dot notation** for nested fields up to 3 levels: `{ 'address.city': 'NYC' }`
+ * - **Dot notation** including nested and array-traversed fields: `{ 'address.city': 'NYC' }`
  *
  * Logical operators `$and`, `$or`, and `$nor` accept arrays of `TypedFilter<T>`
  * for composing complex queries.
@@ -1161,7 +1342,7 @@ type _DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ?
 type TypedFilter<T> = {
     [K in keyof T]?: T[K] | ComparisonOperators<T[K]>;
 } & {
-    [P in _DotPaths<T>]?: _DotPathType<T, P> | ComparisonOperators<_DotPathType<T, P>>;
+    [P in DotSubPaths<T>]?: DotPathValue<T, P> | ComparisonOperators<DotPathValue<T, P>>;
 } & {
     /** Joins clauses with a logical AND. Matches documents that satisfy all filters. */
     $and?: TypedFilter<T>[];
@@ -1451,6 +1632,400 @@ declare function isInclusionProjection(projection: Record<string, 0 | 1 | boolea
  */
 declare function deriveProjectedSchema(schema: z.ZodObject<z.core.$ZodShape>, projection: Record<string, 0 | 1 | boolean>): z.ZodObject<z.core.$ZodShape>;
 
+/**
+ * Typed return value from {@link PopulateRefBuilder.project}.
+ *
+ * Carries the projection type `P` for compile-time narrowing in populate calls.
+ * Callers never construct this directly — it is returned by the builder and
+ * consumed by the `.populate()` overload to narrow the result type.
+ *
+ * @example
+ * ```ts
+ * // P is inferred as { name: 1; email: 1 } — post.authorId is narrowed accordingly
+ * const post = await posts.findOne({}).populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+ * ```
+ */
+type PopulateProjectionConfig<P> = {
+    readonly projection: P;
+};
+/**
+ * Fluent builder passed to populate projection callbacks.
+ *
+ * Call `.project()` to specify which fields to fetch from the referenced collection.
+ * The projection type `P` flows back to the `.populate()` overload to narrow the
+ * result type at compile time.
+ *
+ * @typeParam TDoc - The referenced document type (e.g. `InferDocument<typeof Users>`).
+ *
+ * @example
+ * ```ts
+ * posts.findOne({}).populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+ * // post.authorId is narrowed to { _id: ObjectId; name: string; email: string }
+ * ```
+ */
+declare class PopulateRefBuilder<TDoc> {
+    /**
+     * 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<P extends TypedProjection<TDoc>>(projection: P): PopulateProjectionConfig<P>;
+}
+
+/**
+ * Resolve the populated type for a ref field, preserving wrappers.
+ *
+ * Transforms the field type from ID to document based on the Zod wrapper:
+ * - `ObjectId` → `InferDocument<Target>`
+ * - `ObjectId[]` → `InferDocument<Target>[]`
+ * - `ObjectId | undefined` → `InferDocument<Target> | undefined`
+ * - `ObjectId | null` → `InferDocument<Target> | null`
+ *
+ * @example
+ * ```ts
+ * type Author = PopulateField<typeof Posts, 'authorId'>
+ * //   ^? { _id: ObjectId; name: string; email: string; companyId: ObjectId }
+ *
+ * type Cats = PopulateField<typeof Posts, 'categoryIds'>
+ * //   ^? { _id: ObjectId; title: string }[]
+ * ```
+ */
+type PopulateField<TDef extends AnyCollection, K extends RefFields<TDef>> = TDef['shape'][K] extends z.ZodArray<infer _E> ? InferDocument<ExtractRefCollection<TDef, K>>[] : TDef['shape'][K] extends z.ZodOptional<infer _U> ? InferDocument<ExtractRefCollection<TDef, K>> | undefined : TDef['shape'][K] extends z.ZodNullable<infer _U> ? InferDocument<ExtractRefCollection<TDef, K>> | null : InferDocument<ExtractRefCollection<TDef, K>>;
+/**
+ * Document type with specified ref fields replaced by their populated types.
+ *
+ * @example
+ * ```ts
+ * type PostWithAuthor = Populated<typeof Posts, 'authorId'>
+ * //   ^? { _id: ObjectId; title: string; authorId: User; categoryIds: ObjectId[]; ... }
+ *
+ * type PostFull = Populated<typeof Posts, 'authorId' | 'categoryIds'>
+ * //   ^? { ...; authorId: User; categoryIds: Category[]; ... }
+ * ```
+ */
+type Populated<TDef extends AnyCollection, K extends RefFields<TDef>> = Prettify<Omit<InferDocument<TDef>, K> & {
+    [P in K]: PopulateField<TDef, P>;
+}>;
+/**
+ * Apply a single populate step to the output type.
+ *
+ * Without rename: replaces the field type in-place.
+ * With rename: removes the old key and adds the new key with the populated type.
+ *
+ * @example
+ * ```ts
+ * // No rename: authorId stays, type changes to User
+ * type A = ApplyPopulate<PostDoc, typeof Posts, 'authorId'>
+ *
+ * // Rename: authorId removed, author added with User type
+ * type B = ApplyPopulate<PostDoc, typeof Posts, 'authorId', 'author'>
+ * ```
+ */
+type ApplyPopulate<T, TDef extends AnyCollection, K extends RefFields<TDef>, TAs extends string = K> = Prettify<Omit<T, K> & {
+    [P in TAs]: PopulateField<TDef, K>;
+}>;
+/**
+ * Resolve the projected populated type for a ref field, preserving wrappers.
+ *
+ * Like {@link PopulateField} but applies `ProjectionResult<T, P>` to narrow
+ * the document type to only the projected fields.
+ *
+ * - `ObjectId` → `ProjectionResult<InferDocument<Target>, P>`
+ * - `ObjectId[]` → `ProjectionResult<InferDocument<Target>, P>[]`
+ * - `ObjectId | undefined` → `ProjectionResult<InferDocument<Target>, P> | undefined`
+ * - `ObjectId | null` → `ProjectionResult<InferDocument<Target>, P> | null`
+ *
+ * @example
+ * ```ts
+ * type Author = PopulateFieldProjected<typeof Posts, 'authorId', { name: 1; email: 1 }>
+ * //   ^? { _id: ObjectId; name: string; email: string }
+ * ```
+ */
+type PopulateFieldProjected<TDef extends AnyCollection, K extends RefFields<TDef>, P> = TDef['shape'][K] extends z.ZodArray<infer _E> ? ProjectionResult<InferDocument<ExtractRefCollection<TDef, K>>, P>[] : TDef['shape'][K] extends z.ZodOptional<infer _U> ? ProjectionResult<InferDocument<ExtractRefCollection<TDef, K>>, P> | undefined : TDef['shape'][K] extends z.ZodNullable<infer _U> ? ProjectionResult<InferDocument<ExtractRefCollection<TDef, K>>, P> | null : ProjectionResult<InferDocument<ExtractRefCollection<TDef, K>>, P>;
+/**
+ * Apply a projected populate step to the output type.
+ *
+ * Like {@link ApplyPopulate} but uses {@link PopulateFieldProjected} to narrow
+ * the result to only the projected fields. Use `TAs` to rename the output field.
+ *
+ * @example
+ * ```ts
+ * type Result = ApplyPopulateProjected<PostDoc, typeof Posts, 'authorId', { name: 1; email: 1 }>
+ * //   ^? { ...; authorId: { _id: ObjectId; name: string; email: string } }
+ * ```
+ */
+type ApplyPopulateProjected<T, TDef extends AnyCollection, K extends RefFields<TDef>, P, TAs extends string = K> = Prettify<Omit<T, K> & {
+    [F in TAs]: PopulateFieldProjected<TDef, K, P>;
+}>;
+/**
+ * Apply a populate at an arbitrary nesting depth.
+ *
+ * Splits the dot-path and recursively navigates into the output type.
+ * If a parent field is an array, the element type is transformed.
+ *
+ * @example
+ * ```ts
+ * // Nested: author.companyId → author.company
+ * type Result = DeepPopulate<PostWithAuthor, 'author.companyId', 'companyId', 'company', Company>
+ * ```
+ */
+type DeepPopulate<T, Path extends string, LeafField extends string, TAs extends string, PopType> = Path extends `${infer Parent}.${infer Rest}` ? Parent extends keyof T ? T[Parent] extends (infer E)[] ? Prettify<Omit<T, Parent> & {
+    [P in Parent]: DeepPopulate<E, Rest, LeafField, TAs, PopType>[];
+}> : Prettify<Omit<T, Parent> & {
+    [P in Parent]: DeepPopulate<T[Parent], Rest, LeafField, TAs, PopType>;
+}> : never : Prettify<Omit<T, LeafField> & {
+    [P in TAs]: PopType;
+}>;
+/**
+ * Valid nested populate paths given the current TPopMap.
+ *
+ * Produces a union of `parentPath.refField` strings where `parentPath`
+ * is a key in TPopMap and `refField` is a ref-bearing field in that
+ * parent's collection definition.
+ *
+ * @example
+ * ```ts
+ * // If TPopMap = { author: typeof Users }, produces:
+ * // 'author.companyId' | 'author.<other ref fields>'
+ * type Paths = NestedRefPath<{ author: typeof Users }>
+ * ```
+ */
+type NestedRefPath<TPopMap extends Record<string, AnyCollection>> = {
+    [Path in keyof TPopMap & string]: `${Path}.${RefFields<TPopMap[Path]>}`;
+}[keyof TPopMap & string];
+/**
+ * Runtime data for a single populate step.
+ *
+ * Built by each `.populate()` call and consumed by `executePopulate()`.
+ */
+type PopulateStep = {
+    /** The original field path from the root collection. */
+    readonly originalPath: string;
+    /** The leaf field name in the target shape. */
+    readonly leafField: string;
+    /** The output field name (renamed or original). */
+    readonly as: string;
+    /** Parent path in the output document for nesting, or undefined for top-level. */
+    readonly parentOutputPath: string | undefined;
+    /** The target collection definition resolved from RefMarker metadata. */
+    readonly targetCollection: AnyCollection;
+    /** Whether the field is an array ref. */
+    readonly isArray: boolean;
+    /** MongoDB projection spec to pass to the `$in` query. Omit to fetch the full document. */
+    readonly projection?: Record<string, 0 | 1 | boolean>;
+};
+
+/**
+ * Extract the parent segment from a dot-separated path.
+ *
+ * @example
+ * ```ts
+ * type P = ExtractParent<'author.companyId'> // 'author'
+ * ```
+ */
+type ExtractParent$1<T extends string> = T extends `${infer P}.${string}` ? P : never;
+/**
+ * Extract the leaf segment from a dot-separated path.
+ *
+ * @example
+ * ```ts
+ * type L = ExtractLeaf<'author.companyId'> // 'companyId'
+ * ```
+ */
+type ExtractLeaf$1<T extends string> = T extends `${string}.${infer L}` ? L : never;
+/**
+ * Cursor with chained populate steps, wrapping a {@link TypedFindCursor}.
+ *
+ * Created by calling `.populate()` on a `TypedFindCursor`. Exposes only
+ * `.populate()` (for additional fields) and terminal methods (`toArray`,
+ * async iteration). Cursor modifiers (`sort`, `skip`, `limit`) are not
+ * available -- they must be called before `.populate()`.
+ *
+ * @typeParam TDef - The root collection definition type.
+ * @typeParam TOutput - The current output document type after populate transforms.
+ * @typeParam TPopMap - Map of populated alias names to their collection definitions,
+ *   used to resolve nested populate paths.
+ *
+ * @example
+ * ```ts
+ * const posts = await db.use(Posts)
+ *   .find({ published: true })
+ *   .sort({ createdAt: -1 })
+ *   .limit(10)
+ *   .populate('authorId', 'author')
+ *   .populate('categoryIds')
+ *   .toArray()
+ * ```
+ */
+declare class PopulateCursor<TDef extends AnyCollection, TOutput, TPopMap extends Record<string, AnyCollection> = Record<string, never>> {
+    private readonly cursor;
+    private readonly definition;
+    private readonly steps;
+    private readonly nativeCollection;
+    /** @internal */
+    constructor(cursor: TypedFindCursor<TDef>, definition: TDef, steps: readonly PopulateStep[], nativeCollection: Collection<InferDocument<TDef>>);
+    /**
+     * Populate a top-level ref field, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @returns A new cursor with the field type replaced by the referenced document.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId')
+     *   .toArray()
+     * // posts[0].authorId is now a User document instead of ObjectId
+     * ```
+     */
+    populate<K extends RefFields<TDef>>(field: K): PopulateCursor<TDef, ApplyPopulate<TOutput, TDef, K>, TPopMap & {
+        [P in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field with a projection, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param configure - Callback receiving a builder; call `.project()` to set the projection.
+     * @returns A new cursor with the field type narrowed to only the projected fields.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+     *   .toArray()
+     * // posts[0].authorId is { _id: ObjectId; name: string; email: string }
+     * ```
+     */
+    populate<K extends RefFields<TDef>, P>(field: K, configure: (b: PopulateRefBuilder<InferDocument<ExtractRefCollection<TDef, K>>>) => PopulateProjectionConfig<P>): PopulateCursor<TDef, ApplyPopulateProjected<TOutput, TDef, K, P>, TPopMap & {
+        [F in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field and rename it in the output.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param as - The new field name in the output document.
+     * @returns A new cursor with the old field removed and the new field added.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', 'author')
+     *   .toArray()
+     * // posts[0].author is a User document; posts[0].authorId no longer exists
+     * ```
+     */
+    populate<K extends RefFields<TDef>, TAs extends string>(field: K, as: TAs): PopulateCursor<TDef, ApplyPopulate<TOutput, TDef, K, TAs>, TPopMap & {
+        [P in TAs]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a nested ref field, keeping the leaf field name.
+     *
+     * The parent path must have been populated in a previous `.populate()` call.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @returns A new cursor with the nested field type replaced.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId')
+     *   .toArray()
+     * // posts[0].author.companyId is now a Company document
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>>(path: TPath): PopulateCursor<TDef, DeepPopulate<TOutput, `${ExtractParent$1<TPath>}.${ExtractLeaf$1<TPath>}`, ExtractLeaf$1<TPath>, ExtractLeaf$1<TPath>, PopulateField<TPopMap[ExtractParent$1<TPath>], ExtractLeaf$1<TPath> & RefFields<TPopMap[ExtractParent$1<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent$1<TPath>}.${ExtractLeaf$1<TPath>}`]: ExtractRefCollection<TPopMap[ExtractParent$1<TPath>], ExtractLeaf$1<TPath> & RefFields<TPopMap[ExtractParent$1<TPath>]>>;
+    }>;
+    /**
+     * Populate a nested ref field and rename the leaf in the output.
+     *
+     * The parent path must have been populated in a previous `.populate()` call.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @param as - The new name for the leaf field in the output.
+     * @returns A new cursor with the nested field renamed and typed.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId', 'company')
+     *   .toArray()
+     * // posts[0].author.company is a Company document
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>, TAs extends string>(path: TPath, as: TAs): PopulateCursor<TDef, DeepPopulate<TOutput, `${ExtractParent$1<TPath>}.${TAs}`, ExtractLeaf$1<TPath>, TAs, PopulateField<TPopMap[ExtractParent$1<TPath>], ExtractLeaf$1<TPath> & RefFields<TPopMap[ExtractParent$1<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent$1<TPath>}.${TAs}`]: ExtractRefCollection<TPopMap[ExtractParent$1<TPath>], ExtractLeaf$1<TPath> & RefFields<TPopMap[ExtractParent$1<TPath>]>>;
+    }>;
+    /**
+     * 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()
+     * ```
+     */
+    toArray(): Promise<TOutput[]>;
+    /**
+     * 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)
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<TOutput>;
+}
+/**
+ * Create a new {@link PopulateCursor} from a {@link TypedFindCursor}.
+ *
+ * This factory function exists to break the circular import between
+ * `query/cursor.ts` and `populate/cursor.ts`. The `TypedFindCursor.populate()`
+ * method uses a lazy `require()` to call this function at runtime.
+ *
+ * @param cursor - The typed find cursor to wrap.
+ * @param definition - The collection definition.
+ * @param steps - Initial populate steps (typically empty).
+ * @returns A new PopulateCursor instance.
+ *
+ * @example
+ * ```ts
+ * const popCursor = createPopulateCursor(typedCursor, Posts, [])
+ * ```
+ */
+declare function createPopulateCursor<TDef extends AnyCollection>(cursor: TypedFindCursor<TDef>, definition: TDef, steps: readonly PopulateStep[]): PopulateCursor<TDef, InferDocument<TDef>>;
+
 /**
  * Type-safe sort specification for a document type.
  *
@@ -1489,21 +2064,25 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
     /** @internal */
     private cursor;
     /** @internal */
+    readonly definition: TDef;
+    /** @internal */
     private schema;
     /** @internal */
     private collectionName;
     /** @internal */
     private mode;
     /** @internal */
-    private readonly nativeCollection;
+    readonly nativeCollection: Collection<InferDocument<TDef>>;
     /** @internal */
     private readonly filter;
     /** @internal */
+    private readonly session;
+    /** @internal */
     private sortSpec;
     /** @internal */
     private projectedSchema;
     /** @internal */
-    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false, nativeCollection: Collection<InferDocument<TDef>>, filter: any);
+    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false, nativeCollection: Collection<InferDocument<TDef>>, filter: any, session?: ClientSession);
     /**
      * Set the sort order for the query.
      *
@@ -1590,6 +2169,73 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * ```
      */
     project<P extends TypedProjection<InferDocument<TDef>>>(spec: P): TypedFindCursor<TDef, TIndexNames, Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
+    /**
+     * Populate a top-level ref field, keeping the original field name.
+     *
+     * Transitions to a {@link PopulateCursor} that only exposes `.populate()`
+     * and terminal methods. Cursor modifiers (`sort`, `skip`, `limit`) must
+     * be called before `.populate()`.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @returns A populate cursor with the field type replaced by the referenced document.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId')
+     *   .toArray()
+     * ```
+     */
+    populate<K extends RefFields<TDef>>(field: K): PopulateCursor<TDef, ApplyPopulate<TOutput, TDef, K>, {
+        [P in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field with a projection, keeping the original field name.
+     *
+     * Transitions to a {@link PopulateCursor}. Cursor modifiers (`sort`, `skip`, `limit`)
+     * must be called before `.populate()`.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param configure - Callback receiving a builder; call `.project()` to set the projection.
+     * @returns A populate cursor with the field type narrowed to only the projected fields.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+     *   .toArray()
+     * // posts[0].authorId is { _id: ObjectId; name: string; email: string }
+     * ```
+     */
+    populate<K extends RefFields<TDef>, P>(field: K, configure: (b: PopulateRefBuilder<InferDocument<ExtractRefCollection<TDef, K>>>) => PopulateProjectionConfig<P>): PopulateCursor<TDef, ApplyPopulateProjected<TOutput, TDef, K, P>, {
+        [F in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field and rename it in the output.
+     *
+     * Transitions to a {@link PopulateCursor} that only exposes `.populate()`
+     * and terminal methods. Cursor modifiers (`sort`, `skip`, `limit`) must
+     * be called before `.populate()`.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param as - The new field name in the output document.
+     * @returns A populate cursor with the old field removed and the new field added.
+     *
+     * @example
+     * ```ts
+     * const posts = await db.use(Posts)
+     *   .find({})
+     *   .sort({ createdAt: -1 })
+     *   .limit(10)
+     *   .populate('authorId', 'author')
+     *   .toArray()
+     * ```
+     */
+    populate<K extends RefFields<TDef>, TAs extends string>(field: K, as: TAs): PopulateCursor<TDef, ApplyPopulate<TOutput, TDef, K, TAs>, {
+        [P in TAs]: ExtractRefCollection<TDef, K>;
+    }>;
     /**
      * Execute the query with offset-based pagination, returning a page of documents
      * with total count and navigation metadata.
@@ -1858,16 +2504,6 @@ declare function find<TDef extends AnyCollection>(handle: CollectionHandle<TDef>
  */
 declare function find<TDef extends AnyCollection, P extends TypedProjection<InferDocument<TDef>>>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindProjectionOptions<InferDocument<TDef>, P>): TypedFindCursor<TDef, IndexNames<TDef>, Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
 
-/**
- * Extracts the element type from an array type.
- *
- * @example
- * ```ts
- * type E = ArrayElement<string[]> // string
- * type N = ArrayElement<number[]> // number
- * ```
- */
-type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
 /**
  * Fields valid for `$set`, `$setOnInsert`, `$min`, and `$max` operators.
  *
@@ -1882,7 +2518,7 @@ type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
 type SetFields<T> = {
     [K in keyof T]?: T[K];
 } & {
-    [P in _DotPaths<T>]?: _DotPathType<T, P>;
+    [P in DotSubPaths<T>]?: DotPathValue<T, P>;
 };
 /**
  * Fields valid for the `$inc` operator — only number-typed fields.
@@ -1897,7 +2533,7 @@ type SetFields<T> = {
 type IncFields<T> = {
     [K in keyof T as NonNullable<T[K]> extends number ? K : never]?: number;
 } & {
-    [P in _DotPaths<T> as _DotPathType<T, P> extends number ? P : never]?: number;
+    [P in DotSubPaths<T> as DotPathValue<T, P> extends number ? P : never]?: number;
 };
 /**
  * Modifiers for the `$push` operator.
@@ -2242,6 +2878,257 @@ type SyncIndexesResult = {
     stale: StaleIndex[];
 };
 
+/**
+ * Extract the parent segment from a dot-separated path.
+ *
+ * @example
+ * ```ts
+ * type P = ExtractParent<'author.companyId'> // 'author'
+ * ```
+ */
+type ExtractParent<T extends string> = T extends `${infer P}.${string}` ? P : never;
+/**
+ * Extract the leaf segment from a dot-separated path.
+ *
+ * @example
+ * ```ts
+ * type L = ExtractLeaf<'author.companyId'> // 'companyId'
+ * ```
+ */
+type ExtractLeaf<T extends string> = T extends `${string}.${infer L}` ? L : never;
+/**
+ * Fluent populate builder for findOne queries.
+ *
+ * Implements `PromiseLike` so it can be awaited directly without `.populate()`.
+ * Each `.populate()` call returns a new builder with updated generics.
+ *
+ * @example
+ * ```ts
+ * // Without populate (backward compatible)
+ * const post = await posts.findOne({ title: 'Hello' })
+ *
+ * // With populate
+ * const post = await posts.findOne({ title: 'Hello' })
+ *   .populate('authorId', 'author')
+ *   .populate('author.companyId', 'company')
+ * ```
+ */
+declare class PopulateOneQuery<TDef extends AnyCollection, TOutput, TPopMap extends Record<string, AnyCollection> = Record<string, never>> implements PromiseLike<TOutput | null> {
+    private readonly handle;
+    private readonly filter;
+    private readonly options;
+    private readonly steps;
+    constructor(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindOneOptions | undefined, steps?: readonly PopulateStep[]);
+    /**
+     * Populate a top-level ref field, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @returns A new builder with the field type replaced by the referenced document.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId')
+     * // post.authorId is now a User document instead of ObjectId
+     * ```
+     */
+    populate<K extends RefFields<TDef>>(field: K): PopulateOneQuery<TDef, ApplyPopulate<TOutput, TDef, K>, TPopMap & {
+        [P in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field with a projection, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param configure - Callback receiving a builder; call `.project()` to set the projection.
+     * @returns A new builder with the field type narrowed to only the projected fields.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+     * // post.authorId is { _id: ObjectId; name: string; email: string }
+     * // post.authorId.age  →  TS error
+     * ```
+     */
+    populate<K extends RefFields<TDef>, P>(field: K, configure: (b: PopulateRefBuilder<InferDocument<ExtractRefCollection<TDef, K>>>) => PopulateProjectionConfig<P>): PopulateOneQuery<TDef, ApplyPopulateProjected<TOutput, TDef, K, P>, TPopMap & {
+        [F in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field and rename it in the output.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param as - The new field name in the output document.
+     * @returns A new builder with the old field removed and the new field added.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     * // post.author is a User document; post.authorId no longer exists
+     * ```
+     */
+    populate<K extends RefFields<TDef>, TAs extends string>(field: K, as: TAs): PopulateOneQuery<TDef, ApplyPopulate<TOutput, TDef, K, TAs>, TPopMap & {
+        [P in TAs]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a nested ref field, keeping the leaf field name.
+     *
+     * The parent path must have been populated in a previous `.populate()` call.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @returns A new builder with the nested field type replaced.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId')
+     * // post.author.companyId is now a Company document
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>>(path: TPath): PopulateOneQuery<TDef, DeepPopulate<TOutput, `${ExtractParent<TPath>}.${ExtractLeaf<TPath>}`, ExtractLeaf<TPath>, ExtractLeaf<TPath>, PopulateField<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent<TPath>}.${ExtractLeaf<TPath>}`]: ExtractRefCollection<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>;
+    }>;
+    /**
+     * Populate a nested ref field and rename the leaf in the output.
+     *
+     * The parent path must have been populated in a previous `.populate()` call.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @param as - The new name for the leaf field in the output.
+     * @returns A new builder with the nested field renamed and typed.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId', 'company')
+     * // post.author.company is a Company document
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>, TAs extends string>(path: TPath, as: TAs): PopulateOneQuery<TDef, DeepPopulate<TOutput, `${ExtractParent<TPath>}.${TAs}`, ExtractLeaf<TPath>, TAs, PopulateField<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent<TPath>}.${TAs}`]: ExtractRefCollection<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>;
+    }>;
+    /**
+     * 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.
+     */
+    then<TResult1 = TOutput | null, TResult2 = never>(onfulfilled?: ((value: TOutput | null) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private execute;
+}
+/**
+ * Fluent populate builder for findOneOrThrow queries.
+ *
+ * Identical to {@link PopulateOneQuery} but resolves to `TOutput` (never null).
+ * Throws {@link ZodmonNotFoundError} when no document matches the filter.
+ *
+ * @example
+ * ```ts
+ * const post = await posts.findOneOrThrow({ title: 'Hello' })
+ *   .populate('authorId', 'author')
+ * // Guaranteed non-null; throws if not found
+ * ```
+ */
+declare class PopulateOneOrThrowQuery<TDef extends AnyCollection, TOutput, TPopMap extends Record<string, AnyCollection> = Record<string, never>> implements PromiseLike<TOutput> {
+    private readonly handle;
+    private readonly filter;
+    private readonly options;
+    private readonly steps;
+    constructor(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindOneOptions | undefined, steps?: readonly PopulateStep[]);
+    /**
+     * Populate a top-level ref field, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @returns A new builder with the field type replaced by the referenced document.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId')
+     * ```
+     */
+    populate<K extends RefFields<TDef>>(field: K): PopulateOneOrThrowQuery<TDef, ApplyPopulate<TOutput, TDef, K>, TPopMap & {
+        [P in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field with a projection, keeping the original field name.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param configure - Callback receiving a builder; call `.project()` to set the projection.
+     * @returns A new builder with the field type narrowed to only the projected fields.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', (b) => b.project({ name: 1, email: 1 }))
+     * // post.authorId is { _id: ObjectId; name: string; email: string }
+     * // post.authorId.age  →  TS error
+     * ```
+     */
+    populate<K extends RefFields<TDef>, P>(field: K, configure: (b: PopulateRefBuilder<InferDocument<ExtractRefCollection<TDef, K>>>) => PopulateProjectionConfig<P>): PopulateOneOrThrowQuery<TDef, ApplyPopulateProjected<TOutput, TDef, K, P>, TPopMap & {
+        [F in K]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a top-level ref field and rename it in the output.
+     *
+     * @param field - A ref-bearing field name on the root collection.
+     * @param as - The new field name in the output document.
+     * @returns A new builder with the old field removed and the new field added.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     * ```
+     */
+    populate<K extends RefFields<TDef>, TAs extends string>(field: K, as: TAs): PopulateOneOrThrowQuery<TDef, ApplyPopulate<TOutput, TDef, K, TAs>, TPopMap & {
+        [P in TAs]: ExtractRefCollection<TDef, K>;
+    }>;
+    /**
+     * Populate a nested ref field, keeping the leaf field name.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @returns A new builder with the nested field type replaced.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId')
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>>(path: TPath): PopulateOneOrThrowQuery<TDef, DeepPopulate<TOutput, `${ExtractParent<TPath>}.${ExtractLeaf<TPath>}`, ExtractLeaf<TPath>, ExtractLeaf<TPath>, PopulateField<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent<TPath>}.${ExtractLeaf<TPath>}`]: ExtractRefCollection<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>;
+    }>;
+    /**
+     * Populate a nested ref field and rename the leaf in the output.
+     *
+     * @param path - A dot-separated path like `'author.companyId'`.
+     * @param as - The new name for the leaf field in the output.
+     * @returns A new builder with the nested field renamed and typed.
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     *   .populate('author.companyId', 'company')
+     * ```
+     */
+    populate<TPath extends NestedRefPath<TPopMap>, TAs extends string>(path: TPath, as: TAs): PopulateOneOrThrowQuery<TDef, DeepPopulate<TOutput, `${ExtractParent<TPath>}.${TAs}`, ExtractLeaf<TPath>, TAs, PopulateField<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>>, TPopMap & {
+        [P in `${ExtractParent<TPath>}.${TAs}`]: ExtractRefCollection<TPopMap[ExtractParent<TPath>], ExtractLeaf<TPath> & RefFields<TPopMap[ExtractParent<TPath>]>>;
+    }>;
+    /**
+     * 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.
+     */
+    then<TResult1 = TOutput, TResult2 = never>(onfulfilled?: ((value: TOutput) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    private execute;
+}
+
 /**
  * Typed wrapper around a MongoDB driver `Collection`.
  *
@@ -2257,7 +3144,35 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
     readonly definition: TDef;
     /** The underlying MongoDB driver collection, typed to the inferred document type. */
     readonly native: Collection<InferDocument<TDef>>;
-    constructor(definition: TDef, native: Collection<InferDocument<TDef>>);
+    /**
+     * 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.
+     */
+    readonly session: ClientSession | undefined;
+    constructor(definition: TDef, native: Collection<InferDocument<TDef>>, session?: ClientSession);
+    /**
+     * 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: ClientSession): CollectionHandle<TDef>;
     /**
      * Insert a single document into the collection.
      *
@@ -2301,13 +3216,12 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
     /**
      * 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'`).
+     * Returns a {@link PopulateOneQuery} that can be awaited directly or chained
+     * with `.populate()` calls to resolve foreign key references.
      *
      * @param filter - Type-safe filter to match documents.
      * @param options - Optional validation overrides.
-     * @returns The matched document, or `null` if no document matches.
+     * @returns A populate builder that resolves to the matched document, or `null`.
      * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
      *
      * @example
@@ -2316,13 +3230,20 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * const user = await users.findOne({ name: 'Ada' })
      * if (user) console.log(user.role)
      * ```
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOne({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     * ```
      */
-    findOne(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+    findOne(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): PopulateOneQuery<TDef, InferDocument<TDef>>;
     /**
      * Find a single document matching the filter with a type-safe projection.
      *
      * Returns only the fields specified by the projection. The return type is
      * narrowed to reflect which fields are included or excluded.
+     * Projected queries do not support `.populate()`.
      *
      * @param filter - Type-safe filter to match documents.
      * @param options - Projection and optional validation overrides.
@@ -2340,12 +3261,13 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
     /**
      * 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.
+     * Returns a {@link PopulateOneOrThrowQuery} that can be awaited directly or
+     * chained with `.populate()` calls. Throws {@link ZodmonNotFoundError}
+     * instead of returning `null` when no document matches.
      *
      * @param filter - Type-safe filter to match documents.
      * @param options - Optional validation overrides.
-     * @returns The matched document (never null).
+     * @returns A populate builder that resolves to 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.
      *
@@ -2355,14 +3277,21 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * const user = await users.findOneOrThrow({ name: 'Ada' })
      * console.log(user.role) // guaranteed non-null
      * ```
+     *
+     * @example
+     * ```ts
+     * const post = await posts.findOneOrThrow({ title: 'Hello' })
+     *   .populate('authorId', 'author')
+     * ```
      */
-    findOneOrThrow(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+    findOneOrThrow(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): PopulateOneOrThrowQuery<TDef, InferDocument<TDef>>;
     /**
      * Find a single document matching the filter with a type-safe projection, or throw if none exists.
      *
      * Returns only the fields specified by the projection. The return type is
      * narrowed to reflect which fields are included or excluded. Throws
      * {@link ZodmonNotFoundError} instead of returning `null`.
+     * Projected queries do not support `.populate()`.
      *
      * @param filter - Type-safe filter to match documents.
      * @param options - Projection and optional validation overrides.
@@ -2612,7 +3541,8 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
     protected readonly definition: TDef;
     private readonly nativeCollection;
     private readonly stages;
-    constructor(definition: TDef, nativeCollection: Collection<InferDocument<TDef>>, stages: Document[]);
+    private readonly session;
+    constructor(definition: TDef, nativeCollection: Collection<InferDocument<TDef>>, stages: Document[], session?: ClientSession);
     /**
      * Append an arbitrary aggregation stage to the pipeline (escape hatch).
      *
@@ -2728,10 +3658,21 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
      *   .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<TNarrow extends {
         [K in keyof TNarrow]: K extends keyof TOutput ? TOutput[K] : never;
-    } = {}, F extends TypedFilter<TOutput> = TypedFilter<TOutput>>(filter: F): AggregatePipeline<TDef, Prettify<Omit<NarrowFromFilter<TOutput, F>, keyof TNarrow> & TNarrow>>;
+    } = {}, F extends TypedFilter<TOutput> = TypedFilter<TOutput>>(filter: F, exprCb?: (expr: ExpressionBuilder<TOutput>) => Expression<boolean>): AggregatePipeline<TDef, Prettify<Omit<NarrowFromFilter<TOutput, F>, keyof TNarrow> & TNarrow>>;
     /**
      * Sort documents by one or more fields.
      *
@@ -2848,7 +3789,7 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
      * and compile-time field validation. Builder methods resolve return types
      * to the actual field type (`T[K]`), not `unknown`.
      *
-     * @param field - A field name or array of field names to group by.
+     * @param field - A field name, array of field names, or `null` to aggregate all documents into a single group.
      * @param accumulators - A callback `(acc) => ({ ... })` or plain accumulator object.
      * @returns A new pipeline with the `$group` stage appended.
      *
@@ -2879,7 +3820,20 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
      *   .groupBy(['role', 'dept'], acc => ({ count: acc.count() }))
      *   .toArray()
      * ```
+     *
+     * @example
+     * ```ts
+     * // Null groupBy — aggregate all documents into a single summary
+     * const totals = await aggregate(orders)
+     *   .groupBy(null, acc => ({
+     *     grandTotal: acc.sum('amount'),
+     *     orderCount: acc.count(),
+     *   }))
+     *   .toArray()
+     * // → [{ _id: null, grandTotal: 2740, orderCount: 7 }]
+     * ```
      */
+    groupBy<TAccum extends Record<string, Accumulator>>(field: null, accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByNullResult<TAccum>>;
     groupBy<K extends DotPath<TOutput>, TAccum extends Record<string, Accumulator>>(field: K, accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByResult<TOutput, K, TAccum>>;
     groupBy<K extends DotPath<TOutput>, TAccum extends Record<string, Accumulator>>(field: K[], accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByCompoundResult<TOutput, K, TAccum>>;
     /**
@@ -3016,6 +3970,37 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
     }): AggregatePipeline<TDef, Prettify<TOutput & {
         [P in TAs]: InferDocument<TForeignDef>[];
     }>>;
+    /**
+     * 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<TSpec extends Record<string, (sub: SubPipeline<TDef, TOutput>) => AggregatePipeline<TDef, any>>>(spec: TSpec): AggregatePipeline<TDef, Prettify<InferFacetOutput<TSpec>>>;
     /**
      * Count documents per group, sorted by count descending.
      *
@@ -3112,6 +4097,8 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
     bottom(n: number, options: {
         by: keyof TOutput & string;
     }): AggregatePipeline<TDef, TOutput>;
+    /** @internal Used by facet() to extract branch stages. Not part of the public API. */
+    getStages(): Document[];
 }
 /**
  * Create a new aggregation pipeline for a collection.
@@ -3131,6 +4118,99 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
  * ```
  */
 declare function aggregate<TDef extends AnyCollection>(handle: CollectionHandle<TDef>): AggregatePipeline<TDef, InferDocument<TDef>>;
+/**
+ * A sub-pipeline passed to each `.facet()` branch callback.
+ *
+ * All stage-building methods are available. Execution methods (`toArray`,
+ * `explain`, `[Symbol.asyncIterator]`) are omitted — sub-pipelines are
+ * not executed directly; they only accumulate stages for the parent `$facet` stage.
+ *
+ * @typeParam TDef - The collection definition type.
+ * @typeParam TOutput - The current output document type.
+ *
+ * @example
+ * ```ts
+ * .facet({
+ *   summary: (sub: SubPipeline<typeof Orders, Order>) => sub.groupBy(null, acc => ({ total: acc.sum('amount') }))
+ * })
+ * ```
+ */
+type SubPipeline<TDef extends AnyCollection, TOutput> = Omit<AggregatePipeline<TDef, TOutput>, 'toArray' | 'explain' | typeof Symbol.asyncIterator>;
+/**
+ * Maps a `.facet()` spec object to its inferred output shape.
+ *
+ * Each key maps to the array of results produced by that branch's terminal pipeline.
+ * Uses `any` for the sub-pipeline parameter to avoid TypeScript contravariance
+ * complications — inference of `TOut` from the return type is what matters.
+ *
+ * @example
+ * ```ts
+ * type Spec = {
+ *   byCategory: (sub: SubPipeline<any, any>) => AggregatePipeline<any, { _id: string; count: number }>
+ * }
+ * type Result = InferFacetOutput<Spec>
+ * //   ^? { byCategory: { _id: string; count: number }[] }
+ * ```
+ */
+type InferFacetOutput<TSpec> = {
+    [K in keyof TSpec]: TSpec[K] extends (sub: any) => AggregatePipeline<any, infer TOut> ? TOut[] : never;
+};
+
+/**
+ * The callback signature for {@link Database.transaction}.
+ *
+ * @typeParam T - The return type of the transaction callback.
+ *
+ * @example
+ * ```ts
+ * const fn: TransactionFn<void> = async (tx) => {
+ *   const txUsers = tx.use(users)
+ *   await txUsers.insertOne({ name: 'Ada' })
+ * }
+ * ```
+ */
+type TransactionFn<T> = (tx: TransactionContext) => Promise<T>;
+/**
+ * Transaction context passed to the {@link Database.transaction} callback.
+ *
+ * Use {@link use} to bind existing collection handles to this transaction's
+ * session. All operations on the returned handle participate in the
+ * transaction -- auto-committed on success, auto-rolled-back on error.
+ *
+ * @example
+ * ```ts
+ * await db.transaction(async (tx) => {
+ *   const txUsers = tx.use(users)
+ *   const txPosts = tx.use(posts)
+ *   const user = await txUsers.insertOne({ name: 'Ada' })
+ *   await txPosts.insertOne({ authorId: user._id, title: 'Hello' })
+ * })
+ * ```
+ */
+declare class TransactionContext {
+    /** @internal */
+    private readonly session;
+    /** @internal */
+    constructor(session: ClientSession);
+    /**
+     * 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<TDef extends AnyCollection>(handle: CollectionHandle<TDef>): CollectionHandle<TDef>;
+}
 
 /**
  * Wraps a MongoDB `MongoClient` and `Db`, providing typed collection access
@@ -3187,11 +4267,40 @@ declare class Database {
      */
     syncIndexes(options?: SyncIndexesOptions): Promise<Record<string, SyncIndexesResult>>;
     /**
-     * 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.
+     *
+     * @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' })
+     * })
+     * ```
      *
-     * Stub — full implementation in TASK-106.
+     * @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<T>(_fn: () => Promise<T>): Promise<T>;
+    transaction<T>(fn: TransactionFn<T>): Promise<T>;
     /**
      * Close the underlying `MongoClient` connection. Safe to call even if
      * no connection was established (the driver handles this gracefully).
@@ -4009,6 +5118,68 @@ type WarnableDefinition = {
  */
 declare function checkUnindexedFields(definition: WarnableDefinition, filter: Record<string, unknown>): void;
 
+/**
+ * Walk through Zod wrappers to find the inner schema with ref metadata.
+ *
+ * Mirrors the type-level `UnwrapRef<T>` at runtime. Peels ZodOptional,
+ * ZodNullable, ZodDefault (via `_zod.def.innerType`), and ZodArray
+ * (via `_zod.def.element`).
+ *
+ * @param schema - The Zod schema to unwrap.
+ * @returns The innermost schema after stripping wrappers.
+ *
+ * @example
+ * ```ts
+ * const inner = unwrapRefSchema(Posts.shape.categoryIds)
+ * const ref = getRefMetadata(inner) // { collection: Categories }
+ * ```
+ */
+declare function unwrapRefSchema(schema: z.ZodType): z.ZodType;
+/**
+ * Resolve a `.populate()` call into a `PopulateStep`.
+ *
+ * For top-level fields, inspects the collection's shape directly.
+ * For nested dot-paths, walks previous steps to find the parent
+ * collection definition, then resolves the leaf field in that shape.
+ *
+ * @param definition - The root collection definition.
+ * @param previousSteps - Steps from earlier `.populate()` calls.
+ * @param path - The field path (e.g. `'authorId'` or `'author.companyId'`).
+ * @param as - The output field name (renamed or original).
+ * @param projection - Optional projection to pass to the `$in` query.
+ * @returns A resolved `PopulateStep`.
+ * @throws When the field has no `.ref()` metadata or the parent path is not populated.
+ *
+ * @example
+ * ```ts
+ * const step = resolvePopulateStep(Posts, [], 'authorId', 'author')
+ * // { leafField: 'authorId', as: 'author', targetCollection: Users, ... }
+ * ```
+ */
+declare function resolvePopulateStep(definition: AnyCollection, previousSteps: readonly PopulateStep[], path: string, as: string, projection?: Record<string, 0 | 1 | boolean>): PopulateStep;
+/**
+ * Execute populate steps against a set of documents.
+ *
+ * Processes steps in order. For each step:
+ * 1. Navigate to the parent level for nested paths
+ * 2. Collect unique IDs from the leaf field
+ * 3. Batch query the target collection with `$in`
+ * 4. Merge results back, applying rename if needed
+ *
+ * Mutates the documents in place and returns them.
+ *
+ * @param documents - The documents to populate (mutated in place).
+ * @param steps - The populate steps to execute in order.
+ * @param getCollection - Function to get a native MongoDB Collection by name.
+ * @returns The populated documents.
+ *
+ * @example
+ * ```ts
+ * const docs = await executePopulate(rawDocs, steps, name => db.collection(name))
+ * ```
+ */
+declare function executePopulate(documents: Document[], steps: readonly PopulateStep[], getCollection: (name: string) => Collection): Promise<Document[]>;
+
 /**
  * Convenience namespace that groups all query operators under a single import.
  *
@@ -4317,4 +5488,4 @@ type UpdateFilterOf<TDef extends AnyCollection> = TypedUpdateFilter<InferDocumen
  */
 type SortOf<TDef extends AnyCollection> = TypedSort<InferDocument<TDef>>;
 
-export { $, $addToSet, $and, $avg, $count, $eq, $exists, $first, $gt, $gte, $in, $last, $lt, $lte, $max, $min, $ne, $nin, $nor, $not, $or, $push, $regex, $sum, type Accumulator, type AccumulatorBuilder, type AddToSetEach, type AddToSetFields, AggregatePipeline, type AnyCollection, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionName, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DotPath, type DotPathValue, type ExclusionProjection, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOneProjectionOptions, type FindOptions, type FindProjectionOptions, type GroupByCompoundResult, type GroupByResult, type HandleOf, type IncFields, type InclusionProjection, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferAccumulator, type InferAccumulators, type InferAddedFields, type InferDocument, type InferExpression, type InferInsert, type NarrowFromFilter, type OffsetPage, type OffsetPaginateOptions, type PopFields, type Prettify, type ProjectionResult, type PullFields, type PushFields, type PushModifiers, type RefFields, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, type TypedFilter, TypedFindCursor, type TypedProjection, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UnwindResult, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonAuthError, ZodmonBulkWriteError, ZodmonDocValidationError, ZodmonDuplicateKeyError, ZodmonError, ZodmonIndexError, ZodmonNetworkError, ZodmonNotFoundError, ZodmonQueryError, ZodmonTimeoutError, ZodmonValidationError, ZodmonWriteConflictError, type _DotPathType, type _DotPaths, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, deleteMany, deleteOne, deriveProjectedSchema, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isInclusionProjection, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne, wrapMongoError };
+export { $, $addToSet, $and, $avg, $count, $eq, $exists, $first, $gt, $gte, $in, $last, $lt, $lte, $max, $min, $ne, $nin, $nor, $not, $or, $push, $regex, $sum, type Accumulator, type AccumulatorBuilder, type AddToSetEach, type AddToSetFields, AggregatePipeline, type AnyCollection, type ApplyPopulate, type ApplyPopulateProjected, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionName, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DeepPopulate, type DotPath, type DotPathValue, type DotSubPaths, type ExclusionProjection, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldOrExpr, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOneProjectionOptions, type FindOptions, type FindProjectionOptions, type GroupByCompoundResult, type GroupByNullResult, type GroupByResult, type HandleOf, type IncFields, type InclusionProjection, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferAccumulator, type InferAccumulators, type InferAddedFields, type InferDocument, type InferExpression, type InferInsert, type NarrowFromFilter, type NestedRefPath, type OffsetPage, type OffsetPaginateOptions, type PopFields, PopulateCursor, type PopulateField, type PopulateFieldProjected, PopulateOneOrThrowQuery, PopulateOneQuery, type PopulateProjectionConfig, PopulateRefBuilder, type PopulateStep, type Populated, type Prettify, type ProjectionResult, type PullFields, type PushFields, type PushModifiers, type RefFields, type RefMarker, type RefMetadata, type RenameFields, type ReplaceDots, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, TransactionContext, type TransactionFn, type TypedFilter, TypedFindCursor, type TypedProjection, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UnwindResult, type UnwrapRef, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonAuthError, ZodmonBulkWriteError, ZodmonDocValidationError, ZodmonDuplicateKeyError, ZodmonError, ZodmonIndexError, ZodmonNetworkError, ZodmonNotFoundError, ZodmonQueryError, ZodmonTimeoutError, ZodmonValidationError, ZodmonWriteConflictError, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, createPopulateCursor, deleteMany, deleteOne, deriveProjectedSchema, executePopulate, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isInclusionProjection, isOid, objectId, oid, raw, resolvePopulateStep, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, unwrapRefSchema, updateMany, updateOne, wrapMongoError };