@zodmon/core 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ObjectId, Collection, MongoClientOptions } from 'mongodb';
+import { ObjectId, FindCursor, Collection, MongoClientOptions } from 'mongodb';
 import { ZodPipe, ZodCustom, ZodTransform, z, ZodDefault } from 'zod';
 
 /**
@@ -290,6 +290,124 @@ 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`.
  *
@@ -388,12 +506,11 @@ type DotPathType<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K
  * // 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() },
- * )
+ * // Logical composition — T inferred from find() context
+ * posts.find($and(
+ *   $or({ published: true }, { views: $gte(100) }),
+ *   { title: $regex(/guide/i) },
+ * ))
  *
  * // Dynamic conditional building
  * const conditions: TypedFilter<User>[] = []
@@ -464,6 +581,44 @@ declare function findOne<TDef extends AnyCollection>(handle: CollectionHandle<TD
  * ```
  */
 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`.
@@ -561,6 +716,27 @@ declare class CollectionHandle<TDef extends AnyCollection = AnyCollection> {
      * ```
      */
     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>;
 }
 
 /**
@@ -678,6 +854,8 @@ declare function extractFieldIndexes(shape: z.core.$ZodShape): FieldIndexDefinit
  */
 declare function collection<TShape extends z.core.$ZodShape>(name: string, shape: TShape, options?: CollectionOptions<Extract<keyof TShape, string>>): CollectionDefinition<TShape>;
 
+type IndexDirection = 1 | -1;
+type CompoundIndexOptions = NonNullable<CompoundIndexDefinition['options']>;
 /**
  * A builder for compound index definitions.
  *
@@ -697,9 +875,6 @@ declare function collection<TShape extends z.core.$ZodShape>(name: string, shape
  * index({ email: 1, role: -1 }).unique().name('email_role_idx')
  * ```
  */
-
-type IndexDirection = 1 | -1;
-type CompoundIndexOptions = NonNullable<CompoundIndexDefinition['options']>;
 declare class IndexBuilder<TKeys extends string> {
     readonly fields: Partial<Record<TKeys, IndexDirection>>;
     readonly options: CompoundIndexOptions;
@@ -1012,16 +1187,14 @@ declare const $not: <O extends Record<string, unknown>>(op: O) => {
  *
  * @example
  * ```ts
+ * // T inferred from collection's find() context
  * users.find($or({ role: 'admin' }, { age: $gte(18) }))
  *
- * // Dynamic composition
- * const conditions: TypedFilter<User>[] = []
- * if (name) conditions.push({ name })
- * if (role) conditions.push({ role })
- * users.find($or(...conditions))
+ * // Explicit generic for standalone usage
+ * const filter = $or<User>({ role: 'admin' }, { age: $gte(18) })
  * ```
  */
-declare const $or: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+declare const $or: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
 /**
  * Joins filter clauses with a logical AND. Matches documents that satisfy
  * all of the provided filters. Useful for dynamic filter building where
@@ -1029,6 +1202,7 @@ declare const $or: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
  *
  * @example
  * ```ts
+ * // T inferred from collection's find() context
  * users.find($and(
  *   $or({ role: 'admin' }, { role: 'moderator' }),
  *   { age: $gte(18) },
@@ -1036,7 +1210,7 @@ declare const $or: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
  * ))
  * ```
  */
-declare const $and: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+declare const $and: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
 /**
  * Joins filter clauses with a logical NOR. Matches documents that fail
  * all of the provided filters.
@@ -1047,7 +1221,7 @@ declare const $and: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
  * users.find($nor({ role: 'banned' }, { role: 'suspended' }))
  * ```
  */
-declare const $nor: <T>(...filters: TypedFilter<T>[]) => TypedFilter<T>;
+declare const $nor: <T>(...filters: NoInfer<TypedFilter<T>>[]) => TypedFilter<T>;
 /**
  * Escape hatch for unsupported or raw MongoDB filter operators.
  * Wraps an untyped filter object so it can be passed where `TypedFilter<T>` is expected.
@@ -1060,6 +1234,219 @@ declare const $nor: <T>(...filters: 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
@@ -1144,4 +1531,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, type FindOneOptions, IndexBuilder, type IndexMetadata, type IndexOptions, type InferDocument, type InferInsert, type RefMarker, type RefMetadata, type ResolvedShape, type TypedFilter, type ValidationMode, type ZodObjectId, ZodmonNotFoundError, ZodmonValidationError, collection, createClient, extractDbName, extractFieldIndexes, 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, 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 };