momos 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,573 @@
+import * as mongodb from 'mongodb';
+import { ObjectId, AbstractCursor, FindCursor, AggregationCursor, Document, Db, Collection, InsertOneOptions, InsertOneResult, BulkWriteOptions, InsertManyResult, FindOptions, UpdateOptions, UpdateResult, ReplaceOptions, FindOneAndUpdateOptions, FindOneAndReplaceOptions, DeleteOptions, DeleteResult, FindOneAndDeleteOptions, CountDocumentsOptions, EstimatedDocumentCountOptions, AggregateOptions, IndexSpecification, CreateIndexesOptions, IndexDescription, DropIndexesOptions } from 'mongodb';
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+/**
+ * Comparison operators for a field value
+ */
+type ComparisonOperators<T> = {
+    /** Matches values equal to a specified value */
+    $eq?: T;
+    /** Matches values not equal to a specified value */
+    $ne?: T;
+    /** Matches values greater than a specified value */
+    $gt?: T;
+    /** Matches values greater than or equal to a specified value */
+    $gte?: T;
+    /** Matches values less than a specified value */
+    $lt?: T;
+    /** Matches values less than or equal to a specified value */
+    $lte?: T;
+    /** Matches any of the values specified in an array */
+    $in?: T[];
+    /** Matches none of the values specified in an array */
+    $nin?: T[];
+};
+/**
+ * Element operators
+ */
+type ElementOperators = {
+    /** Matches documents that have the specified field */
+    $exists?: boolean;
+    /** Selects documents if a field is of the specified type */
+    $type?: string | number;
+};
+/**
+ * String-specific operators
+ */
+type StringOperators = {
+    /** Matches documents where the field matches a regular expression */
+    $regex?: RegExp | string;
+    /** Regex options (i, m, x, s) */
+    $options?: string;
+};
+/**
+ * Array-specific operators
+ */
+type ArrayOperators<T> = {
+    /** Matches arrays that contain all specified elements */
+    $all?: T extends Array<infer E> ? E[] : never;
+    /** Matches arrays with a specific number of elements */
+    $size?: T extends Array<unknown> ? number : never;
+    /** Matches documents that contain an array field with at least one element matching a query */
+    $elemMatch?: T extends Array<infer E> ? E extends object ? Filter<E> : ComparisonOperators<E> : never;
+};
+/**
+ * All operators that can be applied to a field
+ */
+type FieldOperators<T> = ComparisonOperators<T> & ElementOperators & (T extends string ? StringOperators : object) & (T extends Array<unknown> ? ArrayOperators<T> : object);
+/**
+ * Condition for a single field - either a direct value or operators
+ */
+type FieldCondition<T> = T | FieldOperators<T>;
+/**
+ * Filter for nested object paths using dot notation
+ * This provides basic support for nested field access
+ */
+type NestedPaths<T, Depth extends number[] = []> = Depth["length"] extends 3 ? never : T extends object ? T extends ObjectId | Date | Array<unknown> ? never : {
+    [K in keyof T & string]: T[K] extends object ? `${K}` | `${K}.${NestedPaths<T[K], [...Depth, 1]> & string}` : `${K}`;
+}[keyof T & string] : never;
+/**
+ * Get the type at a nested path
+ */
+type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathValue<T[K], Rest> : never : P extends keyof T ? T[P] : never;
+/**
+ * Root filter type for querying documents
+ */
+type Filter<Doc> = {
+    [K in keyof Doc]?: FieldCondition<Doc[K]>;
+} & {
+    [K in NestedPaths<Doc>]?: FieldCondition<PathValue<Doc, K>>;
+} & {
+    /** Logical AND - matches all conditions */
+    $and?: Filter<Doc>[];
+    /** Logical OR - matches any condition */
+    $or?: Filter<Doc>[];
+    /** Logical NOR - matches none of the conditions */
+    $nor?: Filter<Doc>[];
+    /** Logical NOT - inverts the condition */
+    $not?: Filter<Doc>;
+    /** Text search */
+    $text?: {
+        $search: string;
+        $language?: string;
+        $caseSensitive?: boolean;
+        $diacriticSensitive?: boolean;
+    };
+    /** JavaScript expression */
+    $where?: string | ((this: Doc) => boolean);
+    /** Comment for the query */
+    $comment?: string;
+};
+/**
+ * Empty filter type for matching all documents
+ */
+type EmptyFilter = Record<string, never>;
+
+/**
+ * Projection to include/exclude fields
+ */
+type Projection<Doc> = {
+    [K in keyof Doc]?: 1 | 0 | true | false;
+} & {
+    /** Always include _id unless explicitly excluded */
+    _id?: 1 | 0 | true | false;
+};
+/**
+ * Include projection - specifies which fields to include
+ */
+type IncludeProjection<Doc> = {
+    [K in keyof Doc]?: 1 | true;
+} & {
+    _id?: 0 | false;
+};
+/**
+ * Exclude projection - specifies which fields to exclude
+ */
+type ExcludeProjection<Doc> = {
+    [K in keyof Doc]?: 0 | false;
+};
+/**
+ * Result type when projection is applied
+ * This is a simplified version - full implementation would need mapped types
+ */
+type ProjectedDocument<Doc, P extends Projection<Doc>> = P extends {
+    _id: 0 | false;
+} ? Omit<Pick<Doc, Extract<keyof P, keyof Doc>>, "_id"> : Pick<Doc, Extract<keyof P, keyof Doc> | "_id">;
+/**
+ * Sort direction
+ */
+type SortDirection = 1 | -1 | "asc" | "desc" | "ascending" | "descending";
+/**
+ * Sort specification
+ */
+type Sort<Doc> = {
+    [K in keyof Doc]?: SortDirection;
+} & {
+    /** Natural order */
+    $natural?: SortDirection;
+};
+
+/**
+ * Helper type to get array element type
+ */
+type ArrayElement<T> = T extends Array<infer E> ? E : never;
+/**
+ * Helper to check if a type is an array
+ */
+type IsArray<T> = T extends Array<unknown> ? true : false;
+/**
+ * Helper to check if a type is a number
+ */
+type IsNumber<T> = T extends number ? true : false;
+/**
+ * $set operator - sets field values
+ */
+type SetOperator<Doc> = {
+    $set?: Partial<Doc>;
+};
+/**
+ * $unset operator - removes fields
+ */
+type UnsetOperator<Doc> = {
+    $unset?: {
+        [K in keyof Doc]?: 1 | "" | true;
+    };
+};
+/**
+ * $inc operator - increments numeric fields
+ */
+type IncOperator<Doc> = {
+    $inc?: {
+        [K in keyof Doc as IsNumber<Doc[K]> extends true ? K : never]?: number;
+    };
+};
+/**
+ * $mul operator - multiplies numeric fields
+ */
+type MulOperator<Doc> = {
+    $mul?: {
+        [K in keyof Doc as IsNumber<Doc[K]> extends true ? K : never]?: number;
+    };
+};
+/**
+ * $min operator - updates if new value is less than current
+ */
+type MinOperator<Doc> = {
+    $min?: {
+        [K in keyof Doc]?: Doc[K];
+    };
+};
+/**
+ * $max operator - updates if new value is greater than current
+ */
+type MaxOperator<Doc> = {
+    $max?: {
+        [K in keyof Doc]?: Doc[K];
+    };
+};
+/**
+ * $rename operator - renames fields
+ */
+type RenameOperator<Doc> = {
+    $rename?: {
+        [K in keyof Doc]?: string;
+    };
+};
+/**
+ * $currentDate operator - sets field to current date
+ */
+type CurrentDateOperator<Doc> = {
+    $currentDate?: {
+        [K in keyof Doc as Doc[K] extends Date ? K : never]?: true | {
+            $type: "date" | "timestamp";
+        };
+    };
+};
+/**
+ * $push operator - adds elements to arrays
+ */
+type PushOperator<Doc> = {
+    $push?: {
+        [K in keyof Doc as IsArray<Doc[K]> extends true ? K : never]?: ArrayElement<Doc[K]> | {
+            $each: ArrayElement<Doc[K]>[];
+            $position?: number;
+            $slice?: number;
+            $sort?: 1 | -1 | Record<string, 1 | -1>;
+        };
+    };
+};
+/**
+ * $addToSet operator - adds elements to arrays only if they don't exist
+ */
+type AddToSetOperator<Doc> = {
+    $addToSet?: {
+        [K in keyof Doc as IsArray<Doc[K]> extends true ? K : never]?: ArrayElement<Doc[K]> | {
+            $each: ArrayElement<Doc[K]>[];
+        };
+    };
+};
+/**
+ * $pop operator - removes first or last element from array
+ */
+type PopOperator<Doc> = {
+    $pop?: {
+        [K in keyof Doc as IsArray<Doc[K]> extends true ? K : never]?: 1 | -1;
+    };
+};
+/**
+ * $pull operator - removes elements matching a condition
+ */
+type PullOperator<Doc> = {
+    $pull?: {
+        [K in keyof Doc as IsArray<Doc[K]> extends true ? K : never]?: ArrayElement<Doc[K]> | Partial<ArrayElement<Doc[K]>>;
+    };
+};
+/**
+ * $pullAll operator - removes all matching values from array
+ */
+type PullAllOperator<Doc> = {
+    $pullAll?: {
+        [K in keyof Doc as IsArray<Doc[K]> extends true ? K : never]?: ArrayElement<Doc[K]>[];
+    };
+};
+/**
+ * Combined update operators
+ */
+type Update<Doc> = SetOperator<Doc> & UnsetOperator<Doc> & IncOperator<Doc> & MulOperator<Doc> & MinOperator<Doc> & MaxOperator<Doc> & RenameOperator<Doc> & CurrentDateOperator<Doc> & PushOperator<Doc> & AddToSetOperator<Doc> & PopOperator<Doc> & PullOperator<Doc> & PullAllOperator<Doc>;
+/**
+ * Update with aggregation pipeline
+ */
+type UpdatePipeline<Doc> = Update<Doc>[];
+
+/**
+ * Base typed cursor wrapper with common operations
+ * Works with both FindCursor and AggregationCursor
+ */
+declare class TypedCursor<Doc, RawCursor extends AbstractCursor<Doc>> {
+    protected readonly cursor: RawCursor;
+    constructor(cursor: RawCursor);
+    /**
+     * Get the underlying MongoDB cursor
+     */
+    get raw(): RawCursor;
+    /**
+     * Returns all documents as an array
+     */
+    toArray(): Promise<Doc[]>;
+    /**
+     * Iterate over documents with a callback
+     */
+    forEach(callback: (doc: Doc) => void | Promise<void>): Promise<void>;
+    /**
+     * Map documents to a new type
+     */
+    map<T>(transform: (doc: Doc) => T): TypedCursor<T, AbstractCursor<T>>;
+    /**
+     * Check if there are more documents
+     */
+    hasNext(): Promise<boolean>;
+    /**
+     * Get the next document
+     */
+    next(): Promise<Doc | null>;
+    /**
+     * Close the cursor
+     */
+    close(): Promise<void>;
+    /**
+     * Make the cursor iterable
+     */
+    [Symbol.asyncIterator](): AsyncIterator<Doc>;
+}
+/**
+ * Typed wrapper around MongoDB's FindCursor
+ * Extends base cursor with find-specific operations
+ */
+declare class TypedFindCursor<Doc> extends TypedCursor<Doc, FindCursor<Doc>> {
+    /**
+     * Map documents to a new type
+     */
+    map<T>(transform: (doc: Doc) => T): TypedFindCursor<T>;
+    /**
+     * Limit the number of documents returned
+     */
+    limit(count: number): this;
+    /**
+     * Skip a number of documents
+     */
+    skip(count: number): this;
+    /**
+     * Sort the documents
+     */
+    sort(sort: Sort<Doc>): this;
+    /**
+     * Project specific fields
+     */
+    project<P extends Projection<Doc>>(projection: P): TypedFindCursor<Doc>;
+    /**
+     * Set batch size for cursor
+     */
+    batchSize(size: number): this;
+}
+/**
+ * Typed wrapper around MongoDB's AggregationCursor
+ * Uses the base TypedCursor functionality
+ */
+declare class TypedAggregationCursor<Doc> extends TypedCursor<Doc, AggregationCursor<Doc>> {
+    /**
+     * Map documents to a new type
+     */
+    map<T>(transform: (doc: Doc) => T): TypedAggregationCursor<T>;
+}
+
+/**
+ * Check if a type has an _id property
+ */
+type HasId<T> = "_id" extends keyof T ? true : false;
+/**
+ * Document type that adds ObjectId _id only if not present in the schema
+ * - If schema defines _id, use the schema's type
+ * - If schema doesn't define _id, add _id: ObjectId
+ */
+type DocumentWithId<T extends Document> = HasId<T> extends true ? T : T & {
+    _id: ObjectId;
+};
+/**
+ * Infer the input type from a Standard Schema (pre-validation)
+ * Used for insert/update operations where data is validated before storage
+ */
+type InferSchemaInput<S extends StandardSchemaV1> = StandardSchemaV1.InferInput<S> & Document;
+/**
+ * Infer the document type from a Standard Schema (post-validation)
+ * Automatically adds _id: ObjectId if not defined in the schema
+ * Used for query results and stored documents
+ */
+type InferDocument<S extends StandardSchemaV1> = DocumentWithId<StandardSchemaV1.InferOutput<S> & Document>;
+/**
+ * Optional _id for insert operations
+ * - If schema defines _id, it remains as defined (could be required or optional)
+ * - If schema doesn't define _id, adds optional _id that accepts ObjectId or string
+ */
+type OptionalId<T extends Document> = HasId<T> extends true ? T : Omit<T, "_id"> & {
+    _id?: ObjectId | string;
+};
+/**
+ * Validation error thrown when schema validation fails
+ */
+declare class ValidationError extends Error {
+    readonly issues: ReadonlyArray<StandardSchemaV1.Issue>;
+    constructor(issues: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+/**
+ * Options for collection operations
+ */
+interface CollectionOptions {
+    /**
+     * Whether to validate documents before insert/update operations
+     * @default true
+     */
+    validate?: boolean;
+}
+
+/**
+ * Type-safe MongoDB collection wrapper
+ * Validates documents before insert/update operations using Standard Schema
+ */
+declare class TypedCollection<S extends StandardSchemaV1> {
+    private readonly collection;
+    private readonly schema;
+    private readonly shouldValidate;
+    constructor(collection: Collection<Document>, schema: S, options?: CollectionOptions);
+    /**
+     * Get the underlying MongoDB collection
+     */
+    get raw(): Collection<Document>;
+    /**
+     * Get the collection name
+     */
+    get collectionName(): string;
+    /**
+     * Insert a single document
+     * Validates the document before insertion if validation is enabled
+     */
+    insertOne(doc: OptionalId<InferSchemaInput<S>>, options?: InsertOneOptions): Promise<InsertOneResult>;
+    /**
+     * Insert multiple documents
+     * Validates all documents before insertion if validation is enabled
+     */
+    insertMany(docs: OptionalId<InferSchemaInput<S>>[], options?: BulkWriteOptions): Promise<InsertManyResult>;
+    /**
+     * Find documents matching the filter
+     * Returns a typed cursor for further operations
+     */
+    find(filter?: Filter<InferDocument<S>>, options?: FindOptions): TypedFindCursor<InferDocument<S>>;
+    /**
+     * Find a single document matching the filter
+     */
+    findOne(filter?: Filter<InferDocument<S>>, options?: FindOptions): Promise<InferDocument<S> | null>;
+    /**
+     * Find a document by its _id
+     */
+    findById(id: string | mongodb.ObjectId, options?: FindOptions): Promise<InferDocument<S> | null>;
+    /**
+     * Update a single document
+     */
+    updateOne(filter: Filter<InferDocument<S>>, update: Update<InferDocument<S>>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Update multiple documents
+     */
+    updateMany(filter: Filter<InferDocument<S>>, update: Update<InferDocument<S>>, options?: UpdateOptions): Promise<UpdateResult>;
+    /**
+     * Replace a single document
+     * Validates the replacement document if validation is enabled
+     */
+    replaceOne(filter: Filter<InferDocument<S>>, replacement: OptionalId<InferSchemaInput<S>>, options?: ReplaceOptions): Promise<UpdateResult>;
+    /**
+     * Find a document and update it atomically
+     */
+    findOneAndUpdate(filter: Filter<InferDocument<S>>, update: Update<InferDocument<S>>, options?: FindOneAndUpdateOptions): Promise<InferDocument<S> | null>;
+    /**
+     * Find a document and replace it atomically
+     * Validates the replacement document if validation is enabled
+     */
+    findOneAndReplace(filter: Filter<InferDocument<S>>, replacement: OptionalId<InferSchemaInput<S>>, options?: FindOneAndReplaceOptions): Promise<InferDocument<S> | null>;
+    /**
+     * Delete a single document
+     */
+    deleteOne(filter: Filter<InferDocument<S>>, options?: DeleteOptions): Promise<DeleteResult>;
+    /**
+     * Delete multiple documents
+     */
+    deleteMany(filter: Filter<InferDocument<S>>, options?: DeleteOptions): Promise<DeleteResult>;
+    /**
+     * Find a document and delete it atomically
+     */
+    findOneAndDelete(filter: Filter<InferDocument<S>>, options?: FindOneAndDeleteOptions): Promise<InferDocument<S> | null>;
+    /**
+     * Count documents matching the filter
+     */
+    countDocuments(filter?: Filter<InferDocument<S>>, options?: CountDocumentsOptions): Promise<number>;
+    /**
+     * Get an estimated count of documents (faster, uses metadata)
+     */
+    estimatedDocumentCount(options?: EstimatedDocumentCountOptions): Promise<number>;
+    /**
+     * Run an aggregation pipeline
+     */
+    aggregate<T extends Document = Document>(pipeline: Document[], options?: AggregateOptions): TypedAggregationCursor<T>;
+    /**
+     * Create an index
+     */
+    createIndex(indexSpec: IndexSpecification, options?: CreateIndexesOptions): Promise<string>;
+    /**
+     * Create multiple indexes
+     */
+    createIndexes(indexSpecs: IndexDescription[], options?: CreateIndexesOptions): Promise<string[]>;
+    /**
+     * Drop an index
+     */
+    dropIndex(indexName: string, options?: DropIndexesOptions): Promise<void>;
+    /**
+     * List all indexes
+     */
+    indexes(): Promise<Document[]>;
+    /**
+     * Get distinct values for a field
+     */
+    distinct<K extends keyof InferDocument<S>>(field: K, filter?: Filter<InferDocument<S>>): Promise<InferDocument<S>[K][]>;
+    /**
+     * Check if a document exists
+     */
+    exists(filter: Filter<InferDocument<S>>): Promise<boolean>;
+    /**
+     * Drop the collection
+     */
+    drop(): Promise<void>;
+}
+/**
+ * Create a typed collection from a database and schema
+ *
+ * @param db - MongoDB database instance
+ * @param name - Collection name
+ * @param schema - Standard Schema compatible validation schema (zod, valibot, arktype, etc.)
+ * @param options - Collection options
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { defineCollection } from 'momos';
+ *
+ * const userSchema = z.object({
+ *   name: z.string(),
+ *   email: z.string().email(),
+ *   age: z.number().min(0),
+ * });
+ *
+ * const users = defineCollection(db, 'users', userSchema);
+ *
+ * // Type-safe insert
+ * await users.insertOne({ name: 'John', email: 'john@example.com', age: 30 });
+ *
+ * // Type-safe queries
+ * const adults = await users.find({ age: { $gte: 18 } }).toArray();
+ * ```
+ */
+declare function defineCollection<S extends StandardSchemaV1>(db: Db, name: string, schema: S, options?: CollectionOptions): TypedCollection<S>;
+
+/**
+ * Validate a value against a Standard Schema
+ * Works with any Standard Schema compatible library (zod, valibot, arktype, etc.)
+ */
+declare function validate<S extends StandardSchemaV1>(schema: S, data: unknown): Promise<StandardSchemaV1.InferOutput<S>>;
+/**
+ * Validate multiple values against a Standard Schema
+ */
+declare function validateMany<S extends StandardSchemaV1>(schema: S, data: unknown[]): Promise<StandardSchemaV1.InferOutput<S>[]>;
+/**
+ * Check if a value is valid according to a Standard Schema (non-throwing)
+ */
+declare function isValid<S extends StandardSchemaV1>(schema: S, data: unknown): Promise<boolean>;
+
+export { TypedAggregationCursor, TypedCollection, TypedCursor, TypedFindCursor, ValidationError, defineCollection, isValid, validate, validateMany };
+export type { AddToSetOperator, ArrayOperators, CollectionOptions, ComparisonOperators, CurrentDateOperator, DocumentWithId, ElementOperators, EmptyFilter, ExcludeProjection, FieldCondition, FieldOperators, Filter, HasId, IncOperator, IncludeProjection, InferDocument, InferSchemaInput, MaxOperator, MinOperator, MulOperator, OptionalId, PopOperator, ProjectedDocument, Projection, PullAllOperator, PullOperator, PushOperator, RenameOperator, SetOperator, Sort, SortDirection, StringOperators, UnsetOperator, Update, UpdatePipeline };