@zodmon/core 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,12 +1,904 @@
-import { ObjectId } from 'mongodb';
-import { ZodPipe, ZodCustom, ZodTransform } from 'zod';
+import { ObjectId, Document, Collection, MongoClientOptions } from 'mongodb';
+import { ZodPipe, ZodCustom, ZodTransform, z } from 'zod';
 
+/**
+ * Options controlling how a field-level MongoDB index is created.
+ *
+ * Passed to the `.index()` Zod extension method. Every property is optional;
+ * omitting all of them creates a standard ascending, non-unique index.
+ */
+type IndexOptions = {
+    /** When `true`, MongoDB enforces a unique constraint on this field. */
+    unique?: boolean;
+    /**
+     * When `true`, the index skips documents where the field is `null` or missing.
+     * Useful for optional fields that should be indexed only when present.
+     */
+    sparse?: boolean;
+    /** When `true`, creates a MongoDB text index for full-text search on this field. */
+    text?: boolean;
+    /**
+     * When `true`, the index is created in descending order (`-1`).
+     * Defaults to ascending (`1`) when omitted.
+     */
+    descending?: boolean;
+    /**
+     * TTL in seconds. MongoDB will automatically delete documents once the
+     * indexed `Date` field is older than this many seconds. Only valid on
+     * fields whose runtime type is `Date`.
+     */
+    expireAfter?: number;
+    /**
+     * A partial filter expression. Only documents matching this filter are
+     * included in the index. Maps directly to MongoDB's `partialFilterExpression`.
+     */
+    partial?: Record<string, unknown>;
+};
+/**
+ * Metadata stored in the WeakMap sidecar for every schema that has been
+ * marked with `.index()`. Always contains `indexed: true` plus any
+ * {@link IndexOptions} the caller provided.
+ */
+type IndexMetadata = {
+    /** Always `true` — acts as a discriminator for "this field is indexed". */
+    indexed: true;
+} & IndexOptions;
+declare module 'zod' {
+    interface ZodType {
+        /**
+         * Mark this field for indexing when `syncIndexes()` is called.
+         *
+         * Stores {@link IndexOptions} in a WeakMap sidecar so the collection
+         * factory can later introspect each field and build the appropriate
+         * MongoDB index specification.
+         *
+         * @param options - Optional index configuration (unique, sparse, etc.).
+         * @returns The same schema instance for chaining.
+         *
+         * @example
+         * ```ts
+         * const UserSchema = z.object({
+         *   email: z.string().index({ unique: true }),
+         *   age: z.number().index({ sparse: true }),
+         * })
+         * ```
+         */
+        index(options?: IndexOptions): this;
+        /**
+         * Shorthand for `.index({ unique: true })`.
+         *
+         * Creates a unique index on this field, causing MongoDB to reject
+         * duplicate values.
+         *
+         * @returns The same schema instance for chaining.
+         *
+         * @example
+         * ```ts
+         * const UserSchema = z.object({
+         *   email: z.string().unique(),
+         * })
+         * ```
+         */
+        unique(): this;
+        /**
+         * Shorthand for `.index({ text: true })`.
+         *
+         * Creates a MongoDB text index on this field, enabling `$text` queries
+         * for full-text search.
+         *
+         * @returns The same schema instance for chaining.
+         *
+         * @example
+         * ```ts
+         * const PostSchema = z.object({
+         *   body: z.string().text(),
+         * })
+         * ```
+         */
+        text(): this;
+        /**
+         * Shorthand for `.index({ expireAfter: seconds })`.
+         *
+         * Creates a TTL (Time-To-Live) index. MongoDB will automatically
+         * remove documents once the indexed `Date` field is older than
+         * the specified number of seconds.
+         *
+         * @param seconds - Number of seconds after which documents expire.
+         * @returns The same schema instance for chaining.
+         *
+         * @example
+         * ```ts
+         * const SessionSchema = z.object({
+         *   createdAt: z.date().expireAfter(3600), // 1 hour TTL
+         * })
+         * ```
+         */
+        expireAfter(seconds: number): this;
+    }
+}
+/**
+ * Retrieve the index metadata attached to a Zod schema, if any.
+ *
+ * Returns `undefined` when the schema was never marked with an index
+ * extension (`.index()`, `.unique()`, `.text()`, or `.expireAfter()`).
+ *
+ * @param schema - The Zod schema to inspect. Accepts `unknown` for
+ *   convenience; non-object values safely return `undefined`.
+ * @returns The {@link IndexMetadata} for the schema, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * const email = z.string().index({ unique: true })
+ * const meta = getIndexMetadata(email)
+ * // => { indexed: true, unique: true }
+ * ```
+ */
+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
+ * input as either a `string` (24-char hex) or an `ObjectId` instance, then
+ * transforms it into a concrete `ObjectId`.
+ *
+ * Use `z.infer<ZodObjectId>` to extract the output type (`ObjectId`) and
+ * `z.input<ZodObjectId>` for the input type (`string | ObjectId`).
+ */
+type ZodObjectId = ZodPipe<ZodCustom<string | ObjectId, string | ObjectId>, ZodTransform<ObjectId, string | ObjectId>>;
+/**
+ * Create a Zod schema that validates and coerces values into MongoDB
+ * `ObjectId` instances.
+ *
+ * Accepts either:
+ * - An existing `ObjectId` instance (passed through unchanged).
+ * - A 24-character hexadecimal string (coerced to `ObjectId`).
+ *
+ * All other inputs are rejected with the message `"Invalid ObjectId"`.
+ *
+ * @returns A {@link ZodObjectId} schema.
+ *
+ * @example
+ * ```ts
+ * const schema = objectId()
+ *
+ * schema.parse(new ObjectId())                     // OK — pass-through
+ * schema.parse('64f1a2b3c4d5e6f7a8b9c0d1')        // OK — coerced to ObjectId
+ * schema.parse('not-valid')                        // throws ZodError
+ * ```
+ *
+ * @example Inside a z.object() shape:
+ * ```ts
+ * const UserSchema = z.object({
+ *   _id: objectId(),
+ *   name: z.string(),
+ * })
+ * ```
+ */
+declare function objectId(): ZodObjectId;
+
+/**
+ * A compound index definition declared at the collection level.
+ * Maps field paths to sort direction (1 ascending, -1 descending)
+ * with optional index-level configuration.
+ *
+ * Generic over `TKeys` so that only fields present in the collection
+ * schema are accepted — referencing a nonexistent field is a type error.
+ */
+type CompoundIndexDefinition<TKeys extends string = string> = {
+    fields: Partial<Record<TKeys, 1 | -1>>;
+    options?: {
+        unique?: boolean;
+        sparse?: boolean;
+        partial?: Record<string, unknown>;
+        name?: string;
+    };
+};
+/**
+ * A resolved field-level index extracted from schema metadata.
+ * Produced by walking the shape and calling getIndexMetadata() on each field.
+ */
+type FieldIndexDefinition = {
+    field: string;
+} & IndexOptions;
+/** Options passed to collection() as the third argument. */
+type CollectionOptions<TKeys extends string = string> = {
+    indexes?: CompoundIndexDefinition<TKeys>[];
+    validation?: 'strict' | 'strip' | 'passthrough';
+    warnUnindexedQueries?: boolean;
+    schemaVersion?: number;
+    migrate?: (doc: Record<string, unknown>, version: number) => Record<string, unknown>;
+    writeback?: boolean;
+};
+/**
+ * Resolves the final shape for a collection schema.
+ *
+ * If the user-provided shape already contains `_id`, it is used as-is.
+ * Otherwise, `_id: ZodObjectId` is prepended automatically.
+ * This allows custom id types (nanoid, UUID, etc.) when needed.
+ */
+type ResolvedShape<TShape extends z.core.$ZodShape> = '_id' extends keyof TShape ? TShape : {
+    _id: ZodObjectId;
+} & TShape;
+/**
+ * The document type inferred from a collection definition.
+ * Uses the compiled schema directly, so it reflects whatever `_id`
+ * type was provided (custom or default ObjectId).
+ *
+ * Uses a structural constraint (`{ schema: z.ZodType }`) instead of
+ * `CollectionDefinition<z.core.$ZodShape>` because the conditional
+ * `ResolvedShape` type creates variance issues with index signatures.
+ */
+type InferDocument<TDef extends {
+    readonly schema: z.ZodType;
+}> = z.infer<TDef['schema']>;
+/**
+ * The immutable definition object returned by collection().
+ * Holds everything needed to later create a live collection handle.
+ */
+type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape> = {
+    readonly name: string;
+    readonly schema: z.ZodObject<ResolvedShape<TShape>>;
+    readonly shape: TShape;
+    readonly fieldIndexes: FieldIndexDefinition[];
+    readonly compoundIndexes: CompoundIndexDefinition<Extract<keyof TShape, string>>[];
+    readonly options: Required<Pick<CollectionOptions, 'validation'>> & Omit<CollectionOptions, 'indexes' | 'validation'>;
+};
+/** Erased collection type for use in generic contexts. */
+type AnyCollection = CollectionDefinition<z.core.$ZodShape>;
+
+/**
+ * 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.
+ *
+ * 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`.
+ */
+declare class CollectionHandle<TDoc extends Document = Document> {
+    /** 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>);
+}
+
+/**
+ * Wraps a MongoDB `MongoClient` and `Db`, providing typed collection access
+ * through {@link CollectionHandle}s.
+ *
+ * Connection is lazy — the driver connects on the first operation, not at
+ * construction time. Call {@link close} for graceful shutdown.
+ *
+ * @example
+ * ```ts
+ * const db = createClient('mongodb://localhost:27017', 'myapp')
+ * const users = db.use(UsersCollection)
+ * await users.native.insertOne({ _id: oid(), name: 'Ada' })
+ * await db.close()
+ * ```
+ */
+declare class Database {
+    private readonly _client;
+    private readonly _db;
+    /** Registered collection definitions, keyed by name. Used by syncIndexes(). */
+    private readonly _collections;
+    constructor(uri: string, dbName: string, options?: MongoClientOptions);
+    /**
+     * Register a collection definition and return a typed {@link CollectionHandle}.
+     *
+     * The handle's `native` property is a MongoDB `Collection<TDoc>` where `TDoc`
+     * is the document type inferred from the definition's Zod schema. Calling
+     * `use()` multiple times with the same definition is safe — each call returns
+     * a new lightweight handle backed by the same underlying driver collection.
+     *
+     * @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>>>;
+    /**
+     * Synchronize indexes defined in registered collections with MongoDB.
+     *
+     * Stub — full implementation in TASK-92.
+     */
+    syncIndexes(): Promise<void>;
+    /**
+     * Execute a function within a MongoDB transaction with auto-commit/rollback.
+     *
+     * Stub — full implementation in TASK-106.
+     */
+    transaction<T>(_fn: () => Promise<T>): Promise<T>;
+    /**
+     * Close the underlying `MongoClient` connection. Safe to call even if
+     * no connection was established (the driver handles this gracefully).
+     */
+    close(): Promise<void>;
+}
+/**
+ * Extract the database name from a MongoDB connection URI.
+ *
+ * Handles standard URIs, multi-host/replica set, SRV (`mongodb+srv://`),
+ * auth credentials, query parameters, and percent-encoded database names.
+ * Returns `undefined` when no database name is present.
+ */
+declare function extractDbName(uri: string): string | undefined;
+/**
+ * Create a new {@link Database} instance wrapping a MongoDB connection.
+ *
+ * The connection is lazy — the driver connects on the first operation.
+ * Pass any `MongoClientOptions` to configure connection pooling, timeouts, etc.
+ *
+ * When `dbName` is omitted, the database name is extracted from the URI path
+ * (e.g. `mongodb://localhost:27017/myapp` → `'myapp'`). If no database name
+ * is found in either the arguments or the URI, a warning is logged and
+ * MongoDB's default `'test'` database is used.
+ *
+ * @param uri - MongoDB connection string (e.g. `mongodb://localhost:27017`).
+ * @param dbName - The database name to use.
+ * @param options - Optional MongoDB driver client options.
+ * @returns A new `Database` instance.
+ */
+declare function createClient(uri: string, dbName: string, options?: MongoClientOptions): Database;
+declare function createClient(uri: string, options?: MongoClientOptions): Database;
+
+/**
+ * Walk a Zod shape and extract field-level index metadata from each field.
+ *
+ * Returns an array of {@link FieldIndexDefinition} for every field that has
+ * been marked with `.index()`, `.unique()`, `.text()`, or `.expireAfter()`.
+ * Fields without index metadata are silently skipped.
+ *
+ * @param shape - A Zod shape object (the value passed to `z.object()`).
+ * @returns An array of field index definitions with the field name attached.
+ */
+declare function extractFieldIndexes(shape: z.core.$ZodShape): FieldIndexDefinition[];
+/**
+ * Define a MongoDB collection with a Zod schema.
+ *
+ * Creates a {@link CollectionDefinition} that:
+ * - Adds `_id: objectId()` if the shape doesn't already include `_id`
+ * - Uses the user-provided `_id` schema if one is present (e.g. nanoid, UUID)
+ * - Extracts field-level index metadata from the shape
+ * - Separates compound indexes from the rest of the options
+ * - Returns an immutable definition object
+ *
+ * @param name - The MongoDB collection name.
+ * @param shape - A Zod shape object defining the document fields. May include a custom `_id`.
+ * @param options - Optional collection-level configuration including compound indexes.
+ * @returns A {@link CollectionDefinition} ready for use with `createClient()`.
+ *
+ * @example
+ * ```ts
+ * const Users = collection('users', {
+ *   email: z.string().unique(),
+ *   name: z.string().index(),
+ *   age: z.number().optional(),
+ * })
+ * ```
+ */
+declare function collection<TShape extends z.core.$ZodShape>(name: string, shape: TShape, options?: CollectionOptions<Extract<keyof TShape, string>>): CollectionDefinition<TShape>;
+
+/**
+ * A builder for compound index definitions.
+ *
+ * Provides a fluent API for declaring compound indexes with options like
+ * `unique`, `sparse`, and custom `name`. Each method returns a new
+ * IndexBuilder instance (immutable pattern — the original is never mutated).
+ *
+ * IndexBuilder is structurally compatible with {@link CompoundIndexDefinition}
+ * so instances can be used directly in `CollectionOptions.indexes`.
+ *
+ * Dot-notation paths like `'address.city'` are accepted at the value level
+ * (any string satisfies `TKeys`), but type-level validation against nested
+ * schema paths is deferred to a future release.
+ *
+ * @example
+ * ```ts
+ * index({ email: 1, role: -1 }).unique().name('email_role_idx')
+ * ```
+ */
+
+type IndexDirection = 1 | -1;
+type CompoundIndexOptions = NonNullable<CompoundIndexDefinition['options']>;
+declare class IndexBuilder<TKeys extends string> {
+    readonly fields: Partial<Record<TKeys, IndexDirection>>;
+    readonly options: CompoundIndexOptions;
+    constructor(fields: Record<TKeys, IndexDirection>);
+    private _clone;
+    unique(): IndexBuilder<TKeys>;
+    sparse(): IndexBuilder<TKeys>;
+    name(name: string): IndexBuilder<TKeys>;
+}
+/**
+ * Create a compound index definition with a fluent builder API.
+ *
+ * Returns an {@link IndexBuilder} that is structurally compatible with
+ * `CompoundIndexDefinition`, so it can be used directly in
+ * `CollectionOptions.indexes` alongside plain objects.
+ *
+ * @param fields - An object mapping field names to sort direction (1 or -1).
+ * @returns An {@link IndexBuilder} instance.
+ *
+ * @example
+ * ```ts
+ * collection('users', { email: z.string(), role: z.string() }, {
+ *   indexes: [
+ *     index({ email: 1, role: -1 }).unique(),
+ *     { fields: { role: 1 } },
+ *   ],
+ * })
+ * ```
+ */
+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.
+ *
+ * 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
+ * oid()                                      // new random ObjectId
+ * oid('64f1a2b3c4d5e6f7a8b9c0d1')           // coerce hex string
+ * oid(existingId)                            // pass-through
+ * ```
+ */
 declare function oid(): ObjectId;
 declare function oid(value: string): ObjectId;
 declare function oid(value: ObjectId): ObjectId;
+/**
+ * Type guard that narrows an `unknown` value to `ObjectId`.
+ *
+ * Uses `instanceof` internally, so it works with any value without risk
+ * of throwing.
+ *
+ * @param value - The value to check.
+ * @returns `true` if `value` is an `ObjectId` instance.
+ *
+ * @example
+ * ```ts
+ * const raw: unknown = getFromDb()
+ * if (isOid(raw)) {
+ *   console.log(raw.toHexString()) // raw is narrowed to ObjectId
+ * }
+ * ```
+ */
 declare function isOid(value: unknown): value is ObjectId;
 
-type ZodObjectId = ZodPipe<ZodCustom<string | ObjectId, string | ObjectId>, ZodTransform<ObjectId, string | ObjectId>>;
-declare function objectId(): ZodObjectId;
+/**
+ * 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>[];
+};
+
+/**
+ * Matches values equal to the specified value.
+ *
+ * @example
+ * ```ts
+ * // Explicit equality (equivalent to { name: 'Alice' })
+ * users.find({ name: $eq('Alice') })
+ * ```
+ */
+declare const $eq: <V>(value: V) => {
+    $eq: V;
+};
+/**
+ * Matches values not equal to the specified value.
+ *
+ * @example
+ * ```ts
+ * users.find({ role: $ne('banned') })
+ * ```
+ */
+declare const $ne: <V>(value: V) => {
+    $ne: V;
+};
+/**
+ * Matches values greater than the specified value.
+ *
+ * @example
+ * ```ts
+ * users.find({ age: $gt(18) })
+ * ```
+ */
+declare const $gt: <V>(value: V) => {
+    $gt: V;
+};
+/**
+ * Matches values greater than or equal to the specified value.
+ *
+ * @example
+ * ```ts
+ * users.find({ age: $gte(18) })
+ * ```
+ */
+declare const $gte: <V>(value: V) => {
+    $gte: V;
+};
+/**
+ * Matches values less than the specified value.
+ *
+ * @example
+ * ```ts
+ * users.find({ age: $lt(65) })
+ * ```
+ */
+declare const $lt: <V>(value: V) => {
+    $lt: V;
+};
+/**
+ * Matches values less than or equal to the specified value.
+ *
+ * @example
+ * ```ts
+ * users.find({ age: $lte(65) })
+ * ```
+ */
+declare const $lte: <V>(value: V) => {
+    $lte: V;
+};
+/**
+ * Matches any value in the specified array.
+ *
+ * @example
+ * ```ts
+ * users.find({ role: $in(['admin', 'moderator']) })
+ * ```
+ */
+declare const $in: <V>(values: V[]) => {
+    $in: V[];
+};
+/**
+ * Matches none of the values in the specified array.
+ *
+ * @example
+ * ```ts
+ * users.find({ role: $nin(['banned', 'suspended']) })
+ * ```
+ */
+declare const $nin: <V>(values: V[]) => {
+    $nin: V[];
+};
+/**
+ * Matches documents where the field exists (or does not exist).
+ * Defaults to `true` when called with no arguments.
+ *
+ * @example
+ * ```ts
+ * // Field must exist
+ * users.find({ email: $exists() })
+ *
+ * // Field must not exist
+ * users.find({ deletedAt: $exists(false) })
+ * ```
+ */
+declare const $exists: (flag?: boolean) => {
+    $exists: boolean;
+};
+/**
+ * Matches string values against a regular expression pattern.
+ * Only valid on string fields.
+ *
+ * @example
+ * ```ts
+ * users.find({ name: $regex(/^A/i) })
+ * users.find({ email: $regex('^admin@') })
+ * ```
+ */
+declare const $regex: (pattern: RegExp | string) => {
+    $regex: RegExp | string;
+};
+/**
+ * Negates a comparison operator. Wraps the given operator object
+ * in a `$not` condition.
+ *
+ * @example
+ * ```ts
+ * // Age is NOT greater than 65
+ * users.find({ age: $not($gt(65)) })
+ *
+ * // Name does NOT match pattern
+ * users.find({ name: $not($regex(/^test/)) })
+ * ```
+ */
+declare const $not: <O extends Record<string, unknown>>(op: O) => {
+    $not: O;
+};
+/**
+ * Joins filter clauses with a logical OR. Matches documents that satisfy
+ * at least one of the provided filters.
+ *
+ * @example
+ * ```ts
+ * users.find($or({ role: 'admin' }, { age: $gte(18) }))
+ *
+ * // Dynamic composition
+ * const conditions: TypedFilter<User>[] = []
+ * if (name) conditions.push({ name })
+ * if (role) conditions.push({ role })
+ * users.find($or(...conditions))
+ * ```
+ */
+declare const $or: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+/**
+ * Joins filter clauses with a logical AND. Matches documents that satisfy
+ * all of the provided filters. Useful for dynamic filter building where
+ * multiple conditions on the same field would conflict in an object literal.
+ *
+ * @example
+ * ```ts
+ * users.find($and(
+ *   $or({ role: 'admin' }, { role: 'moderator' }),
+ *   { age: $gte(18) },
+ *   { email: $exists() },
+ * ))
+ * ```
+ */
+declare const $and: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+/**
+ * Joins filter clauses with a logical NOR. Matches documents that fail
+ * all of the provided filters.
+ *
+ * @example
+ * ```ts
+ * // Exclude banned and suspended users
+ * users.find($nor({ role: 'banned' }, { role: 'suspended' }))
+ * ```
+ */
+declare const $nor: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+/**
+ * Escape hatch for unsupported or raw MongoDB filter operators.
+ * Wraps an untyped filter object so it can be passed where `TypedFilter<T>` is expected.
+ * Use when you need operators not covered by the type system (e.g., `$text`, `$geoNear`).
+ *
+ * @example
+ * ```ts
+ * users.find(raw({ $text: { $search: 'mongodb tutorial' } }))
+ * ```
+ */
+declare const raw: <T = any>(filter: Record<string, unknown>) => TypedFilter<T>;
+
+/**
+ * Type-level marker that carries the target collection type through the
+ * type system. Intersected with the schema return type by `.ref()` so
+ * that `RefFields<T>` (future) can extract ref relationships.
+ *
+ * This is a phantom brand — no runtime value has this property.
+ */
+type RefMarker<TCollection extends AnyCollection = AnyCollection> = {
+    readonly _ref: TCollection;
+};
+/**
+ * Metadata stored in the WeakMap sidecar for schemas marked with `.ref()`.
+ * Holds a reference to the target collection definition object.
+ */
+type RefMetadata = {
+    readonly collection: AnyCollection;
+};
+/**
+ * Module augmentation: adds `.ref()` to all `ZodType` schemas.
+ *
+ * The intersection constraint `this['_zod']['output'] extends InferDocument<TCollection>['_id']`
+ * ensures compile-time type safety: the field's output type must match the
+ * target collection's `_id` type. Mismatches produce a type error.
+ *
+ * Supports both default ObjectId `_id` and custom `_id` types (string, nanoid, etc.):
+ * - `objectId().ref(Users)` compiles when Users has ObjectId `_id`
+ * - `z.string().ref(Orgs)` compiles when Orgs has string `_id`
+ * - `z.string().ref(Users)` is a type error (string ≠ ObjectId)
+ * - `objectId().ref(Orgs)` is a type error (ObjectId ≠ string)
+ */
+declare module 'zod' {
+    interface ZodType {
+        /**
+         * Declare a typed foreign key reference to another collection.
+         *
+         * Stores the target collection definition in metadata for runtime
+         * populate resolution, and brands the return type with
+         * `RefMarker<TCollection>` so `RefFields<T>` can extract refs
+         * at the type level.
+         *
+         * The field's output type must match the target collection's `_id` type.
+         * Mismatched types produce a compile error.
+         *
+         * Apply `.ref()` before wrapper methods like `.optional()` or `.nullable()`:
+         * `objectId().ref(Users).optional()` — not `objectId().optional().ref(Users)`.
+         *
+         * @param collection - The target collection definition object.
+         * @returns The same schema instance, branded with the ref marker.
+         *
+         * @example
+         * ```ts
+         * const Posts = collection('posts', {
+         *   authorId: objectId().ref(Users),
+         *   title: z.string(),
+         * })
+         * ```
+         */
+        ref<TCollection extends AnyCollection>(collection: TCollection & (this['_zod']['output'] extends InferDocument<TCollection>['_id'] ? unknown : never)): this & RefMarker<TCollection>;
+    }
+}
+/**
+ * Retrieve the ref metadata attached to a Zod schema, if any.
+ *
+ * Returns `undefined` when the schema was never marked with `.ref()`.
+ *
+ * @param schema - The Zod schema to inspect. Accepts `unknown` for
+ *   convenience; non-object values safely return `undefined`.
+ * @returns The {@link RefMetadata} for the schema, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * const authorId = objectId().ref(Users)
+ * const meta = getRefMetadata(authorId)
+ * // => { collection: Users }
+ * ```
+ */
+declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
+/**
+ * Install the `.ref()` extension method on `ZodType.prototype`.
+ *
+ * Idempotent — safe to call multiple times.
+ */
+declare function installRefExtension(): void;
 
-export { type ZodObjectId, isOid, objectId, oid };
+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 };