@zodmon/core 0.10.0 → 0.11.0

package/dist/index.d.ts

@@ -319,6 +319,40 @@ type ExtractNames<T extends readonly {
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/**
+ * Generates all valid dot-separated field paths for a document type.
+ *
+ * Recursively traverses nested objects and unwraps arrays to match
+ * MongoDB's implicit array traversal semantics. Both top-level keys
+ * and nested paths are included in the resulting union.
+ *
+ * @example
+ * ```ts
+ * type Doc = { address: { city: string }; tags: Array<{ label: string }> }
+ * type Paths = DotPath<Doc>
+ * //   ^? 'address' | 'address.city' | 'tags' | 'tags.label'
+ * ```
+ */
+type DotPath<T> = T extends ReadonlyArray<infer E> ? DotPath<E> : T extends Record<string, unknown> ? {
+    [K in keyof T & string]: T[K] extends ReadonlyArray<infer E> ? E extends Record<string, unknown> ? K | `${K}.${DotPath<E>}` : K : T[K] extends Record<string, unknown> ? K | `${K}.${DotPath<T[K]>}` : K;
+}[keyof T & string] : never;
+/**
+ * Resolves the value type at a dot-separated path within a document type.
+ *
+ * Splits the path on `.` and recursively descends into nested types.
+ * Unwraps arrays at intermediate levels to match MongoDB's implicit
+ * array traversal. Returns `never` for invalid paths.
+ *
+ * @example
+ * ```ts
+ * type Doc = { address: { city: string }; tags: Array<{ label: string }> }
+ * type City = DotPathValue<Doc, 'address.city'>
+ * //   ^? string
+ * type Label = DotPathValue<Doc, 'tags.label'>
+ * //   ^? string
+ * ```
+ */
+type DotPathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? T[K] extends ReadonlyArray<infer E> ? DotPathValue<E, Rest> : DotPathValue<T[K], Rest> : never : P extends keyof T ? T[P] : never;
 
 /**
  * Type-level marker that carries the target collection type through the
@@ -448,21 +482,25 @@ type InferAccumulators<T extends Record<string, Accumulator>> = {
     [K in keyof T]: InferAccumulator<T[K]>;
 };
 /**
- * Field reference string prefixed with `$`, constrained to keys of `T`.
+ * Field reference string prefixed with `$`, constrained to dot-paths of `T`.
+ *
+ * Supports both top-level fields (`$price`) and nested dot-paths
+ * (`$address.city`, `$address.geo.lat`).
  *
  * @example
  * ```ts
- * type OrderRef = FieldRef<{ price: number; qty: number }>
- * //   ^? '$price' | '$qty'
+ * type OrderRef = FieldRef<{ price: number; address: { city: string } }>
+ * //   ^? '$price' | '$address' | '$address.city'
  * ```
  */
-type FieldRef<T> = `$${keyof T & string}`;
+type FieldRef<T> = `$${DotPath<T>}`;
 /**
  * Typed accumulator factory passed to the `groupBy` callback.
  *
- * Each method constrains field names to `keyof T & string`, providing
- * IDE autocomplete and compile-time validation. Return types resolve
- * to the actual field type (`T[K]`), not `unknown`.
+ * Each method constrains field names to `DotPath<T>`, providing
+ * IDE autocomplete and compile-time validation for both top-level
+ * and nested dot-path fields. Return types resolve to the actual
+ * field type via `DotPathValue<T, F>`, not `unknown`.
  *
  * @typeParam T - The current pipeline output document type.
  *
@@ -470,10 +508,10 @@ type FieldRef<T> = `$${keyof T & string}`;
  * ```ts
  * users.aggregate()
  *   .groupBy('role', acc => ({
- *     minSalary: acc.min('salary'),   // Accumulator<number>
- *     firstName: acc.first('name'),   // Accumulator<string>
- *     allNames: acc.push('name'),     // Accumulator<string[]>
- *     count: acc.count(),             // Accumulator<number>
+ *     minSalary: acc.min('salary'),           // Accumulator<number>
+ *     firstName: acc.first('name'),           // Accumulator<string>
+ *     allCities: acc.push('address.city'),    // Accumulator<string[]>
+ *     count: acc.count(),                     // Accumulator<number>
  *   }))
  * ```
  */
@@ -481,64 +519,79 @@ 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(field: DotPath<T>): 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][]>;
+    avg(field: DotPath<T>): Accumulator<number>;
+    /** Minimum value of a field. Returns `Accumulator<DotPathValue<T, F>>`. */
+    min<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>>;
+    /** Maximum value of a field. Returns `Accumulator<DotPathValue<T, F>>`. */
+    max<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>>;
+    /** First value in each group (by document order). Returns `Accumulator<DotPathValue<T, F>>`. */
+    first<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>>;
+    /** Last value in each group (by document order). Returns `Accumulator<DotPathValue<T, F>>`. */
+    last<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>>;
+    /** Collect values into an array (with duplicates). Returns `Accumulator<DotPathValue<T, F>[]>`. */
+    push<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>[]>;
+    /** Collect unique values into an array. Returns `Accumulator<DotPathValue<T, F>[]>`. */
+    addToSet<F extends DotPath<T>>(field: F): Accumulator<DotPathValue<T, F>[]>;
 };
 /**
  * Resolves the document field type from a `$`-prefixed field reference.
  *
+ * Supports both top-level refs (`$price`) and dot-path refs
+ * (`$address.city`), resolving through nested objects and arrays.
+ *
  * @example
  * ```ts
- * type Order = { price: number; name: string }
+ * type Order = { price: number; address: { city: string } }
  * type PriceType = FieldRefType<Order, '$price'>
  * //   ^? number
+ * type CityType = FieldRefType<Order, '$address.city'>
+ * //   ^? string
  * ```
  */
-type FieldRefType<T, F extends string> = F extends `$${infer K}` ? K extends keyof T ? T[K] : never : never;
+type FieldRefType<T, F extends string> = F extends `$${infer K}` ? DotPathValue<T, K> extends never ? never : DotPathValue<T, K> : never;
 /**
  * Output shape of a single-field `groupBy` stage.
  *
  * The `_id` field holds the grouped-by field's value, and the rest of the
- * shape comes from the inferred accumulator types.
+ * shape comes from the inferred accumulator types. Supports dot-path keys
+ * for grouping by nested fields.
  *
  * @example
  * ```ts
  * type Result = GroupByResult<Order, 'status', { count: Accumulator<number> }>
  * //   ^? { _id: string; count: number }
+ *
+ * type Nested = GroupByResult<Order, 'address.city', { count: Accumulator<number> }>
+ * //   ^? { _id: string; count: number }
  * ```
  */
-type GroupByResult<T, K extends keyof T, TAccum extends Record<string, Accumulator>> = Prettify<{
-    _id: T[K];
+type GroupByResult<T, K extends DotPath<T>, TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: DotPathValue<T, K & string>;
 } & InferAccumulators<TAccum>>;
 /**
  * Output shape of a compound (multi-field) `groupBy` stage.
  *
  * The `_id` field is an object with one property per grouped field,
  * and the rest of the shape comes from the inferred accumulator types.
+ * Supports dot-path keys for grouping by nested fields.
  *
  * @example
  * ```ts
  * type Result = GroupByCompoundResult<Order, 'status' | 'region', { count: Accumulator<number> }>
- * //   ^? { _id: Pick<Order, 'status' | 'region'>; count: number }
+ * //   ^? { _id: { status: string; region: string }; count: number }
+ *
+ * type Nested = GroupByCompoundResult<Order, 'name' | 'address.city', { count: Accumulator<number> }>
+ * //   ^? { _id: { name: string; 'address.city': string }; count: number }
  * ```
  */
-type GroupByCompoundResult<T, K extends keyof T, TAccum extends Record<string, Accumulator>> = Prettify<{
-    _id: Prettify<Pick<T, K>>;
+type GroupByCompoundResult<T, K extends DotPath<T>, TAccum extends Record<string, Accumulator>> = Prettify<{
+    _id: Prettify<{
+        [P in K & string]: DotPathValue<T, P>;
+    }>;
 } & InferAccumulators<TAccum>>;
 /**
  * Output shape after unwinding an array field.
@@ -792,139 +845,169 @@ declare const $avg: (field: `$${string}`) => Accumulator<number>;
 /**
  * Returns the minimum value across documents in each group.
  *
- * For full type safety, prefer the callback builder (`acc.min('price')`).
- * The standalone form accepts an explicit result type `R` for manual typing.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$min<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$min<number>('$price')` — manual result type.
+ * - **Tier 3 (untyped):** `$min('$price')` — defaults to `unknown`.
+ *
+ * For best type safety, prefer the callback builder (`acc.min('price')`).
  *
- * @typeParam R - The expected result type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R>`.
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $min<Doc>('$address.city')  // Accumulator<string>
+ *
  * // Tier 2 — explicit result type
- * const pipeline = orders.aggregate()
- * 	.groupBy('category', { cheapest: $min<number>('$price') })
+ * $min<number>('$price')      // Accumulator<number>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.groupBy('category', acc => ({ cheapest: acc.min('price') }))
+ * // Tier 3 — untyped
+ * $min('$price')              // Accumulator<unknown>
  * ```
  */
-declare const $min: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+declare function $min<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>>;
+declare function $min<R = unknown>(field: `$${string}`): Accumulator<R>;
 /**
  * Returns the maximum value across documents in each group.
  *
- * For full type safety, prefer the callback builder (`acc.max('price')`).
- * The standalone form accepts an explicit result type `R` for manual typing.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$max<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$max<number>('$price')` — manual result type.
+ * - **Tier 3 (untyped):** `$max('$price')` — defaults to `unknown`.
+ *
+ * For best type safety, prefer the callback builder (`acc.max('price')`).
  *
- * @typeParam R - The expected result type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R>`.
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $max<Doc>('$tags.label')    // Accumulator<string>
+ *
  * // Tier 2 — explicit result type
- * const pipeline = orders.aggregate()
- * 	.groupBy('category', { priciest: $max<number>('$price') })
+ * $max<number>('$price')      // Accumulator<number>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.groupBy('category', acc => ({ priciest: acc.max('price') }))
+ * // Tier 3 — untyped
+ * $max('$price')              // Accumulator<unknown>
  * ```
  */
-declare const $max: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+declare function $max<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>>;
+declare function $max<R = unknown>(field: `$${string}`): Accumulator<R>;
 /**
  * Returns the first value in each group according to the document order.
  *
- * For full type safety, prefer the callback builder (`acc.first('name')`).
- * The standalone form accepts an explicit result type `R` for manual typing.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$first<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$first<Date>('$createdAt')` — manual result type.
+ * - **Tier 3 (untyped):** `$first('$name')` — defaults to `unknown`.
  *
- * @typeParam R - The expected result type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R>`.
+ * For best type safety, prefer the callback builder (`acc.first('name')`).
+ *
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $first<Doc>('$address.city')  // Accumulator<string>
+ *
  * // Tier 2 — explicit result type
- * const pipeline = orders.aggregate()
- * 	.sort({ createdAt: 1 })
- * 	.groupBy('status', { earliest: $first<Date>('$createdAt') })
+ * $first<Date>('$createdAt')    // Accumulator<Date>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.sort({ createdAt: 1 })
- * 	.groupBy('status', acc => ({ earliest: acc.first('createdAt') }))
+ * // Tier 3 — untyped
+ * $first('$name')               // Accumulator<unknown>
  * ```
  */
-declare const $first: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+declare function $first<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>>;
+declare function $first<R = unknown>(field: `$${string}`): Accumulator<R>;
 /**
  * Returns the last value in each group according to the document order.
  *
- * For full type safety, prefer the callback builder (`acc.last('name')`).
- * The standalone form accepts an explicit result type `R` for manual typing.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$last<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$last<Date>('$createdAt')` — manual result type.
+ * - **Tier 3 (untyped):** `$last('$name')` — defaults to `unknown`.
+ *
+ * For best type safety, prefer the callback builder (`acc.last('name')`).
  *
- * @typeParam R - The expected result type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R>`.
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $last<Doc>('$address.city')  // Accumulator<string>
+ *
  * // Tier 2 — explicit result type
- * const pipeline = orders.aggregate()
- * 	.sort({ createdAt: -1 })
- * 	.groupBy('status', { latest: $last<Date>('$createdAt') })
+ * $last<Date>('$createdAt')    // Accumulator<Date>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.sort({ createdAt: -1 })
- * 	.groupBy('status', acc => ({ latest: acc.last('createdAt') }))
+ * // Tier 3 — untyped
+ * $last('$name')               // Accumulator<unknown>
  * ```
  */
-declare const $last: <R = unknown>(field: `$${string}`) => Accumulator<R>;
+declare function $last<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>>;
+declare function $last<R = unknown>(field: `$${string}`): Accumulator<R>;
 /**
  * Pushes values into an array for each group.
  *
  * May contain duplicates. Use `$addToSet` for unique values.
- * For full type safety, prefer the callback builder (`acc.push('name')`).
  *
- * @typeParam R - The element type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R[]>`.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$push<Doc>('$address.city')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$push<string>('$name')` — manual element type.
+ * - **Tier 3 (untyped):** `$push('$name')` — defaults to `unknown[]`.
+ *
+ * For best type safety, prefer the callback builder (`acc.push('name')`).
+ *
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved array result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $push<Doc>('$address.city')  // Accumulator<string[]>
+ *
  * // Tier 2 — explicit element type
- * const pipeline = orders.aggregate()
- * 	.groupBy('status', { items: $push<string>('$name') })
+ * $push<string>('$name')       // Accumulator<string[]>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.groupBy('status', acc => ({ items: acc.push('name') }))
+ * // Tier 3 — untyped
+ * $push('$name')               // Accumulator<unknown[]>
  * ```
  */
-declare const $push: <R = unknown>(field: `$${string}`) => Accumulator<R[]>;
+declare function $push<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>[]>;
+declare function $push<R = unknown>(field: `$${string}`): Accumulator<R[]>;
 /**
  * Collects unique values into an array for each group (set semantics).
  *
  * Like `$push` but deduplicates.
- * For full type safety, prefer the callback builder (`acc.addToSet('tag')`).
  *
- * @typeParam R - The element type (defaults to `unknown`).
- * @param field - A `$field` reference.
- * @returns An `Accumulator<R[]>`.
+ * Three tiers of type safety:
+ * - **Tier 1 (document type):** `$addToSet<Doc>('$address.zip')` — resolves via `FieldRefType`.
+ * - **Tier 2 (explicit scalar):** `$addToSet<string>('$tag')` — manual element type.
+ * - **Tier 3 (untyped):** `$addToSet('$tag')` — defaults to `unknown[]`.
+ *
+ * For best type safety, prefer the callback builder (`acc.addToSet('tag')`).
+ *
+ * @param field - A `$field` reference (supports dot-paths with document type param).
+ * @returns An `Accumulator` with the resolved array result type.
  *
  * @example
  * ```ts
+ * // Tier 1 — document type with dot-path
+ * $addToSet<Doc>('$address.zip')  // Accumulator<string[]>
+ *
  * // Tier 2 — explicit element type
- * const pipeline = orders.aggregate()
- * 	.groupBy('category', { uniqueTags: $addToSet<string>('$tag') })
+ * $addToSet<string>('$tag')       // Accumulator<string[]>
  *
- * // Tier 1 — callback builder (recommended)
- * orders.aggregate()
- * 	.groupBy('category', acc => ({ uniqueTags: acc.addToSet('tag') }))
+ * // Tier 3 — untyped
+ * $addToSet('$tag')               // Accumulator<unknown[]>
  * ```
  */
-declare const $addToSet: <R = unknown>(field: `$${string}`) => Accumulator<R[]>;
+declare function $addToSet<T extends Record<string, unknown>>(field: FieldRef<T>): Accumulator<FieldRefType<T, FieldRef<T>>[]>;
+declare function $addToSet<R = unknown>(field: `$${string}`): Accumulator<R[]>;
 /**
  * Create a typed accumulator builder for use inside `groupBy` callbacks.
  *
@@ -1018,11 +1101,11 @@ type Prev = [never, 0, 1, 2];
  * ```ts
  * type User = { address: { city: string; geo: { lat: number; lng: number } } }
  *
- * // DotPaths<User> = 'address.city' | 'address.geo' | 'address.geo.lat' | 'address.geo.lng'
+ * // _DotPaths<User> = 'address.city' | 'address.geo' | 'address.geo.lat' | 'address.geo.lng'
  * ```
  */
-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;
+type _DotPaths<T, Depth extends number = 3> = Depth extends 0 ? never : {
+    [K in keyof T & string]: NonNullable<T[K]> extends ReadonlyArray<unknown> | Date | RegExp | ObjectId ? never : NonNullable<T[K]> extends Record<string, unknown> ? `${K}.${keyof NonNullable<T[K]> & string}` | `${K}.${_DotPaths<NonNullable<T[K]>, Prev[Depth]>}` : never;
 }[keyof T & string];
 /**
  * Resolves the value type at a dot-separated path `P` within type `T`.
@@ -1034,11 +1117,11 @@ type DotPaths<T, Depth extends number = 3> = Depth extends 0 ? never : {
  * ```ts
  * type User = { address: { city: string; geo: { lat: number } } }
  *
- * // DotPathType<User, 'address.city'> = string
- * // DotPathType<User, 'address.geo.lat'> = number
+ * // _DotPathType<User, 'address.city'> = string
+ * // _DotPathType<User, 'address.geo.lat'> = number
  * ```
  */
-type DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? Rest extends keyof NonNullable<T[K]> ? NonNullable<T[K]>[Rest] : DotPathType<NonNullable<T[K]>, Rest> : never : P extends keyof T ? T[P] : never;
+type _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;
 /**
  * Strict type-safe MongoDB filter query type.
  *
@@ -1078,7 +1161,7 @@ type DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K
 type TypedFilter<T> = {
     [K in keyof T]?: T[K] | ComparisonOperators<T[K]>;
 } & {
-    [P in DotPaths<T>]?: DotPathType<T, P> | ComparisonOperators<DotPathType<T, P>>;
+    [P in _DotPaths<T>]?: _DotPathType<T, P> | ComparisonOperators<_DotPathType<T, P>>;
 } & {
     /** Joins clauses with a logical AND. Matches documents that satisfy all filters. */
     $and?: TypedFilter<T>[];
@@ -1239,6 +1322,135 @@ type CursorPage<TDoc> = {
     endCursor: string | null;
 };
 
+type IncludeValue = 1 | true;
+type ExcludeValue = 0 | false;
+/**
+ * Inclusion projection — maps document fields to `1 | true`.
+ *
+ * Allows `_id: 0 | false` to suppress the `_id` field from the result.
+ * All other fields only accept inclusion values (`1` or `true`).
+ *
+ * @example
+ * ```ts
+ * type UserInclusion = InclusionProjection<User>
+ * const proj: UserInclusion = { name: 1, email: 1 }
+ * const withoutId: UserInclusion = { name: 1, _id: 0 }
+ * ```
+ */
+type InclusionProjection<T> = {
+    [K in keyof T & string]?: K extends '_id' ? IncludeValue | ExcludeValue : IncludeValue;
+};
+/**
+ * Exclusion projection — maps document fields to `0 | false`.
+ *
+ * Removes the specified fields from the result, keeping all others.
+ *
+ * @example
+ * ```ts
+ * type UserExclusion = ExclusionProjection<User>
+ * const proj: UserExclusion = { email: 0, age: 0 }
+ * ```
+ */
+type ExclusionProjection<T> = {
+    [K in keyof T & string]?: ExcludeValue;
+};
+/**
+ * Union of inclusion or exclusion projection for a document type `T`.
+ *
+ * MongoDB projections must be either all-inclusion or all-exclusion (with the
+ * exception of `_id`, which can always be excluded). This type enforces that
+ * constraint at the type level.
+ *
+ * @example
+ * ```ts
+ * type UserProjection = TypedProjection<User>
+ * const include: UserProjection = { name: 1, email: 1 }
+ * const exclude: UserProjection = { email: 0, age: 0 }
+ * ```
+ */
+type TypedProjection<T> = InclusionProjection<T> | ExclusionProjection<T>;
+/** True if any key in `P` (excluding `_id`) has value `1 | true`. */
+type IsInclusion<P> = true extends {
+    [K in keyof P]: K extends '_id' ? never : P[K] extends IncludeValue ? true : never;
+}[keyof P] ? true : false;
+/** Keys of `P` whose value is `1 | true` (excluding `_id`). */
+type IncludedKeys<P> = {
+    [K in keyof P]: K extends '_id' ? never : P[K] extends IncludeValue ? K : never;
+}[keyof P];
+/** Keys of `P` whose value is `0 | false`. */
+type ExcludedKeys<P> = {
+    [K in keyof P]: P[K] extends ExcludeValue ? K : never;
+}[keyof P];
+/** True if `P` has `_id` set to `0 | false`. */
+type IsIdSuppressed<P> = '_id' extends keyof P ? P['_id'] extends ExcludeValue ? true : false : false;
+/**
+ * Computes the result type after applying a projection `P` to document type `T`.
+ *
+ * For inclusion projections (`{ name: 1 }`), returns only the included fields
+ * plus `_id` (unless `_id: 0` is specified). For exclusion projections
+ * (`{ email: 0 }`), returns all fields except the excluded ones.
+ *
+ * @example
+ * ```ts
+ * type User = { _id: ObjectId; name: string; email: string; age: number }
+ *
+ * // Inclusion: picks name + _id
+ * type A = ProjectionResult<User, { name: 1 }>
+ * //   ^? { _id: ObjectId; name: string }
+ *
+ * // Inclusion with _id suppressed
+ * type B = ProjectionResult<User, { name: 1; _id: 0 }>
+ * //   ^? { name: string }
+ *
+ * // Exclusion: drops email
+ * type C = ProjectionResult<User, { email: 0 }>
+ * //   ^? { _id: ObjectId; name: string; age: number }
+ * ```
+ */
+type ProjectionResult<T, P> = IsInclusion<P> extends true ? IsIdSuppressed<P> extends true ? Prettify<Pick<T, IncludedKeys<P> & keyof T>> : Prettify<Pick<T, (IncludedKeys<P> | '_id') & keyof T>> : IsIdSuppressed<P> extends true ? Prettify<Omit<T, ExcludedKeys<P>>> : Prettify<Omit<T, Exclude<ExcludedKeys<P>, '_id'>>>;
+/**
+ * Returns `true` if the projection is an inclusion projection.
+ *
+ * A projection is considered inclusion when any key other than `_id` has
+ * a value of `1` or `true`. This mirrors the MongoDB rule: you cannot mix
+ * inclusion and exclusion (except for `_id`, which may always be suppressed).
+ *
+ * @example
+ * ```ts
+ * isInclusionProjection({ name: 1 })            // true
+ * isInclusionProjection({ name: 1, _id: 0 })    // true
+ * isInclusionProjection({ email: 0 })            // false
+ * ```
+ */
+declare function isInclusionProjection(projection: Record<string, 0 | 1 | boolean>): boolean;
+/**
+ * Derives a scoped Zod schema by applying a MongoDB-style projection.
+ *
+ * For inclusion projections (`{ name: 1, email: 1 }`), returns a schema with
+ * only the specified fields plus `_id` (unless `_id: 0`). For exclusion
+ * projections (`{ email: 0 }`), returns a schema with the specified fields
+ * removed.
+ *
+ * Keys not present in the original schema are silently ignored.
+ *
+ * @example
+ * ```ts
+ * const userSchema = z.object({
+ *   _id: z.string(),
+ *   name: z.string(),
+ *   email: z.string(),
+ *   age: z.number(),
+ * })
+ *
+ * // Inclusion: picks name + email + _id
+ * const projected = deriveProjectedSchema(userSchema, { name: 1, email: 1 })
+ *
+ * // Exclusion: drops email
+ * const excluded = deriveProjectedSchema(userSchema, { email: 0 })
+ * ```
+ */
+declare function deriveProjectedSchema(schema: z.ZodObject<z.core.$ZodShape>, projection: Record<string, 0 | 1 | boolean>): z.ZodObject<z.core.$ZodShape>;
+
 /**
  * Type-safe sort specification for a document type.
  *
@@ -1263,6 +1475,7 @@ type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
  *
  * @typeParam TDef - The collection definition type, used to infer the document type.
  * @typeParam TIndexNames - Union of declared index names accepted by `.hint()`.
+ * @typeParam TOutput - The output document type, narrowed by `.project()`.
  *
  * @example
  * ```ts
@@ -1272,7 +1485,7 @@ type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
  *   .toArray()
  * ```
  */
-declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends string = string> {
+declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends string = string, TOutput = InferDocument<TDef>> {
     /** @internal */
     private cursor;
     /** @internal */
@@ -1288,6 +1501,8 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
     /** @internal */
     private sortSpec;
     /** @internal */
+    private projectedSchema;
+    /** @internal */
     constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false, nativeCollection: Collection<InferDocument<TDef>>, filter: any);
     /**
      * Set the sort order for the query.
@@ -1348,6 +1563,33 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * ```
      */
     hint(indexName: TIndexNames): this;
+    /**
+     * Apply a projection to narrow the returned fields.
+     *
+     * Inclusion projections (`{ name: 1 }`) return only the specified fields
+     * plus `_id` (unless `_id: 0`). Exclusion projections (`{ email: 0 }`)
+     * return all fields except those excluded.
+     *
+     * The cursor's output type is narrowed at compile time. A derived Zod
+     * schema is built for runtime validation of the projected fields.
+     *
+     * Projects from the original document type, not from a previous projection.
+     * Calling `.project()` twice overrides the previous projection.
+     *
+     * @param spec - Type-safe projection document.
+     * @returns A new cursor with the narrowed output type.
+     *
+     * @example
+     * ```ts
+     * const names = await find(users, {})
+     *   .project({ name: 1 })
+     *   .sort({ name: 1 })
+     *   .toArray()
+     * // names[0].name   ✓
+     * // names[0].email  TS error
+     * ```
+     */
+    project<P extends TypedProjection<InferDocument<TDef>>>(spec: P): TypedFindCursor<TDef, TIndexNames, Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
     /**
      * Execute the query with offset-based pagination, returning a page of documents
      * with total count and navigation metadata.
@@ -1367,7 +1609,7 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * console.log(page.total, page.totalPages, page.hasNext)
      * ```
      */
-    paginate(opts: OffsetPaginateOptions): Promise<OffsetPage<InferDocument<TDef>>>;
+    paginate(opts: OffsetPaginateOptions): Promise<OffsetPage<TOutput>>;
     /**
      * Execute the query with cursor-based pagination, returning a page of documents
      * with opaque cursors for forward/backward navigation.
@@ -1388,7 +1630,7 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      *   .paginate({ cursor: first.endCursor, limit: 10 })
      * ```
      */
-    paginate(opts: CursorPaginateOptions): Promise<CursorPage<InferDocument<TDef>>>;
+    paginate(opts: CursorPaginateOptions): Promise<CursorPage<TOutput>>;
     /** @internal Offset pagination implementation. */
     private offsetPaginate;
     /** @internal Cursor pagination implementation. */
@@ -1407,7 +1649,7 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * const admins = await find(users, { role: 'admin' }).toArray()
      * ```
      */
-    toArray(): Promise<InferDocument<TDef>[]>;
+    toArray(): Promise<TOutput[]>;
     /**
      * Async iterator for streaming documents one at a time.
      *
@@ -1424,17 +1666,33 @@ declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends st
      * }
      * ```
      */
-    [Symbol.asyncIterator](): AsyncGenerator<InferDocument<TDef>>;
+    [Symbol.asyncIterator](): AsyncGenerator<TOutput>;
     /** @internal Validate a single raw document against the schema. */
     private validateDoc;
 }
 
 /**
- * Options for {@link findOne} and {@link findOneOrThrow}.
+ * Options for {@link findOne} and {@link findOneOrThrow} without projection.
  */
 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;
+};
+/**
+ * Options for projected {@link findOne} and {@link findOneOrThrow} queries.
+ *
+ * @typeParam T - The document type.
+ * @typeParam P - The projection document type.
+ *
+ * @example
+ * ```ts
+ * const user = await findOne(users, { name: 'Ada' }, { project: { name: 1 } })
+ * //    ^? { _id: ObjectId; name: string } | null
+ * ```
+ */
+type FindOneProjectionOptions<T, P extends TypedProjection<T>> = {
+    /** Type-safe MongoDB projection — include (`1 | true`) or exclude (`0 | false`) fields. */
+    project: P;
     /** Override the collection-level validation mode, or `false` to skip validation entirely. */
     validate?: ValidationMode | false;
 };
@@ -1447,7 +1705,7 @@ type FindOneOptions = {
  *
  * @param handle - The collection handle to query.
  * @param filter - Type-safe filter to match documents.
- * @param options - Optional projection and validation overrides.
+ * @param options - Optional validation overrides.
  * @returns The matched document, or `null` if no document matches.
  * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
  *
@@ -1458,6 +1716,26 @@ type FindOneOptions = {
  * ```
  */
 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 with a type-safe projection.
+ *
+ * Returns only the fields specified by the projection. The return type is
+ * narrowed to reflect which fields are included or excluded.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Projection and optional validation overrides.
+ * @returns The projected 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' }, { project: { name: 1 } })
+ * if (user) console.log(user.name) // typed as string
+ * // user.role would be a type error — not in the projection
+ * ```
+ */
+declare function findOne<TDef extends AnyCollection, P extends TypedProjection<InferDocument<TDef>>>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindOneProjectionOptions<InferDocument<TDef>, P>): Promise<Prettify<ProjectionResult<InferDocument<TDef>, P>> | null>;
 /**
  * Find a single document matching the filter, or throw if none exists.
  *
@@ -1466,7 +1744,7 @@ declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TD
  *
  * @param handle - The collection handle to query.
  * @param filter - Type-safe filter to match documents.
- * @param options - Optional projection and validation overrides.
+ * @param options - Optional 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.
@@ -1478,6 +1756,28 @@ declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TD
  * ```
  */
 declare function findOneOrThrow<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+/**
+ * Find a single document matching the filter with a type-safe projection, or throw if none exists.
+ *
+ * Returns only the fields specified by the projection. The return type is
+ * narrowed to reflect which fields are included or excluded. Throws
+ * {@link ZodmonNotFoundError} instead of returning `null`.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Projection and optional validation overrides.
+ * @returns The projected 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' }, { project: { name: 1 } })
+ * console.log(user.name) // typed as string
+ * // user.role would be a type error — not in the projection
+ * ```
+ */
+declare function findOneOrThrow<TDef extends AnyCollection, P extends TypedProjection<InferDocument<TDef>>>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindOneProjectionOptions<InferDocument<TDef>, P>): Promise<Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
 /**
  * Options for {@link find}.
  */
@@ -1485,6 +1785,25 @@ type FindOptions = {
     /** Override the collection-level validation mode, or `false` to skip validation entirely. */
     validate?: ValidationMode | false;
 };
+/**
+ * Options for projected {@link find} queries.
+ *
+ * @typeParam T - The document type.
+ * @typeParam P - The projection document type.
+ *
+ * @example
+ * ```ts
+ * const admins = await find(users, { role: 'admin' }, { project: { name: 1 } })
+ *   .toArray()
+ * //    ^? Array<{ _id: ObjectId; name: string }>
+ * ```
+ */
+type FindProjectionOptions<T, P extends TypedProjection<T>> = {
+    /** Type-safe MongoDB projection — include (`1 | true`) or exclude (`0 | false`) fields. */
+    project: P;
+    /** 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.
  *
@@ -1516,6 +1835,28 @@ type FindOptions = {
  * ```
  */
 declare function find<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
+/**
+ * Find all documents matching the filter with a type-safe projection, returning a chainable typed cursor.
+ *
+ * The cursor is lazy — no query is executed until a terminal method
+ * (`toArray`, `for await`) is called. The return type is narrowed to
+ * reflect which fields are included or excluded by the projection.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Projection and optional validation overrides.
+ * @returns A typed cursor whose output type matches the projection.
+ *
+ * @example
+ * ```ts
+ * const names = await find(users, { role: 'admin' }, { project: { name: 1 } })
+ *   .sort({ name: 1 })
+ *   .toArray()
+ * // names[0].name  — string
+ * // names[0].role  — type error, not in projection
+ * ```
+ */
+declare function find<TDef extends AnyCollection, P extends TypedProjection<InferDocument<TDef>>>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options: FindProjectionOptions<InferDocument<TDef>, P>): TypedFindCursor<TDef, IndexNames<TDef>, Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
 
 /**
  * Extracts the element type from an array type.
@@ -1541,7 +1882,7 @@ type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
 type SetFields<T> = {
     [K in keyof T]?: T[K];
 } & {
-    [P in DotPaths<T>]?: DotPathType<T, P>;
+    [P in _DotPaths<T>]?: _DotPathType<T, P>;
 };
 /**
  * Fields valid for the `$inc` operator — only number-typed fields.
@@ -1556,7 +1897,7 @@ type SetFields<T> = {
 type IncFields<T> = {
     [K in keyof T as NonNullable<T[K]> extends number ? K : never]?: number;
 } & {
-    [P in DotPaths<T> as DotPathType<T, P> extends number ? P : never]?: number;
+    [P in _DotPaths<T> as _DotPathType<T, P> extends number ? P : never]?: number;
 };
 /**
  * Modifiers for the `$push` operator.
@@ -1965,7 +2306,7 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * 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.
+     * @param options - Optional validation overrides.
      * @returns The matched document, or `null` if no document matches.
      * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
      *
@@ -1977,6 +2318,25 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * ```
      */
     findOne(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+    /**
+     * Find a single document matching the filter with a type-safe projection.
+     *
+     * Returns only the fields specified by the projection. The return type is
+     * narrowed to reflect which fields are included or excluded.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Projection and optional validation overrides.
+     * @returns The projected 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' }, { project: { name: 1 } })
+     * if (user) console.log(user.name) // typed as string
+     * ```
+     */
+    findOne<P extends TypedProjection<InferDocument<TDef>>>(filter: TypedFilter<InferDocument<TDef>>, options: FindOneProjectionOptions<InferDocument<TDef>, P>): Promise<Prettify<ProjectionResult<InferDocument<TDef>, P>> | null>;
     /**
      * Find a single document matching the filter, or throw if none exists.
      *
@@ -1984,7 +2344,7 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * 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.
+     * @param options - Optional 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.
@@ -1997,6 +2357,27 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * ```
      */
     findOneOrThrow(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+    /**
+     * Find a single document matching the filter with a type-safe projection, or throw if none exists.
+     *
+     * Returns only the fields specified by the projection. The return type is
+     * narrowed to reflect which fields are included or excluded. Throws
+     * {@link ZodmonNotFoundError} instead of returning `null`.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Projection and optional validation overrides.
+     * @returns The projected 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' }, { project: { name: 1 } })
+     * console.log(user.name) // typed as string
+     * ```
+     */
+    findOneOrThrow<P extends TypedProjection<InferDocument<TDef>>>(filter: TypedFilter<InferDocument<TDef>>, options: FindOneProjectionOptions<InferDocument<TDef>, P>): Promise<Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
     /**
      * Find all documents matching the filter, returning a chainable typed cursor.
      *
@@ -2018,6 +2399,24 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * ```
      */
     find(filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
+    /**
+     * Find all documents matching the filter with a type-safe projection, returning a chainable typed cursor.
+     *
+     * The return type is narrowed to reflect which fields are included or excluded.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Projection and optional validation overrides.
+     * @returns A typed cursor whose output type matches the projection.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const names = await users.find({ role: 'admin' }, { project: { name: 1 } })
+     *   .toArray()
+     * // names[0].name  — string
+     * ```
+     */
+    find<P extends TypedProjection<InferDocument<TDef>>>(filter: TypedFilter<InferDocument<TDef>>, options: FindProjectionOptions<InferDocument<TDef>, P>): TypedFindCursor<TDef, IndexNames<TDef>, Prettify<ProjectionResult<InferDocument<TDef>, P>>>;
     /**
      * Update a single document matching the filter.
      *
@@ -2481,8 +2880,8 @@ declare class AggregatePipeline<TDef extends AnyCollection, TOutput> {
      *   .toArray()
      * ```
      */
-    groupBy<K extends keyof TOutput & string, TAccum extends Record<string, Accumulator>>(field: K, accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByResult<TOutput, K, TAccum>>;
-    groupBy<K extends keyof TOutput & string, TAccum extends Record<string, Accumulator>>(field: K[], accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByCompoundResult<TOutput, K, TAccum>>;
+    groupBy<K extends DotPath<TOutput>, TAccum extends Record<string, Accumulator>>(field: K, accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByResult<TOutput, K, TAccum>>;
+    groupBy<K extends DotPath<TOutput>, TAccum extends Record<string, Accumulator>>(field: K[], accumulators: ((acc: AccumulatorBuilder<TOutput>) => TAccum) | TAccum): AggregatePipeline<TDef, GroupByCompoundResult<TOutput, K, TAccum>>;
     /**
      * Add new fields or overwrite existing ones in the output documents.
      *
@@ -3918,4 +4317,4 @@ type UpdateFilterOf<TDef extends AnyCollection> = TypedUpdateFilter<InferDocumen
  */
 type SortOf<TDef extends AnyCollection> = TypedSort<InferDocument<TDef>>;
 
-export { $, $addToSet, $and, $avg, $count, $eq, $exists, $first, $gt, $gte, $in, $last, $lt, $lte, $max, $min, $ne, $nin, $nor, $not, $or, $push, $regex, $sum, type Accumulator, type AccumulatorBuilder, type AddToSetEach, type AddToSetFields, AggregatePipeline, type AnyCollection, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionName, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DotPathType, type DotPaths, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOptions, type GroupByCompoundResult, type GroupByResult, type HandleOf, type IncFields, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferAccumulator, type InferAccumulators, type InferAddedFields, type InferDocument, type InferExpression, type InferInsert, type NarrowFromFilter, type OffsetPage, type OffsetPaginateOptions, type PopFields, type Prettify, type PullFields, type PushFields, type PushModifiers, type RefFields, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, type TypedFilter, TypedFindCursor, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UnwindResult, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonAuthError, ZodmonBulkWriteError, ZodmonDocValidationError, ZodmonDuplicateKeyError, ZodmonError, ZodmonIndexError, ZodmonNetworkError, ZodmonNotFoundError, ZodmonQueryError, ZodmonTimeoutError, ZodmonValidationError, ZodmonWriteConflictError, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, deleteMany, deleteOne, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne, wrapMongoError };
+export { $, $addToSet, $and, $avg, $count, $eq, $exists, $first, $gt, $gte, $in, $last, $lt, $lte, $max, $min, $ne, $nin, $nor, $not, $or, $push, $regex, $sum, type Accumulator, type AccumulatorBuilder, type AddToSetEach, type AddToSetFields, AggregatePipeline, type AnyCollection, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionName, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, type CursorPage, type CursorPaginateOptions, Database, type DotPath, type DotPathValue, type ExclusionProjection, type Expression, type ExpressionBuilder, type ExtractRefCollection, type FieldIndexDefinition, type FieldRef, type FieldRefType, type FilterOf, type FindOneAndDeleteOptions, type FindOneAndUpdateOptions, type FindOneOptions, type FindOneProjectionOptions, type FindOptions, type FindProjectionOptions, type GroupByCompoundResult, type GroupByResult, type HandleOf, type IncFields, type InclusionProjection, IndexBuilder, type IndexMetadata, type IndexNames, type IndexOptions, type IndexSpec, type InferAccumulator, type InferAccumulators, type InferAddedFields, type InferDocument, type InferExpression, type InferInsert, type NarrowFromFilter, type OffsetPage, type OffsetPaginateOptions, type PopFields, type Prettify, type ProjectionResult, type PullFields, type PushFields, type PushModifiers, type RefFields, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, type TypedFilter, TypedFindCursor, type TypedProjection, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UnwindResult, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonAuthError, ZodmonBulkWriteError, ZodmonDocValidationError, ZodmonDuplicateKeyError, ZodmonError, ZodmonIndexError, ZodmonNetworkError, ZodmonNotFoundError, ZodmonQueryError, ZodmonTimeoutError, ZodmonValidationError, ZodmonWriteConflictError, type _DotPathType, type _DotPaths, aggregate, checkUnindexedFields, collection, createAccumulatorBuilder, createClient, createExpressionBuilder, deleteMany, deleteOne, deriveProjectedSchema, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isInclusionProjection, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne, wrapMongoError };