@gravito/dark-matter 1.0.0 → 1.1.1

package/dist/index.d.ts

@@ -272,6 +272,17 @@ interface GridFSFile {
     metadata?: Record<string, unknown>;
     contentType?: string;
 }
+/**
+ * GridFS 上傳進度資訊
+ */
+interface GridFSUploadProgress {
+    /** 已寫入的位元組數 */
+    bytesWritten: number;
+    /** 總位元組數（串流模式下可能為 0） */
+    totalBytes: number;
+    /** 完成百分比（0-100） */
+    percentage: number;
+}
 /**
  * MongoDB Collection Contract
  */
@@ -308,6 +319,38 @@ interface MongoCollectionContract<T = Document$1> {
     deleteMany(): Promise<DeleteResult>;
     bulkWrite(operations: BulkWriteOperation<T>[]): Promise<BulkWriteResult>;
     watch(pipeline?: PipelineStage[], options?: ChangeStreamOptions): AsyncIterable<ChangeEvent<T>>;
+    /**
+     * 包含已軟刪除的記錄
+     */
+    withTrashed(): this;
+    /**
+     * 只查詢已軟刪除的記錄
+     */
+    onlyTrashed(): this;
+    /**
+     * 軟刪除單一記錄（設置 deletedAt）
+     */
+    softDelete(): Promise<UpdateResult>;
+    /**
+     * 批次軟刪除
+     */
+    softDeleteMany(): Promise<UpdateResult>;
+    /**
+     * 恢復軟刪除的記錄
+     */
+    restore(): Promise<UpdateResult>;
+    /**
+     * 批次恢復
+     */
+    restoreMany(): Promise<UpdateResult>;
+    /**
+     * 強制刪除（真正刪除記錄）
+     */
+    forceDelete(): Promise<DeleteResult>;
+    /**
+     * 批次強制刪除
+     */
+    forceDeleteMany(): Promise<DeleteResult>;
     aggregate(): MongoAggregateContract<T>;
     toFilter(): FilterDocument;
     clone(): MongoCollectionContract<T>;
@@ -370,6 +413,10 @@ interface MongoDatabaseContract {
         schema?: SchemaValidationOptions;
     }): Promise<void>;
     setValidation(collectionName: string, schema: SchemaValidationOptions): Promise<void>;
+    createCollectionWithSchema(name: string, schemaBuilder: unknown, options?: {
+        validationLevel?: 'off' | 'strict' | 'moderate';
+        validationAction?: 'error' | 'warn';
+    }): Promise<void>;
 }
 /**
  * Generic document type
@@ -378,6 +425,12 @@ interface Document$1 {
     _id?: string;
     [key: string]: unknown;
 }
+/**
+ * 支援軟刪除的文檔類型
+ */
+interface SoftDeletableDocument extends Document$1 {
+    deletedAt?: Date | null;
+}
 
 /**
  * MongoDB Facade
@@ -711,6 +764,89 @@ declare class MongoGridFS {
      * ```
      */
     list(filter?: FilterDocument): Promise<GridFSFile[]>;
+    /**
+     * 串流上傳檔案
+     *
+     * 支援進度回調的串流上傳，適合大檔案上傳
+     *
+     * @param stream - ReadableStream 來源
+     * @param options - 上傳選項
+     * @param onProgress - 可選的進度回調函數
+     * @returns Promise 解析為檔案 ID
+     *
+     * @example
+     * ```typescript
+     * const stream = file.stream()
+     * const fileId = await grid.uploadStream(stream, {
+     *   filename: 'video.mp4'
+     * }, (progress) => {
+     *   console.log(`上傳進度: ${progress.percentage}%`)
+     * })
+     * ```
+     */
+    uploadStream(stream: ReadableStream<Uint8Array>, options: GridFSUploadOptions, onProgress?: (progress: GridFSUploadProgress) => void): Promise<string>;
+    /**
+     * 串流下載檔案
+     *
+     * 返回 ReadableStream 以支援大檔案的串流下載
+     *
+     * @param fileId - 檔案 ID
+     * @returns ReadableStream 提供檔案內容
+     *
+     * @example
+     * ```typescript
+     * const stream = grid.downloadStream(fileId)
+     * const reader = stream.getReader()
+     *
+     * while (true) {
+     *   const { done, value } = await reader.read()
+     *   if (done) break
+     *   // 處理 chunk
+     * }
+     * ```
+     */
+    downloadStream(fileId: string): ReadableStream<Uint8Array>;
+    /**
+     * 分片上傳大檔案
+     *
+     * 支援進度追蹤的大檔案上傳，自動處理分片
+     *
+     * @param file - Blob 或 File 物件
+     * @param options - 上傳選項
+     * @param onProgress - 可選的進度回調函數
+     * @returns Promise 解析為檔案 ID
+     *
+     * @example
+     * ```typescript
+     * const fileId = await grid.uploadLargeFile(file, {
+     *   filename: 'large-video.mp4',
+     *   chunkSizeBytes: 255 * 1024 // 255 KB
+     * }, (progress) => {
+     *   console.log(`進度: ${progress.percentage}%`)
+     *   console.log(`已上傳: ${progress.bytesWritten} / ${progress.totalBytes}`)
+     * })
+     * ```
+     */
+    uploadLargeFile(file: Blob | File, options: GridFSUploadOptions, onProgress?: (progress: GridFSUploadProgress) => void): Promise<string>;
+    /**
+     * 取得檔案中繼資料
+     *
+     * 查詢檔案資訊但不下載內容
+     *
+     * @param fileId - 檔案 ID
+     * @returns Promise 解析為檔案中繼資料，找不到時返回 null
+     *
+     * @example
+     * ```typescript
+     * const fileInfo = await grid.findById(fileId)
+     * if (fileInfo) {
+     *   console.log(`檔案名稱: ${fileInfo.filename}`)
+     *   console.log(`檔案大小: ${fileInfo.length} bytes`)
+     *   console.log(`上傳日期: ${fileInfo.uploadDate}`)
+     * }
+     * ```
+     */
+    findById(fileId: string): Promise<GridFSFile | null>;
     private ensureBucket;
 }
 
@@ -898,6 +1034,7 @@ declare class MongoQueryBuilder<T = Document> implements MongoCollectionContract
     private sortSpec;
     private limitCount;
     private skipCount;
+    private softDeleteMode;
     constructor(nativeCollection: MongoNativeCollection, collectionName: string, session?: unknown | undefined);
     /**
      * Adds a basic WHERE clause to the query.
@@ -1320,6 +1457,110 @@ declare class MongoQueryBuilder<T = Document> implements MongoCollectionContract
      * ```
      */
     deleteMany(): Promise<DeleteResult>;
+    /**
+     * 包含已軟刪除的記錄
+     *
+     * 查詢時包含所有記錄，不過濾已刪除的文檔
+     *
+     * @returns 當前查詢建構器實例，支援鏈式調用
+     *
+     * @example
+     * ```typescript
+     * const allUsers = await query.withTrashed().get();
+     * ```
+     */
+    withTrashed(): this;
+    /**
+     * 只查詢已軟刪除的記錄
+     *
+     * 只返回 deletedAt 不為 null 的文檔
+     *
+     * @returns 當前查詢建構器實例，支援鏈式調用
+     *
+     * @example
+     * ```typescript
+     * const trashedUsers = await query.onlyTrashed().get();
+     * ```
+     */
+    onlyTrashed(): this;
+    /**
+     * 軟刪除單一記錄
+     *
+     * 設置 deletedAt 為當前時間，而非真正刪除記錄
+     *
+     * @returns Promise 解析為更新結果
+     *
+     * @example
+     * ```typescript
+     * await query.where('_id', userId).softDelete();
+     * ```
+     */
+    softDelete(): Promise<UpdateResult>;
+    /**
+     * 批次軟刪除
+     *
+     * 設置所有符合條件的文檔的 deletedAt 為當前時間
+     *
+     * @returns Promise 解析為更新結果
+     *
+     * @example
+     * ```typescript
+     * await query.where('status', 'inactive').softDeleteMany();
+     * ```
+     */
+    softDeleteMany(): Promise<UpdateResult>;
+    /**
+     * 恢復軟刪除的記錄
+     *
+     * 將 deletedAt 設置為 null，恢復軟刪除的文檔
+     *
+     * @returns Promise 解析為更新結果
+     *
+     * @example
+     * ```typescript
+     * await query.where('_id', userId).restore();
+     * ```
+     */
+    restore(): Promise<UpdateResult>;
+    /**
+     * 批次恢復軟刪除的記錄
+     *
+     * 將所有符合條件的文檔的 deletedAt 設置為 null
+     *
+     * @returns Promise 解析為更新結果
+     *
+     * @example
+     * ```typescript
+     * await query.onlyTrashed().restoreMany();
+     * ```
+     */
+    restoreMany(): Promise<UpdateResult>;
+    /**
+     * 強制刪除（真正刪除記錄）
+     *
+     * 永久刪除單一文檔，無法恢復
+     *
+     * @returns Promise 解析為刪除結果
+     *
+     * @example
+     * ```typescript
+     * await query.where('_id', userId).forceDelete();
+     * ```
+     */
+    forceDelete(): Promise<DeleteResult>;
+    /**
+     * 批次強制刪除
+     *
+     * 永久刪除所有符合條件的文檔，無法恢復
+     *
+     * @returns Promise 解析為刪除結果
+     *
+     * @example
+     * ```typescript
+     * await query.where('createdAt', '<', oneYearAgo).forceDeleteMany();
+     * ```
+     */
+    forceDeleteMany(): Promise<DeleteResult>;
     /**
      * Executes a bulk write operation.
      *
@@ -1402,6 +1643,15 @@ declare class MongoQueryBuilder<T = Document> implements MongoCollectionContract
     clone(): MongoCollectionContract<T>;
     private mapOperator;
     private normalizeUpdate;
+    /**
+     * 應用軟刪除過濾
+     *
+     * 根據 softDeleteMode 自動過濾已刪除的記錄
+     *
+     * @param filter - 基礎過濾條件
+     * @returns 包含軟刪除過濾的完整過濾條件
+     */
+    private applySoftDeleteFilter;
     private getObjectId;
 }
 /**
@@ -1492,4 +1742,215 @@ interface MongoUpdateResult {
     upsertedId?: MongoObjectId;
 }
 
-export { type BulkWriteOperation, type BulkWriteResult, type DeleteResult, type Document$1 as Document, type FilterDocument, type FilterOperator, type GridFSFile, type GridFSUploadOptions, type InsertManyResult, type InsertResult, type LookupOptions, Mongo, MongoAggregateBuilder, type MongoAggregateContract, MongoClient, type MongoClientContract, type MongoCollectionContract, type MongoConfig, type MongoDatabaseContract, MongoGridFS, MongoManager, type MongoManagerConfig, MongoPoolMonitor, MongoQueryBuilder, type MongoSession, type PipelineStage, type PoolMetrics, type Projection, type RetryConfig, type SortDirection, type SortSpec, type TransactionOptions, type UpdateDocument, type UpdateResult };
+/**
+ * MongoDB Schema Builder
+ * @description 提供型別安全的 Schema 定義 API
+ */
+
+/**
+ * MongoDB Schema Builder
+ *
+ * 提供友善的 API 來建構 MongoDB JSON Schema 驗證規則
+ *
+ * @example
+ * ```typescript
+ * const userSchema = schema()
+ *   .required('username', 'email')
+ *   .string('username', { minLength: 3, maxLength: 50 })
+ *   .string('email', { pattern: '^.+@.+$' })
+ *   .integer('age', { minimum: 0, maximum: 150 })
+ *   .boolean('isActive')
+ *   .date('createdAt')
+ *   .array('roles', 'string', { minItems: 1 })
+ *   .object('profile', (s) =>
+ *     s.string('bio', { maxLength: 500 }).string('avatar')
+ *   )
+ * ```
+ */
+declare class MongoSchemaBuilder {
+    private schema;
+    /**
+     * 定義必填欄位
+     *
+     * @param fields - 必填欄位名稱列表
+     * @returns 當前 Schema Builder 實例
+     *
+     * @example
+     * ```typescript
+     * schema().required('name', 'email', 'age')
+     * ```
+     */
+    required(...fields: string[]): this;
+    /**
+     * 定義字串欄位
+     *
+     * @param field - 欄位名稱
+     * @param options - 字串選項（長度、模式、枚舉等）
+     * @returns 當前 Schema Builder 實例
+     *
+     * @example
+     * ```typescript
+     * schema()
+     *   .string('username', { minLength: 3, maxLength: 50 })
+     *   .string('email', { pattern: '^.+@.+$' })
+     *   .string('status', { enum: ['active', 'inactive'] })
+     * ```
+     */
+    string(field: string, options?: {
+        minLength?: number;
+        maxLength?: number;
+        pattern?: string;
+        enum?: string[];
+    }): this;
+    /**
+     * 定義數字欄位
+     *
+     * @param field - 欄位名稱
+     * @param options - 數字選項（最小值、最大值等）
+     * @returns 當前 Schema Builder 實例
+     *
+     * @example
+     * ```typescript
+     * schema()
+     *   .number('price', { minimum: 0, maximum: 10000 })
+     *   .number('discount', { minimum: 0, maximum: 1, exclusiveMaximum: true })
+     * ```
+     */
+    number(field: string, options?: {
+        minimum?: number;
+        maximum?: number;
+        exclusiveMinimum?: boolean;
+        exclusiveMaximum?: boolean;
+    }): this;
+    /**
+     * 定義整數欄位
+     *
+     * @param field - 欄位名稱
+     * @param options - 整數選項（最小值、最大值）
+     * @returns 當前 Schema Builder 實例
+     *
+     * @example
+     * ```typescript
+     * schema()
+     *   .integer('age', { minimum: 0, maximum: 150 })
+     *   .integer('count')
+     * ```
+     */
+    integer(field: string, options?: {
+        minimum?: number;
+        maximum?: number;
+    }): this;
+    /**
+     * 定義布林欄位
+     *
+     * @param field - 欄位名稱
+     * @returns 當前 Schema Builder 實例
+     *
+     * @example
+     * ```typescript
+     * schema().boolean('isActive').boolean('verified')
+     * ```
+     */
+    boolean(field: string): this;
+    /**
+     * 定義日期欄位
+     *
+     * @param field - 欄位名稱
+     * @returns 當前 Schema Builder 實例
+     *
+     * @example
+     * ```typescript
+     * schema().date('createdAt').date('updatedAt')
+     * ```
+     */
+    date(field: string): this;
+    /**
+     * 定義陣列欄位
+     *
+     * @param field - 欄位名稱
+     * @param itemType - 陣列元素類型
+     * @param options - 陣列選項（長度、唯一性等）
+     * @returns 當前 Schema Builder 實例
+     *
+     * @example
+     * ```typescript
+     * schema()
+     *   .array('tags', 'string')
+     *   .array('scores', 'number')
+     *   .array('roles', 'string', { minItems: 1, uniqueItems: true })
+     * ```
+     */
+    array(field: string, itemType: 'string' | 'number' | 'object' | 'int' | 'bool' | 'date', options?: {
+        minItems?: number;
+        maxItems?: number;
+        uniqueItems?: boolean;
+    }): this;
+    /**
+     * 定義物件欄位
+     *
+     * @param field - 欄位名稱
+     * @param callback - 巢狀 Schema 建構函數
+     * @returns 當前 Schema Builder 實例
+     *
+     * @example
+     * ```typescript
+     * schema().object('profile', (s) =>
+     *   s
+     *     .string('bio', { maxLength: 500 })
+     *     .string('avatar')
+     *     .integer('followers')
+     * )
+     * ```
+     */
+    object(field: string, callback: (builder: MongoSchemaBuilder) => void): this;
+    /**
+     * 建構最終的 JSON Schema
+     *
+     * @returns JSON Schema 物件
+     *
+     * @example
+     * ```typescript
+     * const schema = schema()
+     *   .required('name')
+     *   .string('name')
+     *   .build()
+     * ```
+     */
+    build(): Record<string, unknown>;
+    /**
+     * 轉換為 MongoDB 驗證選項
+     *
+     * @param options - 驗證選項（驗證等級、動作）
+     * @returns MongoDB Schema 驗證選項
+     *
+     * @example
+     * ```typescript
+     * const options = schema()
+     *   .required('name')
+     *   .string('name')
+     *   .toValidationOptions({ validationLevel: 'moderate' })
+     * ```
+     */
+    toValidationOptions(options?: {
+        validationLevel?: 'off' | 'strict' | 'moderate';
+        validationAction?: 'error' | 'warn';
+    }): SchemaValidationOptions;
+}
+/**
+ * 建立 Schema Builder 實例
+ *
+ * @returns 新的 MongoSchemaBuilder 實例
+ *
+ * @example
+ * ```typescript
+ * import { schema } from '@gravito/dark-matter'
+ *
+ * const userSchema = schema()
+ *   .required('name', 'email')
+ *   .string('name')
+ *   .string('email')
+ * ```
+ */
+declare function schema(): MongoSchemaBuilder;
+
+export { type BulkWriteOperation, type BulkWriteResult, type DeleteResult, type Document$1 as Document, type FilterDocument, type FilterOperator, type GridFSFile, type GridFSUploadOptions, type GridFSUploadProgress, type InsertManyResult, type InsertResult, type LookupOptions, Mongo, MongoAggregateBuilder, type MongoAggregateContract, MongoClient, type MongoClientContract, type MongoCollectionContract, type MongoConfig, type MongoDatabaseContract, MongoGridFS, MongoManager, type MongoManagerConfig, MongoPoolMonitor, MongoQueryBuilder, MongoSchemaBuilder, type MongoSession, type PipelineStage, type PoolMetrics, type Projection, type RetryConfig, type SchemaValidationOptions, type SoftDeletableDocument, type SortDirection, type SortSpec, type TransactionOptions, type UpdateDocument, type UpdateResult, schema };