@zodmon/core 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ObjectId, DeleteResult, FindCursor, Collection, UpdateResult, MongoClientOptions } from 'mongodb';
+import { ObjectId, Document, DeleteResult, FindCursor, Collection, UpdateResult, MongoClientOptions } from 'mongodb';
 import { ZodPipe, ZodCustom, ZodTransform, z, ZodDefault } from 'zod';
 
 /**
@@ -253,11 +253,12 @@ type InferInsert<TDef extends {
  * The immutable definition object returned by collection().
  * Holds everything needed to later create a live collection handle.
  *
+ * @typeParam TName - The collection name string literal.
  * @typeParam TShape - The Zod shape defining document fields.
  * @typeParam TIndexes - The compound indexes array type, preserving literal name types.
  */
-type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape, TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]> = {
-    readonly name: string;
+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>>;
     readonly shape: TShape;
     readonly fieldIndexes: FieldIndexDefinition[];
@@ -265,7 +266,7 @@ type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape, TI
     readonly options: Required<Pick<CollectionOptions, 'validation'>> & Omit<CollectionOptions, 'indexes' | 'validation'>;
 };
 /** Erased collection type for use in generic contexts. */
-type AnyCollection = CollectionDefinition<z.core.$ZodShape>;
+type AnyCollection = CollectionDefinition<string, z.core.$ZodShape>;
 /**
  * Extract declared index names from a collection definition.
  *
@@ -304,80 +305,664 @@ type ExtractNames<T extends readonly {
 }[number];
 
 /**
- * Options controlling how {@link syncIndexes} behaves.
+ * Forces TypeScript to eagerly expand mapped/intersection types in tooltips.
+ *
+ * Instead of showing `Omit<{ _id: ObjectId; name: string; salary: number }, "salary">`,
+ * the IDE will display the resolved shape `{ _id: ObjectId; name: string }`.
  *
  * @example
  * ```ts
- * await users.syncIndexes({ dryRun: true })
- * await users.syncIndexes({ dropOrphaned: true })
+ * type Expanded = Prettify<Pick<User, 'name' | 'role'>>
+ * //   ^? { name: string; role: string }
  * ```
  */
-type SyncIndexesOptions = {
-    /**
-     * When `true`, compute the diff without actually creating, dropping, or
-     * modifying any indexes. The returned {@link SyncIndexesResult} shows what
-     * *would* happen.
-     */
-    dryRun?: boolean;
-    /**
-     * When `true`, drop indexes that exist in MongoDB but are not declared in
-     * the schema. Also drops and recreates stale indexes (same key, different
-     * options). When `false` (the default), orphaned and stale indexes are
-     * reported but left untouched.
-     */
-    dropOrphaned?: boolean;
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+
+/**
+ * Type-level marker that carries the target collection type through the
+ * type system. Intersected with the schema return type by `.ref()` so
+ * that `RefFields<T>` (future) can extract ref relationships.
+ *
+ * This is a phantom brand — no runtime value has this property.
+ */
+type RefMarker<TCollection extends AnyCollection = AnyCollection> = {
+    readonly _ref: TCollection;
 };
 /**
- * Describes an index whose key matches a desired index but whose options differ.
+ * Metadata stored in the WeakMap sidecar for schemas marked with `.ref()`.
+ * Holds a reference to the target collection definition object.
+ */
+type RefMetadata = {
+    readonly collection: AnyCollection;
+};
+/**
+ * Module augmentation: adds `.ref()` to all `ZodType` schemas.
  *
- * Returned in {@link SyncIndexesResult.stale} so the caller can decide whether
- * to manually reconcile or re-run with `dropOrphaned: true`.
+ * The intersection constraint `this['_zod']['output'] extends InferDocument<TCollection>['_id']`
+ * ensures compile-time type safety: the field's output type must match the
+ * target collection's `_id` type. Mismatches produce a type error.
+ *
+ * Supports both default ObjectId `_id` and custom `_id` types (string, nanoid, etc.):
+ * - `objectId().ref(Users)` compiles when Users has ObjectId `_id`
+ * - `z.string().ref(Orgs)` compiles when Orgs has string `_id`
+ * - `z.string().ref(Users)` is a type error (string ≠ ObjectId)
+ * - `objectId().ref(Orgs)` is a type error (ObjectId ≠ string)
+ */
+declare module 'zod' {
+    interface ZodType {
+        /**
+         * Declare a typed foreign key reference to another collection.
+         *
+         * Stores the target collection definition in metadata for runtime
+         * populate resolution, and brands the return type with
+         * `RefMarker<TCollection>` so `RefFields<T>` can extract refs
+         * at the type level.
+         *
+         * The field's output type must match the target collection's `_id` type.
+         * Mismatched types produce a compile error.
+         *
+         * Apply `.ref()` before wrapper methods like `.optional()` or `.nullable()`:
+         * `objectId().ref(Users).optional()` — not `objectId().optional().ref(Users)`.
+         *
+         * @param collection - The target collection definition object.
+         * @returns The same schema instance, branded with the ref marker.
+         *
+         * @example
+         * ```ts
+         * const Posts = collection('posts', {
+         *   authorId: objectId().ref(Users),
+         *   title: z.string(),
+         * })
+         * ```
+         */
+        ref<TCollection extends AnyCollection>(collection: TCollection & (this['_zod']['output'] extends InferDocument<TCollection>['_id'] ? unknown : never)): this & RefMarker<TCollection>;
+    }
+}
+/**
+ * Retrieve the ref metadata attached to a Zod schema, if any.
+ *
+ * Returns `undefined` when the schema was never marked with `.ref()`.
+ *
+ * @param schema - The Zod schema to inspect. Accepts `unknown` for
+ *   convenience; non-object values safely return `undefined`.
+ * @returns The {@link RefMetadata} for the schema, or `undefined`.
  *
  * @example
  * ```ts
- * const result = await users.syncIndexes()
- * for (const s of result.stale) {
- *   console.log(`${s.name}: key=${JSON.stringify(s.key)}`)
- *   console.log(`  existing=${JSON.stringify(s.existing)}`)
- *   console.log(`  desired=${JSON.stringify(s.desired)}`)
+ * const authorId = objectId().ref(Users)
+ * const meta = getRefMetadata(authorId)
+ * // => { collection: Users }
+ * ```
+ */
+declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
+
+/**
+ * Branded wrapper for accumulator expressions used inside `groupBy`.
+ *
+ * Carries the MongoDB accumulator expression at runtime and the inferred
+ * result type `T` at the type level.
+ *
+ * @example
+ * ```ts
+ * const acc: Accumulator<number> = {
+ * 	__accum: true,
+ * 	expr: { $sum: '$price' },
  * }
  * ```
  */
-type StaleIndex = {
-    /** The MongoDB index name (e.g. `'email_1'`). */
-    name: string;
-    /** The index key spec (e.g. `{ email: 1 }`). */
-    key: Record<string, 1 | -1 | 'text'>;
-    /** The relevant options currently set on the existing index. */
-    existing: Record<string, unknown>;
-    /** The options the schema declares for this index. */
-    desired: Record<string, unknown>;
+type Accumulator<T = unknown> = {
+    readonly __accum: true;
+    readonly expr: Document;
+    /** @internal Phantom field — carries the result type at the type level. */
+    readonly _type?: T;
 };
 /**
- * The result of a {@link syncIndexes} call.
+ * Extracts the result type from an `Accumulator<T>`.
  *
- * Every array contains index names. `stale` contains full details so the
- * caller can inspect the mismatch.
+ * @example
+ * ```ts
+ * type Count = InferAccumulator<Accumulator<number>>
+ * //   ^? number
+ * ```
+ */
+type InferAccumulator<T> = T extends Accumulator<infer R> ? R : never;
+/**
+ * Maps an accumulator spec object to its inferred output shape.
+ *
+ * Given `{ count: Accumulator<number>, names: Accumulator<string[]> }`,
+ * produces `{ count: number, names: string[] }`.
  *
  * @example
  * ```ts
- * const result = await users.syncIndexes()
- * console.log('created:', result.created)
- * console.log('dropped:', result.dropped)
- * console.log('skipped:', result.skipped)
- * console.log('stale:', result.stale.map(s => s.name))
+ * type Spec = {
+ * 	count: Accumulator<number>
+ * 	total: Accumulator<number>
+ * }
+ * type Result = InferAccumulators<Spec>
+ * //   ^? { count: number; total: number }
  * ```
  */
-type SyncIndexesResult = {
-    /** Names of indexes that were created (or would be created in dryRun mode). */
-    created: string[];
-    /** Names of indexes that were dropped (or would be dropped in dryRun mode). */
-    dropped: string[];
-    /** Names of indexes that already existed with matching options — no action taken. */
-    skipped: string[];
-    /** Indexes whose key matches a desired spec but whose options differ. */
-    stale: StaleIndex[];
+type InferAccumulators<T extends Record<string, Accumulator>> = {
+    [K in keyof T]: InferAccumulator<T[K]>;
 };
+/**
+ * Field reference string prefixed with `$`, constrained to keys of `T`.
+ *
+ * @example
+ * ```ts
+ * type OrderRef = FieldRef<{ price: number; qty: number }>
+ * //   ^? '$price' | '$qty'
+ * ```
+ */
+type FieldRef<T> = `$${keyof T & string}`;
+/**
+ * Typed accumulator factory passed to the `groupBy` callback.
+ *
+ * Each method constrains field names to `keyof T & string`, providing
+ * IDE autocomplete and compile-time validation. Return types resolve
+ * to the actual field type (`T[K]`), not `unknown`.
+ *
+ * @typeParam T - The current pipeline output document type.
+ *
+ * @example
+ * ```ts
+ * users.aggregate()
+ *   .groupBy('role', acc => ({
+ *     minSalary: acc.min('salary'),   // Accumulator<number>
+ *     firstName: acc.first('name'),   // Accumulator<string>
+ *     allNames: acc.push('name'),     // Accumulator<string[]>
+ *     count: acc.count(),             // Accumulator<number>
+ *   }))
+ * ```
+ */
+type AccumulatorBuilder<T> = {
+    /** Count documents in each group. Always returns `Accumulator<number>`. */
+    count(): Accumulator<number>;
+    /** Sum a numeric field. Always returns `Accumulator<number>`. */
+    sum<K extends keyof T & string>(field: K): Accumulator<number>;
+    /** Sum a literal number per document. Always returns `Accumulator<number>`. */
+    sum(value: number): Accumulator<number>;
+    /** Average a numeric field. Always returns `Accumulator<number>`. */
+    avg<K extends keyof T & string>(field: K): Accumulator<number>;
+    /** Minimum value of a field. Returns `Accumulator<T[K]>`. */
+    min<K extends keyof T & string>(field: K): Accumulator<T[K]>;
+    /** Maximum value of a field. Returns `Accumulator<T[K]>`. */
+    max<K extends keyof T & string>(field: K): Accumulator<T[K]>;
+    /** First value in each group (by document order). Returns `Accumulator<T[K]>`. */
+    first<K extends keyof T & string>(field: K): Accumulator<T[K]>;
+    /** Last value in each group (by document order). Returns `Accumulator<T[K]>`. */
+    last<K extends keyof T & string>(field: K): Accumulator<T[K]>;
+    /** Collect values into an array (with duplicates). Returns `Accumulator<T[K][]>`. */
+    push<K extends keyof T & string>(field: K): Accumulator<T[K][]>;
+    /** Collect unique values into an array. Returns `Accumulator<T[K][]>`. */
+    addToSet<K extends keyof T & string>(field: K): Accumulator<T[K][]>;
+};
+/**
+ * Resolves the document field type from a `$`-prefixed field reference.
+ *
+ * @example
+ * ```ts
+ * type Order = { price: number; name: string }
+ * type PriceType = FieldRefType<Order, '$price'>
+ * //   ^? number
+ * ```
+ */
+type FieldRefType<T, F extends string> = F extends `$${infer K}` ? K extends keyof T ? T[K] : never : never;
+/**
+ * Output shape of a single-field `groupBy` stage.
+ *
+ * The `_id` field holds the grouped-by field's value, and the rest of the
+ * shape comes from the inferred accumulator types.
+ *
+ * @example
+ * ```ts
+ * type Result = GroupByResult<Order, 'status', { count: Accumulator<number> }>
+ * //   ^? { _id: string; count: number }
+ * ```
+ */
+type GroupByResult<T, K extends keyof T, TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: T[K];
+} & InferAccumulators<TAccum>>;
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * type Result = GroupByCompoundResult<Order, 'status' | 'region', { count: Accumulator<number> }>
+ * //   ^? { _id: Pick<Order, 'status' | 'region'>; count: number }
+ * ```
+ */
+type GroupByCompoundResult<T, K extends keyof T, TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: Prettify<Pick<T, K>>;
+} & InferAccumulators<TAccum>>;
+/**
+ * Output shape after unwinding an array field.
+ *
+ * The unwound field's type changes from `Array<E>` to `E`; all other
+ * fields are preserved as-is.
+ *
+ * @example
+ * ```ts
+ * type Order = { items: string[]; total: number }
+ * type Unwound = UnwindResult<Order, 'items'>
+ * //   ^? { items: string; total: number }
+ * ```
+ */
+type UnwindResult<T, K extends keyof T> = {
+    [P in keyof T]: P extends K ? (T[P] extends ReadonlyArray<infer E> ? E : T[P]) : T[P];
+};
+/**
+ * Narrows document field types based on a filter expression.
+ *
+ * Inspects each field in the filter for value-constraining operators
+ * (`$eq`, `$in`, `$ne`, `$nin`, or direct equality) and narrows the
+ * corresponding field type in the output. Fields not mentioned in the
+ * filter, or filtered with unsupported operators, keep their original type.
+ *
+ * Used internally by {@link AggregatePipeline.match} for automatic
+ * type narrowing (Tier 2). Requires `as const` on array literals
+ * for `$in` / `$nin` inference.
+ *
+ * @example
+ * ```ts
+ * type Narrowed = NarrowFromFilter<Employee, { role: 'engineer' }>
+ * //   ^? { ..., role: 'engineer', ... }
+ *
+ * type Subset = NarrowFromFilter<Employee, { role: { $in: readonly ['engineer', 'designer'] } }>
+ * //   ^? { ..., role: 'engineer' | 'designer', ... }
+ *
+ * type Excluded = NarrowFromFilter<Employee, { role: { $ne: 'intern' } }>
+ * //   ^? { ..., role: 'engineer' | 'manager' | 'designer', ... }
+ * ```
+ */
+type NarrowFromFilter<T, F> = {
+    [K in keyof T]: K extends keyof F ? F[K] extends T[K] ? F[K] : F[K] extends {
+        $eq: infer V extends T[K];
+    } ? V : F[K] extends {
+        $in: ReadonlyArray<infer V extends T[K]>;
+    } ? V : F[K] extends {
+        $ne: infer V extends T[K];
+    } ? Exclude<T[K], V> : F[K] extends {
+        $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.
+ *
+ * @example
+ * ```ts
+ * CollectionName<typeof Departments> // → 'departments'
+ * ```
+ */
+type CollectionName<TDef extends AnyCollection> = TDef['name'];
+/**
+ * Branded wrapper for computed expressions used inside `addFields`.
+ *
+ * Carries the MongoDB expression at runtime and the inferred
+ * result type `T` at the type level.
+ *
+ * @example
+ * ```ts
+ * const yearExpr: Expression<number> = {
+ * 	__expr: true,
+ * 	value: { $year: '$hiredAt' },
+ * }
+ * ```
+ */
+type Expression<T = unknown> = {
+    readonly __expr: true;
+    readonly value: Document;
+    /** @internal Phantom field — carries the result type at the type level. */
+    readonly _type?: T;
+};
+/**
+ * Unwrap an `Expression<T>` to its result type `T`.
+ * Non-Expression values resolve to `unknown`.
+ *
+ * @example
+ * ```ts
+ * type N = InferExpression<Expression<number>> // → number
+ * type U = InferExpression<{ $year: string }>  // → unknown
+ * ```
+ */
+type InferExpression<T> = T extends Expression<infer R> ? R : unknown;
+/**
+ * Map an added-fields spec to its resolved output shape.
+ *
+ * `Expression<V>` values unwrap to `V`. Raw expression objects resolve
+ * to `unknown`, signaling that type information is lost.
+ *
+ * @example
+ * ```ts
+ * type Spec = { year: Expression<number>; raw: { $year: string } }
+ * type Result = InferAddedFields<Spec>
+ * //   ^? { year: number; raw: unknown }
+ * ```
+ */
+type InferAddedFields<T extends Record<string, unknown>> = {
+    [K in keyof T]: InferExpression<T[K]>;
+};
+/**
+ * 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.
+ *
+ * @typeParam T - The current pipeline output document type.
+ *
+ * @example
+ * ```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>
+ *   }))
+ * ```
+ */
+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>;
+};
+
+/**
+ * Counts the number of documents in each group.
+ *
+ * Equivalent to `{ $sum: 1 }` in a MongoDB `$group` stage.
+ *
+ * @returns An `Accumulator<number>` that counts documents.
+ *
+ * @example
+ * ```ts
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('status', { count: $count() })
+ * ```
+ */
+declare const $count: () => Accumulator<number>;
+/**
+ * Sums numeric values across documents in each group.
+ *
+ * Accepts either a `$`-prefixed field reference or a literal number.
+ *
+ * @param field - A `$field` reference to a numeric field, or a literal number.
+ * @returns An `Accumulator<number>`.
+ *
+ * @example
+ * ```ts
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('status', {
+ * 		total: $sum('$amount'),
+ * 		fixed: $sum(1),
+ * 	})
+ * ```
+ */
+declare const $sum: (field: `$${string}` | number) => Accumulator<number>;
+/**
+ * Computes the average of numeric values across documents in each group.
+ *
+ * @param field - A `$field` reference to a numeric field.
+ * @returns An `Accumulator<number>`.
+ *
+ * @example
+ * ```ts
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('category', { avgPrice: $avg('$price') })
+ * ```
+ */
+declare const $avg: (field: `$${string}`) => Accumulator<number>;
+/**
+ * Returns the minimum value across documents in each group.
+ *
+ * For full type safety, prefer the callback builder (`acc.min('price')`).
+ * The standalone form accepts an explicit result type `R` for manual typing.
+ *
+ * @typeParam R - The expected result type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R>`.
+ *
+ * @example
+ * ```ts
+ * // Tier 2 — explicit result type
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('category', { cheapest: $min<number>('$price') })
+ *
+ * // Tier 1 — callback builder (recommended)
+ * orders.aggregate()
+ * 	.groupBy('category', acc => ({ cheapest: acc.min('price') }))
+ * ```
+ */
+declare const $min: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+/**
+ * Returns the maximum value across documents in each group.
+ *
+ * For full type safety, prefer the callback builder (`acc.max('price')`).
+ * The standalone form accepts an explicit result type `R` for manual typing.
+ *
+ * @typeParam R - The expected result type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R>`.
+ *
+ * @example
+ * ```ts
+ * // Tier 2 — explicit result type
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('category', { priciest: $max<number>('$price') })
+ *
+ * // Tier 1 — callback builder (recommended)
+ * orders.aggregate()
+ * 	.groupBy('category', acc => ({ priciest: acc.max('price') }))
+ * ```
+ */
+declare const $max: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+/**
+ * Returns the first value in each group according to the document order.
+ *
+ * For full type safety, prefer the callback builder (`acc.first('name')`).
+ * The standalone form accepts an explicit result type `R` for manual typing.
+ *
+ * @typeParam R - The expected result type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R>`.
+ *
+ * @example
+ * ```ts
+ * // Tier 2 — explicit result type
+ * const pipeline = orders.aggregate()
+ * 	.sort({ createdAt: 1 })
+ * 	.groupBy('status', { earliest: $first<Date>('$createdAt') })
+ *
+ * // Tier 1 — callback builder (recommended)
+ * orders.aggregate()
+ * 	.sort({ createdAt: 1 })
+ * 	.groupBy('status', acc => ({ earliest: acc.first('createdAt') }))
+ * ```
+ */
+declare const $first: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+/**
+ * Returns the last value in each group according to the document order.
+ *
+ * For full type safety, prefer the callback builder (`acc.last('name')`).
+ * The standalone form accepts an explicit result type `R` for manual typing.
+ *
+ * @typeParam R - The expected result type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R>`.
+ *
+ * @example
+ * ```ts
+ * // Tier 2 — explicit result type
+ * const pipeline = orders.aggregate()
+ * 	.sort({ createdAt: -1 })
+ * 	.groupBy('status', { latest: $last<Date>('$createdAt') })
+ *
+ * // Tier 1 — callback builder (recommended)
+ * orders.aggregate()
+ * 	.sort({ createdAt: -1 })
+ * 	.groupBy('status', acc => ({ latest: acc.last('createdAt') }))
+ * ```
+ */
+declare const $last: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+/**
+ * Pushes values into an array for each group.
+ *
+ * May contain duplicates. Use `$addToSet` for unique values.
+ * For full type safety, prefer the callback builder (`acc.push('name')`).
+ *
+ * @typeParam R - The element type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R[]>`.
+ *
+ * @example
+ * ```ts
+ * // Tier 2 — explicit element type
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('status', { items: $push<string>('$name') })
+ *
+ * // Tier 1 — callback builder (recommended)
+ * orders.aggregate()
+ * 	.groupBy('status', acc => ({ items: acc.push('name') }))
+ * ```
+ */
+declare const $push: <R = unknown>(field: `$${string}`) => Accumulator<R[]>;
+/**
+ * Collects unique values into an array for each group (set semantics).
+ *
+ * Like `$push` but deduplicates.
+ * For full type safety, prefer the callback builder (`acc.addToSet('tag')`).
+ *
+ * @typeParam R - The element type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R[]>`.
+ *
+ * @example
+ * ```ts
+ * // Tier 2 — explicit element type
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('category', { uniqueTags: $addToSet<string>('$tag') })
+ *
+ * // Tier 1 — callback builder (recommended)
+ * orders.aggregate()
+ * 	.groupBy('category', acc => ({ uniqueTags: acc.addToSet('tag') }))
+ * ```
+ */
+declare const $addToSet: <R = unknown>(field: `$${string}`) => Accumulator<R[]>;
+/**
+ * Create a typed accumulator builder for use inside `groupBy` callbacks.
+ *
+ * The builder adds the `$` prefix to field names automatically and returns
+ * properly typed `Accumulator<T[K]>` values. Primarily used internally by
+ * `AggregatePipeline.groupBy` — 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 `AccumulatorBuilder<T>` with methods for each MongoDB accumulator.
+ *
+ * @example
+ * ```ts
+ * const acc = createAccumulatorBuilder<{ salary: number; name: string }>()
+ * acc.min('salary')  // { __accum: true, expr: { $min: '$salary' } }
+ * acc.push('name')   // { __accum: true, expr: { $push: '$name' } }
+ * ```
+ */
+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.
+ *
+ * @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] } }
+ * ```
+ */
+declare function createExpressionBuilder<T>(): ExpressionBuilder<T>;
 
 /**
  * Comparison operators for a field value of type `V`.
@@ -409,10 +994,10 @@ type ComparisonOperators<V> = {
     $lt?: V;
     /** Matches values less than or equal to the specified value. */
     $lte?: V;
-    /** Matches any value in the specified array. */
-    $in?: V[];
-    /** Matches none of the values in the specified array. */
-    $nin?: V[];
+    /** Matches any value in the specified array. Accepts `as const` arrays for type narrowing. */
+    $in?: readonly V[];
+    /** Matches none of the values in the specified array. Accepts `as const` arrays for type narrowing. */
+    $nin?: readonly V[];
     /** Matches documents where the field exists (`true`) or does not exist (`false`). */
     $exists?: boolean;
     /** Negates a comparison operator. */
@@ -1240,6 +1825,82 @@ declare function updateMany<TDef extends AnyCollection>(handle: CollectionHandle
  */
 declare function findOneAndUpdate<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: FindOneAndUpdateOptions): Promise<InferDocument<TDef> | null>;
 
+/**
+ * Options controlling how {@link syncIndexes} behaves.
+ *
+ * @example
+ * ```ts
+ * await users.syncIndexes({ dryRun: true })
+ * await users.syncIndexes({ dropOrphaned: true })
+ * ```
+ */
+type SyncIndexesOptions = {
+    /**
+     * When `true`, compute the diff without actually creating, dropping, or
+     * modifying any indexes. The returned {@link SyncIndexesResult} shows what
+     * *would* happen.
+     */
+    dryRun?: boolean;
+    /**
+     * When `true`, drop indexes that exist in MongoDB but are not declared in
+     * the schema. Also drops and recreates stale indexes (same key, different
+     * options). When `false` (the default), orphaned and stale indexes are
+     * reported but left untouched.
+     */
+    dropOrphaned?: boolean;
+};
+/**
+ * Describes an index whose key matches a desired index but whose options differ.
+ *
+ * Returned in {@link SyncIndexesResult.stale} so the caller can decide whether
+ * to manually reconcile or re-run with `dropOrphaned: true`.
+ *
+ * @example
+ * ```ts
+ * const result = await users.syncIndexes()
+ * for (const s of result.stale) {
+ *   console.log(`${s.name}: key=${JSON.stringify(s.key)}`)
+ *   console.log(`  existing=${JSON.stringify(s.existing)}`)
+ *   console.log(`  desired=${JSON.stringify(s.desired)}`)
+ * }
+ * ```
+ */
+type StaleIndex = {
+    /** The MongoDB index name (e.g. `'email_1'`). */
+    name: string;
+    /** The index key spec (e.g. `{ email: 1 }`). */
+    key: Record<string, 1 | -1 | 'text'>;
+    /** The relevant options currently set on the existing index. */
+    existing: Record<string, unknown>;
+    /** The options the schema declares for this index. */
+    desired: Record<string, unknown>;
+};
+/**
+ * The result of a {@link syncIndexes} call.
+ *
+ * Every array contains index names. `stale` contains full details so the
+ * caller can inspect the mismatch.
+ *
+ * @example
+ * ```ts
+ * const result = await users.syncIndexes()
+ * console.log('created:', result.created)
+ * console.log('dropped:', result.dropped)
+ * console.log('skipped:', result.skipped)
+ * console.log('stale:', result.stale.map(s => s.name))
+ * ```
+ */
+type SyncIndexesResult = {
+    /** Names of indexes that were created (or would be created in dryRun mode). */
+    created: string[];
+    /** Names of indexes that were dropped (or would be dropped in dryRun mode). */
+    dropped: string[];
+    /** Names of indexes that already existed with matching options — no action taken. */
+    skipped: string[];
+    /** Indexes whose key matches a desired spec but whose options differ. */
+    stale: StaleIndex[];
+};
+
 /**
  * Typed wrapper around a MongoDB driver `Collection`.
  *
@@ -1499,14 +2160,578 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      *
      * @example
      * ```ts
-     * // Dry run to preview changes without modifying the database
-     * const diff = await users.syncIndexes({ dryRun: true })
-     * console.log('Would create:', diff.created)
-     * console.log('Would drop:', diff.dropped)
+     * // Dry run to preview changes without modifying the database
+     * const diff = await users.syncIndexes({ dryRun: true })
+     * console.log('Would create:', diff.created)
+     * console.log('Would drop:', diff.dropped)
+     * ```
+     */
+    syncIndexes(options?: SyncIndexesOptions): Promise<SyncIndexesResult>;
+    /**
+     * Start a type-safe aggregation pipeline on this collection.
+     *
+     * Returns a fluent pipeline builder that tracks the output document
+     * shape through each stage. The pipeline is lazy — no query executes
+     * until a terminal method (`toArray`, `for await`, `explain`) is called.
+     *
+     * @returns A new pipeline builder starting with this collection's document type.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.aggregate()
+     *   .match({ role: 'admin' })
+     *   .groupBy('role', { count: $count() })
+     *   .toArray()
+     * ```
+     */
+    aggregate(): AggregatePipeline<TDef, InferDocument<TDef>>;
+}
+
+/**
+ * Immutable aggregation pipeline builder for type-safe MongoDB aggregations.
+ *
+ * Each stage method returns a **new** `AggregatePipeline` instance — the
+ * original is never mutated. This makes it safe to branch from a shared base
+ * pipeline without cross-contamination.
+ *
+ * Use {@link aggregate} to create a pipeline from a {@link CollectionHandle},
+ * or call `raw()` to append arbitrary stages.
+ *
+ * @typeParam TDef - The collection definition type, used to derive document types.
+ * @typeParam TOutput - The current output document type (changes as stages transform the shape).
+ *
+ * @example
+ * ```ts
+ * const results = await aggregate(users)
+ *   .raw({ $match: { role: 'admin' } })
+ *   .raw({ $sort: { name: 1 } })
+ *   .toArray()
+ * ```
+ */
+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[]);
+    /**
+     * Append an arbitrary aggregation stage to the pipeline (escape hatch).
+     *
+     * Returns a new pipeline instance with the stage appended — the
+     * original pipeline is not modified.
+     *
+     * Optionally accepts a type parameter `TNew` to change the output
+     * type when the stage transforms the document shape.
+     *
+     * @typeParam TNew - The output type after this stage. Defaults to the current output type.
+     * @param stage - A raw MongoDB aggregation stage document (e.g. `{ $match: { ... } }`).
+     * @returns A new pipeline with the stage appended.
+     *
+     * @example
+     * ```ts
+     * const admins = aggregate(users)
+     *   .raw({ $match: { role: 'admin' } })
+     *   .toArray()
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Change output type with a $project stage
+     * const names = aggregate(users)
+     *   .raw<{ name: string }>({ $project: { name: 1, _id: 0 } })
+     *   .toArray()
+     * ```
+     */
+    raw<TNew = TOutput>(stage: Document): AggregatePipeline<TDef, TNew>;
+    /**
+     * Execute the pipeline and return all results as an array.
+     *
+     * @returns A promise resolving to the array of output documents.
+     *
+     * @example
+     * ```ts
+     * const results = await aggregate(users)
+     *   .raw({ $match: { age: { $gte: 18 } } })
+     *   .toArray()
+     * ```
+     */
+    toArray(): Promise<TOutput[]>;
+    /**
+     * Stream pipeline results one document at a time via `for await...of`.
+     *
+     * @returns An async generator yielding output documents.
+     *
+     * @example
+     * ```ts
+     * for await (const user of aggregate(users).raw({ $match: { role: 'admin' } })) {
+     *   console.log(user.name)
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<TOutput>;
+    /**
+     * Return the query execution plan without running the pipeline.
+     *
+     * Useful for debugging and understanding how MongoDB will process
+     * the pipeline stages.
+     *
+     * @returns A promise resolving to the explain output document.
+     *
+     * @example
+     * ```ts
+     * const plan = await aggregate(users)
+     *   .raw({ $match: { role: 'admin' } })
+     *   .explain()
+     * console.log(plan)
+     * ```
+     */
+    explain(): Promise<Document>;
+    /**
+     * Filter documents using a type-safe match expression.
+     *
+     * Appends a `$match` stage to the pipeline. The filter is constrained
+     * to the current output type, so only valid fields and operators are accepted.
+     *
+     * Supports two forms of type narrowing:
+     *
+     * **Tier 1 — Explicit type parameter:**
+     * ```ts
+     * .match<{ role: 'engineer' | 'designer' }>({ role: { $in: ['engineer', 'designer'] } })
+     * // role narrows to 'engineer' | 'designer'
+     * ```
+     *
+     * **Tier 2 — Automatic inference from filter literals:**
+     * ```ts
+     * .match({ role: 'engineer' })           // role narrows to 'engineer'
+     * .match({ role: { $ne: 'intern' } })    // role narrows to Exclude<Role, 'intern'>
+     * .match({ role: { $in: ['engineer', 'designer'] as const } })  // needs as const
+     * ```
+     *
+     * When no type parameter is provided and the filter doesn't contain
+     * inferrable literals, the output type is unchanged (backward compatible).
+     *
+     * @typeParam TNarrow - Optional object mapping field names to narrowed types. Must be a subtype of the corresponding fields in TOutput.
+     * @typeParam F - Inferred from the filter argument. Do not provide explicitly.
+     * @param filter - A type-safe filter for the current output type.
+     * @returns A new pipeline with the `$match` stage appended and output type narrowed.
+     *
+     * @example
+     * ```ts
+     * // Explicit narrowing
+     * const filtered = await users.aggregate()
+     *   .match<{ role: 'engineer' }>({ role: 'engineer' })
+     *   .toArray()
+     * // filtered[0].role → 'engineer'
+     *
+     * // Automatic narrowing with $in (requires as const)
+     * const subset = await users.aggregate()
+     *   .match({ role: { $in: ['engineer', 'designer'] as const } })
+     *   .toArray()
+     * // subset[0].role → 'engineer' | 'designer'
+     * ```
+     */
+    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>>;
+    /**
+     * Sort documents by one or more fields.
+     *
+     * Appends a `$sort` stage. Keys are constrained to `keyof TOutput & string`
+     * and values must be `1` (ascending) or `-1` (descending).
+     *
+     * @param spec - A sort specification mapping field names to sort direction.
+     * @returns A new pipeline with the `$sort` stage appended.
+     *
+     * @example
+     * ```ts
+     * const sorted = await aggregate(users)
+     *   .sort({ age: -1, name: 1 })
+     *   .toArray()
+     * ```
+     */
+    sort(spec: Partial<Record<keyof TOutput & string, 1 | -1>>): AggregatePipeline<TDef, TOutput>;
+    /**
+     * Skip a number of documents in the pipeline.
+     *
+     * Appends a `$skip` stage. Commonly used with {@link limit} for pagination.
+     *
+     * @param n - The number of documents to skip.
+     * @returns A new pipeline with the `$skip` stage appended.
+     *
+     * @example
+     * ```ts
+     * // Page 2 (10 items per page)
+     * const page2 = await aggregate(users)
+     *   .sort({ name: 1 })
+     *   .skip(10)
+     *   .limit(10)
+     *   .toArray()
+     * ```
+     */
+    skip(n: number): AggregatePipeline<TDef, TOutput>;
+    /**
+     * Limit the number of documents passing through the pipeline.
+     *
+     * Appends a `$limit` stage. Commonly used with {@link skip} for pagination,
+     * or after {@link sort} to get top/bottom N results.
+     *
+     * @param n - The maximum number of documents to pass through.
+     * @returns A new pipeline with the `$limit` stage appended.
+     *
+     * @example
+     * ```ts
+     * const top5 = await aggregate(users)
+     *   .sort({ score: -1 })
+     *   .limit(5)
+     *   .toArray()
+     * ```
+     */
+    limit(n: number): AggregatePipeline<TDef, TOutput>;
+    /**
+     * Include only specified fields in the output.
+     *
+     * Appends a `$project` stage with inclusion (`1`) for each key.
+     * The `_id` field is always included. The output type narrows to
+     * `Pick<TOutput, K | '_id'>`.
+     *
+     * @param spec - An object mapping field names to `1` for inclusion.
+     * @returns A new pipeline with the `$project` stage appended.
+     *
+     * @example
+     * ```ts
+     * const namesOnly = await aggregate(users)
+     *   .project({ name: 1 })
+     *   .toArray()
+     * // [{ _id: ..., name: 'Ada' }, ...]
+     * ```
+     */
+    project<K extends keyof TOutput & string>(spec: Record<K, 1>): AggregatePipeline<TDef, Prettify<Pick<TOutput, K | ('_id' extends keyof TOutput ? '_id' : never)>>>;
+    /**
+     * Variadic shorthand for {@link project} — pick fields to include.
+     *
+     * Generates a `$project` stage that includes only the listed fields
+     * (plus `_id`). Equivalent to `.project({ field1: 1, field2: 1 })`.
+     *
+     * @param fields - Field names to include in the output.
+     * @returns A new pipeline with the `$project` stage appended.
+     *
+     * @example
+     * ```ts
+     * const namesAndRoles = await aggregate(users)
+     *   .pick('name', 'role')
+     *   .toArray()
+     * ```
+     */
+    pick<K extends keyof TOutput & string>(...fields: K[]): AggregatePipeline<TDef, Prettify<Pick<TOutput, K | ('_id' extends keyof TOutput ? '_id' : never)>>>;
+    /**
+     * Exclude specified fields from the output.
+     *
+     * Appends a `$project` stage with exclusion (`0`) for each key.
+     * All other fields pass through. The output type becomes `Omit<TOutput, K>`.
+     *
+     * @param fields - Field names to exclude from the output.
+     * @returns A new pipeline with the `$project` stage appended.
+     *
+     * @example
+     * ```ts
+     * const noAge = await aggregate(users)
+     *   .omit('age')
+     *   .toArray()
+     * ```
+     */
+    omit<K extends keyof TOutput & string>(...fields: K[]): AggregatePipeline<TDef, Prettify<Omit<TOutput, K>>>;
+    /**
+     * Group documents by one or more fields with accumulator expressions.
+     *
+     * Accepts accumulators as either a **callback** (recommended) or a plain object.
+     *
+     * The callback receives a typed `AccumulatorBuilder` with full autocomplete
+     * 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 accumulators - A callback `(acc) => ({ ... })` or plain accumulator object.
+     * @returns A new pipeline with the `$group` stage appended.
+     *
+     * @example
+     * ```ts
+     * // Callback style (recommended — full type safety)
+     * const byRole = await aggregate(users)
+     *   .groupBy('role', acc => ({
+     *     count: acc.count(),
+     *     minSalary: acc.min('salary'),   // → number
+     *     firstName: acc.first('name'),   // → string
+     *   }))
+     *   .toArray()
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Object style (backward compatible)
+     * const byRole = await aggregate(users)
+     *   .groupBy('role', { count: $count() })
+     *   .toArray()
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Compound groupBy
+     * const byRoleAndDept = await aggregate(users)
+     *   .groupBy(['role', 'dept'], acc => ({ count: acc.count() }))
+     *   .toArray()
+     * ```
+     */
+    groupBy<K extends keyof TOutput & string, TAccum extends Record<string, Accumulator>>(field: K, accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByResult<TOutput, K, TAccum>>;
+    groupBy<K extends keyof TOutput & string, TAccum extends Record<string, Accumulator>>(field: K[], accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByCompoundResult<TOutput, K, TAccum>>;
+    /**
+     * Add new fields or overwrite existing ones in the output documents.
+     *
+     * **Callback style (recommended)** — the `ExpressionBuilder` provides
+     * autocomplete for field names and infers return types automatically:
+     *
+     * ```ts
+     * employees.aggregate()
+     *   .addFields(expr => ({
+     *     hireYear: expr.year('hiredAt'),       // Expression<number>
+     *     isHighPay: expr.gte('salary', 100_000), // Expression<boolean>
+     *   }))
+     * ```
+     *
+     * **Raw style** — pass MongoDB expression objects directly. Use an
+     * explicit type parameter to preserve type safety:
+     *
+     * ```ts
+     * // Tier 2: explicit type parameter
+     * .addFields<{ hireYear: number }>({ hireYear: { $year: '$hiredAt' } })
+     *
+     * // Tier 3: no type parameter — fields resolve to unknown
+     * .addFields({ hireYear: { $year: '$hiredAt' } })
+     * ```
+     *
+     * @param fields - A callback `(expr) => ({ ... })` or plain fields object.
+     * @returns A new pipeline with the `$addFields` stage appended.
+     *
+     * @example
+     * ```ts
+     * const enriched = await aggregate(employees)
+     *   .addFields(expr => ({
+     *     hireYear: expr.year('hiredAt'),
+     *     monthlySalary: expr.divide('salary', 12),
+     *   }))
+     *   .toArray()
+     * ```
+     */
+    addFields<TFields extends Record<string, Expression>>(fields: (expr: ExpressionBuilder<TOutput>) => TFields): AggregatePipeline<TDef, Prettify<TOutput & InferAddedFields<TFields>>>;
+    addFields<TFields extends Record<string, unknown> = Record<string, unknown>>(fields: TFields): AggregatePipeline<TDef, Prettify<TOutput & TFields>>;
+    /**
+     * Deconstruct an array field, outputting one document per array element.
+     *
+     * Appends an `$unwind` stage. The unwound field's type changes from
+     * `T[]` to `T` in the output type. Documents with empty or missing
+     * arrays are dropped unless `preserveEmpty` is `true`.
+     *
+     * @param field - The name of the array field to unwind.
+     * @param options - Optional settings for the unwind stage.
+     * @param options.preserveEmpty - If `true`, documents with null, missing, or empty arrays are preserved.
+     * @returns A new pipeline with the `$unwind` stage appended.
+     *
+     * @example
+     * ```ts
+     * const flat = await aggregate(orders)
+     *   .unwind('items')
+     *   .toArray()
+     * // Each result has a single `items` value instead of an array
+     * ```
+     */
+    unwind<K extends keyof TOutput & string>(field: K, options?: {
+        preserveEmpty?: boolean;
+    }): AggregatePipeline<TDef, UnwindResult<TOutput, K>>;
+    /**
+     * Join documents from another collection via a `$lookup` stage.
+     *
+     * **Forward lookup** — when the field has `.ref()` metadata pointing to
+     * another collection, resolves the target collection and output type
+     * automatically:
+     *
+     * ```ts
+     * books.aggregate().lookup('authorId').toArray()
+     * // Each book gains an `authors: Author[]` array
+     * ```
+     *
+     * **Reverse lookup** — when the foreign key lives on the *other*
+     * collection, pass the collection definition and the `on` field:
+     *
+     * ```ts
+     * users.aggregate().lookup(Books, { on: 'authorId' }).toArray()
+     * // Each user gains a `books: Book[]` array
+     * ```
+     *
+     * Pass `unwind: true` to flatten the joined array into a single object
+     * (adds a `$unwind` stage with `preserveNullAndEmptyArrays: true`).
+     *
+     * @param fieldOrCollection - A ref-bearing field name (forward) or collection definition (reverse).
+     * @param options - `as` alias, `unwind` flag, and `on` (reverse only).
+     * @returns A new pipeline with `$lookup` (and optionally `$unwind`) appended.
+     *
+     * @example
+     * ```ts
+     * // Forward lookup with custom alias and unwind
+     * const results = await aggregate(books)
+     *   .lookup('authorId', { as: 'author', unwind: true })
+     *   .toArray()
+     * // Each book has a single `author: Author` object
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Reverse lookup: each author gains their books
+     * const results = await aggregate(authors)
+     *   .lookup(Books, { on: 'authorId' })
+     *   .toArray()
+     * // Each author has a `books: Book[]` array
+     * ```
+     */
+    lookup<K extends RefFields<TDef>, TAs extends string = CollectionName<ExtractRefCollection<TDef, K>>>(field: K, options: {
+        as?: TAs;
+        unwind: true;
+    }): AggregatePipeline<TDef, Prettify<TOutput & {
+        [P in TAs]: InferDocument<ExtractRefCollection<TDef, K>>;
+    }>>;
+    lookup<K extends RefFields<TDef>, TAs extends string = CollectionName<ExtractRefCollection<TDef, K>>>(field: K, options?: {
+        as?: TAs;
+        unwind?: false;
+    }): AggregatePipeline<TDef, Prettify<TOutput & {
+        [P in TAs]: InferDocument<ExtractRefCollection<TDef, K>>[];
+    }>>;
+    lookup<TForeignDef extends AnyCollection, TAs extends string = CollectionName<TForeignDef>>(from: TForeignDef, options: {
+        on: keyof InferDocument<TForeignDef> & string;
+        as?: TAs;
+        unwind: true;
+    }): AggregatePipeline<TDef, Prettify<TOutput & {
+        [P in TAs]: InferDocument<TForeignDef>;
+    }>>;
+    lookup<TForeignDef extends AnyCollection, TAs extends string = CollectionName<TForeignDef>>(from: TForeignDef, options: {
+        on: keyof InferDocument<TForeignDef> & string;
+        as?: TAs;
+        unwind?: false;
+    }): AggregatePipeline<TDef, Prettify<TOutput & {
+        [P in TAs]: InferDocument<TForeignDef>[];
+    }>>;
+    /**
+     * Count documents per group, sorted by count descending.
+     *
+     * Shorthand for `.groupBy(field, { count: $count() }).sort({ count: -1 })`.
+     *
+     * @param field - The field to group and count by.
+     * @returns A new pipeline producing `{ _id: TOutput[K], count: number }` results.
+     *
+     * @example
+     * ```ts
+     * const roleCounts = await aggregate(users)
+     *   .countBy('role')
+     *   .toArray()
+     * // [{ _id: 'user', count: 3 }, { _id: 'admin', count: 2 }]
+     * ```
+     */
+    countBy<K extends keyof TOutput & string>(field: K): AggregatePipeline<TDef, Prettify<{
+        _id: TOutput[K];
+        count: number;
+    }>>;
+    /**
+     * Sum a numeric field per group, sorted by total descending.
+     *
+     * Shorthand for `.groupBy(field, { total: $sum('$sumField') }).sort({ total: -1 })`.
+     *
+     * @param field - The field to group by.
+     * @param sumField - The numeric field to sum.
+     * @returns A new pipeline producing `{ _id: TOutput[K], total: number }` results.
+     *
+     * @example
+     * ```ts
+     * const revenueByCategory = await aggregate(orders)
+     *   .sumBy('category', 'amount')
+     *   .toArray()
+     * // [{ _id: 'electronics', total: 5000 }, ...]
+     * ```
+     */
+    sumBy<K extends keyof TOutput & string, S extends keyof TOutput & string>(field: K, sumField: S): AggregatePipeline<TDef, Prettify<{
+        _id: TOutput[K];
+        total: number;
+    }>>;
+    /**
+     * Sort by a single field with a friendly direction name.
+     *
+     * Shorthand for `.sort({ [field]: direction === 'desc' ? -1 : 1 })`.
+     *
+     * @param field - The field to sort by.
+     * @param direction - Sort direction: `'asc'` (default) or `'desc'`.
+     * @returns A new pipeline with the `$sort` stage appended.
+     *
+     * @example
+     * ```ts
+     * const youngest = await aggregate(users)
+     *   .sortBy('age')
+     *   .toArray()
+     * ```
+     */
+    sortBy(field: keyof TOutput & string, direction?: 'asc' | 'desc'): AggregatePipeline<TDef, TOutput>;
+    /**
+     * Return the top N documents sorted by a field descending.
+     *
+     * Shorthand for `.sort({ [by]: -1 }).limit(n)`.
+     *
+     * @param n - The number of documents to return.
+     * @param options - An object with a `by` field specifying the sort key.
+     * @returns A new pipeline with `$sort` and `$limit` stages appended.
+     *
+     * @example
+     * ```ts
+     * const top3 = await aggregate(users)
+     *   .top(3, { by: 'score' })
+     *   .toArray()
+     * ```
+     */
+    top(n: number, options: {
+        by: keyof TOutput & string;
+    }): AggregatePipeline<TDef, TOutput>;
+    /**
+     * Return the bottom N documents sorted by a field ascending.
+     *
+     * Shorthand for `.sort({ [by]: 1 }).limit(n)`.
+     *
+     * @param n - The number of documents to return.
+     * @param options - An object with a `by` field specifying the sort key.
+     * @returns A new pipeline with `$sort` and `$limit` stages appended.
+     *
+     * @example
+     * ```ts
+     * const bottom3 = await aggregate(users)
+     *   .bottom(3, { by: 'score' })
+     *   .toArray()
      * ```
      */
-    syncIndexes(options?: SyncIndexesOptions): Promise<SyncIndexesResult>;
+    bottom(n: number, options: {
+        by: keyof TOutput & string;
+    }): AggregatePipeline<TDef, TOutput>;
 }
+/**
+ * Create a new aggregation pipeline for a collection.
+ *
+ * Returns an empty pipeline that can be extended with stage methods
+ * like `raw()`, or future typed stages (`match`, `project`, etc.).
+ *
+ * @param handle - A typed collection handle obtained from `db.use()`.
+ * @returns A new empty `AggregatePipeline` whose output type is the collection's document type.
+ *
+ * @example
+ * ```ts
+ * const users = db.use(Users)
+ * const admins = await aggregate(users)
+ *   .raw({ $match: { role: 'admin' } })
+ *   .toArray()
+ * ```
+ */
+declare function aggregate<TDef extends AnyCollection>(handle: CollectionHandle<TDef>): AggregatePipeline<TDef, InferDocument<TDef>>;
 
 /**
  * Wraps a MongoDB `MongoClient` and `Db`, providing typed collection access
@@ -1540,7 +2765,7 @@ declare class Database {
      * @param def - A collection definition created by `collection()`.
      * @returns A typed collection handle for CRUD operations.
      */
-    use<TShape extends z.core.$ZodShape, TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]>(def: CollectionDefinition<TShape, TIndexes>): CollectionHandle<CollectionDefinition<TShape, TIndexes>>;
+    use<TName extends string, TShape extends z.core.$ZodShape, TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]>(def: CollectionDefinition<TName, TShape, TIndexes>): CollectionHandle<CollectionDefinition<TName, TShape, TIndexes>>;
     /**
      * Synchronize indexes for all registered collections with MongoDB.
      *
@@ -1636,9 +2861,9 @@ declare function extractFieldIndexes(shape: z.core.$ZodShape): FieldIndexDefinit
  * })
  * ```
  */
-declare function collection<TShape extends z.core.$ZodShape, const TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]>(name: string, shape: TShape, options?: Omit<CollectionOptions<Extract<keyof TShape, string>>, 'indexes'> & {
+declare function collection<TName extends string, TShape extends z.core.$ZodShape, const TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]>(name: TName, shape: TShape, options?: Omit<CollectionOptions<Extract<keyof TShape, string>>, 'indexes'> & {
     indexes?: TIndexes;
-}): CollectionDefinition<TShape, [...TIndexes]>;
+}): CollectionDefinition<TName, TShape, [...TIndexes]>;
 
 type IndexDirection = 1 | -1;
 type CompoundIndexOptions = NonNullable<CompoundIndexDefinition['options']>;
@@ -1752,11 +2977,222 @@ declare function insertOne<TDef extends AnyCollection>(handle: CollectionHandle<
  */
 declare function insertMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, docs: InferInsert<TDef>[]): Promise<InferDocument<TDef>[]>;
 
+/**
+ * Base error class for all Zodmon errors.
+ *
+ * Every error thrown by Zodmon extends this class, making it easy to catch all
+ * Zodmon-related errors in a single `catch` block while still allowing more
+ * specific handling via subclass checks.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertOne({ name: 123 })
+ * } catch (err) {
+ *   if (err instanceof ZodmonError) {
+ *     console.log(err.name)       // => 'ZodmonError' (or a subclass name)
+ *     console.log(err.collection) // => 'users'
+ *     console.log(err.cause)      // => original Error, if provided
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonError extends Error {
+    readonly name: string;
+    /** The MongoDB collection name associated with this error. */
+    readonly collection: string;
+    /** The underlying error that caused this error, if any. */
+    readonly cause?: Error;
+    constructor(message: string, collection: string, options?: {
+        cause?: Error;
+    });
+}
+
+/**
+ * Thrown when MongoDB rejects an operation due to authentication or authorization failure.
+ *
+ * Corresponds to MongoDB error codes 13 (Unauthorized) and 18 (AuthenticationFailed).
+ * Inspect `.code` to distinguish between authorization and authentication failures.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertOne({ name: 'Alice' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonAuthError) {
+ *     console.log(err.message)    // => 'Not authorized to perform this operation on "users"'
+ *     console.log(err.code)       // => 13 or 18
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonAuthError extends ZodmonError {
+    readonly name = "ZodmonAuthError";
+    /** The MongoDB error code (13 or 18). */
+    readonly code: number;
+    constructor(collection: string, code: number, cause: Error);
+}
+
+/**
+ * Thrown when a bulk write operation partially or fully fails.
+ *
+ * Exposes partial result counts (`.insertedCount`, `.matchedCount`, etc.) alongside
+ * an array of `.writeErrors` describing each individual failure. Use this to determine
+ * which operations succeeded and which failed.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertMany([{ name: 'Alice' }, { name: 'Alice' }]) // duplicate
+ * } catch (err) {
+ *   if (err instanceof ZodmonBulkWriteError) {
+ *     console.log(err.insertedCount) // => 1
+ *     console.log(err.writeErrors)   // => [{ index: 1, code: 11000, message: '...' }]
+ *     console.log(err.collection)    // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonBulkWriteError extends ZodmonError {
+    readonly name = "ZodmonBulkWriteError";
+    /** Number of documents successfully inserted. */
+    readonly insertedCount: number;
+    /** Number of documents matched by update filters. */
+    readonly matchedCount: number;
+    /** Number of documents actually modified. */
+    readonly modifiedCount: number;
+    /** Number of documents deleted. */
+    readonly deletedCount: number;
+    /** Individual write errors with their operation index, code, and message. */
+    readonly writeErrors: Array<{
+        index: number;
+        code: number;
+        message: string;
+    }>;
+    constructor(collection: string, cause: Error, totalOps?: number);
+}
+
+/**
+ * Thrown when a document fails server-side JSON Schema validation (MongoDB error code 121).
+ *
+ * This is distinct from {@link ZodmonValidationError}, which validates against Zod schemas
+ * on the client side. This error surfaces when MongoDB's own document validation rejects
+ * a write. Inspect `.errInfo` for the server's detailed validation failure information.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertOne({ name: 'Alice', age: -1 })
+ * } catch (err) {
+ *   if (err instanceof ZodmonDocValidationError) {
+ *     console.log(err.message)    // => 'Server-side document validation failed for "users": ...'
+ *     console.log(err.errInfo)    // => { failingDocumentId: ..., details: ... }
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonDocValidationError extends ZodmonError {
+    readonly name = "ZodmonDocValidationError";
+    /** Server-provided validation failure details. */
+    readonly errInfo: unknown;
+    constructor(collection: string, errInfo: unknown, cause: Error);
+}
+
+/**
+ * Thrown when a MongoDB insert or update violates a unique index constraint (E11000).
+ *
+ * Parses the duplicate key information from the MongoDB driver error to expose
+ * structured fields: `.field` (first conflicting key), `.value`, `.index` (index name),
+ * `.keyPattern`, and `.keyValue`. Falls back to regex parsing for older drivers.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.insertOne({ email: 'alice@example.com' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonDuplicateKeyError) {
+ *     console.log(err.field)      // => 'email'
+ *     console.log(err.value)      // => 'alice@example.com'
+ *     console.log(err.index)      // => 'email_1'
+ *     console.log(err.keyPattern) // => { email: 1 }
+ *     console.log(err.keyValue)   // => { email: 'alice@example.com' }
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonDuplicateKeyError extends ZodmonError {
+    readonly name = "ZodmonDuplicateKeyError";
+    /** The first field that caused the duplicate key violation. */
+    readonly field: string;
+    /** The duplicate value, or `undefined` if it could not be extracted. */
+    readonly value: unknown;
+    /** The name of the index that was violated. */
+    readonly index: string;
+    /** The key pattern of the violated index (e.g. `{ email: 1 }`). */
+    readonly keyPattern: Record<string, number>;
+    /** The key values that caused the violation. */
+    readonly keyValue: Record<string, unknown>;
+    constructor(collection: string, cause: Error);
+}
+
+/**
+ * Thrown when a MongoDB index operation fails.
+ *
+ * Corresponds to MongoDB error codes 67 (CannotCreateIndex), 85 (IndexOptionsConflict),
+ * and 86 (IndexKeySpecsConflict). Inspect `.code` to determine the specific failure reason.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await syncIndexes(db, [Users])
+ * } catch (err) {
+ *   if (err instanceof ZodmonIndexError) {
+ *     console.log(err.message)    // => 'Index options conflict on "users": ...'
+ *     console.log(err.code)       // => 67, 85, or 86
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonIndexError extends ZodmonError {
+    readonly name = "ZodmonIndexError";
+    /** The MongoDB error code (67, 85, or 86). */
+    readonly code: number;
+    constructor(collection: string, code: number, errmsg: string, cause: Error);
+}
+
+/**
+ * Thrown when a MongoDB operation fails due to a network error.
+ *
+ * Wraps `MongoNetworkError` from the MongoDB driver with the collection name
+ * and the original error message for easier debugging.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.find({ status: 'active' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonNetworkError) {
+ *     console.log(err.message)    // => 'Network error on "users": connection refused'
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonNetworkError extends ZodmonError {
+    readonly name = "ZodmonNetworkError";
+    constructor(collection: string, cause: Error);
+}
+
 /**
  * Thrown when a query expected to find a document returns no results.
  *
  * Used by {@link findOneOrThrow} when no document matches the provided filter.
- * Callers can inspect `.collection` to identify which collection the query targeted.
+ * Callers can inspect `.collection` to identify which collection the query targeted,
+ * and `.filter` to see the query that produced no results.
  *
  * @example
  * ```ts
@@ -1766,15 +3202,68 @@ declare function insertMany<TDef extends AnyCollection>(handle: CollectionHandle
  *   if (err instanceof ZodmonNotFoundError) {
  *     console.log(err.message)    // => 'Document not found in "users"'
  *     console.log(err.collection) // => 'users'
+ *     console.log(err.filter)     // => { name: 'nonexistent' }
  *   }
  * }
  * ```
  */
-declare class ZodmonNotFoundError extends Error {
+declare class ZodmonNotFoundError extends ZodmonError {
     readonly name = "ZodmonNotFoundError";
-    /** The MongoDB collection name where the query found no results. */
-    readonly collection: string;
-    constructor(collection: string);
+    /** The filter that produced no results. */
+    readonly filter: unknown;
+    constructor(collection: string, filter: unknown);
+}
+
+/**
+ * Thrown when a MongoDB query is malformed or exceeds resource limits.
+ *
+ * Corresponds to MongoDB error codes 2 (BadValue), 9 (FailedToParse), and
+ * 292 (QueryExceededMemoryLimit). Inspect `.code` to determine the specific failure.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.find({ $invalid: true })
+ * } catch (err) {
+ *   if (err instanceof ZodmonQueryError) {
+ *     console.log(err.message)    // => 'Bad value in query on "users": ...'
+ *     console.log(err.code)       // => 2, 9, or 292
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonQueryError extends ZodmonError {
+    readonly name = "ZodmonQueryError";
+    /** The MongoDB error code (2, 9, or 292). */
+    readonly code: number;
+    constructor(collection: string, code: number, errmsg: string, cause: Error);
+}
+
+/**
+ * Thrown when a MongoDB operation exceeds its server time limit.
+ *
+ * Corresponds to MongoDB error codes 50 (MaxTimeMSExpired) and
+ * 262 (ExceededTimeLimit). Inspect `.code` to distinguish between the two.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await users.find({ status: 'active' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonTimeoutError) {
+ *     console.log(err.message)    // => 'Operation timed out on "users": ...'
+ *     console.log(err.code)       // => 50 or 262
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonTimeoutError extends ZodmonError {
+    readonly name = "ZodmonTimeoutError";
+    /** The MongoDB error code (50 or 262). */
+    readonly code: number;
+    constructor(collection: string, code: number, cause: Error);
 }
 
 /**
@@ -1794,17 +3283,62 @@ declare class ZodmonNotFoundError extends Error {
  *     // => 'Validation failed for "users": name (Expected string, received number)'
  *     console.log(err.collection) // => 'users'
  *     console.log(err.zodError)   // => ZodError with .issues array
+ *     console.log(err.document)   // => the document that failed validation
  *   }
  * }
  * ```
  */
-declare class ZodmonValidationError extends Error {
+declare class ZodmonValidationError extends ZodmonError {
     readonly name = "ZodmonValidationError";
-    /** The MongoDB collection name where the validation failed. */
-    readonly collection: string;
     /** The original Zod validation error with detailed issue information. */
     readonly zodError: z.ZodError;
-    constructor(collection: string, zodError: z.ZodError);
+    /** The document that failed validation. */
+    readonly document: unknown;
+    constructor(collection: string, zodError: z.ZodError, document: unknown);
+}
+
+/**
+ * Maps a caught MongoDB error to the appropriate Zodmon error subclass and throws it.
+ *
+ * This function always throws — it never returns. Use it in `catch` blocks to convert
+ * raw MongoDB driver errors into structured, typed Zodmon errors. If the error is already
+ * a `ZodmonError`, it is rethrown as-is to prevent double-wrapping.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await db.collection('users').insertOne(doc)
+ * } catch (err) {
+ *   wrapMongoError(err, 'users')
+ * }
+ * ```
+ */
+declare function wrapMongoError(err: unknown, collection: string): never;
+
+/**
+ * Thrown when a transaction encounters a write conflict (MongoDB error code 112).
+ *
+ * This occurs when another operation modifies the same document concurrently during
+ * a transaction. The recommended recovery strategy is to retry the transaction.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await db.transaction(async (tx) => {
+ *     const users = tx.use(Users)
+ *     await users.updateOne({ _id: id }, { $inc: { balance: -100 } })
+ *   })
+ * } catch (err) {
+ *   if (err instanceof ZodmonWriteConflictError) {
+ *     console.log(err.message)    // => 'Write conflict in "users": ...'
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
+ * ```
+ */
+declare class ZodmonWriteConflictError extends ZodmonError {
+    readonly name = "ZodmonWriteConflictError";
+    constructor(collection: string, cause: Error);
 }
 
 /**
@@ -2111,11 +3645,11 @@ declare const $: {
     readonly lte: <V>(value: V) => {
         $lte: V;
     };
-    readonly in: <V>(values: V[]) => {
-        $in: V[];
+    readonly in: <V>(values: readonly V[]) => {
+        $in: readonly V[];
     };
-    readonly nin: <V>(values: V[]) => {
-        $nin: V[];
+    readonly nin: <V>(values: readonly V[]) => {
+        $nin: readonly V[];
     };
     readonly exists: (flag?: boolean) => {
         $exists: boolean;
@@ -2207,8 +3741,8 @@ declare const $lte: <V>(value: V) => {
  * users.find({ role: $in(['admin', 'moderator']) })
  * ```
  */
-declare const $in: <V>(values: V[]) => {
-    $in: V[];
+declare const $in: <V>(values: readonly V[]) => {
+    $in: readonly V[];
 };
 /**
  * Matches none of the values in the specified array.
@@ -2218,8 +3752,8 @@ declare const $in: <V>(values: V[]) => {
  * users.find({ role: $nin(['banned', 'suspended']) })
  * ```
  */
-declare const $nin: <V>(values: V[]) => {
-    $nin: V[];
+declare const $nin: <V>(values: readonly V[]) => {
+    $nin: readonly V[];
 };
 /**
  * Matches documents where the field exists (or does not exist).
@@ -2319,84 +3853,6 @@ declare const $nor: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>
  */
 declare const raw: <T = any>(filter: Record<string, unknown>) => TypedFilter<T>;
 
-/**
- * Type-level marker that carries the target collection type through the
- * type system. Intersected with the schema return type by `.ref()` so
- * that `RefFields<T>` (future) can extract ref relationships.
- *
- * This is a phantom brand — no runtime value has this property.
- */
-type RefMarker<TCollection extends AnyCollection = AnyCollection> = {
-    readonly _ref: TCollection;
-};
-/**
- * Metadata stored in the WeakMap sidecar for schemas marked with `.ref()`.
- * Holds a reference to the target collection definition object.
- */
-type RefMetadata = {
-    readonly collection: AnyCollection;
-};
-/**
- * Module augmentation: adds `.ref()` to all `ZodType` schemas.
- *
- * The intersection constraint `this['_zod']['output'] extends InferDocument<TCollection>['_id']`
- * ensures compile-time type safety: the field's output type must match the
- * target collection's `_id` type. Mismatches produce a type error.
- *
- * Supports both default ObjectId `_id` and custom `_id` types (string, nanoid, etc.):
- * - `objectId().ref(Users)` compiles when Users has ObjectId `_id`
- * - `z.string().ref(Orgs)` compiles when Orgs has string `_id`
- * - `z.string().ref(Users)` is a type error (string ≠ ObjectId)
- * - `objectId().ref(Orgs)` is a type error (ObjectId ≠ string)
- */
-declare module 'zod' {
-    interface ZodType {
-        /**
-         * Declare a typed foreign key reference to another collection.
-         *
-         * Stores the target collection definition in metadata for runtime
-         * populate resolution, and brands the return type with
-         * `RefMarker<TCollection>` so `RefFields<T>` can extract refs
-         * at the type level.
-         *
-         * The field's output type must match the target collection's `_id` type.
-         * Mismatched types produce a compile error.
-         *
-         * Apply `.ref()` before wrapper methods like `.optional()` or `.nullable()`:
-         * `objectId().ref(Users).optional()` — not `objectId().optional().ref(Users)`.
-         *
-         * @param collection - The target collection definition object.
-         * @returns The same schema instance, branded with the ref marker.
-         *
-         * @example
-         * ```ts
-         * const Posts = collection('posts', {
-         *   authorId: objectId().ref(Users),
-         *   title: z.string(),
-         * })
-         * ```
-         */
-        ref<TCollection extends AnyCollection>(collection: TCollection & (this['_zod']['output'] extends InferDocument<TCollection>['_id'] ? unknown : never)): this & RefMarker<TCollection>;
-    }
-}
-/**
- * Retrieve the ref metadata attached to a Zod schema, if any.
- *
- * Returns `undefined` when the schema was never marked with `.ref()`.
- *
- * @param schema - The Zod schema to inspect. Accepts `unknown` for
- *   convenience; non-object values safely return `undefined`.
- * @returns The {@link RefMetadata} for the schema, or `undefined`.
- *
- * @example
- * ```ts
- * const authorId = objectId().ref(Users)
- * const meta = getRefMetadata(authorId)
- * // => { collection: Users }
- * ```
- */
-declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
-
 /**
  * Shorthand for `CollectionHandle<TDef>`.
  *
@@ -2462,4 +3918,4 @@ type UpdateFilterOf<TDef extends AnyCollection> = TypedUpdateFilter<InferDocumen
  */
 type SortOf<TDef extends AnyCollection> = TypedSort<InferDocument<TDef>>;
 
-export { $, $and, $eq, $exists, $gt, $gte, $in, $lt, $lte, $ne, $nin, $nor, $not, $or, $regex, type AddToSetEach, type AddToSetFields, type AnyCollection, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DotPathType, type DotPaths, type FieldIndexDefinition, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOptions, type HandleOf, type IncFields, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferDocument, type InferInsert, type OffsetPage, type OffsetPaginateOptions, type PopFields, type PullFields, type PushFields, type PushModifiers, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, type TypedFilter, TypedFindCursor, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonNotFoundError, ZodmonValidationError, checkUnindexedFields, collection, createClient, deleteMany, deleteOne, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne };
+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 DotPathType, type DotPaths, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOptions, type GroupByCompoundResult, type GroupByResult, type HandleOf, type IncFields, 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 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 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, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, deleteMany, deleteOne, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne, wrapMongoError };