@zodmon/core 0.5.0 → 0.7.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ObjectId, FindCursor, Collection, MongoClientOptions } from 'mongodb';
+import { ObjectId, DeleteResult, FindCursor, Collection, UpdateResult, MongoClientOptions } from 'mongodb';
 import { ZodPipe, ZodCustom, ZodTransform, z, ZodDefault } from 'zod';
 
 /**
@@ -134,32 +134,6 @@ declare module 'zod' {
  * ```
  */
 declare function getIndexMetadata(schema: unknown): IndexMetadata | undefined;
-/**
- * Monkey-patch Zod's `ZodType.prototype` with Zodmon extension methods
- * (`.index()`, `.unique()`, `.text()`, `.expireAfter()`).
- *
- * In Zod v4, methods are copied from `ZodType.prototype` to each instance
- * during construction via the internal `init` loop (`Object.keys(proto)` ->
- * copy to instance). Extension methods use `enumerable: true` so they are
- * picked up by this loop for every schema created after installation.
- *
- * The function is idempotent: calling it more than once is a safe no-op,
- * guarded by a non-enumerable `Symbol.for('zodmon_extensions')` property
- * on the prototype.
- *
- * This function is called at module level when `extensions.ts` is first
- * imported, so consumers never need to call it manually. It is exported
- * primarily for use in tests.
- *
- * @example
- * ```ts
- * import { installExtensions } from '@zodmon/core/schema/extensions'
- * installExtensions() // safe to call multiple times
- *
- * const indexed = z.string().index({ unique: true })
- * ```
- */
-declare function installExtensions(): void;
 
 /**
  * The Zod type produced by {@link objectId}. A pipeline that validates an
@@ -290,6 +264,281 @@ type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape> =
 /** Erased collection type for use in generic contexts. */
 type AnyCollection = CollectionDefinition<z.core.$ZodShape>;
 
+/**
+ * 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}.
+ *
+ * @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 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];
+/**
+ * Generates a union of all valid dot-separated paths for nested object fields in `T`.
+ *
+ * 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
+ * type User = { address: { city: string; geo: { lat: number; lng: number } } }
+ *
+ * // 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;
+}[keyof T & string];
+/**
+ * Resolves the value type at a dot-separated path `P` within type `T`.
+ *
+ * Splits `P` on the first `.` and recursively descends into `T`'s nested types.
+ * Returns `never` if the path is invalid.
+ *
+ * @example
+ * ```ts
+ * type User = { address: { city: string; geo: { lat: number } } }
+ *
+ * // DotPathType<User, 'address.city'> = string
+ * // DotPathType<User, 'address.geo.lat'> = number
+ * ```
+ */
+type DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? Rest extends keyof NonNullable<T[K]> ? NonNullable<T[K]>[Rest] : DotPathType<NonNullable<T[K]>, Rest> : never : P extends keyof T ? T[P] : never;
+/**
+ * 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`.
+ *
+ * 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' }`
+ *
+ * Logical operators `$and`, `$or`, and `$nor` accept arrays of `TypedFilter<T>`
+ * for composing complex queries.
+ *
+ * @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) : {}
+ * ```
+ */
+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 findOneAndDelete}.
+ */
+type FindOneAndDeleteOptions = {
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
+/**
+ * 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 handle - The collection handle to delete from.
+ * @param filter - Type-safe filter to match documents.
+ * @returns The MongoDB `DeleteResult` with the deleted count.
+ *
+ * @example
+ * ```ts
+ * const result = await deleteOne(users, { name: 'Ada' })
+ * console.log(result.deletedCount) // 1
+ * ```
+ */
+declare function deleteOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, 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 handle - The collection handle to delete from.
+ * @param filter - Type-safe filter to match documents.
+ * @returns The MongoDB `DeleteResult` with the deleted count.
+ *
+ * @example
+ * ```ts
+ * const result = await deleteMany(users, { role: 'guest' })
+ * console.log(result.deletedCount) // number of guests removed
+ * ```
+ */
+declare function deleteMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, 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 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
+ * const user = await findOneAndDelete(users, { name: 'Ada' })
+ * if (user) console.log(user.name) // 'Ada' (the deleted document)
+ * ```
+ *
+ * @example
+ * ```ts
+ * const user = await findOneAndDelete(
+ *   users,
+ *   { role: 'guest' },
+ *   { validate: false },
+ * )
+ * ```
+ */
+declare function findOneAndDelete<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneAndDeleteOptions): Promise<InferDocument<TDef> | null>;
+
+/**
+ * Options for offset-based pagination.
+ *
+ * @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.
+ *
+ * @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 })
+ * ```
+ */
+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.
  *
@@ -332,7 +581,13 @@ declare class TypedFindCursor<TDef extends AnyCollection> {
     /** @internal */
     private mode;
     /** @internal */
-    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false);
+    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.
      *
@@ -372,6 +627,51 @@ declare class TypedFindCursor<TDef extends AnyCollection> {
      * ```
      */
     limit(n: number): 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.
      *
@@ -409,217 +709,400 @@ declare class TypedFindCursor<TDef extends AnyCollection> {
 }
 
 /**
- * Comparison operators for a field value of type `V`.
+ * 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.
  *
- * Maps each MongoDB comparison operator to its expected value type.
- * `$regex` is only available when `V` extends `string`.
+ * 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'`).
  *
- * Used as the operator object that can be assigned to a field in {@link TypedFilter}.
+ * @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
- * // As a raw object (without builder functions)
- * const filter: TypedFilter<User> = { age: { $gt: 25, $lte: 65 } }
+ * 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.
  *
- * // $regex only available on string fields
- * const filter: TypedFilter<User> = { name: { $regex: /^A/i } }
+ * 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
  * ```
  */
-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];
+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>;
+
+/**
+ * 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[];
+};
 /**
- * Generates a union of all valid dot-separated paths for nested object fields in `T`.
+ * Fields valid for the `$addToSet` operator — only array-typed fields.
  *
- * 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.
+ * Accepts a single element value or `{ $each: [...] }` for multiple elements.
  *
  * @example
  * ```ts
- * type User = { address: { city: string; geo: { lat: number; lng: number } } }
- *
- * // DotPaths<User> = 'address.city' | 'address.geo' | 'address.geo.lat' | 'address.geo.lng'
+ * const add: AddToSetFields<User> = { tags: 'dev' }
+ * const addMany: AddToSetFields<User> = { tags: { $each: ['a', 'b'] } }
  * ```
  */
-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 AddToSetFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | AddToSetEach<ArrayElement<NonNullable<T[K]>>>;
+};
 /**
- * Resolves the value type at a dot-separated path `P` within type `T`.
+ * Fields valid for the `$pop` operator — only array-typed fields.
  *
- * Splits `P` on the first `.` and recursively descends into `T`'s nested types.
- * Returns `never` if the path is invalid.
+ * Value `1` removes the last element, `-1` removes the first.
  *
  * @example
  * ```ts
- * type User = { address: { city: string; geo: { lat: number } } }
- *
- * // DotPathType<User, 'address.city'> = string
- * // DotPathType<User, 'address.geo.lat'> = number
+ * const pop: PopFields<User> = { tags: -1 } // remove first
  * ```
  */
-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 PopFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: 1 | -1;
+};
 /**
- * Strict type-safe MongoDB filter query type.
+ * Fields valid for the `$unset` operator — any existing field.
  *
- * 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`.
+ * Value is `''`, `true`, or `1` (all mean "remove this field").
  *
- * 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' }`
+ * @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.
  *
- * Logical operators `$and`, `$or`, and `$nor` accept arrays of `TypedFilter<T>`
- * for composing complex queries.
+ * Sets the field to the current date. Value is `true` or `{ $type: 'date' }`.
  *
  * @example
  * ```ts
- * // Simple equality
- * const filter: TypedFilter<User> = { name: 'Alice' }
+ * 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.
  *
- * // Builder functions mixed with object literals
- * const filter: TypedFilter<User> = { age: $gte(18), role: $in(['admin', 'mod']) }
+ * Renames an existing field to a new name. Key is the current field name,
+ * value is the new name as a string.
  *
- * // Logical composition
- * const filter = $and<User>(
- *   $or<User>({ role: 'admin' }, { role: 'moderator' }),
- *   { age: $gte(18) },
- *   { email: $exists() },
- * )
+ * @example
+ * ```ts
+ * const rename: RenameFields<User> = { name: 'fullName' }
+ * ```
+ */
+type RenameFields<T> = {
+    [K in keyof T & string]?: string;
+};
+/**
+ * Strict type-safe MongoDB update filter.
  *
- * // 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) : {}
+ * 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 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 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 findOne} and {@link findOneOrThrow}.
+ * Options for {@link updateOne} and {@link updateMany}.
  */
-type FindOneOptions = {
-    /** MongoDB projection — include (`1`) or exclude (`0`) fields. Typed projections deferred to v1.0. */
-    project?: Record<string, 0 | 1>;
+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;
 };
 /**
- * Find a single document matching the filter.
+ * Update 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'`).
+ * 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 query.
+ * @param handle - The collection handle to update in.
  * @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.
+ * @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 user = await findOne(users, { name: 'Ada' })
- * if (user) console.log(user.role) // typed as 'admin' | 'user'
+ * const result = await updateOne(users, { name: 'Ada' }, { $set: { role: 'admin' } })
+ * console.log(result.modifiedCount) // 1
  * ```
  */
-declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+declare function updateOne<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, or throw if none exists.
+ * Update all documents matching the filter.
  *
- * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
- * instead of returning `null` when no document matches 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 query.
+ * @param handle - The collection handle to update in.
  * @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 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 user = await findOneOrThrow(users, { name: 'Ada' })
- * console.log(user.role) // typed as 'admin' | 'user', guaranteed non-null
+ * const result = await updateMany(users, { role: 'guest' }, { $set: { role: 'user' } })
+ * console.log(result.modifiedCount) // number of guests promoted
  * ```
  */
-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 function updateMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
 /**
- * Find all documents matching the filter, returning a chainable typed cursor.
+ * Find a single document matching the filter, apply an update, and return the document.
  *
- * 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.
+ * 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 query.
+ * @param handle - The collection handle to update in.
  * @param filter - Type-safe filter to match documents.
- * @param options - Optional validation overrides.
- * @returns A typed cursor for chaining query modifiers.
+ * @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 admins = await find(users, { role: 'admin' })
- *   .sort({ name: 1 })
- *   .limit(10)
- *   .toArray()
+ * const user = await findOneAndUpdate(
+ *   users,
+ *   { name: 'Ada' },
+ *   { $set: { role: 'admin' } },
+ * )
+ * if (user) console.log(user.role) // 'admin' (returned after update)
  * ```
  *
  * @example
  * ```ts
- * for await (const user of find(users, {})) {
- *   console.log(user.name)
- * }
+ * const before = await findOneAndUpdate(
+ *   users,
+ *   { name: 'Ada' },
+ *   { $inc: { loginCount: 1 } },
+ *   { returnDocument: 'before' },
+ * )
  * ```
  */
-declare function find<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef>;
+declare function findOneAndUpdate<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: FindOneAndUpdateOptions): Promise<InferDocument<TDef> | null>;
 
 /**
  * Typed wrapper around a MongoDB driver `Collection`.
@@ -738,6 +1221,127 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * ```
      */
     find(filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<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>;
 }
 
 /**
@@ -855,6 +1459,8 @@ declare function extractFieldIndexes(shape: z.core.$ZodShape): FieldIndexDefinit
  */
 declare function collection<TShape extends z.core.$ZodShape>(name: string, shape: TShape, options?: CollectionOptions<Extract<keyof TShape, string>>): CollectionDefinition<TShape>;
 
+type IndexDirection = 1 | -1;
+type CompoundIndexOptions = NonNullable<CompoundIndexDefinition['options']>;
 /**
  * A builder for compound index definitions.
  *
@@ -874,9 +1480,6 @@ declare function collection<TShape extends z.core.$ZodShape>(name: string, shape
  * index({ email: 1, role: -1 }).unique().name('email_role_idx')
  * ```
  */
-
-type IndexDirection = 1 | -1;
-type CompoundIndexOptions = NonNullable<CompoundIndexDefinition['options']>;
 declare class IndexBuilder<TKeys extends string> {
     readonly fields: Partial<Record<TKeys, IndexDirection>>;
     readonly options: CompoundIndexOptions;
@@ -1049,6 +1652,62 @@ declare function oid(value: ObjectId): ObjectId;
  */
 declare function isOid(value: unknown): value is ObjectId;
 
+/**
+ * Convenience namespace that groups all query operators under a single import.
+ *
+ * Property names strip the `$` prefix since the namespace itself is `$`.
+ * Individual operator exports (`$or`, `$gt`, etc.) remain available for
+ * tree-shaking — this namespace is the ergonomic alternative.
+ *
+ * @example
+ * ```ts
+ * import { $ } from '@zodmon/core'
+ *
+ * users.find($.or({ role: 'admin' }, { age: $.gte(25) }))
+ * users.find({ name: $.regex(/^A/i), age: $.gt(18) })
+ * users.find($.and({ published: true }, { views: $.gte(100) }))
+ * ```
+ */
+declare const $: {
+    readonly eq: <V>(value: V) => {
+        $eq: V;
+    };
+    readonly ne: <V>(value: V) => {
+        $ne: V;
+    };
+    readonly gt: <V>(value: V) => {
+        $gt: V;
+    };
+    readonly gte: <V>(value: V) => {
+        $gte: V;
+    };
+    readonly lt: <V>(value: V) => {
+        $lt: V;
+    };
+    readonly lte: <V>(value: V) => {
+        $lte: V;
+    };
+    readonly in: <V>(values: V[]) => {
+        $in: V[];
+    };
+    readonly nin: <V>(values: V[]) => {
+        $nin: V[];
+    };
+    readonly exists: (flag?: boolean) => {
+        $exists: boolean;
+    };
+    readonly regex: (pattern: RegExp | string) => {
+        $regex: RegExp | string;
+    };
+    readonly not: <O extends Record<string, unknown>>(op: O) => {
+        $not: O;
+    };
+    readonly or: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
+    readonly and: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
+    readonly nor: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
+    readonly raw: <T = any>(filter: Record<string, unknown>) => TypedFilter<T>;
+};
+
 /**
  * Matches values equal to the specified value.
  *
@@ -1189,16 +1848,14 @@ declare const $not: <O extends Record<string, unknown>>(op: O) => {
  *
  * @example
  * ```ts
+ * // T inferred from collection's find() context
  * users.find($or({ role: 'admin' }, { age: $gte(18) }))
  *
- * // Dynamic composition
- * const conditions: TypedFilter<User>[] = []
- * if (name) conditions.push({ name })
- * if (role) conditions.push({ role })
- * users.find($or(...conditions))
+ * // Explicit generic for standalone usage
+ * const filter = $or<User>({ role: 'admin' }, { age: $gte(18) })
  * ```
  */
-declare const $or: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+declare const $or: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
 /**
  * Joins filter clauses with a logical AND. Matches documents that satisfy
  * all of the provided filters. Useful for dynamic filter building where
@@ -1206,6 +1863,7 @@ declare const $or: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
  *
  * @example
  * ```ts
+ * // T inferred from collection's find() context
  * users.find($and(
  *   $or({ role: 'admin' }, { role: 'moderator' }),
  *   { age: $gte(18) },
@@ -1213,7 +1871,7 @@ declare const $or: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
  * ))
  * ```
  */
-declare const $and: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+declare const $and: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
 /**
  * Joins filter clauses with a logical NOR. Matches documents that fail
  * all of the provided filters.
@@ -1224,7 +1882,7 @@ declare const $and: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
  * users.find($nor({ role: 'banned' }, { role: 'suspended' }))
  * ```
  */
-declare const $nor: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+declare const $nor: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
 /**
  * Escape hatch for unsupported or raw MongoDB filter operators.
  * Wraps an untyped filter object so it can be passed where `TypedFilter<T>` is expected.
@@ -1314,11 +1972,70 @@ declare module 'zod' {
  * ```
  */
 declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
+
+/**
+ * Shorthand for `CollectionHandle<TDef>`.
+ *
+ * Reduces boilerplate in function signatures that accept a collection handle.
+ *
+ * @example
+ * ```ts
+ * import { type HandleOf } from '@zodmon/core'
+ *
+ * const Users = collection('users', { name: z.string() })
+ *
+ * async function seed(users: HandleOf<typeof Users>) {
+ *   await users.insertOne({ name: 'Ada' })
+ * }
+ * ```
+ */
+type HandleOf<TDef extends AnyCollection> = CollectionHandle<TDef>;
+/**
+ * Shorthand for `TypedFilter<InferDocument<TDef>>`.
+ *
+ * Derives the filter type directly from a collection definition,
+ * removing the need to compose `TypedFilter` and `InferDocument` manually.
+ *
+ * @example
+ * ```ts
+ * import { type FilterOf } from '@zodmon/core'
+ *
+ * const Users = collection('users', { name: z.string(), age: z.number() })
+ *
+ * const conditions: FilterOf<typeof Users>[] = []
+ * conditions.push({ age: { $gte: 18 } })
+ * ```
+ */
+type FilterOf<TDef extends AnyCollection> = TypedFilter<InferDocument<TDef>>;
+/**
+ * Shorthand for `TypedUpdateFilter<InferDocument<TDef>>`.
+ *
+ * Derives the update filter type directly from a collection definition.
+ *
+ * @example
+ * ```ts
+ * import { type UpdateFilterOf } from '@zodmon/core'
+ *
+ * const Users = collection('users', { name: z.string(), role: z.string() })
+ *
+ * const update: UpdateFilterOf<typeof Users> = { $set: { role: 'admin' } }
+ * ```
+ */
+type UpdateFilterOf<TDef extends AnyCollection> = TypedUpdateFilter<InferDocument<TDef>>;
 /**
- * Install the `.ref()` extension method on `ZodType.prototype`.
+ * Shorthand for `TypedSort<InferDocument<TDef>>`.
+ *
+ * Derives the sort specification type directly from a collection definition.
+ *
+ * @example
+ * ```ts
+ * import { type SortOf } from '@zodmon/core'
  *
- * Idempotent — safe to call multiple times.
+ * const Users = collection('users', { name: z.string(), age: z.number() })
+ *
+ * const sort: SortOf<typeof Users> = { age: -1, name: 1 }
+ * ```
  */
-declare function installRefExtension(): void;
+type SortOf<TDef extends AnyCollection> = TypedSort<InferDocument<TDef>>;
 
-export { $and, $eq, $exists, $gt, $gte, $in, $lt, $lte, $ne, $nin, $nor, $not, $or, $regex, type AnyCollection, type CollectionDefinition, CollectionHandle, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, Database, type DotPathType, type DotPaths, type FieldIndexDefinition, type FindOneOptions, type FindOptions, IndexBuilder, type IndexMetadata, type IndexOptions, type InferDocument, type InferInsert, type RefMarker, type RefMetadata, type ResolvedShape, type TypedFilter, TypedFindCursor, type TypedSort, type ValidationMode, type ZodObjectId, ZodmonNotFoundError, ZodmonValidationError, collection, createClient, extractDbName, extractFieldIndexes, find, findOne, findOneOrThrow, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, installExtensions, installRefExtension, isOid, objectId, oid, raw };
+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 IndexOptions, 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 TypedFilter, TypedFindCursor, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonNotFoundError, ZodmonValidationError, collection, createClient, deleteMany, deleteOne, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isOid, objectId, oid, raw, updateMany, updateOne };