monsqlize 1.3.0 → 2.0.0

package/types/chain.ts

@@ -1,254 +0,0 @@
-/**
- * 链式调用 API 类型定义
- * @module types/chain
- * @since v2.0+
- */
-
-import type { ExplainResult } from './stream';
-
-/**
- * Collation 选项（字符串排序规则）
- */
-export interface CollationOptions {
-    locale: string;                  // 语言代码，如 'zh', 'en'
-    strength?: number;               // 比较级别：1=基本, 2=重音, 3=大小写
-    caseLevel?: boolean;             // 是否区分大小写
-    caseFirst?: 'upper' | 'lower';   // 大小写优先级
-    numericOrdering?: boolean;       // 数字排序
-    alternate?: 'non-ignorable' | 'shifted'; // 空格和标点处理
-    maxVariable?: 'punct' | 'space'; // 最大可变字符
-    backwards?: boolean;             // 反向比较
-}
-
-/**
- * FindChain - find 查询的链式调用构建器
- *
- * @template T - 文档类型
- *
- * @example
- * // 基础链式调用
- * const results = await collection<Product>('products')
- *   .find({ category: 'electronics' })
- *   .limit(10)
- *   .skip(5)
- *   .sort({ price: -1 });
- */
-export interface FindChain<T = any> extends PromiseLike<T[]> {
-    /**
-     * 限制返回文档数量
-     * @param n - 限制数量，必须为非负数
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 n 不是非负数
-     */
-    limit(n: number): FindChain<T>;
-
-    /**
-     * 跳过指定数量的文档
-     * @param n - 跳过数量，必须为非负数
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 n 不是非负数
-     */
-    skip(n: number): FindChain<T>;
-
-    /**
-     * 设置排序规则
-     * @param spec - 排序配置，如 { price: -1, name: 1 }
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 spec 不是对象或数组
-     */
-    sort(spec: Record<string, 1 | -1> | Array<[string, 1 | -1]>): FindChain<T>;
-
-    /**
-     * 设置字段投影
-     * @param spec - 投影配置，如 { name: 1, price: 1 }
-     * @returns 返回带有投影类型的新链
-     * @throws {Error} 如果 spec 不是对象或数组
-     */
-    project<K extends keyof T>(spec: Record<K, 1 | 0> | Array<K>): FindChain<Pick<T, K>>;
-    project(spec: Record<string, 1 | 0> | string[]): FindChain<Partial<T>>;
-
-    /**
-     * 设置索引提示（强制使用指定索引）
-     * @param spec - 索引名称或索引规格
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 spec 为空
-     */
-    hint(spec: Record<string, 1 | -1> | string): FindChain<T>;
-
-    /**
-     * 设置排序规则（用于字符串排序）
-     * @param spec - 排序规则配置
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 spec 不是对象
-     */
-    collation(spec: CollationOptions): FindChain<T>;
-
-    /**
-     * 设置查询注释（用于日志追踪）
-     * @param str - 注释内容
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 str 不是字符串
-     */
-    comment(str: string): FindChain<T>;
-
-    /**
-     * 设置查询超时时间
-     * @param ms - 超时时间（毫秒）
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 ms 不是非负数
-     */
-    maxTimeMS(ms: number): FindChain<T>;
-
-    /**
-     * 设置批处理大小
-     * @param n - 批处理大小
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 n 不是非负数
-     */
-    batchSize(n: number): FindChain<T>;
-
-    /**
-     * 返回查询执行计划（不执行查询）
-     * @param verbosity - 详细级别
-     * @returns 执行计划
-     */
-    explain(verbosity?: 'queryPlanner' | 'executionStats' | 'allPlansExecution'): Promise<ExplainResult>;
-
-    /**
-     * 返回流式结果
-     * @returns MongoDB 游标流
-     */
-    stream(): NodeJS.ReadableStream;
-
-    /**
-     * 显式转换为数组（执行查询）
-     * @returns 查询结果数组
-     * @throws {Error} 如果查询已执行
-     */
-    toArray(): Promise<T[]>;
-
-    /**
-     * Promise.then 接口
-     */
-    then<TResult1 = T[], TResult2 = never>(
-        onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
-        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
-    ): Promise<TResult1 | TResult2>;
-
-    /**
-     * Promise.catch 接口
-     */
-    catch<TResult = never>(
-        onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
-    ): Promise<T[] | TResult>;
-
-    /**
-     * Promise.finally 接口
-     */
-    finally(onfinally?: (() => void) | null): Promise<T[]>;
-}
-
-/**
- * AggregateChain - aggregate 查询的链式调用构建器
- *
- * @template T - 文档类型
- *
- * @example
- * // 基础聚合
- * const results = await collection<Order>('orders')
- *   .aggregate([
- *     { $match: { status: 'paid' } },
- *     { $group: { _id: '$category', total: { $sum: '$amount' } } }
- *   ])
- *   .allowDiskUse(true);
- */
-export interface AggregateChain<T = any> extends PromiseLike<T[]> {
-    /**
-     * 设置索引提示（强制使用指定索引）
-     * @param spec - 索引名称或索引规格
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 spec 为空
-     */
-    hint(spec: Record<string, 1 | -1> | string): AggregateChain<T>;
-
-    /**
-     * 设置排序规则（用于字符串排序）
-     * @param spec - 排序规则配置
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 spec 不是对象
-     */
-    collation(spec: CollationOptions): AggregateChain<T>;
-
-    /**
-     * 设置查询注释（用于日志追踪）
-     * @param str - 注释内容
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 str 不是字符串
-     */
-    comment(str: string): AggregateChain<T>;
-
-    /**
-     * 设置查询超时时间
-     * @param ms - 超时时间（毫秒）
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 ms 不是非负数
-     */
-    maxTimeMS(ms: number): AggregateChain<T>;
-
-    /**
-     * 允许使用磁盘进行大数据量排序/分组
-     * @param bool - 是否允许
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 bool 不是布尔值
-     */
-    allowDiskUse(bool: boolean): AggregateChain<T>;
-
-    /**
-     * 设置批处理大小
-     * @param n - 批处理大小
-     * @returns 返回自身以支持链式调用
-     * @throws {Error} 如果 n 不是非负数
-     */
-    batchSize(n: number): AggregateChain<T>;
-
-    /**
-     * 返回聚合执行计划（不执行聚合）
-     * @param verbosity - 详细级别
-     * @returns 执行计划
-     */
-    explain(verbosity?: 'queryPlanner' | 'executionStats' | 'allPlansExecution'): Promise<ExplainResult>;
-
-    /**
-     * 返回流式结果
-     * @returns MongoDB 游标流
-     */
-    stream(): NodeJS.ReadableStream;
-
-    /**
-     * 显式转换为数组（执行聚合）
-     * @returns 聚合结果数组
-     * @throws {Error} 如果查询已执行
-     */
-    toArray(): Promise<T[]>;
-
-    /**
-     * Promise.then 接口
-     */
-    then<TResult1 = T[], TResult2 = never>(
-        onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null,
-        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null
-    ): Promise<TResult1 | TResult2>;
-
-    /**
-     * Promise.catch 接口
-     */
-    catch<TResult = never>(
-        onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
-    ): Promise<T[] | TResult>;
-
-    /**
-     * Promise.finally 接口
-     */
-    finally(onfinally?: (() => void) | null): Promise<T[]>;
-}
-

package/types/collection.ts

@@ -1,357 +0,0 @@
-/**
- * Collection API 相关类型定义
- * @module types/collection
- */
-
-import type {
-  FindOptions,
-  CountOptions,
-  AggregateOptions,
-  DistinctOptions,
-} from "./query";
-import type {
-  InsertOneSimplifiedOptions,
-  InsertOneOptions,
-  InsertOneResult,
-  InsertManySimplifiedOptions,
-  InsertManyOptions,
-  InsertManyResult,
-} from "./write";
-import type {
-  InsertBatchOptions,
-  InsertBatchResult,
-  UpdateBatchOptions,
-  UpdateBatchResult,
-  DeleteBatchOptions,
-  DeleteBatchResult,
-} from "./batch";
-import type {
-  FindPageOptions,
-  PageResult,
-  ResultWithMeta,
-  MetaOptions,
-  BookmarkKeyDims,
-  PrewarmBookmarksResult,
-  ListBookmarksResult,
-  ClearBookmarksResult,
-} from "./pagination";
-import type { StreamOptions, ExplainOptions } from "./stream";
-import type { FindChain, AggregateChain } from "./chain";
-
-/**
- * 健康视图
- */
-export interface HealthView {
-  status: "up" | "down";
-  connected: boolean;
-  defaults?: any;
-  cache?: any;
-  driver?: { connected: boolean };
-}
-
-/**
- * Collection 访问器接口
- * 提供所有 Collection 操作方法
- */
-export interface CollectionAccessor<TSchema = any> {
-  /**
-   * 获取命名空间信息
-   */
-  getNamespace(): { iid: string; type: string; db: string; collection: string };
-
-  /**
-   * 删除集合
-   */
-  dropCollection(): Promise<boolean>;
-
-  /**
-   * 创建集合
-   */
-  createCollection(name?: string | null, options?: any): Promise<boolean>;
-
-  /**
-   * 创建视图
-   */
-  createView(
-    viewName: string,
-    source: string,
-    pipeline?: any[],
-  ): Promise<boolean>;
-
-  // ============================================================================
-  // 查询方法
-  // ============================================================================
-
-  /**
-   * 查询单个文档
-   * 支持 meta 参数和泛型
-   */
-  findOne<T = TSchema>(
-    query?: any,
-    options?: Omit<FindOptions, "meta">,
-  ): Promise<T | null>;
-  findOne<T = TSchema>(
-    query: any,
-    options: FindOptions & { meta: true | MetaOptions },
-  ): Promise<ResultWithMeta<T | null>>;
-  findOne<T = TSchema>(
-    query?: any,
-    options?: FindOptions,
-  ): Promise<T | null | ResultWithMeta<T | null>>;
-
-  /**
-   * 通过 _id 查询单个文档（便利方法）
-   * @param id - 文档的 _id（字符串会自动转换为 ObjectId）
-   * @param options - 查询选项
-   */
-  findOneById(
-    id: string | any,
-    options?: Omit<FindOptions, "meta">,
-  ): Promise<any | null>;
-
-  /**
-   * 批量通过 _id 查询多个文档（便利方法）
-   * @param ids - _id 数组
-   * @param options - 查询选项
-   */
-  findByIds(
-    ids: Array<string | any>,
-    options?: {
-      projection?: Record<string, any>;
-      sort?: Record<string, 1 | -1>;
-      cache?: number;
-      maxTimeMS?: number;
-      comment?: string;
-      preserveOrder?: boolean;
-    },
-  ): Promise<any[]>;
-
-  /**
-   * 查询多个文档
-   * 支持 meta 参数和链式调用
-   */
-  find<T = TSchema>(query?: any): FindChain<T>;
-  find<T = TSchema>(
-    query: any,
-    options: FindOptions & { meta: true | MetaOptions },
-  ): Promise<ResultWithMeta<T[]>>;
-  find<T = TSchema>(
-    query?: any,
-    options?: FindOptions,
-  ): Promise<T[]> | FindChain<T> | ResultWithMeta<T[]>;
-
-  /**
-   * 计数
-   * 支持 meta 参数
-   */
-  count(query?: any, options?: Omit<CountOptions, "meta">): Promise<number>;
-  count(
-    query: any,
-    options: CountOptions & { meta: true | MetaOptions },
-  ): Promise<ResultWithMeta<number>>;
-  count(
-    query?: any,
-    options?: CountOptions,
-  ): Promise<number | ResultWithMeta<number>>;
-
-  /**
-   * 聚合查询
-   * 支持 meta 参数和链式调用
-   */
-  aggregate<T = TSchema>(pipeline?: any[]): AggregateChain<T>;
-  aggregate<T = TSchema>(
-    pipeline: any[],
-    options: AggregateOptions & { meta: true | MetaOptions },
-  ): Promise<ResultWithMeta<T[]>>;
-  aggregate<T = TSchema>(
-    pipeline?: any[],
-    options?: AggregateOptions,
-  ): Promise<T[]> | AggregateChain<T> | ResultWithMeta<T[]>;
-
-  /**
-   * 去重查询
-   * 支持 meta 参数
-   */
-  distinct<T = any>(
-    field: string,
-    query?: any,
-    options?: Omit<DistinctOptions, "meta">,
-  ): Promise<T[]>;
-  distinct<T = any>(
-    field: string,
-    query: any,
-    options: DistinctOptions & { meta: true | MetaOptions },
-  ): Promise<ResultWithMeta<T[]>>;
-  distinct<T = any>(
-    field: string,
-    query?: any,
-    options?: DistinctOptions,
-  ): Promise<T[] | ResultWithMeta<T[]>>;
-
-  /**
-   * 流式查询
-   * 返回 Node.js 可读流
-   */
-  stream(query?: any, options?: StreamOptions): NodeJS.ReadableStream;
-
-  /**
-   * 查询执行计划诊断
-   */
-  explain(query?: any, options?: ExplainOptions): Promise<any>;
-
-  // ============================================================================
-  // 分页相关
-  // ============================================================================
-
-  /**
-   * 深度分页
-   */
-  findPage<T = TSchema>(options: FindPageOptions): Promise<PageResult<T>>;
-
-  /**
-   * Bookmark 维护 APIs
-   */
-  prewarmBookmarks(
-    keyDims: BookmarkKeyDims,
-    pages: number[],
-  ): Promise<PrewarmBookmarksResult>;
-  listBookmarks(keyDims?: BookmarkKeyDims): Promise<ListBookmarksResult>;
-  clearBookmarks(keyDims?: BookmarkKeyDims): Promise<ClearBookmarksResult>;
-
-  // ============================================================================
-  // 写入操作
-  // ============================================================================
-
-  /**
-   * 插入单个文档
-   * 支持简化调用和完整配置
-   */
-  insertOne<T = TSchema>(
-    document: T,
-    options?: InsertOneSimplifiedOptions,
-  ): Promise<InsertOneResult>;
-  insertOne(options: InsertOneOptions): Promise<InsertOneResult>;
-
-  /**
-   * 插入多个文档
-   * 支持简化调用和完整配置
-   */
-  insertMany<T = TSchema>(
-    documents: T[],
-    options?: InsertManySimplifiedOptions,
-  ): Promise<InsertManyResult>;
-  insertMany(options: InsertManyOptions): Promise<InsertManyResult>;
-
-  /**
-   * Upsert 单个文档（存在则更新，不存在则插入）
-   * @param filter - 查询条件
-   * @param update - 更新内容
-   * @param options - 操作选项
-   */
-  upsertOne(
-    filter: Record<string, any>,
-    update: Record<string, any>,
-    options?: {
-      maxTimeMS?: number;
-      comment?: string;
-    },
-  ): Promise<{
-    acknowledged: boolean;
-    matchedCount: number;
-    modifiedCount: number;
-    upsertedId?: any;
-    upsertedCount: number;
-  }>;
-
-  /**
-   * 原子递增/递减字段值（便利方法）
-   * @param filter - 查询条件
-   * @param field - 字段名或字段-增量对象
-   * @param increment - 增量（默认 1，负数为递减）
-   * @param options - 操作选项
-   */
-  incrementOne(
-    filter: Record<string, any>,
-    field: string | Record<string, number>,
-    increment?: number,
-    options?: {
-      returnDocument?: "before" | "after";
-      projection?: Record<string, any>;
-      maxTimeMS?: number;
-      comment?: string;
-    },
-  ): Promise<{
-    acknowledged: boolean;
-    matchedCount: number;
-    modifiedCount: number;
-    value: any | null;
-  }>;
-
-  /**
-   * 使缓存失效
-   */
-  invalidate(
-    op?: "find" | "findOne" | "count" | "findPage" | "aggregate" | "distinct",
-  ): Promise<number>;
-
-  // ============================================================================
-  // 批量操作
-  // ============================================================================
-
-  /**
-   * 大批量插入（自动分批+重试）
-   * @since v1.0.0
-   */
-  insertBatch<T = TSchema>(
-    documents: T[],
-    options?: InsertBatchOptions,
-  ): Promise<InsertBatchResult>;
-
-  /**
-   * 批量更新文档（流式查询+分批更新）
-   * @since v1.0.0
-   */
-  updateBatch(
-    filter: Record<string, any>,
-    update: Record<string, any>,
-    options?: UpdateBatchOptions,
-  ): Promise<UpdateBatchResult>;
-
-  /**
-   * 批量删除文档（流式查询+分批删除）
-   * @since v1.0.0
-   */
-  deleteBatch(
-    filter: Record<string, any>,
-    options?: DeleteBatchOptions,
-  ): Promise<DeleteBatchResult>;
-
-  /**
-   * 查询文档并返回总数（便利方法）
-   * @since v1.0.0
-   */
-  findAndCount<T = TSchema>(
-    filter?: Record<string, any>,
-    options?: FindOptions,
-  ): Promise<{ documents: T[]; total: number }>;
-}
-
-/**
- * Collection 类型别名（与 CollectionAccessor 等价）
- * @since v1.0.4
- */
-export type Collection<TSchema = any> = CollectionAccessor<TSchema>;
-
-/**
- * 数据库访问器
- */
-export type DbAccessor = {
-  collection<TSchema = any>(name: string): CollectionAccessor<TSchema>;
-  db(dbName: string): {
-    collection<TSchema = any>(name: string): CollectionAccessor<TSchema>;
-  };
-  /** `db()` 的别名，语义更清晰：`app.db.use('logs')` */
-  use(dbName: string): {
-    collection<TSchema = any>(name: string): CollectionAccessor<TSchema>;
-  };
-};