@zodmon/core 0.2.0 → 0.3.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 } from 'mongodb';
 
 /**
  * Options controlling how a field-level MongoDB index is created.
@@ -271,6 +271,105 @@ type CollectionDefinition<TShape extends z.core.$ZodShape = z.core.$ZodShape> =
 /** 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.
  *
@@ -405,6 +504,319 @@ declare function oid(value: ObjectId): ObjectId;
  */
 declare function isOid(value: unknown): value is ObjectId;
 
+/**
+ * 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
@@ -489,4 +901,4 @@ declare function getRefMetadata(schema: unknown): RefMetadata | undefined;
  */
 declare function installRefExtension(): void;
 
-export { type AnyCollection, type CollectionDefinition, type CollectionOptions, type CompoundIndexDefinition, type FieldIndexDefinition, IndexBuilder, type IndexMetadata, type IndexOptions, type InferDocument, type RefMarker, type RefMetadata, type ResolvedShape, type ZodObjectId, collection, extractFieldIndexes, getIndexMetadata, getRefMetadata, index, installExtensions, installRefExtension, 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 };