@zodmon/core 0.6.0 → 0.8.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
@@ -278,135 +252,132 @@ type InferInsert<TDef extends {
 /**
  * The immutable definition object returned by collection().
  * Holds everything needed to later create a live collection handle.
+ *
+ * @typeParam TShape - The Zod shape defining document fields.
+ * @typeParam TIndexes - The compound indexes array type, preserving literal name types.
  */
-type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape> = {
+type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape, TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]> = {
     readonly name: string;
     readonly schema: z.ZodObject<ResolvedShape<TShape>>;
     readonly shape: TShape;
     readonly fieldIndexes: FieldIndexDefinition[];
-    readonly compoundIndexes: CompoundIndexDefinition<Extract<keyof TShape, string>>[];
+    readonly compoundIndexes: TIndexes;
     readonly options: Required<Pick<CollectionOptions, 'validation'>> & Omit<CollectionOptions, 'indexes' | 'validation'>;
 };
 /** Erased collection type for use in generic contexts. */
 type AnyCollection = CollectionDefinition<z.core.$ZodShape>;
-
 /**
- * Type-safe sort specification for a document type.
+ * Extract declared index names from a collection definition.
  *
- * Constrains sort keys to top-level fields of `T` with direction `1` (ascending)
- * or `-1` (descending). Dot-path sorts deferred to v1.0.
+ * Walks the `compoundIndexes` tuple and extracts the literal `name` string
+ * from each index that declared one via `.name()`. Falls back to `string`
+ * when no compound indexes have names, allowing any string as a hint.
  *
  * @example
  * ```ts
- * const sort: TypedSort<User> = { name: 1, createdAt: -1 }
+ * const Users = collection('users', { email: z.string() }, {
+ *   indexes: [
+ *     index({ email: 1 }).name('email_idx'),
+ *   ],
+ * })
+ * type Names = IndexNames<typeof Users> // 'email_idx'
  * ```
  */
-type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
+type IndexNames<TDef extends {
+    readonly compoundIndexes: readonly {
+        options?: {
+            name?: string;
+        };
+    }[];
+}> = ExtractNames<TDef['compoundIndexes']> extends never ? string : ExtractNames<TDef['compoundIndexes']>;
+/** @internal Helper that extracts the `name` literal from each index in a tuple. */
+type ExtractNames<T extends readonly {
+    options?: {
+        name?: string;
+    };
+}[]> = {
+    [K in keyof T]: T[K] extends {
+        readonly options: {
+            readonly name: infer N;
+        };
+    } ? N extends string ? N : never : never;
+}[number];
+
 /**
- * Type-safe cursor wrapping MongoDB's `FindCursor`.
- *
- * Provides chainable query modifiers (`sort`, `skip`, `limit`) that return
- * `this` for fluent chaining, and terminal methods (`toArray`,
- * `[Symbol.asyncIterator]`) that validate each document against the
- * collection's Zod schema before returning.
- *
- * Created by {@link find} — do not construct directly.
- *
- * @typeParam TDef - The collection definition type, used to infer the document type.
+ * Options controlling how {@link syncIndexes} behaves.
  *
  * @example
  * ```ts
- * const docs = await find(users, { role: 'admin' })
- *   .sort({ name: 1 })
- *   .limit(10)
- *   .toArray()
+ * await users.syncIndexes({ dryRun: true })
+ * await users.syncIndexes({ dropOrphaned: true })
  * ```
  */
-declare class TypedFindCursor<TDef extends AnyCollection> {
-    /** @internal */
-    private cursor;
-    /** @internal */
-    private schema;
-    /** @internal */
-    private collectionName;
-    /** @internal */
-    private mode;
-    /** @internal */
-    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false);
-    /**
-     * Set the sort order for the query.
-     *
-     * Only top-level document fields are accepted as sort keys.
-     * Values must be `1` (ascending) or `-1` (descending).
-     *
-     * @param spec - Sort specification mapping field names to sort direction.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * find(users, {}).sort({ name: 1, age: -1 }).toArray()
-     * ```
-     */
-    sort(spec: TypedSort<InferDocument<TDef>>): this;
-    /**
-     * Skip the first `n` documents in the result set.
-     *
-     * @param n - Number of documents to skip.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * find(users, {}).skip(10).limit(10).toArray() // page 2
-     * ```
-     */
-    skip(n: number): this;
-    /**
-     * Limit the number of documents returned.
-     *
-     * @param n - Maximum number of documents to return.
-     * @returns `this` for chaining.
-     *
-     * @example
-     * ```ts
-     * find(users, {}).limit(10).toArray() // at most 10 docs
-     * ```
-     */
-    limit(n: number): this;
+type SyncIndexesOptions = {
     /**
-     * Execute the query and return all matching documents as an array.
-     *
-     * Each document is validated against the collection's Zod schema
-     * according to the resolved validation mode.
-     *
-     * @returns Array of validated documents.
-     * @throws {ZodmonValidationError} When a document fails schema validation in strict/strip mode.
-     *
-     * @example
-     * ```ts
-     * const admins = await find(users, { role: 'admin' }).toArray()
-     * ```
+     * When `true`, compute the diff without actually creating, dropping, or
+     * modifying any indexes. The returned {@link SyncIndexesResult} shows what
+     * *would* happen.
      */
-    toArray(): Promise<InferDocument<TDef>[]>;
+    dryRun?: boolean;
     /**
-     * Async iterator for streaming documents one at a time.
-     *
-     * Each yielded document is validated against the collection's Zod schema.
-     * Memory-efficient for large result sets.
-     *
-     * @yields Validated documents one at a time.
-     * @throws {ZodmonValidationError} When a document fails schema validation.
-     *
-     * @example
-     * ```ts
-     * for await (const user of find(users, {})) {
-     *   console.log(user.name)
-     * }
-     * ```
+     * When `true`, drop indexes that exist in MongoDB but are not declared in
+     * the schema. Also drops and recreates stale indexes (same key, different
+     * options). When `false` (the default), orphaned and stale indexes are
+     * reported but left untouched.
      */
-    [Symbol.asyncIterator](): AsyncGenerator<InferDocument<TDef>>;
-    /** @internal Validate a single raw document against the schema. */
-    private validateDoc;
-}
+    dropOrphaned?: boolean;
+};
+/**
+ * Describes an index whose key matches a desired index but whose options differ.
+ *
+ * Returned in {@link SyncIndexesResult.stale} so the caller can decide whether
+ * to manually reconcile or re-run with `dropOrphaned: true`.
+ *
+ * @example
+ * ```ts
+ * const result = await users.syncIndexes()
+ * for (const s of result.stale) {
+ *   console.log(`${s.name}: key=${JSON.stringify(s.key)}`)
+ *   console.log(`  existing=${JSON.stringify(s.existing)}`)
+ *   console.log(`  desired=${JSON.stringify(s.desired)}`)
+ * }
+ * ```
+ */
+type StaleIndex = {
+    /** The MongoDB index name (e.g. `'email_1'`). */
+    name: string;
+    /** The index key spec (e.g. `{ email: 1 }`). */
+    key: Record<string, 1 | -1 | 'text'>;
+    /** The relevant options currently set on the existing index. */
+    existing: Record<string, unknown>;
+    /** The options the schema declares for this index. */
+    desired: Record<string, unknown>;
+};
+/**
+ * The result of a {@link syncIndexes} call.
+ *
+ * Every array contains index names. `stale` contains full details so the
+ * caller can inspect the mismatch.
+ *
+ * @example
+ * ```ts
+ * const result = await users.syncIndexes()
+ * console.log('created:', result.created)
+ * console.log('dropped:', result.dropped)
+ * console.log('skipped:', result.skipped)
+ * console.log('stale:', result.stale.map(s => s.name))
+ * ```
+ */
+type SyncIndexesResult = {
+    /** Names of indexes that were created (or would be created in dryRun mode). */
+    created: string[];
+    /** Names of indexes that were dropped (or would be dropped in dryRun mode). */
+    dropped: string[];
+    /** Names of indexes that already existed with matching options — no action taken. */
+    skipped: string[];
+    /** Indexes whose key matches a desired spec but whose options differ. */
+    stale: StaleIndex[];
+};
 
 /**
  * Comparison operators for a field value of type `V`.
@@ -533,136 +504,785 @@ type TypedFilter<T> = {
 };
 
 /**
- * Options for {@link findOne} and {@link findOneOrThrow}.
+ * Options for {@link findOneAndDelete}.
  */
-type FindOneOptions = {
-    /** MongoDB projection — include (`1`) or exclude (`0`) fields. Typed projections deferred to v1.0. */
-    project?: Record<string, 0 | 1>;
+type FindOneAndDeleteOptions = {
     /** Override the collection-level validation mode, or `false` to skip validation entirely. */
     validate?: ValidationMode | false;
 };
 /**
- * Find a single document matching the filter.
+ * Delete 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'`).
+ * 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 query.
+ * @param handle - The collection handle to delete from.
  * @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.
+ * @returns The MongoDB `DeleteResult` with the deleted count.
  *
  * @example
  * ```ts
- * const user = await findOne(users, { name: 'Ada' })
- * if (user) console.log(user.role) // typed as 'admin' | 'user'
+ * const result = await deleteOne(users, { name: 'Ada' })
+ * console.log(result.deletedCount) // 1
  * ```
  */
-declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+declare function deleteOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
 /**
- * Find a single document matching the filter, or throw if none exists.
+ * Delete all documents matching the filter.
  *
- * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
- * instead of returning `null` when no document matches 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 query.
+ * @param handle - The collection handle to delete from.
  * @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.
+ * @returns The MongoDB `DeleteResult` with the deleted count.
  *
  * @example
  * ```ts
- * const user = await findOneOrThrow(users, { name: 'Ada' })
- * console.log(user.role) // typed as 'admin' | 'user', guaranteed non-null
+ * const result = await deleteMany(users, { role: 'guest' })
+ * console.log(result.deletedCount) // number of guests removed
  * ```
  */
-declare function findOneOrThrow<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+declare function deleteMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
 /**
- * Options for {@link find}.
+ * 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 },
+ * )
+ * ```
  */
-type FindOptions = {
-    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
-    validate?: ValidationMode | false;
-};
+declare function findOneAndDelete<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneAndDeleteOptions): Promise<InferDocument<TDef> | null>;
+
 /**
- * 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.
+ * Options for offset-based pagination.
  *
- * Each document is validated against the collection's Zod schema when
- * a terminal method consumes it.
+ * @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.
  *
- * @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 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 admins = await find(users, { role: 'admin' })
- *   .sort({ name: 1 })
- *   .limit(10)
- *   .toArray()
+ * 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
- * for await (const user of find(users, {})) {
- *   console.log(user.name)
+ * const page = await users.find({}).paginate({ limit: 10 })
+ * if (page.hasNext) {
+ *   const next = await users.find({}).paginate({ cursor: page.endCursor, limit: 10 })
  * }
  * ```
  */
-declare function find<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef>;
+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;
+};
 
 /**
- * Typed wrapper around a MongoDB driver `Collection`.
+ * Type-safe sort specification for a document type.
  *
- * Created by {@link Database.use}. Holds the original `CollectionDefinition`
- * (for runtime schema validation and index metadata) alongside the native
- * driver collection parameterized with the inferred document type.
+ * Constrains sort keys to top-level fields of `T` with direction `1` (ascending)
+ * or `-1` (descending). Dot-path sorts deferred to v1.0.
  *
- * @typeParam TDef - The collection definition type. Used to derive both
- *   the document type (`InferDocument`) and the insert type (`InferInsert`).
+ * @example
+ * ```ts
+ * const sort: TypedSort<User> = { name: 1, createdAt: -1 }
+ * ```
  */
-declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
-    /** The collection definition containing schema, name, and index metadata. */
-    readonly definition: TDef;
-    /** The underlying MongoDB driver collection, typed to the inferred document type. */
-    readonly native: Collection<InferDocument<TDef>>;
-    constructor(definition: TDef, native: Collection<InferDocument<TDef>>);
-    /**
-     * Insert a single document into the collection.
-     *
-     * Validates the input against the collection's Zod schema before writing.
-     * Schema defaults (including auto-generated `_id`) are applied during
-     * validation. Returns the full document with all defaults filled in.
-     *
-     * @param doc - The document to insert. Fields with `.default()` are optional.
-     * @returns The inserted document with `_id` and all defaults applied.
-     * @throws {ZodmonValidationError} When the document fails schema validation.
-     *
-     * @example
-     * ```ts
-     * const users = db.use(Users)
-     * const user = await users.insertOne({ name: 'Ada' })
-     * console.log(user._id) // ObjectId (auto-generated)
-     * console.log(user.role) // 'user' (schema default)
-     * ```
-     */
-    insertOne(doc: InferInsert<TDef>): Promise<InferDocument<TDef>>;
-    /**
-     * Insert multiple documents into the collection.
-     *
-     * Validates every document against the collection's Zod schema before
-     * writing any to MongoDB. If any document fails validation, none are
-     * inserted (fail-fast before the driver call).
-     *
+type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
+/**
+ * Type-safe cursor wrapping MongoDB's `FindCursor`.
+ *
+ * Provides chainable query modifiers (`sort`, `skip`, `limit`, `hint`) that return
+ * `this` for fluent chaining, and terminal methods (`toArray`,
+ * `[Symbol.asyncIterator]`) that validate each document against the
+ * collection's Zod schema before returning.
+ *
+ * Created by {@link find} — do not construct directly.
+ *
+ * @typeParam TDef - The collection definition type, used to infer the document type.
+ * @typeParam TIndexNames - Union of declared index names accepted by `.hint()`.
+ *
+ * @example
+ * ```ts
+ * const docs = await find(users, { role: 'admin' })
+ *   .sort({ name: 1 })
+ *   .limit(10)
+ *   .toArray()
+ * ```
+ */
+declare class TypedFindCursor<TDef extends AnyCollection, TIndexNames extends string = string> {
+    /** @internal */
+    private cursor;
+    /** @internal */
+    private schema;
+    /** @internal */
+    private collectionName;
+    /** @internal */
+    private mode;
+    /** @internal */
+    private readonly nativeCollection;
+    /** @internal */
+    private readonly filter;
+    /** @internal */
+    private sortSpec;
+    /** @internal */
+    constructor(cursor: FindCursor<InferDocument<TDef>>, definition: TDef, mode: ValidationMode | false, nativeCollection: Collection<InferDocument<TDef>>, filter: any);
+    /**
+     * Set the sort order for the query.
+     *
+     * Only top-level document fields are accepted as sort keys.
+     * Values must be `1` (ascending) or `-1` (descending).
+     *
+     * @param spec - Sort specification mapping field names to sort direction.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * find(users, {}).sort({ name: 1, age: -1 }).toArray()
+     * ```
+     */
+    sort(spec: TypedSort<InferDocument<TDef>>): this;
+    /**
+     * Skip the first `n` documents in the result set.
+     *
+     * @param n - Number of documents to skip.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * find(users, {}).skip(10).limit(10).toArray() // page 2
+     * ```
+     */
+    skip(n: number): this;
+    /**
+     * Limit the number of documents returned.
+     *
+     * @param n - Maximum number of documents to return.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * find(users, {}).limit(10).toArray() // at most 10 docs
+     * ```
+     */
+    limit(n: number): this;
+    /**
+     * Force the query optimizer to use the specified index.
+     *
+     * Only accepts index names that were declared via `.name()` in the
+     * collection definition. If no named indexes exist, any string is accepted.
+     *
+     * @param indexName - The name of a declared compound index.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * const Users = collection('users', { email: z.string(), role: z.string() }, {
+     *   indexes: [index({ email: 1, role: -1 }).name('email_role_idx')],
+     * })
+     * const admins = await users.find({ role: 'admin' })
+     *   .hint('email_role_idx')
+     *   .toArray()
+     * ```
+     */
+    hint(indexName: TIndexNames): this;
+    /**
+     * Execute the query with offset-based pagination, returning a page of documents
+     * with total count and navigation metadata.
+     *
+     * Runs `countDocuments` and `find` in parallel for performance. Ignores any
+     * `.skip()` or `.limit()` already set on the cursor — issues a fresh query.
+     *
+     * @param opts - Offset pagination options: `page` (1-indexed) and `perPage`.
+     * @returns A page with `docs`, `total`, `totalPages`, `hasNext`, `hasPrev`.
+     * @throws {ZodmonValidationError} When a document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * const page = await users.find({ role: 'admin' })
+     *   .sort({ createdAt: -1 })
+     *   .paginate({ page: 2, perPage: 10 })
+     * console.log(page.total, page.totalPages, page.hasNext)
+     * ```
+     */
+    paginate(opts: OffsetPaginateOptions): Promise<OffsetPage<InferDocument<TDef>>>;
+    /**
+     * Execute the query with cursor-based pagination, returning a page of documents
+     * with opaque cursors for forward/backward navigation.
+     *
+     * Uses the `limit + 1` trick to determine `hasNext`/`hasPrev` without extra queries.
+     * Direction is encoded in the cursor — pass `endCursor` to go forward, `startCursor`
+     * to go backward.
+     *
+     * @param opts - Cursor pagination options: `limit` and optional `cursor`.
+     * @returns A page with `docs`, `hasNext`, `hasPrev`, `startCursor`, `endCursor`.
+     * @throws {ZodmonValidationError} When a document fails schema validation.
+     * @throws {Error} When the cursor string is malformed.
+     *
+     * @example
+     * ```ts
+     * const first = await users.find({}).sort({ name: 1 }).paginate({ limit: 10 })
+     * const next = await users.find({}).sort({ name: 1 })
+     *   .paginate({ cursor: first.endCursor, limit: 10 })
+     * ```
+     */
+    paginate(opts: CursorPaginateOptions): Promise<CursorPage<InferDocument<TDef>>>;
+    /** @internal Offset pagination implementation. */
+    private offsetPaginate;
+    /** @internal Cursor pagination implementation. */
+    private cursorPaginate;
+    /**
+     * Execute the query and return all matching documents as an array.
+     *
+     * Each document is validated against the collection's Zod schema
+     * according to the resolved validation mode.
+     *
+     * @returns Array of validated documents.
+     * @throws {ZodmonValidationError} When a document fails schema validation in strict/strip mode.
+     *
+     * @example
+     * ```ts
+     * const admins = await find(users, { role: 'admin' }).toArray()
+     * ```
+     */
+    toArray(): Promise<InferDocument<TDef>[]>;
+    /**
+     * Async iterator for streaming documents one at a time.
+     *
+     * Each yielded document is validated against the collection's Zod schema.
+     * Memory-efficient for large result sets.
+     *
+     * @yields Validated documents one at a time.
+     * @throws {ZodmonValidationError} When a document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * for await (const user of find(users, {})) {
+     *   console.log(user.name)
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncGenerator<InferDocument<TDef>>;
+    /** @internal Validate a single raw document against the schema. */
+    private validateDoc;
+}
+
+/**
+ * Options for {@link findOne} and {@link findOneOrThrow}.
+ */
+type FindOneOptions = {
+    /** MongoDB projection — include (`1`) or exclude (`0`) fields. Typed projections deferred to v1.0. */
+    project?: Record<string, 0 | 1>;
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
+/**
+ * Find a single document matching the filter.
+ *
+ * Queries MongoDB, then validates the fetched document against the collection's
+ * Zod schema. Validation mode is resolved from the per-query option, falling
+ * back to the collection-level default (which defaults to `'strict'`).
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Optional projection and validation overrides.
+ * @returns The matched document, or `null` if no document matches.
+ * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+ *
+ * @example
+ * ```ts
+ * const user = await findOne(users, { name: 'Ada' })
+ * if (user) console.log(user.role) // typed as 'admin' | 'user'
+ * ```
+ */
+declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+/**
+ * Find a single document matching the filter, or throw if none exists.
+ *
+ * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
+ * instead of returning `null` when no document matches the filter.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Optional projection and validation overrides.
+ * @returns The matched document (never null).
+ * @throws {ZodmonNotFoundError} When no document matches the filter.
+ * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+ *
+ * @example
+ * ```ts
+ * const user = await findOneOrThrow(users, { name: 'Ada' })
+ * console.log(user.role) // typed as 'admin' | 'user', guaranteed non-null
+ * ```
+ */
+declare function findOneOrThrow<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+/**
+ * Options for {@link find}.
+ */
+type FindOptions = {
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
+/**
+ * Find all documents matching the filter, returning a chainable typed cursor.
+ *
+ * The cursor is lazy — no query is executed until a terminal method
+ * (`toArray`, `for await`) is called. Use `sort`, `skip`, and `limit`
+ * to shape the query before executing.
+ *
+ * Each document is validated against the collection's Zod schema when
+ * a terminal method consumes it.
+ *
+ * @param handle - The collection handle to query.
+ * @param filter - Type-safe filter to match documents.
+ * @param options - Optional validation overrides.
+ * @returns A typed cursor for chaining query modifiers.
+ *
+ * @example
+ * ```ts
+ * const admins = await find(users, { role: 'admin' })
+ *   .sort({ name: 1 })
+ *   .limit(10)
+ *   .toArray()
+ * ```
+ *
+ * @example
+ * ```ts
+ * for await (const user of find(users, {})) {
+ *   console.log(user.name)
+ * }
+ * ```
+ */
+declare function find<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
+
+/**
+ * Extracts the element type from an array type.
+ *
+ * @example
+ * ```ts
+ * type E = ArrayElement<string[]> // string
+ * type N = ArrayElement<number[]> // number
+ * ```
+ */
+type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
+/**
+ * Fields valid for `$set`, `$setOnInsert`, `$min`, and `$max` operators.
+ *
+ * Allows top-level fields with matching value types plus dot-notation paths
+ * for nested field updates.
+ *
+ * @example
+ * ```ts
+ * const set: SetFields<User> = { name: 'Alice', 'address.city': 'NYC' }
+ * ```
+ */
+type SetFields<T> = {
+    [K in keyof T]?: T[K];
+} & {
+    [P in DotPaths<T>]?: DotPathType<T, P>;
+};
+/**
+ * Fields valid for the `$inc` operator — only number-typed fields.
+ *
+ * Includes dot-notation paths that resolve to number types.
+ *
+ * @example
+ * ```ts
+ * const inc: IncFields<User> = { age: 1, 'stats.views': 5 }
+ * ```
+ */
+type IncFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends number ? K : never]?: number;
+} & {
+    [P in DotPaths<T> as DotPathType<T, P> extends number ? P : never]?: number;
+};
+/**
+ * Modifiers for the `$push` operator.
+ *
+ * Use with `$push` to insert multiple elements and control array position/size.
+ *
+ * @example
+ * ```ts
+ * const push = { tags: { $each: ['a', 'b'], $position: 0, $slice: 10 } }
+ * ```
+ */
+type PushModifiers<E> = {
+    /** Array of elements to push. */
+    $each: E[];
+    /** Position at which to insert elements. */
+    $position?: number;
+    /** Maximum array length after push. */
+    $slice?: number;
+    /** Sort order applied after push. */
+    $sort?: 1 | -1 | Record<string, 1 | -1>;
+};
+/**
+ * Fields valid for the `$push` operator — only array-typed fields.
+ *
+ * Accepts a single element value or a modifier object with `$each`.
+ *
+ * @example
+ * ```ts
+ * const push: PushFields<User> = { tags: 'dev' }
+ * const pushMany: PushFields<User> = { tags: { $each: ['a', 'b'] } }
+ * ```
+ */
+type PushFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | PushModifiers<ArrayElement<NonNullable<T[K]>>>;
+};
+/**
+ * Fields valid for the `$pull` operator — only array-typed fields.
+ *
+ * For primitive arrays: accepts a value or comparison operators.
+ * For object arrays: also accepts a `TypedFilter` on the element type.
+ *
+ * @example
+ * ```ts
+ * const pull: PullFields<User> = { tags: 'old' }
+ * const pullQuery: PullFields<User> = { scores: { $lt: 50 } }
+ * const pullObj: PullFields<User> = { comments: { author: 'spam' } }
+ * ```
+ */
+type PullFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | ComparisonOperators<ArrayElement<NonNullable<T[K]>>> | (ArrayElement<NonNullable<T[K]>> extends Record<string, unknown> ? TypedFilter<ArrayElement<NonNullable<T[K]>>> : unknown);
+};
+/**
+ * Modifier for the `$addToSet` operator's `$each` syntax.
+ *
+ * @example
+ * ```ts
+ * const addToSet = { tags: { $each: ['a', 'b'] } }
+ * ```
+ */
+type AddToSetEach<E> = {
+    $each: E[];
+};
+/**
+ * Fields valid for the `$addToSet` operator — only array-typed fields.
+ *
+ * Accepts a single element value or `{ $each: [...] }` for multiple elements.
+ *
+ * @example
+ * ```ts
+ * const add: AddToSetFields<User> = { tags: 'dev' }
+ * const addMany: AddToSetFields<User> = { tags: { $each: ['a', 'b'] } }
+ * ```
+ */
+type AddToSetFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | AddToSetEach<ArrayElement<NonNullable<T[K]>>>;
+};
+/**
+ * Fields valid for the `$pop` operator — only array-typed fields.
+ *
+ * Value `1` removes the last element, `-1` removes the first.
+ *
+ * @example
+ * ```ts
+ * const pop: PopFields<User> = { tags: -1 } // remove first
+ * ```
+ */
+type PopFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: 1 | -1;
+};
+/**
+ * Fields valid for the `$unset` operator — any existing field.
+ *
+ * Value is `''`, `true`, or `1` (all mean "remove this field").
+ *
+ * @example
+ * ```ts
+ * const unset: UnsetFields<User> = { middleName: '' }
+ * ```
+ */
+type UnsetFields<T> = {
+    [K in keyof T]?: '' | true | 1;
+};
+/**
+ * Fields valid for the `$currentDate` operator — only Date-typed fields.
+ *
+ * Sets the field to the current date. Value is `true` or `{ $type: 'date' }`.
+ *
+ * @example
+ * ```ts
+ * const cd: CurrentDateFields<User> = { createdAt: true }
+ * ```
+ */
+type CurrentDateFields<T> = {
+    [K in keyof T as NonNullable<T[K]> extends Date ? K : never]?: true | {
+        $type: 'date';
+    };
+};
+/**
+ * Fields valid for the `$rename` operator.
+ *
+ * Renames an existing field to a new name. Key is the current field name,
+ * value is the new name as a string.
+ *
+ * @example
+ * ```ts
+ * const rename: RenameFields<User> = { name: 'fullName' }
+ * ```
+ */
+type RenameFields<T> = {
+    [K in keyof T & string]?: string;
+};
+/**
+ * Strict type-safe MongoDB update filter.
+ *
+ * Validates update operators against field types at compile time. Each operator
+ * constrains which fields it accepts (e.g. `$inc` only on numbers, `$push` only
+ * on arrays). Supports dot-notation paths for nested field access.
+ *
+ * @example
+ * ```ts
+ * const update: TypedUpdateFilter<User> = {
+ *   $set: { name: 'Alice' },
+ *   $inc: { age: 1 },
+ * }
+ * ```
+ */
+type TypedUpdateFilter<T> = {
+    /** Sets the value of one or more fields. */
+    $set?: SetFields<T>;
+    /** Sets fields only when inserting (upsert). Same typing as `$set`. */
+    $setOnInsert?: SetFields<T>;
+    /** Increments numeric fields by the given amount. Only accepts number-typed fields. */
+    $inc?: IncFields<T>;
+    /** Updates the field if the given value is less than the current value. */
+    $min?: SetFields<T>;
+    /** Updates the field if the given value is greater than the current value. */
+    $max?: SetFields<T>;
+    /** Appends a value to an array field. Supports `$each`, `$position`, `$slice`, `$sort`. */
+    $push?: PushFields<T>;
+    /** Removes matching values from an array field. */
+    $pull?: PullFields<T>;
+    /** Adds a value to an array only if it doesn't already exist. */
+    $addToSet?: AddToSetFields<T>;
+    /** Removes the first (`-1`) or last (`1`) element of an array. */
+    $pop?: PopFields<T>;
+    /** Removes the specified fields from the document. */
+    $unset?: UnsetFields<T>;
+    /** Sets the field to the current date. Only accepts Date-typed fields. */
+    $currentDate?: CurrentDateFields<T>;
+    /** Renames a field. */
+    $rename?: RenameFields<T>;
+};
+
+/**
+ * Options for {@link updateOne} and {@link updateMany}.
+ */
+type UpdateOptions = {
+    /** When `true`, inserts a new document if no document matches the filter. */
+    upsert?: boolean;
+};
+/**
+ * Options for {@link findOneAndUpdate}.
+ */
+type FindOneAndUpdateOptions = {
+    /** Whether to return the document before or after the update. Defaults to `'after'`. */
+    returnDocument?: 'before' | 'after';
+    /** When `true`, inserts a new document if no document matches the filter. */
+    upsert?: boolean;
+    /** Override the collection-level validation mode, or `false` to skip validation entirely. */
+    validate?: ValidationMode | false;
+};
+/**
+ * Update a single document matching the filter.
+ *
+ * Applies the update operators to the first document that matches the filter.
+ * Does not validate the update against the Zod schema — validation happens
+ * at the field-operator level through {@link TypedUpdateFilter}.
+ *
+ * @param handle - The collection handle to update in.
+ * @param filter - Type-safe filter to match documents.
+ * @param update - Type-safe update operators to apply.
+ * @param options - Optional settings such as `upsert`.
+ * @returns The MongoDB `UpdateResult` with match/modify counts.
+ *
+ * @example
+ * ```ts
+ * const result = await updateOne(users, { name: 'Ada' }, { $set: { role: 'admin' } })
+ * console.log(result.modifiedCount) // 1
+ * ```
+ */
+declare function updateOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+/**
+ * Update all documents matching the filter.
+ *
+ * Applies the update operators to every document that matches the filter.
+ * Does not validate the update against the Zod schema — validation happens
+ * at the field-operator level through {@link TypedUpdateFilter}.
+ *
+ * @param handle - The collection handle to update in.
+ * @param filter - Type-safe filter to match documents.
+ * @param update - Type-safe update operators to apply.
+ * @param options - Optional settings such as `upsert`.
+ * @returns The MongoDB `UpdateResult` with match/modify counts.
+ *
+ * @example
+ * ```ts
+ * const result = await updateMany(users, { role: 'guest' }, { $set: { role: 'user' } })
+ * console.log(result.modifiedCount) // number of guests promoted
+ * ```
+ */
+declare function updateMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+/**
+ * Find a single document matching the filter, apply an update, and return the document.
+ *
+ * By default, returns the document **after** the update is applied. Set
+ * `returnDocument: 'before'` to get the pre-update snapshot. The returned
+ * document is validated against the collection's Zod schema using the same
+ * resolution logic as {@link findOne}.
+ *
+ * @param handle - The collection handle to update in.
+ * @param filter - Type-safe filter to match documents.
+ * @param update - Type-safe update operators to apply.
+ * @param options - Optional settings: `returnDocument`, `upsert`, `validate`.
+ * @returns The matched document (before or after update), or `null` if no document matches.
+ * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+ *
+ * @example
+ * ```ts
+ * const user = await findOneAndUpdate(
+ *   users,
+ *   { name: 'Ada' },
+ *   { $set: { role: 'admin' } },
+ * )
+ * if (user) console.log(user.role) // 'admin' (returned after update)
+ * ```
+ *
+ * @example
+ * ```ts
+ * const before = await findOneAndUpdate(
+ *   users,
+ *   { name: 'Ada' },
+ *   { $inc: { loginCount: 1 } },
+ *   { returnDocument: 'before' },
+ * )
+ * ```
+ */
+declare function findOneAndUpdate<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: FindOneAndUpdateOptions): Promise<InferDocument<TDef> | null>;
+
+/**
+ * Typed wrapper around a MongoDB driver `Collection`.
+ *
+ * Created by {@link Database.use}. Holds the original `CollectionDefinition`
+ * (for runtime schema validation and index metadata) alongside the native
+ * driver collection parameterized with the inferred document type.
+ *
+ * @typeParam TDef - The collection definition type. Used to derive both
+ *   the document type (`InferDocument`) and the insert type (`InferInsert`).
+ */
+declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
+    /** The collection definition containing schema, name, and index metadata. */
+    readonly definition: TDef;
+    /** The underlying MongoDB driver collection, typed to the inferred document type. */
+    readonly native: Collection<InferDocument<TDef>>;
+    constructor(definition: TDef, native: Collection<InferDocument<TDef>>);
+    /**
+     * Insert a single document into the collection.
+     *
+     * Validates the input against the collection's Zod schema before writing.
+     * Schema defaults (including auto-generated `_id`) are applied during
+     * validation. Returns the full document with all defaults filled in.
+     *
+     * @param doc - The document to insert. Fields with `.default()` are optional.
+     * @returns The inserted document with `_id` and all defaults applied.
+     * @throws {ZodmonValidationError} When the document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.insertOne({ name: 'Ada' })
+     * console.log(user._id) // ObjectId (auto-generated)
+     * console.log(user.role) // 'user' (schema default)
+     * ```
+     */
+    insertOne(doc: InferInsert<TDef>): Promise<InferDocument<TDef>>;
+    /**
+     * Insert multiple documents into the collection.
+     *
+     * Validates every document against the collection's Zod schema before
+     * writing any to MongoDB. If any document fails validation, none are
+     * inserted (fail-fast before the driver call).
+     *
      * @param docs - The documents to insert.
      * @returns The inserted documents with `_id` and all defaults applied.
      * @throws {ZodmonValidationError} When any document fails schema validation.
@@ -736,7 +1356,156 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      *   .toArray()
      * ```
      */
-    find(filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef>;
+    find(filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef, IndexNames<TDef>>;
+    /**
+     * Update a single document matching the filter.
+     *
+     * Applies the update operators to the first document that matches the filter.
+     * Does not validate the update against the Zod schema — validation happens
+     * at the field-operator level through {@link TypedUpdateFilter}.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param update - Type-safe update operators to apply.
+     * @param options - Optional settings such as `upsert`.
+     * @returns The MongoDB `UpdateResult` with match/modify counts.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.updateOne({ name: 'Ada' }, { $set: { role: 'admin' } })
+     * console.log(result.modifiedCount) // 1
+     * ```
+     */
+    updateOne(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Update all documents matching the filter.
+     *
+     * Applies the update operators to every document that matches the filter.
+     * Does not validate the update against the Zod schema — validation happens
+     * at the field-operator level through {@link TypedUpdateFilter}.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param update - Type-safe update operators to apply.
+     * @param options - Optional settings such as `upsert`.
+     * @returns The MongoDB `UpdateResult` with match/modify counts.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.updateMany({ role: 'guest' }, { $set: { role: 'user' } })
+     * console.log(result.modifiedCount) // number of guests promoted
+     * ```
+     */
+    updateMany(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Find a single document matching the filter, apply an update, and return the document.
+     *
+     * By default, returns the document **after** the update is applied. Set
+     * `returnDocument: 'before'` to get the pre-update snapshot. The returned
+     * document is validated against the collection's Zod schema using the same
+     * resolution logic as {@link findOne}.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param update - Type-safe update operators to apply.
+     * @param options - Optional settings: `returnDocument`, `upsert`, `validate`.
+     * @returns The matched document (before or after update), or `null` if no document matches.
+     * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOneAndUpdate(
+     *   { name: 'Ada' },
+     *   { $set: { role: 'admin' } },
+     * )
+     * if (user) console.log(user.role) // 'admin' (returned after update)
+     * ```
+     */
+    findOneAndUpdate(filter: TypedFilter<InferDocument<TDef>>, update: TypedUpdateFilter<InferDocument<TDef>>, options?: FindOneAndUpdateOptions): Promise<InferDocument<TDef> | null>;
+    /**
+     * Delete a single document matching the filter.
+     *
+     * Removes the first document that matches the filter from the collection.
+     * No validation is performed — the document is deleted directly through
+     * the MongoDB driver.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @returns The MongoDB `DeleteResult` with the deleted count.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.deleteOne({ name: 'Ada' })
+     * console.log(result.deletedCount) // 1
+     * ```
+     */
+    deleteOne(filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
+    /**
+     * Delete all documents matching the filter.
+     *
+     * Removes every document that matches the filter from the collection.
+     * No validation is performed — documents are deleted directly through
+     * the MongoDB driver.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @returns The MongoDB `DeleteResult` with the deleted count.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.deleteMany({ role: 'guest' })
+     * console.log(result.deletedCount) // number of guests removed
+     * ```
+     */
+    deleteMany(filter: TypedFilter<InferDocument<TDef>>): Promise<DeleteResult>;
+    /**
+     * Find a single document matching the filter, delete it, and return the document.
+     *
+     * Returns the deleted document, or `null` if no document matches the filter.
+     * The returned document is validated against the collection's Zod schema
+     * using the same resolution logic as {@link findOne}.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Optional settings: `validate`.
+     * @returns The deleted document, or `null` if no document matches.
+     * @throws {ZodmonValidationError} When the returned document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOneAndDelete({ name: 'Ada' })
+     * if (user) console.log(user.name) // 'Ada' (the deleted document)
+     * ```
+     */
+    findOneAndDelete(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneAndDeleteOptions): Promise<InferDocument<TDef> | null>;
+    /**
+     * Synchronize the indexes declared in this collection's schema with MongoDB.
+     *
+     * Compares the desired indexes (from field-level `.index()` / `.unique()` /
+     * `.text()` / `.expireAfter()` and compound `indexes` in collection options)
+     * with the indexes that currently exist in MongoDB, then creates, drops, or
+     * reports differences depending on the options.
+     *
+     * @param options - Optional sync behavior (dryRun, dropOrphaned).
+     * @returns A summary of created, dropped, skipped, and stale indexes.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const result = await users.syncIndexes()
+     * console.log('Created:', result.created)
+     * console.log('Stale:', result.stale.map(s => s.name))
+     * ```
+     *
+     * @example
+     * ```ts
+     * // Dry run to preview changes without modifying the database
+     * const diff = await users.syncIndexes({ dryRun: true })
+     * console.log('Would create:', diff.created)
+     * console.log('Would drop:', diff.dropped)
+     * ```
+     */
+    syncIndexes(options?: SyncIndexesOptions): Promise<SyncIndexesResult>;
 }
 
 /**
@@ -771,13 +1540,28 @@ declare class Database {
      * @param def - A collection definition created by `collection()`.
      * @returns A typed collection handle for CRUD operations.
      */
-    use<TShape extends z.core.$ZodShape>(def: CollectionDefinition<TShape>): CollectionHandle<CollectionDefinition<TShape>>;
+    use<TShape extends z.core.$ZodShape, TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]>(def: CollectionDefinition<TShape, TIndexes>): CollectionHandle<CollectionDefinition<TShape, TIndexes>>;
     /**
-     * Synchronize indexes defined in registered collections with MongoDB.
+     * Synchronize indexes for all registered collections with MongoDB.
+     *
+     * Iterates every collection registered via {@link use} and calls
+     * {@link syncIndexes} on each one. Returns a record keyed by collection
+     * name with the sync result for each.
+     *
+     * @param options - Optional sync behavior (dryRun, dropOrphaned).
+     * @returns A record mapping collection names to their sync results.
      *
-     * Stub — full implementation in TASK-92.
+     * @example
+     * ```ts
+     * const db = createClient('mongodb://localhost:27017', 'myapp')
+     * db.use(Users)
+     * db.use(Posts)
+     * const results = await db.syncIndexes()
+     * console.log(results['users'].created) // ['email_1']
+     * console.log(results['posts'].created) // ['title_1']
+     * ```
      */
-    syncIndexes(): Promise<void>;
+    syncIndexes(options?: SyncIndexesOptions): Promise<Record<string, SyncIndexesResult>>;
     /**
      * Execute a function within a MongoDB transaction with auto-commit/rollback.
      *
@@ -852,7 +1636,9 @@ 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>;
+declare function collection<TShape extends z.core.$ZodShape, const TIndexes extends readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[] = readonly CompoundIndexDefinition<Extract<keyof TShape, string>>[]>(name: string, shape: TShape, options?: Omit<CollectionOptions<Extract<keyof TShape, string>>, 'indexes'> & {
+    indexes?: TIndexes;
+}): CollectionDefinition<TShape, [...TIndexes]>;
 
 type IndexDirection = 1 | -1;
 type CompoundIndexOptions = NonNullable<CompoundIndexDefinition['options']>;
@@ -880,9 +1666,27 @@ declare class IndexBuilder<TKeys extends string> {
     readonly options: CompoundIndexOptions;
     constructor(fields: Record<TKeys, IndexDirection>);
     private _clone;
-    unique(): IndexBuilder<TKeys>;
-    sparse(): IndexBuilder<TKeys>;
-    name(name: string): IndexBuilder<TKeys>;
+    unique(): this;
+    sparse(): this;
+    /**
+     * Set a custom name for this index, preserving the literal type.
+     *
+     * The returned builder carries the literal name type via an intersection,
+     * enabling type-safe `.hint()` on cursors that only accepts declared names.
+     *
+     * @param name - The index name.
+     * @returns A new IndexBuilder with the name recorded at the type level.
+     *
+     * @example
+     * ```ts
+     * index({ email: 1, role: -1 }).name('email_role_idx')
+     * ```
+     */
+    name<TName extends string>(name: TName): IndexBuilder<TKeys> & {
+        readonly options: {
+            readonly name: TName;
+        };
+    };
 }
 /**
  * Create a compound index definition with a fluent builder API.
@@ -1047,6 +1851,287 @@ declare function oid(value: ObjectId): ObjectId;
  */
 declare function isOid(value: unknown): value is ObjectId;
 
+/**
+ * A normalized index specification ready for comparison and creation.
+ *
+ * `key` maps field paths to direction (`1`, `-1`, or `'text'`).
+ * `options` holds MongoDB index options (`unique`, `sparse`, etc.).
+ *
+ * @example
+ * ```ts
+ * const spec: IndexSpec = {
+ *   key: { email: 1 },
+ *   options: { unique: true },
+ * }
+ * ```
+ */
+type IndexSpec = {
+    key: Record<string, 1 | -1 | 'text'>;
+    options: Record<string, unknown>;
+};
+/**
+ * Convert a field-level index definition to a normalized {@link IndexSpec}.
+ *
+ * Maps schema metadata (`text`, `descending`, `unique`, `sparse`, `expireAfter`,
+ * `partial`) to their MongoDB driver equivalents.
+ *
+ * @param def - A field index definition extracted from schema metadata.
+ * @returns A normalized index spec with key and options.
+ *
+ * @example
+ * ```ts
+ * const spec = toFieldIndexSpec({ field: 'email', indexed: true, unique: true })
+ * // => { key: { email: 1 }, options: { unique: true } }
+ *
+ * const ttl = toFieldIndexSpec({ field: 'expiresAt', indexed: true, expireAfter: 3600 })
+ * // => { key: { expiresAt: 1 }, options: { expireAfterSeconds: 3600 } }
+ * ```
+ */
+declare function toFieldIndexSpec(def: FieldIndexDefinition): IndexSpec;
+/**
+ * Convert a compound index definition to a normalized {@link IndexSpec}.
+ *
+ * Copies the `fields` map directly to `key` and maps builder options
+ * (`unique`, `sparse`, `name`, `partial`) to MongoDB driver equivalents.
+ *
+ * @param def - A compound index definition from the collection options.
+ * @returns A normalized index spec with key and options.
+ *
+ * @example
+ * ```ts
+ * const spec = toCompoundIndexSpec({
+ *   fields: { email: 1, role: -1 },
+ *   options: { unique: true, name: 'email_role_idx' },
+ * })
+ * // => { key: { email: 1, role: -1 }, options: { unique: true, name: 'email_role_idx' } }
+ * ```
+ */
+declare function toCompoundIndexSpec(def: CompoundIndexDefinition): IndexSpec;
+/**
+ * Produce a stable, deterministic string from an index key for comparison.
+ *
+ * Entries are sorted alphabetically by field name and formatted as
+ * `field:direction` pairs joined by commas. Two index keys that should be
+ * considered the same will always produce the same string.
+ *
+ * @param key - An index key mapping field names to direction.
+ * @returns A string like `'email:1,role:-1'`.
+ *
+ * @example
+ * ```ts
+ * serializeIndexKey({ email: 1, role: -1 })
+ * // => 'email:1,role:-1'
+ *
+ * serializeIndexKey({ name: 'text' })
+ * // => 'name:text'
+ * ```
+ */
+declare function serializeIndexKey(key: Record<string, 1 | -1 | 'text'>): string;
+
+/**
+ * Structural constraint for the handle argument of {@link syncIndexes}.
+ *
+ * Uses a structural type rather than `CollectionHandle<AnyCollection>` to avoid
+ * TypeScript variance issues with `exactOptionalPropertyTypes`. Any collection
+ * handle returned by `db.use()` satisfies this constraint.
+ */
+type SyncableHandle = {
+    readonly definition: {
+        readonly fieldIndexes: FieldIndexDefinition[];
+        readonly compoundIndexes: readonly CompoundIndexDefinition[];
+    };
+    readonly native: Collection<any>;
+};
+/**
+ * Extract the comparable options from a MongoDB index info object.
+ *
+ * Pulls only the keys listed in {@link COMPARABLE_OPTION_KEYS} from the raw
+ * index info returned by `listIndexes()`. Keys whose value is `undefined`
+ * are omitted so that JSON comparison works correctly.
+ *
+ * @param info - A raw MongoDB index info object.
+ * @returns A plain object with only the relevant option keys.
+ *
+ * @example
+ * ```ts
+ * const opts = extractComparableOptions({ v: 2, unique: true, key: { email: 1 } })
+ * // => { unique: true }
+ * ```
+ */
+declare function extractComparableOptions(info: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Generate the default MongoDB index name from a key spec.
+ *
+ * MongoDB names indexes by joining `field_direction` pairs with underscores.
+ * For example, `{ email: 1, role: -1 }` becomes `'email_1_role_-1'`.
+ *
+ * @param key - An index key mapping field names to direction.
+ * @returns The generated index name string.
+ *
+ * @example
+ * ```ts
+ * generateIndexName({ email: 1 })
+ * // => 'email_1'
+ *
+ * generateIndexName({ email: 1, role: -1 })
+ * // => 'email_1_role_-1'
+ * ```
+ */
+declare function generateIndexName(key: Record<string, 1 | -1 | 'text'>): string;
+/**
+ * Synchronize the indexes declared in a collection's schema with MongoDB.
+ *
+ * Compares the desired indexes (from field-level and compound index definitions)
+ * with the indexes that currently exist in MongoDB, then creates, drops, or
+ * reports differences depending on the options.
+ *
+ * **Algorithm:**
+ * 1. Build desired specs from field indexes and compound indexes.
+ * 2. Fetch existing indexes from MongoDB via `listIndexes()`.
+ * 3. For each desired spec, compare against existing:
+ *    - Missing → create (unless `dryRun`).
+ *    - Present with same options → skip.
+ *    - Present with different options → stale (or drop+recreate if `dropOrphaned`).
+ * 4. For each existing index not in desired set (excluding `_id_`):
+ *    - If `dropOrphaned` → drop (unless `dryRun`).
+ * 5. Return a summary of all actions taken.
+ *
+ * @param handle - A collection handle created by `db.use()`.
+ * @param options - Optional sync behavior (dryRun, dropOrphaned).
+ * @returns A summary of created, dropped, skipped, and stale indexes.
+ *
+ * @example
+ * ```ts
+ * import { syncIndexes } from '@zodmon/core'
+ *
+ * const users = db.use(Users)
+ * const result = await syncIndexes(users)
+ * console.log('Created:', result.created)
+ * console.log('Stale:', result.stale.map(s => s.name))
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Dry run — no changes made
+ * const diff = await syncIndexes(users, { dryRun: true })
+ * console.log('Would create:', diff.created)
+ * console.log('Would drop:', diff.dropped)
+ * ```
+ */
+declare function syncIndexes(handle: SyncableHandle, options?: SyncIndexesOptions): Promise<SyncIndexesResult>;
+
+/**
+ * Structural constraint for the definition argument of {@link checkUnindexedFields}.
+ *
+ * Uses a structural type rather than `CollectionDefinition<z.core.$ZodShape>` to avoid
+ * TypeScript variance issues with `exactOptionalPropertyTypes`. Any collection
+ * definition returned by `collection()` satisfies this constraint.
+ */
+type WarnableDefinition = {
+    readonly name: string;
+    readonly fieldIndexes: FieldIndexDefinition[];
+    readonly compoundIndexes: readonly CompoundIndexDefinition[];
+    readonly options: {
+        warnUnindexedQueries?: boolean;
+    };
+};
+/**
+ * Warn about unindexed fields used in a query filter.
+ *
+ * When `warnUnindexedQueries` is enabled on a collection definition, this
+ * function checks each top-level field in the filter against the collection's
+ * declared indexes. Fields that are not covered by any index produce a
+ * `console.warn` message to help identify queries that may cause full
+ * collection scans in development.
+ *
+ * **Covered fields:**
+ * - `_id` (always indexed by MongoDB)
+ * - Fields with `.index()`, `.unique()`, `.text()`, or `.expireAfter()` (field-level indexes)
+ * - The **first** field of each compound index (prefix matching)
+ *
+ * **Skipped keys:**
+ * - MongoDB operators: `$or`, `$and`, `$nor`, `$text`, `$where`, `$expr`, `$comment`
+ *
+ * This function is a no-op (zero overhead) when `warnUnindexedQueries` is not
+ * explicitly set to `true`.
+ *
+ * @param definition - The collection definition containing index metadata.
+ * @param filter - The query filter to check for unindexed fields.
+ *
+ * @example
+ * ```ts
+ * import { collection, checkUnindexedFields } from '@zodmon/core'
+ *
+ * const Users = collection('users', {
+ *   email: z.string().unique(),
+ *   name: z.string(),
+ * }, { warnUnindexedQueries: true })
+ *
+ * // No warning — email is indexed
+ * checkUnindexedFields(Users, { email: 'ada@example.com' })
+ *
+ * // Warns: "[zodmon] warn: query on 'users' uses unindexed field 'name'"
+ * checkUnindexedFields(Users, { name: 'Ada' })
+ * ```
+ */
+declare function checkUnindexedFields(definition: WarnableDefinition, filter: Record<string, unknown>): void;
+
+/**
+ * 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.
  *
@@ -1234,219 +2319,6 @@ declare const $nor: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>
  */
 declare const raw: <T = any>(filter: Record<string, unknown>) => TypedFilter<T>;
 
-/**
- * Extracts the element type from an array type.
- *
- * @example
- * ```ts
- * type E = ArrayElement<string[]> // string
- * type N = ArrayElement<number[]> // number
- * ```
- */
-type ArrayElement<T> = T extends ReadonlyArray<infer E> ? E : never;
-/**
- * Fields valid for `$set`, `$setOnInsert`, `$min`, and `$max` operators.
- *
- * Allows top-level fields with matching value types plus dot-notation paths
- * for nested field updates.
- *
- * @example
- * ```ts
- * const set: SetFields<User> = { name: 'Alice', 'address.city': 'NYC' }
- * ```
- */
-type SetFields<T> = {
-    [K in keyof T]?: T[K];
-} & {
-    [P in DotPaths<T>]?: DotPathType<T, P>;
-};
-/**
- * Fields valid for the `$inc` operator — only number-typed fields.
- *
- * Includes dot-notation paths that resolve to number types.
- *
- * @example
- * ```ts
- * const inc: IncFields<User> = { age: 1, 'stats.views': 5 }
- * ```
- */
-type IncFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends number ? K : never]?: number;
-} & {
-    [P in DotPaths<T> as DotPathType<T, P> extends number ? P : never]?: number;
-};
-/**
- * Modifiers for the `$push` operator.
- *
- * Use with `$push` to insert multiple elements and control array position/size.
- *
- * @example
- * ```ts
- * const push = { tags: { $each: ['a', 'b'], $position: 0, $slice: 10 } }
- * ```
- */
-type PushModifiers<E> = {
-    /** Array of elements to push. */
-    $each: E[];
-    /** Position at which to insert elements. */
-    $position?: number;
-    /** Maximum array length after push. */
-    $slice?: number;
-    /** Sort order applied after push. */
-    $sort?: 1 | -1 | Record<string, 1 | -1>;
-};
-/**
- * Fields valid for the `$push` operator — only array-typed fields.
- *
- * Accepts a single element value or a modifier object with `$each`.
- *
- * @example
- * ```ts
- * const push: PushFields<User> = { tags: 'dev' }
- * const pushMany: PushFields<User> = { tags: { $each: ['a', 'b'] } }
- * ```
- */
-type PushFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | PushModifiers<ArrayElement<NonNullable<T[K]>>>;
-};
-/**
- * Fields valid for the `$pull` operator — only array-typed fields.
- *
- * For primitive arrays: accepts a value or comparison operators.
- * For object arrays: also accepts a `TypedFilter` on the element type.
- *
- * @example
- * ```ts
- * const pull: PullFields<User> = { tags: 'old' }
- * const pullQuery: PullFields<User> = { scores: { $lt: 50 } }
- * const pullObj: PullFields<User> = { comments: { author: 'spam' } }
- * ```
- */
-type PullFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | ComparisonOperators<ArrayElement<NonNullable<T[K]>>> | (ArrayElement<NonNullable<T[K]>> extends Record<string, unknown> ? TypedFilter<ArrayElement<NonNullable<T[K]>>> : unknown);
-};
-/**
- * Modifier for the `$addToSet` operator's `$each` syntax.
- *
- * @example
- * ```ts
- * const addToSet = { tags: { $each: ['a', 'b'] } }
- * ```
- */
-type AddToSetEach<E> = {
-    $each: E[];
-};
-/**
- * Fields valid for the `$addToSet` operator — only array-typed fields.
- *
- * Accepts a single element value or `{ $each: [...] }` for multiple elements.
- *
- * @example
- * ```ts
- * const add: AddToSetFields<User> = { tags: 'dev' }
- * const addMany: AddToSetFields<User> = { tags: { $each: ['a', 'b'] } }
- * ```
- */
-type AddToSetFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: ArrayElement<NonNullable<T[K]>> | AddToSetEach<ArrayElement<NonNullable<T[K]>>>;
-};
-/**
- * Fields valid for the `$pop` operator — only array-typed fields.
- *
- * Value `1` removes the last element, `-1` removes the first.
- *
- * @example
- * ```ts
- * const pop: PopFields<User> = { tags: -1 } // remove first
- * ```
- */
-type PopFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends ReadonlyArray<unknown> ? K : never]?: 1 | -1;
-};
-/**
- * Fields valid for the `$unset` operator — any existing field.
- *
- * Value is `''`, `true`, or `1` (all mean "remove this field").
- *
- * @example
- * ```ts
- * const unset: UnsetFields<User> = { middleName: '' }
- * ```
- */
-type UnsetFields<T> = {
-    [K in keyof T]?: '' | true | 1;
-};
-/**
- * Fields valid for the `$currentDate` operator — only Date-typed fields.
- *
- * Sets the field to the current date. Value is `true` or `{ $type: 'date' }`.
- *
- * @example
- * ```ts
- * const cd: CurrentDateFields<User> = { createdAt: true }
- * ```
- */
-type CurrentDateFields<T> = {
-    [K in keyof T as NonNullable<T[K]> extends Date ? K : never]?: true | {
-        $type: 'date';
-    };
-};
-/**
- * Fields valid for the `$rename` operator.
- *
- * Renames an existing field to a new name. Key is the current field name,
- * value is the new name as a string.
- *
- * @example
- * ```ts
- * const rename: RenameFields<User> = { name: 'fullName' }
- * ```
- */
-type RenameFields<T> = {
-    [K in keyof T & string]?: string;
-};
-/**
- * Strict type-safe MongoDB update filter.
- *
- * Validates update operators against field types at compile time. Each operator
- * constrains which fields it accepts (e.g. `$inc` only on numbers, `$push` only
- * on arrays). Supports dot-notation paths for nested field access.
- *
- * @example
- * ```ts
- * const update: TypedUpdateFilter<User> = {
- *   $set: { name: 'Alice' },
- *   $inc: { age: 1 },
- * }
- * ```
- */
-type TypedUpdateFilter<T> = {
-    /** Sets the value of one or more fields. */
-    $set?: SetFields<T>;
-    /** Sets fields only when inserting (upsert). Same typing as `$set`. */
-    $setOnInsert?: SetFields<T>;
-    /** Increments numeric fields by the given amount. Only accepts number-typed fields. */
-    $inc?: IncFields<T>;
-    /** Updates the field if the given value is less than the current value. */
-    $min?: SetFields<T>;
-    /** Updates the field if the given value is greater than the current value. */
-    $max?: SetFields<T>;
-    /** Appends a value to an array field. Supports `$each`, `$position`, `$slice`, `$sort`. */
-    $push?: PushFields<T>;
-    /** Removes matching values from an array field. */
-    $pull?: PullFields<T>;
-    /** Adds a value to an array only if it doesn't already exist. */
-    $addToSet?: AddToSetFields<T>;
-    /** Removes the first (`-1`) or last (`1`) element of an array. */
-    $pop?: PopFields<T>;
-    /** Removes the specified fields from the document. */
-    $unset?: UnsetFields<T>;
-    /** Sets the field to the current date. Only accepts Date-typed fields. */
-    $currentDate?: CurrentDateFields<T>;
-    /** Renames a field. */
-    $rename?: RenameFields<T>;
-};
-
 /**
  * Type-level marker that carries the target collection type through the
  * type system. Intersected with the schema return type by `.ref()` so
@@ -1524,11 +2396,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 AddToSetEach, type AddToSetFields, type AnyCollection, type ArrayElement, type CollectionDefinition, CollectionHandle, type CollectionOptions, type ComparisonOperators, type CompoundIndexDefinition, type CurrentDateFields, Database, type DotPathType, type DotPaths, type FieldIndexDefinition, type FindOneOptions, type FindOptions, type IncFields, IndexBuilder, type IndexMetadata, type IndexOptions, type InferDocument, type InferInsert, type PopFields, type PullFields, type PushFields, type PushModifiers, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type TypedFilter, TypedFindCursor, type TypedSort, type TypedUpdateFilter, type UnsetFields, 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 IndexNames, type IndexOptions, type IndexSpec, type InferDocument, type InferInsert, type OffsetPage, type OffsetPaginateOptions, type PopFields, type PullFields, type PushFields, type PushModifiers, type RefMarker, type RefMetadata, type RenameFields, type ResolvedShape, type SetFields, type SortOf, type StaleIndex, type SyncIndexesOptions, type SyncIndexesResult, type TypedFilter, TypedFindCursor, type TypedSort, type TypedUpdateFilter, type UnsetFields, type UpdateFilterOf, type UpdateOptions, type ValidationMode, type ZodObjectId, ZodmonNotFoundError, ZodmonValidationError, checkUnindexedFields, collection, createClient, deleteMany, deleteOne, extractComparableOptions, extractDbName, extractFieldIndexes, find, findOne, findOneAndDelete, findOneAndUpdate, findOneOrThrow, generateIndexName, getIndexMetadata, getRefMetadata, index, insertMany, insertOne, isOid, objectId, oid, raw, serializeIndexKey, syncIndexes, toCompoundIndexSpec, toFieldIndexSpec, updateMany, updateOne };