@zodmon/core 0.8.0 → 0.9.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,1209 +305,2433 @@ 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 }
  * ```
  */
-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>;
-};
+declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
+
 /**
- * The result of a {@link syncIndexes} call.
+ * Branded wrapper for accumulator expressions used inside `groupBy`.
  *
- * Every array contains index names. `stale` contains full details so the
- * caller can inspect the mismatch.
+ * Carries the MongoDB accumulator expression at runtime and the inferred
+ * result type `T` at the type level.
  *
  * @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))
+ * const acc: Accumulator<number> = {
+ * 	__accum: true,
+ * 	expr: { $sum: '$price' },
+ * }
  * ```
  */
-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 Accumulator<T = unknown> = {
+    readonly __accum: true;
+    readonly expr: Document;
+    /** @internal Phantom field — carries the result type at the type level. */
+    readonly _type?: T;
 };
-
 /**
- * Comparison operators for a field value of type `V`.
- *
- * Maps each MongoDB comparison operator to its expected value type.
- * `$regex` is only available when `V` extends `string`.
- *
- * Used as the operator object that can be assigned to a field in {@link TypedFilter}.
+ * Extracts the result type from an `Accumulator<T>`.
  *
  * @example
  * ```ts
- * // As a raw object (without builder functions)
- * const filter: TypedFilter<User> = { age: { $gt: 25, $lte: 65 } }
- *
- * // $regex only available on string fields
- * const filter: TypedFilter<User> = { name: { $regex: /^A/i } }
+ * type Count = InferAccumulator<Accumulator<number>>
+ * //   ^? number
  * ```
  */
-type ComparisonOperators<V> = {
-    /** Matches values equal to the specified value. */
-    $eq?: V;
-    /** Matches values not equal to the specified value. */
-    $ne?: V;
-    /** Matches values greater than the specified value. */
-    $gt?: V;
-    /** Matches values greater than or equal to the specified value. */
-    $gte?: V;
-    /** Matches values less than the specified value. */
-    $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 documents where the field exists (`true`) or does not exist (`false`). */
-    $exists?: boolean;
-    /** Negates a comparison operator. */
-    $not?: 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];
+type InferAccumulator<T> = T extends Accumulator<infer R> ? R : never;
 /**
- * Generates a union of all valid dot-separated paths for nested object fields in `T`.
+ * Maps an accumulator spec object to its inferred output shape.
  *
- * 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.
+ * Given `{ count: Accumulator<number>, names: Accumulator<string[]> }`,
+ * produces `{ count: number, names: string[] }`.
  *
  * @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 Spec = {
+ * 	count: Accumulator<number>
+ * 	total: Accumulator<number>
+ * }
+ * type Result = InferAccumulators<Spec>
+ * //   ^? { count: number; total: number }
  * ```
  */
-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];
+type InferAccumulators<T extends Record<string, Accumulator>> = {
+    [K in keyof T]: InferAccumulator<T[K]>;
+};
 /**
- * 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.
+ * Field reference string prefixed with `$`, constrained to keys of `T`.
  *
  * @example
  * ```ts
- * type User = { address: { city: string; geo: { lat: number } } }
- *
- * // DotPathType<User, 'address.city'> = string
- * // DotPathType<User, 'address.geo.lat'> = number
+ * type OrderRef = FieldRef<{ price: number; qty: number }>
+ * //   ^? '$price' | '$qty'
  * ```
  */
-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 FieldRef<T> = `$${keyof T & string}`;
 /**
- * Strict type-safe MongoDB filter query type.
- *
- * Validates filter objects at compile time — rejects nonexistent fields, type mismatches,
- * and invalid operator usage. Unlike the MongoDB driver's `Filter<T>`, does NOT allow
- * arbitrary keys via `& Document`.
+ * Typed accumulator factory passed to the `groupBy` callback.
  *
- * 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' }`
+ * 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`.
  *
- * Logical operators `$and`, `$or`, and `$nor` accept arrays of `TypedFilter<T>`
- * for composing complex queries.
+ * @typeParam T - The current pipeline output document type.
  *
  * @example
  * ```ts
- * // Simple equality
- * const filter: TypedFilter<User> = { name: 'Alice' }
- *
- * // Builder functions mixed with object literals
- * const filter: TypedFilter<User> = { age: $gte(18), role: $in(['admin', 'mod']) }
- *
- * // Logical composition — T inferred from find() context
- * posts.find($and(
- *   $or({ published: true }, { views: $gte(100) }),
- *   { title: $regex(/guide/i) },
- * ))
- *
- * // Dynamic conditional building
- * const conditions: TypedFilter<User>[] = []
- * if (name)   conditions.push({ name })
- * if (minAge) conditions.push({ age: $gte(minAge) })
- * const filter = conditions.length ? $and<User>(...conditions) : {}
+ * 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 TypedFilter<T> = {
-    [K in keyof T]?: T[K] | ComparisonOperators<T[K]>;
-} & {
-    [P in DotPaths<T>]?: DotPathType<T, P> | ComparisonOperators<DotPathType<T, P>>;
-} & {
-    /** Joins clauses with a logical AND. Matches documents that satisfy all filters. */
-    $and?: TypedFilter<T>[];
-    /** Joins clauses with a logical OR. Matches documents that satisfy at least one filter. */
-    $or?: TypedFilter<T>[];
-    /** Joins clauses with a logical NOR. Matches documents that fail all filters. */
-    $nor?: TypedFilter<T>[];
+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][]>;
 };
-
 /**
- * Options for {@link findOneAndDelete}.
+ * 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 FindOneAndDeleteOptions = {
-    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
-    validate?: ValidationMode | false;
-};
+type FieldRefType<T, F extends string> = F extends `$${infer K}` ? K extends keyof T ? T[K] : never : never;
 /**
- * Delete a single document matching the filter.
+ * Output shape of a single-field `groupBy` stage.
  *
- * Removes the first document that matches the filter from the collection.
- * No validation is performed — the document is deleted directly through
- * the MongoDB driver.
- *
- * @param handle - The collection handle to delete from.
- * @param filter - Type-safe filter to match documents.
- * @returns The MongoDB `DeleteResult` with the deleted count.
+ * The `_id` field holds the grouped-by field's value, and the rest of the
+ * shape comes from the inferred accumulator types.
  *
  * @example
  * ```ts
- * const result = await deleteOne(users, { name: 'Ada' })
- * console.log(result.deletedCount) // 1
+ * type Result = GroupByResult<Order, 'status', { count: Accumulator<number> }>
+ * //   ^? { _id: string; count: number }
  * ```
  */
-declare function deleteOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
+type GroupByResult<T, K extends keyof T, TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: T[K];
+} & InferAccumulators<TAccum>>;
 /**
- * Delete all documents matching the filter.
- *
- * Removes every document that matches the filter from the collection.
- * No validation is performed — documents are deleted directly through
- * the MongoDB driver.
+ * Output shape of a compound (multi-field) `groupBy` stage.
  *
- * @param handle - The collection handle to delete from.
- * @param filter - Type-safe filter to match documents.
- * @returns The MongoDB `DeleteResult` with the deleted count.
+ * 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
- * const result = await deleteMany(users, { role: 'guest' })
- * console.log(result.deletedCount) // number of guests removed
+ * type Result = GroupByCompoundResult<Order, 'status' | 'region', { count: Accumulator<number> }>
+ * //   ^? { _id: Pick<Order, 'status' | 'region'>; count: number }
  * ```
  */
-declare function deleteMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
+type GroupByCompoundResult<T, K extends keyof T, TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: Prettify<Pick<T, K>>;
+} & InferAccumulators<TAccum>>;
 /**
- * Find a single document matching the filter, delete it, and return the document.
+ * Output shape after unwinding an array field.
  *
- * Returns the deleted document, or `null` if no document matches the filter.
- * The returned document is validated against the collection's Zod schema
- * using the same resolution logic as {@link findOne}.
+ * The unwound field's type changes from `Array<E>` to `E`; all other
+ * fields are preserved as-is.
  *
- * @param handle - The collection handle to delete from.
- * @param filter - Type-safe filter to match documents.
- * @param options - Optional settings: `validate`.
- * @returns The deleted document, or `null` if no document matches.
- * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+ * @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
- * const user = await findOneAndDelete(users, { name: 'Ada' })
- * if (user) console.log(user.name) // 'Ada' (the deleted document)
+ * 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
- * const user = await findOneAndDelete(
- *   users,
- *   { role: 'guest' },
- *   { validate: false },
- * )
+ * type EmpRefs = RefFields<typeof Employees> // → 'departmentId'
  * ```
  */
-declare function findOneAndDelete<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneAndDeleteOptions): Promise<InferDocument<TDef> | null>;
-
+type RefFields<TDef extends AnyCollection> = {
+    [K in keyof TDef['shape'] & string]: TDef['shape'][K] extends RefMarker ? K : never;
+}[keyof TDef['shape'] & string];
 /**
- * Options for offset-based pagination.
+ * Given a collection definition and a ref-bearing field key, extract
+ * the target collection type from the `RefMarker<TCollection>` phantom.
  *
  * @example
  * ```ts
- * await users.find({}).sort({ name: 1 }).paginate({ page: 2, perPage: 10 })
+ * type Target = ExtractRefCollection<typeof Employees, 'departmentId'>
+ * // → typeof Departments
  * ```
  */
-type OffsetPaginateOptions = {
-    /** The page number to retrieve (1-indexed). */
-    page: number;
-    /** The number of documents per page. */
-    perPage: number;
-};
+type ExtractRefCollection<TDef extends AnyCollection, K extends RefFields<TDef>> = TDef['shape'][K] extends RefMarker<infer TCol> ? TCol : never;
 /**
- * Options for cursor-based pagination.
+ * Extract the collection name string literal from a collection definition.
  *
  * @example
  * ```ts
- * const first = await users.find({}).sort({ name: 1 }).paginate({ limit: 10 })
- * const next = await users.find({}).sort({ name: 1 }).paginate({ cursor: first.endCursor, limit: 10 })
+ * CollectionName<typeof Departments> // → 'departments'
  * ```
  */
-type CursorPaginateOptions = {
-    /** Maximum number of documents to return. */
-    limit: number;
-    /** Opaque cursor string from a previous `startCursor` or `endCursor`. */
-    cursor?: string | null;
-};
+type CollectionName<TDef extends AnyCollection> = TDef['name'];
 /**
- * Result of offset-based pagination.
+ * 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 page = await users.find({}).paginate({ page: 1, perPage: 10 })
- * console.log(page.total, page.totalPages, page.hasNext)
+ * const yearExpr: Expression<number> = {
+ * 	__expr: true,
+ * 	value: { $year: '$hiredAt' },
+ * }
  * ```
  */
-type OffsetPage<TDoc> = {
-    /** The documents for this page. */
-    docs: TDoc[];
-    /** Total number of matching documents. */
-    total: number;
-    /** Current page number (1-indexed). */
-    page: number;
-    /** Number of documents per page. */
-    perPage: number;
-    /** Total number of pages (`Math.ceil(total / perPage)`). */
-    totalPages: number;
-    /** Whether there is a next page. */
-    hasNext: boolean;
-    /** Whether there is a previous page. */
-    hasPrev: boolean;
+type Expression<T = unknown> = {
+    readonly __expr: true;
+    readonly value: Document;
+    /** @internal Phantom field — carries the result type at the type level. */
+    readonly _type?: T;
 };
 /**
- * Result of cursor-based pagination.
+ * Unwrap an `Expression<T>` to its result type `T`.
+ * Non-Expression values resolve to `unknown`.
  *
  * @example
  * ```ts
- * const page = await users.find({}).paginate({ limit: 10 })
- * if (page.hasNext) {
- *   const next = await users.find({}).paginate({ cursor: page.endCursor, limit: 10 })
- * }
+ * type N = InferExpression<Expression<number>> // → number
+ * type U = InferExpression<{ $year: string }>  // → unknown
  * ```
  */
-type CursorPage<TDoc> = {
-    /** The documents for this page. */
-    docs: TDoc[];
-    /** Whether there are more documents after this page. */
-    hasNext: boolean;
-    /** Whether there are documents before this page. */
-    hasPrev: boolean;
-    /** Cursor for the first document (pass to `cursor` to go backward). `null` when empty. */
-    startCursor: string | null;
-    /** Cursor for the last document (pass to `cursor` to go forward). `null` when empty. */
-    endCursor: string | null;
+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>;
 };
 
 /**
- * Type-safe sort specification for a document type.
+ * Counts the number of documents in each group.
  *
- * Constrains sort keys to top-level fields of `T` with direction `1` (ascending)
- * or `-1` (descending). Dot-path sorts deferred to v1.0.
+ * Equivalent to `{ $sum: 1 }` in a MongoDB `$group` stage.
+ *
+ * @returns An `Accumulator<number>` that counts documents.
  *
  * @example
  * ```ts
- * const sort: TypedSort<User> = { name: 1, createdAt: -1 }
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('status', { count: $count() })
  * ```
  */
-type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
+declare const $count: () => Accumulator<number>;
 /**
- * Type-safe cursor wrapping MongoDB's `FindCursor`.
+ * Sums numeric values across documents in each group.
  *
- * Provides chainable query modifiers (`sort`, `skip`, `limit`, `hint`) that return
- * `this` for fluent chaining, and terminal methods (`toArray`,
- * `[Symbol.asyncIterator]`) that validate each document against the
- * collection's Zod schema before returning.
+ * Accepts either a `$`-prefixed field reference or a literal number.
  *
- * Created by {@link find} — do not construct directly.
+ * @param field - A `$field` reference to a numeric field, or a literal number.
+ * @returns An `Accumulator<number>`.
  *
- * @typeParam TDef - The collection definition type, used to infer the document type.
- * @typeParam TIndexNames - Union of declared index names accepted by `.hint()`.
+ * @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 docs = await find(users, { role: 'admin' })
- *   .sort({ name: 1 })
- *   .limit(10)
- *   .toArray()
+ * const pipeline = orders.aggregate()
+ * 	.groupBy('category', { avgPrice: $avg('$price') })
  * ```
  */
-declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends string = string> {
-    /** @internal */
-    private cursor;
-    /** @internal */
-    private schema;
-    /** @internal */
-    private collectionName;
-    /** @internal */
-    private mode;
-    /** @internal */
-    private readonly nativeCollection;
-    /** @internal */
-    private readonly filter;
-    /** @internal */
-    private sortSpec;
-    /** @internal */
-    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false, nativeCollection: Collection<InferDocument<TDef>>, filter: any);
-    /**
-     * Set the sort order for the query.
-     *
-     * Only top-level document fields are accepted as sort keys.
-     * Values must be `1` (ascending) or `-1` (descending).
-     *
-     * @param spec - Sort specification mapping field names to sort direction.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * find(users, {}).sort({ name: 1, age: -1 }).toArray()
-     * ```
-     */
-    sort(spec: TypedSort<InferDocument<TDef>>): this;
-    /**
-     * Skip the first `n` documents in the result set.
-     *
-     * @param n - Number of documents to skip.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * find(users, {}).skip(10).limit(10).toArray() // page 2
-     * ```
-     */
-    skip(n: number): this;
-    /**
-     * Limit the number of documents returned.
-     *
-     * @param n - Maximum number of documents to return.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * find(users, {}).limit(10).toArray() // at most 10 docs
-     * ```
-     */
-    limit(n: number): this;
-    /**
-     * Force the query optimizer to use the specified index.
-     *
-     * Only accepts index names that were declared via `.name()` in the
-     * collection definition. If no named indexes exist, any string is accepted.
-     *
-     * @param indexName - The name of a declared compound index.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * const Users = collection('users', { email: z.string(), role: z.string() }, {
-     *   indexes: [index({ email: 1, role: -1 }).name('email_role_idx')],
-     * })
-     * const admins = await users.find({ role: 'admin' })
-     *   .hint('email_role_idx')
-     *   .toArray()
-     * ```
-     */
-    hint(indexName: TIndexNames): this;
-    /**
-     * Execute the query with offset-based pagination, returning a page of documents
-     * with total count and navigation metadata.
-     *
-     * Runs `countDocuments` and `find` in parallel for performance. Ignores any
-     * `.skip()` or `.limit()` already set on the cursor — issues a fresh query.
-     *
-     * @param opts - Offset pagination options: `page` (1-indexed) and `perPage`.
-     * @returns A page with `docs`, `total`, `totalPages`, `hasNext`, `hasPrev`.
-     * @throws {ZodmonValidationError} When a document fails schema validation.
-     *
-     * @example
-     * ```ts
-     * const page = await users.find({ role: 'admin' })
-     *   .sort({ createdAt: -1 })
-     *   .paginate({ page: 2, perPage: 10 })
-     * console.log(page.total, page.totalPages, page.hasNext)
-     * ```
-     */
-    paginate(opts: OffsetPaginateOptions): Promise<OffsetPage<InferDocument<TDef>>>;
-    /**
-     * Execute the query with cursor-based pagination, returning a page of documents
-     * with opaque cursors for forward/backward navigation.
-     *
-     * Uses the `limit + 1` trick to determine `hasNext`/`hasPrev` without extra queries.
-     * Direction is encoded in the cursor — pass `endCursor` to go forward, `startCursor`
-     * to go backward.
-     *
-     * @param opts - Cursor pagination options: `limit` and optional `cursor`.
-     * @returns A page with `docs`, `hasNext`, `hasPrev`, `startCursor`, `endCursor`.
-     * @throws {ZodmonValidationError} When a document fails schema validation.
-     * @throws {Error} When the cursor string is malformed.
-     *
-     * @example
-     * ```ts
-     * const first = await users.find({}).sort({ name: 1 }).paginate({ limit: 10 })
-     * const next = await users.find({}).sort({ name: 1 })
-     *   .paginate({ cursor: first.endCursor, limit: 10 })
-     * ```
-     */
-    paginate(opts: CursorPaginateOptions): Promise<CursorPage<InferDocument<TDef>>>;
-    /** @internal Offset pagination implementation. */
-    private offsetPaginate;
-    /** @internal Cursor pagination implementation. */
-    private cursorPaginate;
-    /**
-     * Execute the query and return all matching documents as an array.
-     *
-     * Each document is validated against the collection's Zod schema
-     * according to the resolved validation mode.
-     *
-     * @returns Array of validated documents.
-     * @throws {ZodmonValidationError} When a document fails schema validation in strict/strip mode.
-     *
-     * @example
-     * ```ts
-     * const admins = await find(users, { role: 'admin' }).toArray()
-     * ```
-     */
-    toArray(): Promise<InferDocument<TDef>[]>;
-    /**
-     * Async iterator for streaming documents one at a time.
-     *
-     * Each yielded document is validated against the collection's Zod schema.
-     * Memory-efficient for large result sets.
-     *
-     * @yields Validated documents one at a time.
-     * @throws {ZodmonValidationError} When a document fails schema validation.
-     *
-     * @example
-     * ```ts
-     * for await (const user of find(users, {})) {
-     *   console.log(user.name)
-     * }
-     * ```
-     */
-    [Symbol.asyncIterator](): AsyncGenerator<InferDocument<TDef>>;
-    /** @internal Validate a single raw document against the schema. */
-    private validateDoc;
-}
-
-/**
- * Options for {@link findOne} and {@link findOneOrThrow}.
- */
-type FindOneOptions = {
-    /** MongoDB projection — include (`1`) or exclude (`0`) fields. Typed projections deferred to v1.0. */
-    project?: Record<string, 0 | 1>;
-    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
-    validate?: ValidationMode | false;
-};
+declare const $avg: (field: `$${string}`) => Accumulator<number>;
 /**
- * Find a single document matching the filter.
+ * Returns the minimum value across documents in each group.
  *
- * 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'`).
+ * For full type safety, prefer the callback builder (`acc.min('price')`).
+ * The standalone form accepts an explicit result type `R` for manual typing.
  *
- * @param handle - The collection handle to query.
- * @param filter - Type-safe filter to match documents.
- * @param options - Optional projection and validation overrides.
- * @returns The matched document, or `null` if no document matches.
- * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+ * @typeParam R - The expected result type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R>`.
  *
  * @example
  * ```ts
- * const user = await findOne(users, { name: 'Ada' })
- * if (user) console.log(user.role) // typed as 'admin' | 'user'
+ * // 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 function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+declare const $min: <R = unknown>(field: `$${string}`) => Accumulator<R>;
 /**
- * Find a single document matching the filter, or throw if none exists.
+ * Returns the maximum value across documents in each group.
  *
- * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
- * instead of returning `null` when no document matches the filter.
+ * For full type safety, prefer the callback builder (`acc.max('price')`).
+ * The standalone form accepts an explicit result type `R` for manual typing.
  *
- * @param handle - The collection handle to query.
- * @param filter - Type-safe filter to match documents.
- * @param options - Optional projection and validation overrides.
- * @returns The matched document (never null).
- * @throws {ZodmonNotFoundError} When no document matches the filter.
- * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+ * @typeParam R - The expected result type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R>`.
  *
  * @example
  * ```ts
- * const user = await findOneOrThrow(users, { name: 'Ada' })
- * console.log(user.role) // typed as 'admin' | 'user', guaranteed non-null
+ * // 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 function findOneOrThrow<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
-/**
- * Options for {@link find}.
- */
-type FindOptions = {
-    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
-    validate?: ValidationMode | false;
-};
+declare const $max: <R = unknown>(field: `$${string}`) => Accumulator<R>;
 /**
- * Find all documents matching the filter, returning a chainable typed cursor.
- *
- * The cursor is lazy — no query is executed until a terminal method
- * (`toArray`, `for await`) is called. Use `sort`, `skip`, and `limit`
- * to shape the query before executing.
+ * Returns the first value in each group according to the document order.
  *
- * Each document is validated against the collection's Zod schema when
- * a terminal method consumes it.
+ * For full type safety, prefer the callback builder (`acc.first('name')`).
+ * The standalone form accepts an explicit result type `R` for manual typing.
  *
- * @param handle - The collection handle to query.
- * @param filter - Type-safe filter to match documents.
- * @param options - Optional validation overrides.
- * @returns A typed cursor for chaining query modifiers.
+ * @typeParam R - The expected result type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R>`.
  *
  * @example
  * ```ts
- * const admins = await find(users, { role: 'admin' })
- *   .sort({ name: 1 })
- *   .limit(10)
- *   .toArray()
- * ```
+ * // Tier 2 — explicit result type
+ * const pipeline = orders.aggregate()
+ * 	.sort({ createdAt: 1 })
+ * 	.groupBy('status', { earliest: $first<Date>('$createdAt') })
  *
- * @example
- * ```ts
- * for await (const user of find(users, {})) {
- *   console.log(user.name)
- * }
+ * // Tier 1 — callback builder (recommended)
+ * orders.aggregate()
+ * 	.sort({ createdAt: 1 })
+ * 	.groupBy('status', acc => ({ earliest: acc.first('createdAt') }))
  * ```
  */
-declare function find<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
-
+declare const $first: <R = unknown>(field: `$${string}`) => Accumulator<R>;
 /**
- * Extracts the element type from an array type.
+ * Returns the last value in each group according to the document order.
  *
- * @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.
+ * For full type safety, prefer the callback builder (`acc.last('name')`).
+ * The standalone form accepts an explicit result type `R` for manual typing.
  *
- * Allows top-level fields with matching value types plus dot-notation paths
- * for nested field updates.
+ * @typeParam R - The expected result type (defaults to `unknown`).
+ * @param field - A `$field` reference.
+ * @returns An `Accumulator<R>`.
  *
  * @example
  * ```ts
- * const set: SetFields<User> = { name: 'Alice', 'address.city': 'NYC' }
+ * // 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') }))
  * ```
  */
-type SetFields<T> = {
-    [K in keyof T]?: T[K];
-} & {
-    [P in DotPaths<T>]?: DotPathType<T, P>;
-};
+declare const $last: <R = unknown>(field: `$${string}`) => Accumulator<R>;
 /**
- * Fields valid for the `$inc` operator — only number-typed fields.
+ * Pushes values into an array for each group.
  *
- * Includes dot-notation paths that resolve to number types.
+ * 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
- * const inc: IncFields<User> = { age: 1, 'stats.views': 5 }
+ * // 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') }))
  * ```
  */
-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;
-};
+declare const $push: <R = unknown>(field: `$${string}`) => Accumulator<R[]>;
 /**
- * Modifiers for the `$push` operator.
+ * Collects unique values into an array for each group (set semantics).
  *
- * Use with `$push` to insert multiple elements and control array position/size.
+ * 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
- * const push = { tags: { $each: ['a', 'b'], $position: 0, $slice: 10 } }
+ * // 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') }))
  * ```
  */
-type PushModifiers<E> = {
-    /** Array of elements to push. */
-    $each: E[];
-    /** Position at which to insert elements. */
-    $position?: number;
-    /** Maximum array length after push. */
-    $slice?: number;
-    /** Sort order applied after push. */
-    $sort?: 1 | -1 | Record<string, 1 | -1>;
-};
+declare const $addToSet: <R = unknown>(field: `$${string}`) => Accumulator<R[]>;
 /**
- * Fields valid for the `$push` operator — only array-typed fields.
+ * Create a typed accumulator builder for use inside `groupBy` callbacks.
  *
- * Accepts a single element value or a modifier object with `$each`.
+ * 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 push: PushFields<User> = { tags: 'dev' }
- * const pushMany: PushFields<User> = { tags: { $each: ['a', 'b'] } }
+ * const acc = createAccumulatorBuilder<{ salary: number; name: string }>()
+ * acc.min('salary')  // { __accum: true, expr: { $min: '$salary' } }
+ * acc.push('name')   // { __accum: true, expr: { $push: '$name' } }
  * ```
  */
-type PushFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | PushModifiers<ArrayElement<NonNullable<T[K]>>>;
-};
+declare function createAccumulatorBuilder<T>(): AccumulatorBuilder<T>;
 /**
- * Fields valid for the `$pull` operator — only array-typed fields.
+ * Create a typed expression builder for use inside `addFields` callbacks.
  *
- * For primitive arrays: accepts a value or comparison operators.
- * For object arrays: also accepts a `TypedFilter` on the element type.
+ * 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.
  *
- * @example
- * ```ts
- * const pull: PullFields<User> = { tags: 'old' }
- * const pullQuery: PullFields<User> = { scores: { $lt: 50 } }
- * const pullObj: PullFields<User> = { comments: { author: 'spam' } }
- * ```
- */
-type PullFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | ComparisonOperators<ArrayElement<NonNullable<T[K]>>> | (ArrayElement<NonNullable<T[K]>> extends Record<string, unknown> ? TypedFilter<ArrayElement<NonNullable<T[K]>>> : unknown);
-};
-/**
- * Modifier for the `$addToSet` operator's `$each` syntax.
+ * @typeParam T - The current pipeline output document type.
+ * @returns An `ExpressionBuilder<T>` with methods for each MongoDB expression operator.
  *
  * @example
  * ```ts
- * const addToSet = { tags: { $each: ['a', 'b'] } }
+ * 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] } }
  * ```
  */
-type AddToSetEach<E> = {
-    $each: E[];
-};
+declare function createExpressionBuilder<T>(): ExpressionBuilder<T>;
+
 /**
- * Fields valid for the `$addToSet` operator — only array-typed fields.
+ * Comparison operators for a field value of type `V`.
  *
- * Accepts a single element value or `{ $each: [...] }` for multiple elements.
+ * Maps each MongoDB comparison operator to its expected value type.
+ * `$regex` is only available when `V` extends `string`.
+ *
+ * Used as the operator object that can be assigned to a field in {@link TypedFilter}.
  *
  * @example
  * ```ts
- * const add: AddToSetFields<User> = { tags: 'dev' }
- * const addMany: AddToSetFields<User> = { tags: { $each: ['a', 'b'] } }
+ * // As a raw object (without builder functions)
+ * const filter: TypedFilter<User> = { age: { $gt: 25, $lte: 65 } }
+ *
+ * // $regex only available on string fields
+ * const filter: TypedFilter<User> = { name: { $regex: /^A/i } }
  * ```
  */
-type AddToSetFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | AddToSetEach<ArrayElement<NonNullable<T[K]>>>;
-};
+type ComparisonOperators<V> = {
+    /** Matches values equal to the specified value. */
+    $eq?: V;
+    /** Matches values not equal to the specified value. */
+    $ne?: V;
+    /** Matches values greater than the specified value. */
+    $gt?: V;
+    /** Matches values greater than or equal to the specified value. */
+    $gte?: V;
+    /** Matches values less than the specified value. */
+    $lt?: V;
+    /** Matches values less than or equal to the specified value. */
+    $lte?: 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. */
+    $not?: 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];
 /**
- * Fields valid for the `$pop` operator — only array-typed fields.
+ * Generates a union of all valid dot-separated paths for nested object fields in `T`.
  *
- * Value `1` removes the last element, `-1` removes the first.
+ * 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.
  *
  * @example
  * ```ts
- * const pop: PopFields<User> = { tags: -1 } // remove first
+ * type User = { address: { city: string; geo: { lat: number; lng: number } } }
+ *
+ * // DotPaths<User> = 'address.city' | 'address.geo' | 'address.geo.lat' | 'address.geo.lng'
  * ```
  */
-type PopFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: 1 | -1;
-};
+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];
 /**
- * Fields valid for the `$unset` operator — any existing field.
+ * Resolves the value type at a dot-separated path `P` within type `T`.
  *
- * Value is `''`, `true`, or `1` (all mean "remove this field").
+ * Splits `P` on the first `.` and recursively descends into `T`'s nested types.
+ * Returns `never` if the path is invalid.
  *
  * @example
  * ```ts
- * const unset: UnsetFields<User> = { middleName: '' }
+ * type User = { address: { city: string; geo: { lat: number } } }
+ *
+ * // DotPathType<User, 'address.city'> = string
+ * // DotPathType<User, 'address.geo.lat'> = number
  * ```
  */
-type UnsetFields<T> = {
-    [K in keyof T]?: '' | true | 1;
-};
+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;
 /**
- * Fields valid for the `$currentDate` operator — only Date-typed fields.
+ * Strict type-safe MongoDB filter query type.
  *
- * Sets the field to the current date. Value is `true` or `{ $type: 'date' }`.
+ * Validates filter objects at compile time — rejects nonexistent fields, type mismatches,
+ * and invalid operator usage. Unlike the MongoDB driver's `Filter<T>`, does NOT allow
+ * arbitrary keys via `& Document`.
  *
- * @example
- * ```ts
- * const cd: CurrentDateFields<User> = { createdAt: true }
- * ```
- */
-type CurrentDateFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends Date ? K : never]?: true | {
-        $type: 'date';
-    };
-};
-/**
- * Fields valid for the `$rename` operator.
+ * 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' }`
  *
- * Renames an existing field to a new name. Key is the current field name,
- * value is the new name as a string.
+ * Logical operators `$and`, `$or`, and `$nor` accept arrays of `TypedFilter<T>`
+ * for composing complex queries.
  *
  * @example
  * ```ts
- * const rename: RenameFields<User> = { name: 'fullName' }
- * ```
- */
-type RenameFields<T> = {
-    [K in keyof T & string]?: string;
-};
-/**
- * Strict type-safe MongoDB update filter.
- *
- * Validates update operators against field types at compile time. Each operator
- * constrains which fields it accepts (e.g. `$inc` only on numbers, `$push` only
- * on arrays). Supports dot-notation paths for nested field access.
+ * // Simple equality
+ * const filter: TypedFilter<User> = { name: 'Alice' }
  *
- * @example
- * ```ts
- * const update: TypedUpdateFilter<User> = {
- *   $set: { name: 'Alice' },
- *   $inc: { age: 1 },
- * }
+ * // Builder functions mixed with object literals
+ * const filter: TypedFilter<User> = { age: $gte(18), role: $in(['admin', 'mod']) }
+ *
+ * // Logical composition — T inferred from find() context
+ * posts.find($and(
+ *   $or({ published: true }, { views: $gte(100) }),
+ *   { title: $regex(/guide/i) },
+ * ))
+ *
+ * // Dynamic conditional building
+ * const conditions: TypedFilter<User>[] = []
+ * if (name)   conditions.push({ name })
+ * if (minAge) conditions.push({ age: $gte(minAge) })
+ * const filter = conditions.length ? $and<User>(...conditions) : {}
  * ```
  */
-type TypedUpdateFilter<T> = {
-    /** Sets the value of one or more fields. */
-    $set?: SetFields<T>;
-    /** Sets fields only when inserting (upsert). Same typing as `$set`. */
-    $setOnInsert?: SetFields<T>;
-    /** Increments numeric fields by the given amount. Only accepts number-typed fields. */
-    $inc?: IncFields<T>;
-    /** Updates the field if the given value is less than the current value. */
-    $min?: SetFields<T>;
-    /** Updates the field if the given value is greater than the current value. */
-    $max?: SetFields<T>;
-    /** Appends a value to an array field. Supports `$each`, `$position`, `$slice`, `$sort`. */
-    $push?: PushFields<T>;
-    /** Removes matching values from an array field. */
-    $pull?: PullFields<T>;
-    /** Adds a value to an array only if it doesn't already exist. */
-    $addToSet?: AddToSetFields<T>;
-    /** Removes the first (`-1`) or last (`1`) element of an array. */
-    $pop?: PopFields<T>;
-    /** Removes the specified fields from the document. */
-    $unset?: UnsetFields<T>;
-    /** Sets the field to the current date. Only accepts Date-typed fields. */
-    $currentDate?: CurrentDateFields<T>;
-    /** Renames a field. */
-    $rename?: RenameFields<T>;
+type TypedFilter<T> = {
+    [K in keyof T]?: T[K] | ComparisonOperators<T[K]>;
+} & {
+    [P in DotPaths<T>]?: DotPathType<T, P> | ComparisonOperators<DotPathType<T, P>>;
+} & {
+    /** Joins clauses with a logical AND. Matches documents that satisfy all filters. */
+    $and?: TypedFilter<T>[];
+    /** Joins clauses with a logical OR. Matches documents that satisfy at least one filter. */
+    $or?: TypedFilter<T>[];
+    /** Joins clauses with a logical NOR. Matches documents that fail all filters. */
+    $nor?: TypedFilter<T>[];
 };
 
 /**
- * Options for {@link updateOne} and {@link updateMany}.
- */
-type UpdateOptions = {
-    /** When `true`, inserts a new document if no document matches the filter. */
-    upsert?: boolean;
-};
-/**
- * Options for {@link findOneAndUpdate}.
+ * Options for {@link findOneAndDelete}.
  */
-type FindOneAndUpdateOptions = {
-    /** Whether to return the document before or after the update. Defaults to `'after'`. */
-    returnDocument?: 'before' | 'after';
-    /** When `true`, inserts a new document if no document matches the filter. */
-    upsert?: boolean;
+type FindOneAndDeleteOptions = {
     /** Override the collection-level validation mode, or `false` to skip validation entirely. */
     validate?: ValidationMode | false;
 };
 /**
- * Update a single document matching the filter.
+ * Delete a single document matching the filter.
  *
- * Applies the update operators to the first document that matches the filter.
- * Does not validate the update against the Zod schema — validation happens
- * at the field-operator level through {@link TypedUpdateFilter}.
+ * Removes the first document that matches the filter from the collection.
+ * No validation is performed — the document is deleted directly through
+ * the MongoDB driver.
  *
- * @param handle - The collection handle to update in.
+ * @param handle - The collection handle to delete from.
  * @param filter - Type-safe filter to match documents.
- * @param update - Type-safe update operators to apply.
- * @param options - Optional settings such as `upsert`.
- * @returns The MongoDB `UpdateResult` with match/modify counts.
+ * @returns The MongoDB `DeleteResult` with the deleted count.
  *
  * @example
  * ```ts
- * const result = await updateOne(users, { name: 'Ada' }, { $set: { role: 'admin' } })
- * console.log(result.modifiedCount) // 1
+ * const result = await deleteOne(users, { name: 'Ada' })
+ * console.log(result.deletedCount) // 1
  * ```
  */
-declare function updateOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+declare function deleteOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
 /**
- * Update all documents matching the filter.
+ * Delete all documents matching the filter.
  *
- * Applies the update operators to every document that matches the filter.
- * Does not validate the update against the Zod schema — validation happens
- * at the field-operator level through {@link TypedUpdateFilter}.
+ * Removes every document that matches the filter from the collection.
+ * No validation is performed — documents are deleted directly through
+ * the MongoDB driver.
  *
- * @param handle - The collection handle to update in.
+ * @param handle - The collection handle to delete from.
  * @param filter - Type-safe filter to match documents.
- * @param update - Type-safe update operators to apply.
- * @param options - Optional settings such as `upsert`.
- * @returns The MongoDB `UpdateResult` with match/modify counts.
+ * @returns The MongoDB `DeleteResult` with the deleted count.
  *
  * @example
  * ```ts
- * const result = await updateMany(users, { role: 'guest' }, { $set: { role: 'user' } })
- * console.log(result.modifiedCount) // number of guests promoted
+ * const result = await deleteMany(users, { role: 'guest' })
+ * console.log(result.deletedCount) // number of guests removed
  * ```
  */
-declare function updateMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+declare function deleteMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
 /**
- * Find a single document matching the filter, apply an update, and return the document.
+ * Find a single document matching the filter, delete it, and return the document.
  *
- * By default, returns the document **after** the update is applied. Set
- * `returnDocument: 'before'` to get the pre-update snapshot. The returned
- * document is validated against the collection's Zod schema using the same
- * resolution logic as {@link findOne}.
+ * Returns the deleted document, or `null` if no document matches the filter.
+ * The returned document is validated against the collection's Zod schema
+ * using the same resolution logic as {@link findOne}.
  *
- * @param handle - The collection handle to update in.
+ * @param handle - The collection handle to delete from.
  * @param filter - Type-safe filter to match documents.
- * @param update - Type-safe update operators to apply.
- * @param options - Optional settings: `returnDocument`, `upsert`, `validate`.
- * @returns The matched document (before or after update), or `null` if no document matches.
+ * @param options - Optional settings: `validate`.
+ * @returns The deleted document, or `null` if no document matches.
  * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
  *
  * @example
  * ```ts
- * const user = await findOneAndUpdate(
- *   users,
- *   { name: 'Ada' },
- *   { $set: { role: 'admin' } },
- * )
- * if (user) console.log(user.role) // 'admin' (returned after update)
+ * const user = await findOneAndDelete(users, { name: 'Ada' })
+ * if (user) console.log(user.name) // 'Ada' (the deleted document)
  * ```
  *
  * @example
  * ```ts
- * const before = await findOneAndUpdate(
+ * const user = await findOneAndDelete(
  *   users,
- *   { name: 'Ada' },
- *   { $inc: { loginCount: 1 } },
- *   { returnDocument: 'before' },
+ *   { role: 'guest' },
+ *   { validate: false },
  * )
  * ```
  */
-declare function findOneAndUpdate<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: FindOneAndUpdateOptions): Promise<InferDocument<TDef> | null>;
+declare function findOneAndDelete<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneAndDeleteOptions): Promise<InferDocument<TDef> | null>;
 
 /**
- * Typed wrapper around a MongoDB driver `Collection`.
+ * Options for offset-based pagination.
  *
- * Created by {@link Database.use}. Holds the original `CollectionDefinition`
- * (for runtime schema validation and index metadata) alongside the native
- * driver collection parameterized with the inferred document type.
+ * @example
+ * ```ts
+ * await users.find({}).sort({ name: 1 }).paginate({ page: 2, perPage: 10 })
+ * ```
+ */
+type OffsetPaginateOptions = {
+    /** The page number to retrieve (1-indexed). */
+    page: number;
+    /** The number of documents per page. */
+    perPage: number;
+};
+/**
+ * Options for cursor-based pagination.
  *
- * @typeParam TDef - The collection definition type. Used to derive both
- *   the document type (`InferDocument`) and the insert type (`InferInsert`).
+ * @example
+ * ```ts
+ * const first = await users.find({}).sort({ name: 1 }).paginate({ limit: 10 })
+ * const next = await users.find({}).sort({ name: 1 }).paginate({ cursor: first.endCursor, limit: 10 })
+ * ```
  */
-declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
-    /** The collection definition containing schema, name, and index metadata. */
-    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>>);
-    /**
-     * Insert a single document into the collection.
-     *
-     * Validates the input against the collection's Zod schema before writing.
-     * Schema defaults (including auto-generated `_id`) are applied during
-     * validation. Returns the full document with all defaults filled in.
-     *
-     * @param doc - The document to insert. Fields with `.default()` are optional.
-     * @returns The inserted document with `_id` and all defaults applied.
-     * @throws {ZodmonValidationError} When the document fails schema validation.
-     *
-     * @example
-     * ```ts
-     * const users = db.use(Users)
-     * const user = await users.insertOne({ name: 'Ada' })
-     * console.log(user._id) // ObjectId (auto-generated)
-     * console.log(user.role) // 'user' (schema default)
-     * ```
-     */
-    insertOne(doc: InferInsert<TDef>): Promise<InferDocument<TDef>>;
-    /**
-     * Insert multiple documents into the collection.
-     *
-     * Validates every document against the collection's Zod schema before
-     * writing any to MongoDB. If any document fails validation, none are
-     * inserted (fail-fast before the driver call).
-     *
-     * @param docs - The documents to insert.
-     * @returns The inserted documents with `_id` and all defaults applied.
-     * @throws {ZodmonValidationError} When any document fails schema validation.
-     *
-     * @example
-     * ```ts
-     * const created = await users.insertMany([
-     *   { name: 'Ada' },
-     *   { name: 'Bob', role: 'admin' },
-     * ])
-     * ```
-     */
-    insertMany(docs: InferInsert<TDef>[]): Promise<InferDocument<TDef>[]>;
-    /**
-     * 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'`).
+type CursorPaginateOptions = {
+    /** Maximum number of documents to return. */
+    limit: number;
+    /** Opaque cursor string from a previous `startCursor` or `endCursor`. */
+    cursor?: string | null;
+};
+/**
+ * Result of offset-based pagination.
+ *
+ * @example
+ * ```ts
+ * const page = await users.find({}).paginate({ page: 1, perPage: 10 })
+ * console.log(page.total, page.totalPages, page.hasNext)
+ * ```
+ */
+type OffsetPage<TDoc> = {
+    /** The documents for this page. */
+    docs: TDoc[];
+    /** Total number of matching documents. */
+    total: number;
+    /** Current page number (1-indexed). */
+    page: number;
+    /** Number of documents per page. */
+    perPage: number;
+    /** Total number of pages (`Math.ceil(total / perPage)`). */
+    totalPages: number;
+    /** Whether there is a next page. */
+    hasNext: boolean;
+    /** Whether there is a previous page. */
+    hasPrev: boolean;
+};
+/**
+ * Result of cursor-based pagination.
+ *
+ * @example
+ * ```ts
+ * const page = await users.find({}).paginate({ limit: 10 })
+ * if (page.hasNext) {
+ *   const next = await users.find({}).paginate({ cursor: page.endCursor, limit: 10 })
+ * }
+ * ```
+ */
+type CursorPage<TDoc> = {
+    /** The documents for this page. */
+    docs: TDoc[];
+    /** Whether there are more documents after this page. */
+    hasNext: boolean;
+    /** Whether there are documents before this page. */
+    hasPrev: boolean;
+    /** Cursor for the first document (pass to `cursor` to go backward). `null` when empty. */
+    startCursor: string | null;
+    /** Cursor for the last document (pass to `cursor` to go forward). `null` when empty. */
+    endCursor: string | null;
+};
+
+/**
+ * Type-safe sort specification for a document type.
+ *
+ * Constrains sort keys to top-level fields of `T` with direction `1` (ascending)
+ * or `-1` (descending). Dot-path sorts deferred to v1.0.
+ *
+ * @example
+ * ```ts
+ * const sort: TypedSort<User> = { name: 1, createdAt: -1 }
+ * ```
+ */
+type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
+/**
+ * Type-safe cursor wrapping MongoDB's `FindCursor`.
+ *
+ * Provides chainable query modifiers (`sort`, `skip`, `limit`, `hint`) that return
+ * `this` for fluent chaining, and terminal methods (`toArray`,
+ * `[Symbol.asyncIterator]`) that validate each document against the
+ * collection's Zod schema before returning.
+ *
+ * Created by {@link find} — do not construct directly.
+ *
+ * @typeParam TDef - The collection definition type, used to infer the document type.
+ * @typeParam TIndexNames - Union of declared index names accepted by `.hint()`.
+ *
+ * @example
+ * ```ts
+ * const docs = await find(users, { role: 'admin' })
+ *   .sort({ name: 1 })
+ *   .limit(10)
+ *   .toArray()
+ * ```
+ */
+declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends string = string> {
+    /** @internal */
+    private cursor;
+    /** @internal */
+    private schema;
+    /** @internal */
+    private collectionName;
+    /** @internal */
+    private mode;
+    /** @internal */
+    private readonly nativeCollection;
+    /** @internal */
+    private readonly filter;
+    /** @internal */
+    private sortSpec;
+    /** @internal */
+    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false, nativeCollection: Collection<InferDocument<TDef>>, filter: any);
+    /**
+     * Set the sort order for the query.
+     *
+     * Only top-level document fields are accepted as sort keys.
+     * Values must be `1` (ascending) or `-1` (descending).
+     *
+     * @param spec - Sort specification mapping field names to sort direction.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * find(users, {}).sort({ name: 1, age: -1 }).toArray()
+     * ```
+     */
+    sort(spec: TypedSort<InferDocument<TDef>>): this;
+    /**
+     * Skip the first `n` documents in the result set.
+     *
+     * @param n - Number of documents to skip.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * find(users, {}).skip(10).limit(10).toArray() // page 2
+     * ```
+     */
+    skip(n: number): this;
+    /**
+     * Limit the number of documents returned.
+     *
+     * @param n - Maximum number of documents to return.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * find(users, {}).limit(10).toArray() // at most 10 docs
+     * ```
+     */
+    limit(n: number): this;
+    /**
+     * Force the query optimizer to use the specified index.
+     *
+     * Only accepts index names that were declared via `.name()` in the
+     * collection definition. If no named indexes exist, any string is accepted.
+     *
+     * @param indexName - The name of a declared compound index.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * const Users = collection('users', { email: z.string(), role: z.string() }, {
+     *   indexes: [index({ email: 1, role: -1 }).name('email_role_idx')],
+     * })
+     * const admins = await users.find({ role: 'admin' })
+     *   .hint('email_role_idx')
+     *   .toArray()
+     * ```
+     */
+    hint(indexName: TIndexNames): this;
+    /**
+     * Execute the query with offset-based pagination, returning a page of documents
+     * with total count and navigation metadata.
+     *
+     * Runs `countDocuments` and `find` in parallel for performance. Ignores any
+     * `.skip()` or `.limit()` already set on the cursor — issues a fresh query.
+     *
+     * @param opts - Offset pagination options: `page` (1-indexed) and `perPage`.
+     * @returns A page with `docs`, `total`, `totalPages`, `hasNext`, `hasPrev`.
+     * @throws {ZodmonValidationError} When a document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * const page = await users.find({ role: 'admin' })
+     *   .sort({ createdAt: -1 })
+     *   .paginate({ page: 2, perPage: 10 })
+     * console.log(page.total, page.totalPages, page.hasNext)
+     * ```
+     */
+    paginate(opts: OffsetPaginateOptions): Promise<OffsetPage<InferDocument<TDef>>>;
+    /**
+     * Execute the query with cursor-based pagination, returning a page of documents
+     * with opaque cursors for forward/backward navigation.
+     *
+     * Uses the `limit + 1` trick to determine `hasNext`/`hasPrev` without extra queries.
+     * Direction is encoded in the cursor — pass `endCursor` to go forward, `startCursor`
+     * to go backward.
+     *
+     * @param opts - Cursor pagination options: `limit` and optional `cursor`.
+     * @returns A page with `docs`, `hasNext`, `hasPrev`, `startCursor`, `endCursor`.
+     * @throws {ZodmonValidationError} When a document fails schema validation.
+     * @throws {Error} When the cursor string is malformed.
+     *
+     * @example
+     * ```ts
+     * const first = await users.find({}).sort({ name: 1 }).paginate({ limit: 10 })
+     * const next = await users.find({}).sort({ name: 1 })
+     *   .paginate({ cursor: first.endCursor, limit: 10 })
+     * ```
+     */
+    paginate(opts: CursorPaginateOptions): Promise<CursorPage<InferDocument<TDef>>>;
+    /** @internal Offset pagination implementation. */
+    private offsetPaginate;
+    /** @internal Cursor pagination implementation. */
+    private cursorPaginate;
+    /**
+     * Execute the query and return all matching documents as an array.
+     *
+     * Each document is validated against the collection's Zod schema
+     * according to the resolved validation mode.
+     *
+     * @returns Array of validated documents.
+     * @throws {ZodmonValidationError} When a document fails schema validation in strict/strip mode.
+     *
+     * @example
+     * ```ts
+     * const admins = await find(users, { role: 'admin' }).toArray()
+     * ```
+     */
+    toArray(): Promise<InferDocument<TDef>[]>;
+    /**
+     * Async iterator for streaming documents one at a time.
+     *
+     * Each yielded document is validated against the collection's Zod schema.
+     * Memory-efficient for large result sets.
+     *
+     * @yields Validated documents one at a time.
+     * @throws {ZodmonValidationError} When a document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * for await (const user of find(users, {})) {
+     *   console.log(user.name)
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<InferDocument<TDef>>;
+    /** @internal Validate a single raw document against the schema. */
+    private validateDoc;
+}
+
+/**
+ * Options for {@link findOne} and {@link findOneOrThrow}.
+ */
+type FindOneOptions = {
+    /** MongoDB projection — include (`1`) or exclude (`0`) fields. Typed projections deferred to v1.0. */
+    project?: Record<string, 0 | 1>;
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
+/**
+ * Find a single document matching the filter.
+ *
+ * Queries MongoDB, then validates the fetched document against the collection's
+ * Zod schema. Validation mode is resolved from the per-query option, falling
+ * back to the collection-level default (which defaults to `'strict'`).
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Optional projection and validation overrides.
+ * @returns The matched document, or `null` if no document matches.
+ * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+ *
+ * @example
+ * ```ts
+ * const user = await findOne(users, { name: 'Ada' })
+ * if (user) console.log(user.role) // typed as 'admin' | 'user'
+ * ```
+ */
+declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+/**
+ * Find a single document matching the filter, or throw if none exists.
+ *
+ * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
+ * instead of returning `null` when no document matches the filter.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Optional projection and validation overrides.
+ * @returns The matched document (never null).
+ * @throws {ZodmonNotFoundError} When no document matches the filter.
+ * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+ *
+ * @example
+ * ```ts
+ * const user = await findOneOrThrow(users, { name: 'Ada' })
+ * console.log(user.role) // typed as 'admin' | 'user', guaranteed non-null
+ * ```
+ */
+declare function findOneOrThrow<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+/**
+ * Options for {@link find}.
+ */
+type FindOptions = {
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
+/**
+ * Find all documents matching the filter, returning a chainable typed cursor.
+ *
+ * The cursor is lazy — no query is executed until a terminal method
+ * (`toArray`, `for await`) is called. Use `sort`, `skip`, and `limit`
+ * to shape the query before executing.
+ *
+ * Each document is validated against the collection's Zod schema when
+ * a terminal method consumes it.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Optional validation overrides.
+ * @returns A typed cursor for chaining query modifiers.
+ *
+ * @example
+ * ```ts
+ * const admins = await find(users, { role: 'admin' })
+ *   .sort({ name: 1 })
+ *   .limit(10)
+ *   .toArray()
+ * ```
+ *
+ * @example
+ * ```ts
+ * for await (const user of find(users, {})) {
+ *   console.log(user.name)
+ * }
+ * ```
+ */
+declare function find<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
+
+/**
+ * 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.
+ *
+ * Allows top-level fields with matching value types plus dot-notation paths
+ * for nested field updates.
+ *
+ * @example
+ * ```ts
+ * const set: SetFields<User> = { name: 'Alice', 'address.city': 'NYC' }
+ * ```
+ */
+type SetFields<T> = {
+    [K in keyof T]?: T[K];
+} & {
+    [P in DotPaths<T>]?: DotPathType<T, P>;
+};
+/**
+ * Fields valid for the `$inc` operator — only number-typed fields.
+ *
+ * Includes dot-notation paths that resolve to number types.
+ *
+ * @example
+ * ```ts
+ * const inc: IncFields<User> = { age: 1, 'stats.views': 5 }
+ * ```
+ */
+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;
+};
+/**
+ * Modifiers for the `$push` operator.
+ *
+ * Use with `$push` to insert multiple elements and control array position/size.
+ *
+ * @example
+ * ```ts
+ * const push = { tags: { $each: ['a', 'b'], $position: 0, $slice: 10 } }
+ * ```
+ */
+type PushModifiers<E> = {
+    /** Array of elements to push. */
+    $each: E[];
+    /** Position at which to insert elements. */
+    $position?: number;
+    /** Maximum array length after push. */
+    $slice?: number;
+    /** Sort order applied after push. */
+    $sort?: 1 | -1 | Record<string, 1 | -1>;
+};
+/**
+ * Fields valid for the `$push` operator — only array-typed fields.
+ *
+ * Accepts a single element value or a modifier object with `$each`.
+ *
+ * @example
+ * ```ts
+ * const push: PushFields<User> = { tags: 'dev' }
+ * const pushMany: PushFields<User> = { tags: { $each: ['a', 'b'] } }
+ * ```
+ */
+type PushFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | PushModifiers<ArrayElement<NonNullable<T[K]>>>;
+};
+/**
+ * Fields valid for the `$pull` operator — only array-typed fields.
+ *
+ * For primitive arrays: accepts a value or comparison operators.
+ * For object arrays: also accepts a `TypedFilter` on the element type.
+ *
+ * @example
+ * ```ts
+ * const pull: PullFields<User> = { tags: 'old' }
+ * const pullQuery: PullFields<User> = { scores: { $lt: 50 } }
+ * const pullObj: PullFields<User> = { comments: { author: 'spam' } }
+ * ```
+ */
+type PullFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | ComparisonOperators<ArrayElement<NonNullable<T[K]>>> | (ArrayElement<NonNullable<T[K]>> extends Record<string, unknown> ? TypedFilter<ArrayElement<NonNullable<T[K]>>> : unknown);
+};
+/**
+ * Modifier for the `$addToSet` operator's `$each` syntax.
+ *
+ * @example
+ * ```ts
+ * const addToSet = { tags: { $each: ['a', 'b'] } }
+ * ```
+ */
+type AddToSetEach<E> = {
+    $each: E[];
+};
+/**
+ * Fields valid for the `$addToSet` operator — only array-typed fields.
+ *
+ * Accepts a single element value or `{ $each: [...] }` for multiple elements.
+ *
+ * @example
+ * ```ts
+ * const add: AddToSetFields<User> = { tags: 'dev' }
+ * const addMany: AddToSetFields<User> = { tags: { $each: ['a', 'b'] } }
+ * ```
+ */
+type AddToSetFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | AddToSetEach<ArrayElement<NonNullable<T[K]>>>;
+};
+/**
+ * Fields valid for the `$pop` operator — only array-typed fields.
+ *
+ * Value `1` removes the last element, `-1` removes the first.
+ *
+ * @example
+ * ```ts
+ * const pop: PopFields<User> = { tags: -1 } // remove first
+ * ```
+ */
+type PopFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: 1 | -1;
+};
+/**
+ * Fields valid for the `$unset` operator — any existing field.
+ *
+ * Value is `''`, `true`, or `1` (all mean "remove this field").
+ *
+ * @example
+ * ```ts
+ * const unset: UnsetFields<User> = { middleName: '' }
+ * ```
+ */
+type UnsetFields<T> = {
+    [K in keyof T]?: '' | true | 1;
+};
+/**
+ * Fields valid for the `$currentDate` operator — only Date-typed fields.
+ *
+ * Sets the field to the current date. Value is `true` or `{ $type: 'date' }`.
+ *
+ * @example
+ * ```ts
+ * const cd: CurrentDateFields<User> = { createdAt: true }
+ * ```
+ */
+type CurrentDateFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends Date ? K : never]?: true | {
+        $type: 'date';
+    };
+};
+/**
+ * Fields valid for the `$rename` operator.
+ *
+ * Renames an existing field to a new name. Key is the current field name,
+ * value is the new name as a string.
+ *
+ * @example
+ * ```ts
+ * const rename: RenameFields<User> = { name: 'fullName' }
+ * ```
+ */
+type RenameFields<T> = {
+    [K in keyof T & string]?: string;
+};
+/**
+ * Strict type-safe MongoDB update filter.
+ *
+ * Validates update operators against field types at compile time. Each operator
+ * constrains which fields it accepts (e.g. `$inc` only on numbers, `$push` only
+ * on arrays). Supports dot-notation paths for nested field access.
+ *
+ * @example
+ * ```ts
+ * const update: TypedUpdateFilter<User> = {
+ *   $set: { name: 'Alice' },
+ *   $inc: { age: 1 },
+ * }
+ * ```
+ */
+type TypedUpdateFilter<T> = {
+    /** Sets the value of one or more fields. */
+    $set?: SetFields<T>;
+    /** Sets fields only when inserting (upsert). Same typing as `$set`. */
+    $setOnInsert?: SetFields<T>;
+    /** Increments numeric fields by the given amount. Only accepts number-typed fields. */
+    $inc?: IncFields<T>;
+    /** Updates the field if the given value is less than the current value. */
+    $min?: SetFields<T>;
+    /** Updates the field if the given value is greater than the current value. */
+    $max?: SetFields<T>;
+    /** Appends a value to an array field. Supports `$each`, `$position`, `$slice`, `$sort`. */
+    $push?: PushFields<T>;
+    /** Removes matching values from an array field. */
+    $pull?: PullFields<T>;
+    /** Adds a value to an array only if it doesn't already exist. */
+    $addToSet?: AddToSetFields<T>;
+    /** Removes the first (`-1`) or last (`1`) element of an array. */
+    $pop?: PopFields<T>;
+    /** Removes the specified fields from the document. */
+    $unset?: UnsetFields<T>;
+    /** Sets the field to the current date. Only accepts Date-typed fields. */
+    $currentDate?: CurrentDateFields<T>;
+    /** Renames a field. */
+    $rename?: RenameFields<T>;
+};
+
+/**
+ * Options for {@link updateOne} and {@link updateMany}.
+ */
+type UpdateOptions = {
+    /** When `true`, inserts a new document if no document matches the filter. */
+    upsert?: boolean;
+};
+/**
+ * Options for {@link findOneAndUpdate}.
+ */
+type FindOneAndUpdateOptions = {
+    /** Whether to return the document before or after the update. Defaults to `'after'`. */
+    returnDocument?: 'before' | 'after';
+    /** When `true`, inserts a new document if no document matches the filter. */
+    upsert?: boolean;
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
+/**
+ * Update a single document matching the filter.
+ *
+ * Applies the update operators to the first document that matches the filter.
+ * Does not validate the update against the Zod schema — validation happens
+ * at the field-operator level through {@link TypedUpdateFilter}.
+ *
+ * @param handle - The collection handle to update in.
+ * @param filter - Type-safe filter to match documents.
+ * @param update - Type-safe update operators to apply.
+ * @param options - Optional settings such as `upsert`.
+ * @returns The MongoDB `UpdateResult` with match/modify counts.
+ *
+ * @example
+ * ```ts
+ * const result = await updateOne(users, { name: 'Ada' }, { $set: { role: 'admin' } })
+ * console.log(result.modifiedCount) // 1
+ * ```
+ */
+declare function updateOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+/**
+ * Update all documents matching the filter.
+ *
+ * Applies the update operators to every document that matches the filter.
+ * Does not validate the update against the Zod schema — validation happens
+ * at the field-operator level through {@link TypedUpdateFilter}.
+ *
+ * @param handle - The collection handle to update in.
+ * @param filter - Type-safe filter to match documents.
+ * @param update - Type-safe update operators to apply.
+ * @param options - Optional settings such as `upsert`.
+ * @returns The MongoDB `UpdateResult` with match/modify counts.
+ *
+ * @example
+ * ```ts
+ * const result = await updateMany(users, { role: 'guest' }, { $set: { role: 'user' } })
+ * console.log(result.modifiedCount) // number of guests promoted
+ * ```
+ */
+declare function updateMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+/**
+ * Find a single document matching the filter, apply an update, and return the document.
+ *
+ * By default, returns the document **after** the update is applied. Set
+ * `returnDocument: 'before'` to get the pre-update snapshot. The returned
+ * document is validated against the collection's Zod schema using the same
+ * resolution logic as {@link findOne}.
+ *
+ * @param handle - The collection handle to update in.
+ * @param filter - Type-safe filter to match documents.
+ * @param update - Type-safe update operators to apply.
+ * @param options - Optional settings: `returnDocument`, `upsert`, `validate`.
+ * @returns The matched document (before or after update), or `null` if no document matches.
+ * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+ *
+ * @example
+ * ```ts
+ * const user = await findOneAndUpdate(
+ *   users,
+ *   { name: 'Ada' },
+ *   { $set: { role: 'admin' } },
+ * )
+ * if (user) console.log(user.role) // 'admin' (returned after update)
+ * ```
+ *
+ * @example
+ * ```ts
+ * const before = await findOneAndUpdate(
+ *   users,
+ *   { name: 'Ada' },
+ *   { $inc: { loginCount: 1 } },
+ *   { returnDocument: 'before' },
+ * )
+ * ```
+ */
+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`.
+ *
+ * Created by {@link Database.use}. Holds the original `CollectionDefinition`
+ * (for runtime schema validation and index metadata) alongside the native
+ * driver collection parameterized with the inferred document type.
+ *
+ * @typeParam TDef - The collection definition type. Used to derive both
+ *   the document type (`InferDocument`) and the insert type (`InferInsert`).
+ */
+declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
+    /** The collection definition containing schema, name, and index metadata. */
+    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>>);
+    /**
+     * Insert a single document into the collection.
+     *
+     * Validates the input against the collection's Zod schema before writing.
+     * Schema defaults (including auto-generated `_id`) are applied during
+     * validation. Returns the full document with all defaults filled in.
+     *
+     * @param doc - The document to insert. Fields with `.default()` are optional.
+     * @returns The inserted document with `_id` and all defaults applied.
+     * @throws {ZodmonValidationError} When the document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.insertOne({ name: 'Ada' })
+     * console.log(user._id) // ObjectId (auto-generated)
+     * console.log(user.role) // 'user' (schema default)
+     * ```
+     */
+    insertOne(doc: InferInsert<TDef>): Promise<InferDocument<TDef>>;
+    /**
+     * Insert multiple documents into the collection.
+     *
+     * Validates every document against the collection's Zod schema before
+     * writing any to MongoDB. If any document fails validation, none are
+     * inserted (fail-fast before the driver call).
+     *
+     * @param docs - The documents to insert.
+     * @returns The inserted documents with `_id` and all defaults applied.
+     * @throws {ZodmonValidationError} When any document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * const created = await users.insertMany([
+     *   { name: 'Ada' },
+     *   { name: 'Bob', role: 'admin' },
+     * ])
+     * ```
+     */
+    insertMany(docs: InferInsert<TDef>[]): Promise<InferDocument<TDef>[]>;
+    /**
+     * Find a single document matching the filter.
+     *
+     * Queries MongoDB, then validates the fetched document against the collection's
+     * Zod schema. Validation mode is resolved from the per-query option, falling
+     * back to the collection-level default (which defaults to `'strict'`).
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Optional projection and validation overrides.
+     * @returns The matched document, or `null` if no document matches.
+     * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOne({ name: 'Ada' })
+     * if (user) console.log(user.role)
+     * ```
+     */
+    findOne(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+    /**
+     * Find a single document matching the filter, or throw if none exists.
+     *
+     * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
+     * instead of returning `null` when no document matches the filter.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Optional projection and validation overrides.
+     * @returns The matched document (never null).
+     * @throws {ZodmonNotFoundError} When no document matches the filter.
+     * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOneOrThrow({ name: 'Ada' })
+     * console.log(user.role) // guaranteed non-null
+     * ```
+     */
+    findOneOrThrow(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+    /**
+     * Find all documents matching the filter, returning a chainable typed cursor.
+     *
+     * The cursor is lazy — no query is executed until a terminal method
+     * (`toArray`, `for await`) is called. Use `sort`, `skip`, and `limit`
+     * to shape the query before executing.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Optional validation overrides.
+     * @returns A typed cursor for chaining query modifiers.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const admins = await users.find({ role: 'admin' })
+     *   .sort({ name: 1 })
+     *   .limit(10)
+     *   .toArray()
+     * ```
+     */
+    find(filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
+    /**
+     * Update a single document matching the filter.
+     *
+     * Applies the update operators to the first document that matches the filter.
+     * Does not validate the update against the Zod schema — validation happens
+     * at the field-operator level through {@link TypedUpdateFilter}.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param update - Type-safe update operators to apply.
+     * @param options - Optional settings such as `upsert`.
+     * @returns The MongoDB `UpdateResult` with match/modify counts.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.updateOne({ name: 'Ada' }, { $set: { role: 'admin' } })
+     * console.log(result.modifiedCount) // 1
+     * ```
+     */
+    updateOne(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Update all documents matching the filter.
+     *
+     * Applies the update operators to every document that matches the filter.
+     * Does not validate the update against the Zod schema — validation happens
+     * at the field-operator level through {@link TypedUpdateFilter}.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param update - Type-safe update operators to apply.
+     * @param options - Optional settings such as `upsert`.
+     * @returns The MongoDB `UpdateResult` with match/modify counts.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.updateMany({ role: 'guest' }, { $set: { role: 'user' } })
+     * console.log(result.modifiedCount) // number of guests promoted
+     * ```
+     */
+    updateMany(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Find a single document matching the filter, apply an update, and return the document.
+     *
+     * By default, returns the document **after** the update is applied. Set
+     * `returnDocument: 'before'` to get the pre-update snapshot. The returned
+     * document is validated against the collection's Zod schema using the same
+     * resolution logic as {@link findOne}.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param update - Type-safe update operators to apply.
+     * @param options - Optional settings: `returnDocument`, `upsert`, `validate`.
+     * @returns The matched document (before or after update), or `null` if no document matches.
+     * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOneAndUpdate(
+     *   { name: 'Ada' },
+     *   { $set: { role: 'admin' } },
+     * )
+     * if (user) console.log(user.role) // 'admin' (returned after update)
+     * ```
+     */
+    findOneAndUpdate(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: FindOneAndUpdateOptions): Promise<InferDocument<TDef> | null>;
+    /**
+     * Delete a single document matching the filter.
+     *
+     * Removes the first document that matches the filter from the collection.
+     * No validation is performed — the document is deleted directly through
+     * the MongoDB driver.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @returns The MongoDB `DeleteResult` with the deleted count.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.deleteOne({ name: 'Ada' })
+     * console.log(result.deletedCount) // 1
+     * ```
+     */
+    deleteOne(filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
+    /**
+     * Delete all documents matching the filter.
+     *
+     * Removes every document that matches the filter from the collection.
+     * No validation is performed — documents are deleted directly through
+     * the MongoDB driver.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @returns The MongoDB `DeleteResult` with the deleted count.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.deleteMany({ role: 'guest' })
+     * console.log(result.deletedCount) // number of guests removed
+     * ```
+     */
+    deleteMany(filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
+    /**
+     * Find a single document matching the filter, delete it, and return the document.
+     *
+     * Returns the deleted document, or `null` if no document matches the filter.
+     * The returned document is validated against the collection's Zod schema
+     * using the same resolution logic as {@link findOne}.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Optional settings: `validate`.
+     * @returns The deleted document, or `null` if no document matches.
+     * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOneAndDelete({ name: 'Ada' })
+     * if (user) console.log(user.name) // 'Ada' (the deleted document)
+     * ```
+     */
+    findOneAndDelete(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneAndDeleteOptions): Promise<InferDocument<TDef> | null>;
+    /**
+     * Synchronize the indexes declared in this collection's schema with MongoDB.
+     *
+     * Compares the desired indexes (from field-level `.index()` / `.unique()` /
+     * `.text()` / `.expireAfter()` and compound `indexes` in collection options)
+     * with the indexes that currently exist in MongoDB, then creates, drops, or
+     * reports differences depending on the options.
+     *
+     * @param options - Optional sync behavior (dryRun, dropOrphaned).
+     * @returns A summary of created, dropped, skipped, and stale indexes.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.syncIndexes()
+     * console.log('Created:', result.created)
+     * console.log('Stale:', result.stale.map(s => s.name))
+     * ```
+     *
+     * @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)
+     * ```
+     */
+    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.
      *
-     * @param filter - Type-safe filter to match documents.
-     * @param options - Optional projection and validation overrides.
-     * @returns The matched document, or `null` if no document matches.
-     * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+     * 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 users = db.use(Users)
-     * const user = await users.findOne({ name: 'Ada' })
-     * if (user) console.log(user.role)
+     * const namesAndRoles = await aggregate(users)
+     *   .pick('name', 'role')
+     *   .toArray()
      * ```
      */
-    findOne(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+    pick<K extends keyof TOutput & string>(...fields: K[]): AggregatePipeline<TDef, Prettify<Pick<TOutput, K | ('_id' extends keyof TOutput ? '_id' : never)>>>;
     /**
-     * Find a single document matching the filter, or throw if none exists.
+     * Exclude specified fields from the output.
      *
-     * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
-     * instead of returning `null` when no document matches the filter.
+     * Appends a `$project` stage with exclusion (`0`) for each key.
+     * All other fields pass through. The output type becomes `Omit<TOutput, K>`.
      *
-     * @param filter - Type-safe filter to match documents.
-     * @param options - Optional projection and validation overrides.
-     * @returns The matched document (never null).
-     * @throws {ZodmonNotFoundError} When no document matches the filter.
-     * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+     * @param fields - Field names to exclude from the output.
+     * @returns A new pipeline with the `$project` stage appended.
      *
      * @example
      * ```ts
-     * const users = db.use(Users)
-     * const user = await users.findOneOrThrow({ name: 'Ada' })
-     * console.log(user.role) // guaranteed non-null
+     * const noAge = await aggregate(users)
+     *   .omit('age')
+     *   .toArray()
      * ```
      */
-    findOneOrThrow(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+    omit<K extends keyof TOutput & string>(...fields: K[]): AggregatePipeline<TDef, Prettify<Omit<TOutput, K>>>;
     /**
-     * Find all documents matching the filter, returning a chainable typed cursor.
+     * Group documents by one or more fields with accumulator expressions.
      *
-     * The cursor is lazy — no query is executed until a terminal method
-     * (`toArray`, `for await`) is called. Use `sort`, `skip`, and `limit`
-     * to shape the query before executing.
+     * Accepts accumulators as either a **callback** (recommended) or a plain object.
      *
-     * @param filter - Type-safe filter to match documents.
-     * @param options - Optional validation overrides.
-     * @returns A typed cursor for chaining query modifiers.
+     * 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
-     * const users = db.use(Users)
-     * const admins = await users.find({ role: 'admin' })
-     *   .sort({ name: 1 })
-     *   .limit(10)
+     * // 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()
      * ```
      */
-    find(filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
+    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>>;
     /**
-     * Update a single document matching the filter.
+     * Add new fields or overwrite existing ones in the output documents.
      *
-     * Applies the update operators to the first document that matches the filter.
-     * Does not validate the update against the Zod schema — validation happens
-     * at the field-operator level through {@link TypedUpdateFilter}.
+     * **Callback style (recommended)** — the `ExpressionBuilder` provides
+     * autocomplete for field names and infers return types automatically:
      *
-     * @param filter - Type-safe filter to match documents.
-     * @param update - Type-safe update operators to apply.
-     * @param options - Optional settings such as `upsert`.
-     * @returns The MongoDB `UpdateResult` with match/modify counts.
+     * ```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 users = db.use(Users)
-     * const result = await users.updateOne({ name: 'Ada' }, { $set: { role: 'admin' } })
-     * console.log(result.modifiedCount) // 1
+     * const enriched = await aggregate(employees)
+     *   .addFields(expr => ({
+     *     hireYear: expr.year('hiredAt'),
+     *     monthlySalary: expr.divide('salary', 12),
+     *   }))
+     *   .toArray()
      * ```
      */
-    updateOne(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+    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>>;
     /**
-     * Update all documents matching the filter.
+     * Deconstruct an array field, outputting one document per array element.
      *
-     * Applies the update operators to every document that matches the filter.
-     * Does not validate the update against the Zod schema — validation happens
-     * at the field-operator level through {@link TypedUpdateFilter}.
+     * 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 filter - Type-safe filter to match documents.
-     * @param update - Type-safe update operators to apply.
-     * @param options - Optional settings such as `upsert`.
-     * @returns The MongoDB `UpdateResult` with match/modify counts.
+     * @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 users = db.use(Users)
-     * const result = await users.updateMany({ role: 'guest' }, { $set: { role: 'user' } })
-     * console.log(result.modifiedCount) // number of guests promoted
+     * const flat = await aggregate(orders)
+     *   .unwind('items')
+     *   .toArray()
+     * // Each result has a single `items` value instead of an array
      * ```
      */
-    updateMany(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+    unwind<K extends keyof TOutput & string>(field: K, options?: {
+        preserveEmpty?: boolean;
+    }): AggregatePipeline<TDef, UnwindResult<TOutput, K>>;
     /**
-     * Find a single document matching the filter, apply an update, and return the document.
+     * Join documents from another collection via a `$lookup` stage.
      *
-     * By default, returns the document **after** the update is applied. Set
-     * `returnDocument: 'before'` to get the pre-update snapshot. The returned
-     * document is validated against the collection's Zod schema using the same
-     * resolution logic as {@link findOne}.
+     * **Forward lookup** — when the field has `.ref()` metadata pointing to
+     * another collection, resolves the target collection and output type
+     * automatically:
      *
-     * @param filter - Type-safe filter to match documents.
-     * @param update - Type-safe update operators to apply.
-     * @param options - Optional settings: `returnDocument`, `upsert`, `validate`.
-     * @returns The matched document (before or after update), or `null` if no document matches.
-     * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+     * ```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
-     * const users = db.use(Users)
-     * const user = await users.findOneAndUpdate(
-     *   { name: 'Ada' },
-     *   { $set: { role: 'admin' } },
-     * )
-     * if (user) console.log(user.role) // 'admin' (returned after update)
+     * // 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
      * ```
      */
-    findOneAndUpdate(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: FindOneAndUpdateOptions): Promise<InferDocument<TDef> | null>;
+    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>[];
+    }>>;
     /**
-     * Delete a single document matching the filter.
+     * Count documents per group, sorted by count descending.
      *
-     * Removes the first document that matches the filter from the collection.
-     * No validation is performed — the document is deleted directly through
-     * the MongoDB driver.
+     * Shorthand for `.groupBy(field, { count: $count() }).sort({ count: -1 })`.
      *
-     * @param filter - Type-safe filter to match documents.
-     * @returns The MongoDB `DeleteResult` with the deleted count.
+     * @param field - The field to group and count by.
+     * @returns A new pipeline producing `{ _id: TOutput[K], count: number }` results.
      *
      * @example
      * ```ts
-     * const users = db.use(Users)
-     * const result = await users.deleteOne({ name: 'Ada' })
-     * console.log(result.deletedCount) // 1
+     * const roleCounts = await aggregate(users)
+     *   .countBy('role')
+     *   .toArray()
+     * // [{ _id: 'user', count: 3 }, { _id: 'admin', count: 2 }]
      * ```
      */
-    deleteOne(filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
+    countBy<K extends keyof TOutput & string>(field: K): AggregatePipeline<TDef, Prettify<{
+        _id: TOutput[K];
+        count: number;
+    }>>;
     /**
-     * Delete all documents matching the filter.
+     * Sum a numeric field per group, sorted by total descending.
      *
-     * Removes every document that matches the filter from the collection.
-     * No validation is performed — documents are deleted directly through
-     * the MongoDB driver.
+     * Shorthand for `.groupBy(field, { total: $sum('$sumField') }).sort({ total: -1 })`.
      *
-     * @param filter - Type-safe filter to match documents.
-     * @returns The MongoDB `DeleteResult` with the deleted count.
+     * @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 users = db.use(Users)
-     * const result = await users.deleteMany({ role: 'guest' })
-     * console.log(result.deletedCount) // number of guests removed
+     * const revenueByCategory = await aggregate(orders)
+     *   .sumBy('category', 'amount')
+     *   .toArray()
+     * // [{ _id: 'electronics', total: 5000 }, ...]
      * ```
      */
-    deleteMany(filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
+    sumBy<K extends keyof TOutput & string, S extends keyof TOutput & string>(field: K, sumField: S): AggregatePipeline<TDef, Prettify<{
+        _id: TOutput[K];
+        total: number;
+    }>>;
     /**
-     * Find a single document matching the filter, delete it, and return the document.
+     * Sort by a single field with a friendly direction name.
      *
-     * Returns the deleted document, or `null` if no document matches the filter.
-     * The returned document is validated against the collection's Zod schema
-     * using the same resolution logic as {@link findOne}.
+     * Shorthand for `.sort({ [field]: direction === 'desc' ? -1 : 1 })`.
      *
-     * @param filter - Type-safe filter to match documents.
-     * @param options - Optional settings: `validate`.
-     * @returns The deleted document, or `null` if no document matches.
-     * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+     * @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 users = db.use(Users)
-     * const user = await users.findOneAndDelete({ name: 'Ada' })
-     * if (user) console.log(user.name) // 'Ada' (the deleted document)
+     * const youngest = await aggregate(users)
+     *   .sortBy('age')
+     *   .toArray()
      * ```
      */
-    findOneAndDelete(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneAndDeleteOptions): Promise<InferDocument<TDef> | null>;
+    sortBy(field: keyof TOutput & string, direction?: 'asc' | 'desc'): AggregatePipeline<TDef, TOutput>;
     /**
-     * Synchronize the indexes declared in this collection's schema with MongoDB.
+     * Return the top N documents sorted by a field descending.
      *
-     * Compares the desired indexes (from field-level `.index()` / `.unique()` /
-     * `.text()` / `.expireAfter()` and compound `indexes` in collection options)
-     * with the indexes that currently exist in MongoDB, then creates, drops, or
-     * reports differences depending on the options.
+     * Shorthand for `.sort({ [by]: -1 }).limit(n)`.
      *
-     * @param options - Optional sync behavior (dryRun, dropOrphaned).
-     * @returns A summary of created, dropped, skipped, and stale indexes.
+     * @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 users = db.use(Users)
-     * const result = await users.syncIndexes()
-     * console.log('Created:', result.created)
-     * console.log('Stale:', result.stale.map(s => s.name))
+     * 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
-     * // 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)
+     * 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']>;
@@ -2111,11 +3336,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 +3432,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 +3443,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 +3544,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 +3609,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, ZodmonNotFoundError, ZodmonValidationError, 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 };