@zodmon/core 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { ObjectId, Document, Collection, MongoClientOptions } from 'mongodb';
-import { ZodPipe, ZodCustom, ZodTransform, z } from 'zod';
+import { ObjectId, FindCursor, Collection, MongoClientOptions } from 'mongodb';
+import { ZodPipe, ZodCustom, ZodTransform, z, ZodDefault } from 'zod';
 
 /**
  * Options controlling how a field-level MongoDB index is created.
@@ -225,10 +225,12 @@ type CompoundIndexDefinition<TKeys extends string = string> = {
 type FieldIndexDefinition = {
     field: string;
 } & IndexOptions;
+/** Validation strategy for documents read from or written to MongoDB. */
+type ValidationMode = 'strict' | 'strip' | 'passthrough';
 /** Options passed to collection() as the third argument. */
 type CollectionOptions<TKeys extends string = string> = {
     indexes?: CompoundIndexDefinition<TKeys>[];
-    validation?: 'strict' | 'strip' | 'passthrough';
+    validation?: ValidationMode;
     warnUnindexedQueries?: boolean;
     schemaVersion?: number;
     migrate?: (doc: Record<string, unknown>, version: number) => Record<string, unknown>;
@@ -242,7 +244,7 @@ type CollectionOptions<TKeys extends string = string> = {
  * This allows custom id types (nanoid, UUID, etc.) when needed.
  */
 type ResolvedShape<TShape extends z.core.$ZodShape> = '_id' extends keyof TShape ? TShape : {
-    _id: ZodObjectId;
+    _id: ZodDefault<ZodObjectId>;
 } & TShape;
 /**
  * The document type inferred from a collection definition.
@@ -256,6 +258,23 @@ type ResolvedShape<TShape extends z.core.$ZodShape> = '_id' extends keyof TShape
 type InferDocument<TDef extends {
     readonly schema: z.ZodType;
 }> = z.infer<TDef['schema']>;
+/**
+ * The input type for inserting a document into a collection.
+ *
+ * Uses Zod's input type so fields with `.default()` (including the
+ * auto-generated `_id`) are optional. Custom `_id` fields without
+ * a default remain required.
+ *
+ * @example
+ * ```ts
+ * // Auto-generated _id — optional on insert
+ * type Insert = InferInsert<typeof Users>
+ * // { _id?: string | ObjectId; name: string; role?: string }
+ * ```
+ */
+type InferInsert<TDef extends {
+    readonly schema: z.ZodType;
+}> = z.input<TDef['schema']>;
 /**
  * The immutable definition object returned by collection().
  * Holds everything needed to later create a live collection handle.
@@ -271,6 +290,337 @@ type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape> =
 /** Erased collection type for use in generic contexts. */
 type AnyCollection = CollectionDefinition<z.core.$ZodShape>;
 
+/**
+ * Type-safe sort specification for a document type.
+ *
+ * Constrains sort keys to top-level fields of `T` with direction `1` (ascending)
+ * or `-1` (descending). Dot-path sorts deferred to v1.0.
+ *
+ * @example
+ * ```ts
+ * const sort: TypedSort<User> = { name: 1, createdAt: -1 }
+ * ```
+ */
+type TypedSort<T> = Partial<Record<keyof T & string, 1 | -1>>;
+/**
+ * Type-safe cursor wrapping MongoDB's `FindCursor`.
+ *
+ * Provides chainable query modifiers (`sort`, `skip`, `limit`) 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.
+ *
+ * @example
+ * ```ts
+ * const docs = await find(users, { role: 'admin' })
+ *   .sort({ name: 1 })
+ *   .limit(10)
+ *   .toArray()
+ * ```
+ */
+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;
+    /**
+     * 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;
+}
+
+/**
+ * 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
+ * const filter = $and<User>(
+ *   $or<User>({ role: 'admin' }, { role: 'moderator' }),
+ *   { age: $gte(18) },
+ *   { email: $exists() },
+ * )
+ *
+ * // 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 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>;
+
 /**
  * Typed wrapper around a MongoDB driver `Collection`.
  *
@@ -278,18 +628,116 @@ type AnyCollection = CollectionDefinition<z.core.$ZodShape>;
  * (for runtime schema validation and index metadata) alongside the native
  * driver collection parameterized with the inferred document type.
  *
- * CRUD methods (insertOne, find, etc.) are added to this class by
- * subsequent modules — the handle itself is intentionally behavior-free.
- *
- * @typeParam TDoc - The document type inferred from the Zod schema
- *   (e.g. `{ _id: ObjectId; name: string }`). Defaults to `Document`.
+ * @typeParam TDef - The collection definition type. Used to derive both
+ *   the document type (`InferDocument`) and the insert type (`InferInsert`).
  */
-declare class CollectionHandle<TDoc extends Document = Document> {
+declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
     /** The collection definition containing schema, name, and index metadata. */
-    readonly definition: AnyCollection;
-    /** The underlying MongoDB driver collection, typed to `TDoc`. */
-    readonly native: Collection<TDoc>;
-    constructor(definition: AnyCollection, native: Collection<TDoc>);
+    readonly definition: TDef;
+    /** The underlying MongoDB driver collection, typed to the inferred document type. */
+    readonly native: Collection<InferDocument<TDef>>;
+    constructor(definition: TDef, native: Collection<InferDocument<TDef>>);
+    /**
+     * Insert a single document into the collection.
+     *
+     * Validates the input against the collection's Zod schema before writing.
+     * Schema defaults (including auto-generated `_id`) are applied during
+     * validation. Returns the full document with all defaults filled in.
+     *
+     * @param doc - The document to insert. Fields with `.default()` are optional.
+     * @returns The inserted document with `_id` and all defaults applied.
+     * @throws {ZodmonValidationError} When the document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.insertOne({ name: 'Ada' })
+     * console.log(user._id) // ObjectId (auto-generated)
+     * console.log(user.role) // 'user' (schema default)
+     * ```
+     */
+    insertOne(doc: InferInsert<TDef>): Promise<InferDocument<TDef>>;
+    /**
+     * Insert multiple documents into the collection.
+     *
+     * Validates every document against the collection's Zod schema before
+     * writing any to MongoDB. If any document fails validation, none are
+     * inserted (fail-fast before the driver call).
+     *
+     * @param docs - The documents to insert.
+     * @returns The inserted documents with `_id` and all defaults applied.
+     * @throws {ZodmonValidationError} When any document fails schema validation.
+     *
+     * @example
+     * ```ts
+     * const created = await users.insertMany([
+     *   { name: 'Ada' },
+     *   { name: 'Bob', role: 'admin' },
+     * ])
+     * ```
+     */
+    insertMany(docs: InferInsert<TDef>[]): Promise<InferDocument<TDef>[]>;
+    /**
+     * Find a single document matching the filter.
+     *
+     * Queries MongoDB, then validates the fetched document against the collection's
+     * Zod schema. Validation mode is resolved from the per-query option, falling
+     * back to the collection-level default (which defaults to `'strict'`).
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Optional projection and validation overrides.
+     * @returns The matched document, or `null` if no document matches.
+     * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOne({ name: 'Ada' })
+     * if (user) console.log(user.role)
+     * ```
+     */
+    findOne(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef> | null>;
+    /**
+     * Find a single document matching the filter, or throw if none exists.
+     *
+     * Behaves identically to {@link findOne} but throws {@link ZodmonNotFoundError}
+     * instead of returning `null` when no document matches the filter.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Optional projection and validation overrides.
+     * @returns The matched document (never null).
+     * @throws {ZodmonNotFoundError} When no document matches the filter.
+     * @throws {ZodmonValidationError} When the fetched document fails schema validation in strict mode.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const user = await users.findOneOrThrow({ name: 'Ada' })
+     * console.log(user.role) // guaranteed non-null
+     * ```
+     */
+    findOneOrThrow(filter: TypedFilter<InferDocument<TDef>>, options?: FindOneOptions): Promise<InferDocument<TDef>>;
+    /**
+     * Find all documents matching the filter, returning a chainable typed cursor.
+     *
+     * The cursor is lazy — no query is executed until a terminal method
+     * (`toArray`, `for await`) is called. Use `sort`, `skip`, and `limit`
+     * to shape the query before executing.
+     *
+     * @param filter - Type-safe filter to match documents.
+     * @param options - Optional validation overrides.
+     * @returns A typed cursor for chaining query modifiers.
+     *
+     * @example
+     * ```ts
+     * const users = db.use(Users)
+     * const admins = await users.find({ role: 'admin' })
+     *   .sort({ name: 1 })
+     *   .limit(10)
+     *   .toArray()
+     * ```
+     */
+    find(filter: TypedFilter<InferDocument<TDef>>, options?: FindOptions): TypedFindCursor<TDef>;
 }
 
 /**
@@ -324,7 +772,7 @@ declare class Database {
      * @param def - A collection definition created by `collection()`.
      * @returns A typed collection handle for CRUD operations.
      */
-    use<TShape extends z.core.$ZodShape>(def: CollectionDefinition<TShape>): CollectionHandle<InferDocument<CollectionDefinition<TShape>>>;
+    use<TShape extends z.core.$ZodShape>(def: CollectionDefinition<TShape>): CollectionHandle<CollectionDefinition<TShape>>;
     /**
      * Synchronize indexes defined in registered collections with MongoDB.
      *
@@ -461,173 +909,145 @@ declare class IndexBuilder<TKeys extends string> {
 declare function index<TKeys extends string>(fields: Record<TKeys, IndexDirection>): IndexBuilder<TKeys>;
 
 /**
- * Create or coerce a MongoDB `ObjectId`.
- *
- * - Called with **no arguments**: generates a brand-new `ObjectId`.
- * - Called with a **hex string**: coerces it to an `ObjectId` via
- *   `ObjectId.createFromHexString`.
- * - Called with an **existing `ObjectId`**: returns it unchanged.
+ * Insert a single document into the collection.
  *
- * This is a convenience wrapper that removes the need for `new ObjectId()`
- * boilerplate throughout application code.
+ * 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 value - Optional hex string or `ObjectId` to coerce. Omit to
- *   generate a new `ObjectId`.
- * @returns An `ObjectId` instance.
+ * @param handle - The collection handle to insert into.
+ * @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
- * oid()                                      // new random ObjectId
- * oid('64f1a2b3c4d5e6f7a8b9c0d1')           // coerce hex string
- * oid(existingId)                            // pass-through
+ * const user = await insertOne(users, { name: 'Ada' })
+ * console.log(user._id) // ObjectId (auto-generated)
+ * console.log(user.role) // 'user' (schema default)
  * ```
  */
-declare function oid(): ObjectId;
-declare function oid(value: string): ObjectId;
-declare function oid(value: ObjectId): ObjectId;
+declare function insertOne<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, doc: InferInsert<TDef>): Promise<InferDocument<TDef>>;
 /**
- * Type guard that narrows an `unknown` value to `ObjectId`.
+ * Insert multiple documents into the collection.
  *
- * Uses `instanceof` internally, so it works with any value without risk
- * of throwing.
+ * 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 value - The value to check.
- * @returns `true` if `value` is an `ObjectId` instance.
+ * @param handle - The collection handle to insert into.
+ * @param docs - The documents to insert.
+ * @returns The inserted documents with `_id` and all defaults applied.
+ * @throws {ZodmonValidationError} When any document fails schema validation.
  *
  * @example
  * ```ts
- * const raw: unknown = getFromDb()
- * if (isOid(raw)) {
- *   console.log(raw.toHexString()) // raw is narrowed to ObjectId
- * }
+ * const users = await insertMany(handle, [
+ *   { name: 'Ada' },
+ *   { name: 'Bob', role: 'admin' },
+ * ])
  * ```
  */
-declare function isOid(value: unknown): value is ObjectId;
+declare function insertMany<TDef extends AnyCollection>(handle: CollectionHandle<TDef>, docs: InferInsert<TDef>[]): Promise<InferDocument<TDef>[]>;
 
 /**
- * Comparison operators for a field value of type `V`.
+ * Thrown when a query expected to find a document returns no results.
  *
- * 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}.
+ * Used by {@link findOneOrThrow} when no document matches the provided filter.
+ * Callers can inspect `.collection` to identify which collection the query targeted.
  *
  * @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 } }
+ * try {
+ *   await users.findOneOrThrow({ name: 'nonexistent' })
+ * } catch (err) {
+ *   if (err instanceof ZodmonNotFoundError) {
+ *     console.log(err.message)    // => 'Document not found in "users"'
+ *     console.log(err.collection) // => 'users'
+ *   }
+ * }
  * ```
  */
-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 class ZodmonNotFoundError extends Error {
+    readonly name = "ZodmonNotFoundError";
+    /** The MongoDB collection name where the query found no results. */
+    readonly collection: string;
+    constructor(collection: string);
+}
+
 /**
- * Generates a union of all valid dot-separated paths for nested object fields in `T`.
+ * Thrown when a document fails Zod schema validation before a MongoDB write.
  *
- * 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.
+ * Wraps the original `ZodError` with the collection name and a human-readable
+ * message listing each invalid field and its error. Callers can inspect
+ * `.zodError.issues` for programmatic access to individual failures.
  *
  * @example
  * ```ts
- * type User = { address: { city: string; geo: { lat: number; lng: number } } }
- *
- * // DotPaths<User> = 'address.city' | 'address.geo' | 'address.geo.lat' | 'address.geo.lng'
+ * try {
+ *   await users.insertOne({ name: 123 })
+ * } catch (err) {
+ *   if (err instanceof ZodmonValidationError) {
+ *     console.log(err.message)
+ *     // => 'Validation failed for "users": name (Expected string, received number)'
+ *     console.log(err.collection) // => 'users'
+ *     console.log(err.zodError)   // => ZodError with .issues array
+ *   }
+ * }
  * ```
  */
-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];
+declare class ZodmonValidationError extends Error {
+    readonly name = "ZodmonValidationError";
+    /** The MongoDB collection name where the validation failed. */
+    readonly collection: string;
+    /** The original Zod validation error with detailed issue information. */
+    readonly zodError: z.ZodError;
+    constructor(collection: string, zodError: z.ZodError);
+}
+
 /**
- * Resolves the value type at a dot-separated path `P` within type `T`.
+ * Create or coerce a MongoDB `ObjectId`.
  *
- * Splits `P` on the first `.` and recursively descends into `T`'s nested types.
- * Returns `never` if the path is invalid.
+ * - Called with **no arguments**: generates a brand-new `ObjectId`.
+ * - Called with a **hex string**: coerces it to an `ObjectId` via
+ *   `ObjectId.createFromHexString`.
+ * - Called with an **existing `ObjectId`**: returns it unchanged.
+ *
+ * This is a convenience wrapper that removes the need for `new ObjectId()`
+ * boilerplate throughout application code.
+ *
+ * @param value - Optional hex string or `ObjectId` to coerce. Omit to
+ *   generate a new `ObjectId`.
+ * @returns An `ObjectId` instance.
  *
  * @example
  * ```ts
- * type User = { address: { city: string; geo: { lat: number } } }
- *
- * // DotPathType<User, 'address.city'> = string
- * // DotPathType<User, 'address.geo.lat'> = number
+ * oid()                                      // new random ObjectId
+ * oid('64f1a2b3c4d5e6f7a8b9c0d1')           // coerce hex string
+ * oid(existingId)                            // pass-through
  * ```
  */
-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;
+declare function oid(): ObjectId;
+declare function oid(value: string): ObjectId;
+declare function oid(value: ObjectId): ObjectId;
 /**
- * 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`.
+ * Type guard that narrows an `unknown` value to `ObjectId`.
  *
- * 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' }`
+ * Uses `instanceof` internally, so it works with any value without risk
+ * of throwing.
  *
- * Logical operators `$and`, `$or`, and `$nor` accept arrays of `TypedFilter<T>`
- * for composing complex queries.
+ * @param value - The value to check.
+ * @returns `true` if `value` is an `ObjectId` instance.
  *
  * @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
- * const filter = $and<User>(
- *   $or<User>({ role: 'admin' }, { role: 'moderator' }),
- *   { age: $gte(18) },
- *   { email: $exists() },
- * )
- *
- * // 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) : {}
+ * const raw: unknown = getFromDb()
+ * if (isOid(raw)) {
+ *   console.log(raw.toHexString()) // raw is narrowed to ObjectId
+ * }
  * ```
  */
-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>[];
-};
+declare function isOid(value: unknown): value is ObjectId;
 
 /**
  * Matches values equal to the specified value.
@@ -901,4 +1321,4 @@ declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
  */
 declare function installRefExtension(): void;
 
-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, IndexBuilder, type IndexMetadata, type IndexOptions, type InferDocument, type RefMarker, type RefMetadata, type ResolvedShape, type TypedFilter, type ZodObjectId, collection, createClient, extractDbName, extractFieldIndexes, getIndexMetadata, getRefMetadata, index, installExtensions, installRefExtension, isOid, objectId, oid, raw };
+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 };