mondel 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,888 @@
+import * as mongodb from 'mongodb';
+import { AggregateOptions, Document, FindOptions as FindOptions$1, Sort, InsertOneOptions, BulkWriteOptions, UpdateOptions as UpdateOptions$1, DeleteOptions as DeleteOptions$1, CountDocumentsOptions, ObjectId, Filter, MongoClientOptions, Db, ClientSessionOptions, ClientSession, WithId, OptionalUnlessRequiredId, InsertOneResult, InsertManyResult, UpdateResult, DeleteResult, Collection } from 'mongodb';
+export { ClientSession, ObjectId } from 'mongodb';
+import { z, ZodTypeAny } from 'zod';
+
+type FieldType = "string" | "number" | "boolean" | "date" | "objectId" | "array" | "object" | "json" | "literal";
+interface IndexOptions {
+    type?: 1 | -1 | "text" | "2dsphere" | "2d";
+    name?: string;
+    unique?: boolean;
+    sparse?: boolean;
+    expireAfterSeconds?: number;
+    partialFilterExpression?: Document;
+}
+interface CompoundIndexDefinition {
+    fields: Record<string, 1 | -1 | "text" | "2dsphere" | "2d">;
+    options?: {
+        name?: string;
+        unique?: boolean;
+        sparse?: boolean;
+        partialFilterExpression?: Document;
+        weights?: Record<string, number>;
+    };
+}
+interface FieldDefinition<T = unknown> {
+    type: FieldType;
+    required: boolean;
+    unique: boolean;
+    default?: T | "auto";
+    index?: IndexOptions;
+    enum?: readonly string[];
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    email?: boolean;
+    url?: boolean;
+    items?: FieldDefinition;
+    properties?: Record<string, FieldDefinition>;
+    literal?: string | number | boolean;
+}
+interface TimestampConfig {
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface ValidationConfig {
+    enabled?: boolean;
+    mode?: "strict" | "loose" | "off";
+}
+interface SchemaDefinition<TFields extends Record<string, FieldDefinition> = Record<string, FieldDefinition>> {
+    collection?: string;
+    timestamps?: boolean | TimestampConfig;
+    validation?: ValidationConfig;
+    connection?: string;
+    fields: TFields;
+    indexes?: CompoundIndexDefinition[];
+}
+interface Schema<TName extends string = string, TFields extends Record<string, FieldDefinition> = Record<string, FieldDefinition>> {
+    name: TName;
+    collection: string;
+    timestamps: TimestampConfig | false;
+    validation: ValidationConfig;
+    connection?: string;
+    fields: TFields;
+    indexes: CompoundIndexDefinition[];
+}
+type ValidationMode = "strict" | "loose" | "off";
+type InferFieldType<T extends FieldDefinition> = T extends {
+    type: "string";
+} ? T extends {
+    enum: readonly (infer E)[];
+} ? E : string : T extends {
+    type: "number";
+} ? number : T extends {
+    type: "boolean";
+} ? boolean : T extends {
+    type: "date";
+} ? Date : T extends {
+    type: "objectId";
+} ? ObjectId : T extends {
+    type: "array";
+    items: infer I extends FieldDefinition;
+} ? InferFieldType<I>[] : T extends {
+    type: "object";
+    properties: infer P extends Record<string, FieldDefinition>;
+} ? {
+    [K in keyof P]: InferFieldType<P[K]>;
+} : T extends {
+    type: "json";
+} ? unknown : T extends {
+    type: "literal";
+    literal: infer L;
+} ? L : unknown;
+type InferBuilderValue<T> = T extends {
+    build(): FieldDefinition<infer V>;
+} ? V : unknown;
+type TimestampFields<T extends Schema> = T["timestamps"] extends false ? never : T["timestamps"] extends {
+    createdAt?: infer C;
+    updatedAt?: infer U;
+} ? (C extends string ? C : "createdAt") | (U extends string ? U : "updatedAt") : "createdAt" | "updatedAt";
+type TimestampFieldsType<T extends Schema> = T["timestamps"] extends false ? object : T["timestamps"] extends {
+    createdAt?: infer C;
+    updatedAt?: infer U;
+} ? {
+    [K in C extends string ? C : "createdAt"]?: Date;
+} & {
+    [K in U extends string ? U : "updatedAt"]?: Date;
+} : {
+    createdAt?: Date;
+    updatedAt?: Date;
+};
+type InferSchemaType<T extends Schema> = {
+    _id: ObjectId;
+} & (T extends {
+    __fields: infer TFields;
+} ? {
+    [K in keyof TFields]?: InferBuilderValue<TFields[K]>;
+} : {
+    [K in keyof T["fields"]]?: InferFieldType<T["fields"][K]>;
+}) & TimestampFieldsType<T>;
+type CreateInput<T extends Schema> = Omit<InferSchemaType<T>, "_id" | TimestampFields<T>>;
+type UpdateInput<T extends Schema> = Partial<Omit<InferSchemaType<T>, "_id" | TimestampFields<T>>>;
+type WhereInput<T extends Schema> = Filter<InferSchemaType<T>>;
+type SelectInput<T extends Schema> = {
+    _id?: boolean | 0 | 1;
+} & {
+    [K in keyof T["fields"]]?: boolean | 0 | 1;
+} & (T["timestamps"] extends false ? object : T["timestamps"] extends {
+    createdAt?: infer C;
+    updatedAt?: infer U;
+} ? {
+    [K in C extends string ? C : "createdAt"]?: boolean | 0 | 1;
+} & {
+    [K in U extends string ? U : "updatedAt"]?: boolean | 0 | 1;
+} : {
+    createdAt?: boolean | 0 | 1;
+    updatedAt?: boolean | 0 | 1;
+});
+type SortInput<T extends Schema> = Sort;
+interface FindOptions<T extends Schema> extends Omit<FindOptions$1, "projection" | "sort"> {
+    select?: SelectInput<T>;
+    sort?: SortInput<T>;
+    skip?: number;
+    limit?: number;
+}
+interface CreateOptions extends InsertOneOptions {
+    timestamps?: boolean;
+}
+interface CreateManyOptions extends BulkWriteOptions {
+    timestamps?: boolean;
+}
+interface UpdateOptions extends UpdateOptions$1 {
+    timestamps?: boolean;
+}
+interface DeleteOptions extends DeleteOptions$1 {
+    soft?: boolean;
+}
+interface CountOptions extends CountDocumentsOptions {
+}
+interface AggregateOpts extends AggregateOptions {
+}
+
+type SchemaToCollectionProxy<TSchema extends Schema<string, Record<string, FieldDefinition>>> = {
+    findOne(where?: Filter<InferSchemaType<TSchema>>, options?: FindOptions<TSchema>): Promise<InferSchemaType<TSchema> | null>;
+    findMany(where?: Filter<InferSchemaType<TSchema>>, options?: FindOptions<TSchema>): Promise<InferSchemaType<TSchema>[]>;
+    findById(id: ObjectId | string, options?: FindOptions<TSchema>): Promise<InferSchemaType<TSchema> | null>;
+    create(data: CreateInput<TSchema>, options?: CreateOptions): Promise<{
+        insertedId: ObjectId;
+    } & InferSchemaType<TSchema>>;
+    createMany(data: CreateInput<TSchema>[], options?: CreateManyOptions): Promise<{
+        insertedIds: Record<number, ObjectId>;
+    }>;
+    updateOne(where: Filter<InferSchemaType<TSchema>>, data: UpdateInput<TSchema> | Document, options?: UpdateOptions): Promise<{
+        matchedCount: number;
+        modifiedCount: number;
+        upsertedId?: ObjectId;
+    }>;
+    updateMany(where: Filter<InferSchemaType<TSchema>>, data: UpdateInput<TSchema> | Document, options?: UpdateOptions): Promise<{
+        matchedCount: number;
+        modifiedCount: number;
+        upsertedId?: ObjectId;
+    }>;
+    updateById(id: ObjectId | string, data: UpdateInput<TSchema> | Document, options?: UpdateOptions): Promise<{
+        matchedCount: number;
+        modifiedCount: number;
+    }>;
+    deleteOne(where: Filter<InferSchemaType<TSchema>>, options?: DeleteOptions): Promise<{
+        deletedCount: number;
+    }>;
+    deleteMany(where: Filter<InferSchemaType<TSchema>>, options?: DeleteOptions): Promise<{
+        deletedCount: number;
+    }>;
+    deleteById(id: ObjectId | string, options?: DeleteOptions): Promise<{
+        deletedCount: number;
+    }>;
+    count(where?: Filter<InferSchemaType<TSchema>>, options?: CountOptions): Promise<number>;
+    exists(where: Filter<InferSchemaType<TSchema>>, options?: CountOptions): Promise<boolean>;
+    aggregate<T = InferSchemaType<TSchema>>(pipeline: Document[], options?: AggregateOpts): Promise<T[]>;
+    getCollection(): mongodb.Collection;
+};
+
+declare const __type: unique symbol;
+declare const __required: unique symbol;
+declare class FieldBuilder<T = unknown, TRequired extends boolean = false> {
+    private definition;
+    readonly [__type]: T;
+    readonly [__required]: TRequired;
+    constructor(type: FieldDefinition["type"]);
+    required(): FieldBuilder<T, true>;
+    unique(): this;
+    default(value: T | "auto"): this;
+    index(options?: IndexOptions): this;
+    build(): FieldDefinition<T>;
+}
+declare class StringFieldBuilder extends FieldBuilder<string> {
+    constructor();
+    min(length: number): this;
+    max(length: number): this;
+    pattern(regex: RegExp): this;
+    email(): this;
+    url(): this;
+    text(): this;
+    enum<const E extends readonly string[]>(values: E): EnumFieldBuilder<E[number]>;
+}
+declare class EnumFieldBuilder<T extends string> extends FieldBuilder<T> {
+    constructor(values: readonly T[]);
+}
+declare class NumberFieldBuilder extends FieldBuilder<number> {
+    constructor();
+    min(value: number): this;
+    max(value: number): this;
+}
+declare class BooleanFieldBuilder extends FieldBuilder<boolean> {
+    constructor();
+}
+declare class DateFieldBuilder extends FieldBuilder<Date> {
+    constructor();
+}
+declare class ObjectIdFieldBuilder extends FieldBuilder<unknown> {
+    constructor();
+}
+declare class ArrayFieldBuilder<T> extends FieldBuilder<T[]> {
+    constructor(items: FieldDefinition);
+}
+declare class ObjectFieldBuilder<T extends Record<string, unknown>> extends FieldBuilder<T> {
+    constructor(properties: Record<string, FieldDefinition>);
+}
+declare class JsonFieldBuilder extends FieldBuilder<unknown> {
+    constructor();
+}
+declare class LiteralFieldBuilder<T extends string | number | boolean> extends FieldBuilder<T> {
+    constructor(value: T);
+}
+
+type FieldBuilderResult = {
+    build(): FieldDefinition;
+    required(): FieldBuilderResult;
+    unique(): FieldBuilderResult;
+    default(value: unknown): FieldBuilderResult;
+    index(options?: IndexOptions): FieldBuilderResult;
+};
+type SchemaFieldsInput = Record<string, FieldBuilderResult>;
+declare const s: {
+    string(): StringFieldBuilder;
+    number(): NumberFieldBuilder;
+    boolean(): BooleanFieldBuilder;
+    date(): DateFieldBuilder;
+    objectId(): ObjectIdFieldBuilder;
+    array<T>(items: {
+        build(): FieldDefinition;
+    }): ArrayFieldBuilder<T>;
+    object<T extends Record<string, unknown>>(properties: Record<string, {
+        build(): FieldDefinition;
+    }>): ObjectFieldBuilder<T>;
+    json(): JsonFieldBuilder;
+    literal<T extends string | number | boolean>(value: T): LiteralFieldBuilder<T>;
+    enum<const E extends readonly string[]>(values: E): EnumFieldBuilder<E[number]>;
+};
+
+interface SchemaInput<TFields extends SchemaFieldsInput, TTimestamps extends boolean | TimestampConfig = boolean | TimestampConfig> {
+    collection?: string;
+    timestamps?: TTimestamps;
+    validation?: {
+        enabled?: boolean;
+        mode?: "strict" | "loose" | "off";
+    };
+    connection?: string;
+    fields: TFields;
+    indexes?: CompoundIndexDefinition[];
+}
+type InferSchemaFields<TFields extends SchemaFieldsInput> = {
+    [K in keyof TFields]: TFields[K] extends {
+        build(): infer FD;
+    } ? FD extends FieldDefinition<infer T> ? FieldDefinition<T> & {
+        required: TFields[K] extends {
+            _required: true;
+        } ? true : false;
+        unique: TFields[K] extends {
+            _unique: true;
+        } ? true : false;
+    } : FieldDefinition : FieldDefinition;
+};
+type ResolvedTimestamps<T> = T extends true ? {
+    createdAt: "createdAt";
+    updatedAt: "updatedAt";
+} : T extends TimestampConfig ? T : false;
+type InferredSchema<TName extends string, TFields extends SchemaFieldsInput, TTimestamps extends boolean | TimestampConfig = true> = Omit<Schema<TName, InferSchemaFields<TFields>>, "timestamps"> & {
+    readonly timestamps: ResolvedTimestamps<TTimestamps>;
+    readonly __fields: TFields;
+};
+declare function schema<const TName extends string, const TFields extends SchemaFieldsInput, const TTimestamps extends boolean | TimestampConfig = false>(name: TName, definition: SchemaInput<TFields, TTimestamps>): InferredSchema<TName, TFields, TTimestamps>;
+declare const defineSchema: typeof schema;
+
+type AnySchema = Schema<string, Record<string, FieldDefinition>>;
+/**
+ * Configuration for serverless environments (Cloudflare Workers, Vercel Edge, etc.)
+ * Returns a factory function that creates connections on-demand.
+ *
+ * @template TSchemas - Tuple of schema types for type inference
+ *
+ * @example
+ * ```typescript
+ * const connectDb = createClient({
+ *   serverless: true,
+ *   schemas: [userSchema, postSchema] as const,
+ *   syncIndexes: false, // Recommended for serverless
+ *   validation: "strict"
+ * });
+ *
+ * // Later, in request handler:
+ * const db = await connectDb(env.MONGODB_URI);
+ * ```
+ */
+interface ServerlessClientConfig<TSchemas extends readonly AnySchema[]> {
+    /** Must be true for serverless mode */
+    serverless: true;
+    /** Array of schemas to register (use `as const` for type inference) */
+    schemas: TSchemas;
+    /** Whether to sync indexes on connect (default: false for serverless) */
+    syncIndexes?: boolean;
+    /** Validation mode: "strict" | "loose" | "off" (default: "strict") */
+    validation?: ValidationMode;
+}
+/**
+ * Configuration for traditional Node.js environments.
+ * Connects immediately and returns a ready-to-use client.
+ *
+ * @template TSchemas - Tuple of schema types for type inference
+ *
+ * @example
+ * ```typescript
+ * const db = await createClient({
+ *   uri: process.env.MONGODB_URI,
+ *   schemas: [userSchema, postSchema] as const,
+ *   syncIndexes: true,
+ *   validation: "strict"
+ * });
+ * ```
+ */
+interface NodeClientConfig<TSchemas extends readonly AnySchema[]> {
+    /** Set to false or omit for Node.js mode */
+    serverless?: false;
+    /** MongoDB connection URI (e.g., mongodb://localhost:27017/mydb) */
+    uri: string;
+    /** Array of schemas to register (use `as const` for type inference) */
+    schemas: TSchemas;
+    /** Whether to sync indexes on connect (default: true) */
+    syncIndexes?: boolean;
+    /** Validation mode: "strict" | "loose" | "off" (default: "strict") */
+    validation?: ValidationMode;
+    /** MongoDB driver options (maxPoolSize, etc.) */
+    options?: MongoClientOptions;
+}
+/**
+ * Union type of all client configurations.
+ */
+type ClientConfig<TSchemas extends readonly AnySchema[]> = ServerlessClientConfig<TSchemas> | NodeClientConfig<TSchemas>;
+type ClientMethods = {
+    readonly close: () => Promise<void>;
+    readonly getDb: () => Db;
+    readonly startSession: (options?: ClientSessionOptions) => ClientSession;
+};
+type SchemaNames<TSchemas extends readonly AnySchema[]> = TSchemas[number]["name"];
+type ValidClientKeys<TSchemas extends readonly AnySchema[]> = SchemaNames<TSchemas> | keyof ClientMethods;
+type SchemasToClient<TSchemas extends readonly AnySchema[]> = {
+    readonly [K in ValidClientKeys<TSchemas>]: K extends SchemaNames<TSchemas> ? SchemaToCollectionProxy<Extract<TSchemas[number], {
+        name: K;
+    }>> : K extends keyof ClientMethods ? ClientMethods[K] : never;
+};
+/**
+ * Create a type-safe MongoDB client with schema-based collection access.
+ *
+ * **Serverless Mode** (recommended for Cloudflare Workers, Vercel Edge):
+ * Returns a factory function that creates connections on-demand.
+ *
+ * @param config - Client configuration with `serverless: true`
+ * @returns Factory function: `(uri: string, options?) => Promise<Client>`
+ *
+ * @example
+ * ```typescript
+ * import { createClient, type SchemasToClient } from "mondel";
+ * import { userSchema, postSchema } from "./schemas";
+ *
+ * const schemas = [userSchema, postSchema] as const;
+ * export type DbClient = SchemasToClient<typeof schemas>;
+ *
+ * // Create factory (no connection yet)
+ * const connectDb = createClient({
+ *   serverless: true,
+ *   schemas,
+ *   syncIndexes: false,
+ *   validation: "strict"
+ * });
+ *
+ * // In request handler
+ * export async function handleRequest(env: Env) {
+ *   const db = await connectDb(env.MONGODB_URI);
+ *   const users = await db.users.findMany({ isActive: true });
+ *   await db.close();
+ *   return users;
+ * }
+ * ```
+ */
+declare function createClient<const TSchemas extends readonly AnySchema[]>(config: ServerlessClientConfig<TSchemas>): (uri: string, options?: MongoClientOptions) => Promise<SchemasToClient<TSchemas>>;
+/**
+ * Create a type-safe MongoDB client with schema-based collection access.
+ *
+ * **Node.js Mode** (for traditional servers, scripts, tests):
+ * Connects immediately and returns a ready-to-use client.
+ *
+ * @param config - Client configuration with `serverless: false` or omitted
+ * @returns Promise resolving to connected client
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "mondel";
+ * import { userSchema, postSchema } from "./schemas";
+ *
+ * async function main() {
+ *   const db = await createClient({
+ *     uri: process.env.MONGODB_URI!,
+ *     schemas: [userSchema, postSchema] as const,
+ *     syncIndexes: true,
+ *     validation: "strict"
+ *   });
+ *
+ *   // Type-safe access to collections
+ *   const users = await db.users.findMany({ role: "ADMIN" });
+ *
+ *   // Close when done
+ *   await db.close();
+ * }
+ * ```
+ */
+declare function createClient<const TSchemas extends readonly AnySchema[]>(config: NodeClientConfig<TSchemas>): Promise<SchemasToClient<TSchemas>>;
+
+/**
+ * Creates a complete Zod schema from a Mondel schema definition.
+ * Includes all fields and timestamp fields if configured.
+ *
+ * @param schema - Mondel schema definition
+ * @returns Zod object schema for full document validation
+ *
+ * @example
+ * ```typescript
+ * const zod = zodSchema(userSchema);
+ * const result = zod.safeParse(document);
+ * ```
+ */
+declare function zodSchema<TSchema extends Schema>(schema: TSchema): z.ZodObject<Record<string, ZodTypeAny>>;
+/**
+ * Creates a Zod schema for insert operations.
+ * Excludes _id and timestamp fields (auto-generated).
+ * Used internally by `create()` and `createMany()` methods.
+ *
+ * @param schema - Mondel schema definition
+ * @returns Zod schema for create validation
+ */
+declare function zodCreateSchema<TSchema extends Schema>(schema: TSchema): z.ZodObject<Record<string, ZodTypeAny>>;
+/**
+ * Creates a Zod schema for update operations.
+ * All fields become optional (partial update support).
+ * Used internally by `updateOne()`, `updateMany()`, `updateById()` methods.
+ *
+ * @param schema - Mondel schema definition
+ * @returns Zod schema with all fields optional
+ */
+declare function zodUpdateSchema<TSchema extends Schema>(schema: TSchema): z.ZodObject<Record<string, ZodTypeAny>>;
+/**
+ * Validates data against a Zod schema.
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @returns Result object with success status and data or errors
+ *
+ * @example
+ * ```typescript
+ * const result = validate(zodCreateSchema(userSchema), userData);
+ * if (result.success) {
+ *   console.log(result.data);
+ * } else {
+ *   console.error(result.errors);
+ * }
+ * ```
+ */
+declare function validate<T>(schema: z.ZodType<T>, data: unknown): {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: z.ZodError;
+};
+
+/**
+ * Type-safe collection proxy for MongoDB operations.
+ * Provides CRUD methods with full TypeScript support and Zod validation.
+ *
+ * @template TSchema - The schema type for this collection
+ *
+ * @example
+ * ```typescript
+ * // Access via client
+ * const db = await getMondelClient(env);
+ * const users = await db.users.findMany({ isActive: true });
+ * ```
+ */
+declare class CollectionProxy<TSchema extends Schema> {
+    private collection;
+    private schema;
+    private validationMode;
+    constructor(db: Db, schema: TSchema, validationMode?: ValidationMode);
+    private validateCreate;
+    private validateUpdate;
+    /**
+     * Find a single document matching the filter.
+     *
+     * @param where - MongoDB filter query
+     * @param options - Find options (select, sort, skip, limit, session)
+     * @returns The matching document or null
+     *
+     * @example
+     * ```typescript
+     * // Find by email
+     * const user = await db.users.findOne({ email: "john@example.com" });
+     *
+     * // With field selection
+     * const user = await db.users.findOne(
+     *   { email: "john@example.com" },
+     *   { select: { _id: true, email: true, name: true } }
+     * );
+     *
+     * // With session (for transactions)
+     * const user = await db.users.findOne(
+     *   { email: "john@example.com" },
+     *   { session }
+     * );
+     * ```
+     */
+    findOne(where: Filter<Document>, options?: FindOptions<TSchema>): Promise<WithId<Document> | null>;
+    /**
+     * Find multiple documents matching the filter.
+     *
+     * @param where - MongoDB filter query (optional, defaults to {})
+     * @param options - Find options (select, sort, skip, limit, session)
+     * @returns Array of matching documents
+     *
+     * @example
+     * ```typescript
+     * // Find all active users
+     * const users = await db.users.findMany({ isActive: true });
+     *
+     * // With pagination and sorting
+     * const users = await db.users.findMany(
+     *   { role: "ADMIN" },
+     *   {
+     *     select: { _id: true, email: true, name: true },
+     *     sort: { createdAt: -1 },
+     *     skip: 0,
+     *     limit: 10
+     *   }
+     * );
+     *
+     * // Using MongoDB operators
+     * const users = await db.users.findMany({
+     *   age: { $gte: 18, $lte: 65 },
+     *   role: { $in: ["ADMIN", "MODERATOR"] }
+     * });
+     * ```
+     */
+    findMany(where?: Filter<Document>, options?: FindOptions<TSchema>): Promise<WithId<Document>[]>;
+    /**
+     * Find a document by its _id.
+     *
+     * @param id - ObjectId or string representation
+     * @param options - Find options (select, session)
+     * @returns The matching document or null
+     *
+     * @example
+     * ```typescript
+     * // Find by string ID
+     * const user = await db.users.findById("507f1f77bcf86cd799439011");
+     *
+     * // Find by ObjectId
+     * const user = await db.users.findById(new ObjectId("507f1f77bcf86cd799439011"));
+     *
+     * // With field selection
+     * const user = await db.users.findById(userId, {
+     *   select: { email: true, name: true }
+     * });
+     * ```
+     */
+    findById(id: ObjectId | string, options?: FindOptions<TSchema>): Promise<WithId<Document> | null>;
+    /**
+     * Create a new document.
+     * Automatically adds timestamps if enabled in schema.
+     *
+     * @param data - Document data (validated against schema)
+     * @param options - Create options (timestamps, session)
+     * @returns Insert result with insertedId
+     *
+     * @example
+     * ```typescript
+     * // Create a user
+     * const result = await db.users.create({
+     *   email: "john@example.com",
+     *   name: "John Doe",
+     *   role: "USER"
+     * });
+     * console.log(result.insertedId); // ObjectId
+     *
+     * // Disable automatic timestamps
+     * await db.users.create(userData, { timestamps: false });
+     *
+     * // With session (for transactions)
+     * await db.users.create(userData, { session });
+     * ```
+     */
+    create(data: OptionalUnlessRequiredId<Document>, options?: CreateOptions): Promise<InsertOneResult>;
+    /**
+     * Create multiple documents in a single operation.
+     * Automatically adds timestamps if enabled in schema.
+     *
+     * @param data - Array of document data
+     * @param options - Create options (timestamps, ordered, session)
+     * @returns Insert result with insertedIds
+     *
+     * @example
+     * ```typescript
+     * // Create multiple users
+     * const result = await db.users.createMany([
+     *   { email: "user1@example.com", name: "User 1" },
+     *   { email: "user2@example.com", name: "User 2" },
+     *   { email: "user3@example.com", name: "User 3" }
+     * ]);
+     * console.log(result.insertedIds); // { 0: ObjectId, 1: ObjectId, 2: ObjectId }
+     *
+     * // With session (for transactions)
+     * await db.users.createMany(usersData, { session });
+     * ```
+     */
+    createMany(data: OptionalUnlessRequiredId<Document>[], options?: CreateManyOptions): Promise<InsertManyResult>;
+    /**
+     * Update a single document matching the filter.
+     * Supports both simple updates and MongoDB update operators.
+     *
+     * @param where - MongoDB filter query
+     * @param data - Update data or MongoDB update operators ($set, $inc, etc.)
+     * @param options - Update options (upsert, timestamps, session)
+     * @returns Update result with matchedCount, modifiedCount, upsertedId
+     *
+     * @example
+     * ```typescript
+     * // Simple update (automatically wrapped in $set)
+     * await db.users.updateOne(
+     *   { email: "john@example.com" },
+     *   { name: "John Smith" }
+     * );
+     *
+     * // Using MongoDB operators
+     * await db.users.updateOne(
+     *   { _id: userId },
+     *   { $set: { name: "John" }, $inc: { loginCount: 1 } }
+     * );
+     *
+     * // Upsert - create if not exists
+     * await db.users.updateOne(
+     *   { email: "john@example.com" },
+     *   { $set: { name: "John", isActive: true } },
+     *   { upsert: true }
+     * );
+     *
+     * // With session (for transactions)
+     * await db.users.updateOne(filter, update, { session });
+     * ```
+     */
+    updateOne(where: Filter<Document>, data: Document, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Update multiple documents matching the filter.
+     * Supports both simple updates and MongoDB update operators.
+     *
+     * @param where - MongoDB filter query
+     * @param data - Update data or MongoDB update operators
+     * @param options - Update options (upsert, timestamps, session)
+     * @returns Update result with matchedCount, modifiedCount
+     *
+     * @example
+     * ```typescript
+     * // Deactivate all users with expired subscriptions
+     * await db.users.updateMany(
+     *   { subscriptionExpiry: { $lt: new Date() } },
+     *   { $set: { isActive: false } }
+     * );
+     *
+     * // Increment login count for all admins
+     * await db.users.updateMany(
+     *   { role: "ADMIN" },
+     *   { $inc: { loginCount: 1 } }
+     * );
+     * ```
+     */
+    updateMany(where: Filter<Document>, data: Document, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Update a document by its _id.
+     * Convenience method that wraps updateOne with _id filter.
+     *
+     * @param id - ObjectId or string representation
+     * @param data - Update data or MongoDB update operators
+     * @param options - Update options (upsert, timestamps, session)
+     * @returns Update result with matchedCount, modifiedCount
+     *
+     * @example
+     * ```typescript
+     * // Update by ID
+     * await db.users.updateById(userId, { name: "New Name" });
+     *
+     * // Using operators
+     * await db.users.updateById(userId, {
+     *   $set: { name: "New Name" },
+     *   $push: { tags: "premium" }
+     * });
+     * ```
+     */
+    updateById(id: ObjectId | string, data: Document, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Delete a single document matching the filter.
+     *
+     * @param where - MongoDB filter query
+     * @param options - Delete options (session)
+     * @returns Delete result with deletedCount
+     *
+     * @example
+     * ```typescript
+     * // Delete by email
+     * await db.users.deleteOne({ email: "john@example.com" });
+     *
+     * // With session (for transactions)
+     * await db.users.deleteOne({ _id: userId }, { session });
+     * ```
+     */
+    deleteOne(where: Filter<Document>, options?: DeleteOptions): Promise<DeleteResult>;
+    /**
+     * Delete multiple documents matching the filter.
+     *
+     * @param where - MongoDB filter query
+     * @param options - Delete options (session)
+     * @returns Delete result with deletedCount
+     *
+     * @example
+     * ```typescript
+     * // Delete all inactive users
+     * const result = await db.users.deleteMany({ isActive: false });
+     * console.log(`Deleted ${result.deletedCount} users`);
+     *
+     * // Delete users created before a date
+     * await db.users.deleteMany({
+     *   createdAt: { $lt: new Date("2023-01-01") }
+     * });
+     * ```
+     */
+    deleteMany(where: Filter<Document>, options?: DeleteOptions): Promise<DeleteResult>;
+    /**
+     * Delete a document by its _id.
+     *
+     * @param id - ObjectId or string representation
+     * @param options - Delete options (session)
+     * @returns Delete result with deletedCount
+     *
+     * @example
+     * ```typescript
+     * await db.users.deleteById("507f1f77bcf86cd799439011");
+     * await db.users.deleteById(userId, { session });
+     * ```
+     */
+    deleteById(id: ObjectId | string, options?: DeleteOptions): Promise<DeleteResult>;
+    /**
+     * Count documents matching the filter.
+     *
+     * @param where - MongoDB filter query (optional)
+     * @param options - Count options (limit, skip, session)
+     * @returns Number of matching documents
+     *
+     * @example
+     * ```typescript
+     * // Count all users
+     * const total = await db.users.count();
+     *
+     * // Count active users
+     * const activeCount = await db.users.count({ isActive: true });
+     *
+     * // Count with limit (for existence check optimization)
+     * const hasAdmins = await db.users.count({ role: "ADMIN" }, { limit: 1 }) > 0;
+     * ```
+     */
+    count(where?: Filter<Document>, options?: CountDocumentsOptions): Promise<number>;
+    /**
+     * Check if any document matches the filter.
+     * Optimized to stop after finding first match.
+     *
+     * @param where - MongoDB filter query
+     * @param options - Count options (session)
+     * @returns true if at least one document matches
+     *
+     * @example
+     * ```typescript
+     * // Check if email is taken
+     * const emailTaken = await db.users.exists({ email: "john@example.com" });
+     *
+     * // Check if user has admin role
+     * const isAdmin = await db.users.exists({ _id: userId, role: "ADMIN" });
+     * ```
+     */
+    exists(where: Filter<Document>, options?: CountDocumentsOptions): Promise<boolean>;
+    /**
+     * Run an aggregation pipeline.
+     * Provides full access to MongoDB aggregation framework.
+     *
+     * @param pipeline - Array of aggregation stages
+     * @param options - Aggregation options (allowDiskUse, session)
+     * @returns Array of aggregation results
+     *
+     * @example
+     * ```typescript
+     * // Group users by role and count
+     * const stats = await db.users.aggregate([
+     *   { $match: { isActive: true } },
+     *   { $group: { _id: "$role", count: { $sum: 1 } } },
+     *   { $sort: { count: -1 } }
+     * ]);
+     *
+     * // Lookup related documents
+     * const usersWithPosts = await db.users.aggregate([
+     *   { $lookup: {
+     *       from: "posts",
+     *       localField: "_id",
+     *       foreignField: "authorId",
+     *       as: "posts"
+     *   }}
+     * ]);
+     *
+     * // With options
+     * const bigResult = await db.users.aggregate(pipeline, {
+     *   allowDiskUse: true
+     * });
+     * ```
+     */
+    aggregate(pipeline: Document[], options?: AggregateOptions): Promise<Document[]>;
+    /**
+     * Get the underlying MongoDB Collection instance.
+     * Use for advanced operations not covered by the proxy.
+     *
+     * @returns MongoDB Collection instance
+     *
+     * @example
+     * ```typescript
+     * const collection = db.users.getCollection();
+     *
+     * // Use for watch, bulkWrite, or other advanced operations
+     * const changeStream = collection.watch();
+     * ```
+     */
+    getCollection(): Collection<Document>;
+    private applyTimestamps;
+    private parseObjectId;
+    private applyUpdateTimestamps;
+}
+
+export { type AggregateOpts, type ClientConfig, CollectionProxy, type CompoundIndexDefinition, type CountOptions, type CreateInput, type CreateManyOptions, type CreateOptions, type DeleteOptions, type FieldDefinition, type FindOptions, type IndexOptions, type InferSchemaType, type NodeClientConfig, type Schema, type SchemaDefinition, type SchemasToClient, type SelectInput, type ServerlessClientConfig, type SortInput, type TimestampConfig, type UpdateInput, type UpdateOptions, type ValidationConfig, type WhereInput, createClient, defineSchema, s, schema, validate, zodCreateSchema, zodSchema, zodUpdateSchema };