@gravito/dark-matter 1.0.0 → 1.1.1

package/dist/index.cjs

@@ -36,7 +36,9 @@ __export(index_exports, {
   MongoGridFS: () => MongoGridFS,
   MongoManager: () => MongoManager,
   MongoPoolMonitor: () => MongoPoolMonitor,
-  MongoQueryBuilder: () => MongoQueryBuilder
+  MongoQueryBuilder: () => MongoQueryBuilder,
+  MongoSchemaBuilder: () => MongoSchemaBuilder,
+  schema: () => schema
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -54,6 +56,7 @@ var MongoQueryBuilder = class _MongoQueryBuilder {
   sortSpec = {};
   limitCount;
   skipCount;
+  softDeleteMode = "exclude";
   // ============================================================================
   // WHERE Clauses
   // ============================================================================
@@ -649,6 +652,163 @@ var MongoQueryBuilder = class _MongoQueryBuilder {
       acknowledged: result.acknowledged
     };
   }
+  // ============================================================================
+  // Soft Delete Methods
+  // ============================================================================
+  /**
+   * 包含已軟刪除的記錄
+   *
+   * 查詢時包含所有記錄，不過濾已刪除的文檔
+   *
+   * @returns 當前查詢建構器實例，支援鏈式調用
+   *
+   * @example
+   * ```typescript
+   * const allUsers = await query.withTrashed().get();
+   * ```
+   */
+  withTrashed() {
+    this.softDeleteMode = "include";
+    return this;
+  }
+  /**
+   * 只查詢已軟刪除的記錄
+   *
+   * 只返回 deletedAt 不為 null 的文檔
+   *
+   * @returns 當前查詢建構器實例，支援鏈式調用
+   *
+   * @example
+   * ```typescript
+   * const trashedUsers = await query.onlyTrashed().get();
+   * ```
+   */
+  onlyTrashed() {
+    this.softDeleteMode = "only";
+    return this;
+  }
+  /**
+   * 軟刪除單一記錄
+   *
+   * 設置 deletedAt 為當前時間，而非真正刪除記錄
+   *
+   * @returns Promise 解析為更新結果
+   *
+   * @example
+   * ```typescript
+   * await query.where('_id', userId).softDelete();
+   * ```
+   */
+  async softDelete() {
+    const updateDoc = { $set: { deletedAt: /* @__PURE__ */ new Date() } };
+    const result = await this.nativeCollection.updateOne(this.toFilter(), updateDoc, {
+      session: this.session
+    });
+    return {
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+      acknowledged: result.acknowledged
+    };
+  }
+  /**
+   * 批次軟刪除
+   *
+   * 設置所有符合條件的文檔的 deletedAt 為當前時間
+   *
+   * @returns Promise 解析為更新結果
+   *
+   * @example
+   * ```typescript
+   * await query.where('status', 'inactive').softDeleteMany();
+   * ```
+   */
+  async softDeleteMany() {
+    const updateDoc = { $set: { deletedAt: /* @__PURE__ */ new Date() } };
+    const result = await this.nativeCollection.updateMany(this.toFilter(), updateDoc, {
+      session: this.session
+    });
+    return {
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+      acknowledged: result.acknowledged
+    };
+  }
+  /**
+   * 恢復軟刪除的記錄
+   *
+   * 將 deletedAt 設置為 null，恢復軟刪除的文檔
+   *
+   * @returns Promise 解析為更新結果
+   *
+   * @example
+   * ```typescript
+   * await query.where('_id', userId).restore();
+   * ```
+   */
+  async restore() {
+    const updateDoc = { $set: { deletedAt: null } };
+    const result = await this.nativeCollection.updateOne(this.toFilter(), updateDoc, {
+      session: this.session
+    });
+    return {
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+      acknowledged: result.acknowledged
+    };
+  }
+  /**
+   * 批次恢復軟刪除的記錄
+   *
+   * 將所有符合條件的文檔的 deletedAt 設置為 null
+   *
+   * @returns Promise 解析為更新結果
+   *
+   * @example
+   * ```typescript
+   * await query.onlyTrashed().restoreMany();
+   * ```
+   */
+  async restoreMany() {
+    const updateDoc = { $set: { deletedAt: null } };
+    const result = await this.nativeCollection.updateMany(this.toFilter(), updateDoc, {
+      session: this.session
+    });
+    return {
+      matchedCount: result.matchedCount,
+      modifiedCount: result.modifiedCount,
+      acknowledged: result.acknowledged
+    };
+  }
+  /**
+   * 強制刪除（真正刪除記錄）
+   *
+   * 永久刪除單一文檔，無法恢復
+   *
+   * @returns Promise 解析為刪除結果
+   *
+   * @example
+   * ```typescript
+   * await query.where('_id', userId).forceDelete();
+   * ```
+   */
+  async forceDelete() {
+    return await this.delete();
+  }
+  /**
+   * 批次強制刪除
+   *
+   * 永久刪除所有符合條件的文檔，無法恢復
+   *
+   * @returns Promise 解析為刪除結果
+   *
+   * @example
+   * ```typescript
+   * await query.where('createdAt', '<', oneYearAgo).forceDeleteMany();
+   * ```
+   */
+  async forceDeleteMany() {
+    return await this.deleteMany();
+  }
   /**
    * Executes a bulk write operation.
    *
@@ -757,17 +917,15 @@ var MongoQueryBuilder = class _MongoQueryBuilder {
   toFilter() {
     const hasMainFilters = Object.keys(this.filters).length > 0;
     const hasOrFilters = this.orFilters.length > 0;
+    let baseFilter;
     if (!hasOrFilters) {
-      return { ...this.filters };
-    }
-    if (!hasMainFilters) {
-      return {
-        $or: this.orFilters
-      };
+      baseFilter = { ...this.filters };
+    } else if (!hasMainFilters) {
+      baseFilter = { $or: this.orFilters };
+    } else {
+      baseFilter = { $or: [this.filters, ...this.orFilters] };
     }
-    return {
-      $or: [this.filters, ...this.orFilters]
-    };
+    return this.applySoftDeleteFilter(baseFilter);
   }
   /**
    * Creates a deep copy of the query builder.
@@ -795,6 +953,7 @@ var MongoQueryBuilder = class _MongoQueryBuilder {
     cloned.sortSpec = { ...this.sortSpec };
     cloned.limitCount = this.limitCount;
     cloned.skipCount = this.skipCount;
+    cloned.softDeleteMode = this.softDeleteMode;
     return cloned;
   }
   // ============================================================================
@@ -833,6 +992,34 @@ var MongoQueryBuilder = class _MongoQueryBuilder {
     }
     return { $set: update };
   }
+  /**
+   * 應用軟刪除過濾
+   *
+   * 根據 softDeleteMode 自動過濾已刪除的記錄
+   *
+   * @param filter - 基礎過濾條件
+   * @returns 包含軟刪除過濾的完整過濾條件
+   */
+  applySoftDeleteFilter(filter) {
+    if (this.softDeleteMode === "include") {
+      return filter;
+    }
+    if (this.softDeleteMode === "only") {
+      return {
+        ...filter,
+        deletedAt: { $ne: null }
+      };
+    }
+    const softDeleteFilter = {
+      $or: [{ deletedAt: null }, { deletedAt: { $exists: false } }]
+    };
+    if (Object.keys(filter).length === 0) {
+      return softDeleteFilter;
+    }
+    return {
+      $and: [filter, softDeleteFilter]
+    };
+  }
   async getObjectId() {
     if (_MongoQueryBuilder.ObjectIdCtor) {
       return _MongoQueryBuilder.ObjectIdCtor;
@@ -1210,12 +1397,38 @@ var MongoDatabaseWrapper = class {
     }
     await this.db.createCollection(name, createOptions);
   }
-  async setValidation(collectionName, schema) {
+  async setValidation(collectionName, schema2) {
     await this.db.command({
       collMod: collectionName,
-      validator: schema.validator,
-      validationLevel: schema.validationLevel ?? "strict",
-      validationAction: schema.validationAction ?? "error"
+      validator: schema2.validator,
+      validationLevel: schema2.validationLevel ?? "strict",
+      validationAction: schema2.validationAction ?? "error"
+    });
+  }
+  /**
+   * 使用 Schema Builder 建立 Collection
+   *
+   * 提供友善的 API 來建立帶有 Schema 驗證的 Collection
+   *
+   * @param name - Collection 名稱
+   * @param schemaBuilder - Schema Builder 實例
+   * @param options - 驗證選項（驗證等級、動作）
+   *
+   * @example
+   * ```typescript
+   * import { schema } from '@gravito/dark-matter'
+   *
+   * const userSchema = schema()
+   *   .required('name', 'email')
+   *   .string('name')
+   *   .string('email')
+   *
+   * await Mongo.database().createCollectionWithSchema('users', userSchema)
+   * ```
+   */
+  async createCollectionWithSchema(name, schemaBuilder, options) {
+    await this.createCollection(name, {
+      schema: schemaBuilder.toValidationOptions(options)
     });
   }
 };
@@ -1525,7 +1738,9 @@ var MongoGridFS = class {
       const reader = source.getReader();
       while (true) {
         const { done, value } = await reader.read();
-        if (done) break;
+        if (done) {
+          break;
+        }
         uploadStream.write(value);
       }
       uploadStream.end();
@@ -1594,6 +1809,190 @@ var MongoGridFS = class {
     const cursor = this.bucket.find(filter ?? {});
     return await cursor.toArray();
   }
+  /**
+   * 串流上傳檔案
+   *
+   * 支援進度回調的串流上傳，適合大檔案上傳
+   *
+   * @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}%`)
+   * })
+   * ```
+   */
+  async uploadStream(stream, options, onProgress) {
+    await this.ensureBucket();
+    const uploadStream = this.bucket.openUploadStream(options.filename, {
+      chunkSizeBytes: options.chunkSizeBytes,
+      metadata: options.metadata,
+      contentType: options.contentType
+    });
+    let bytesWritten = 0;
+    const reader = stream.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        uploadStream.write(Buffer.from(value));
+        bytesWritten += value.length;
+        if (onProgress) {
+          onProgress({
+            bytesWritten,
+            totalBytes: 0,
+            // 串流無法預知總大小
+            percentage: 0
+          });
+        }
+      }
+      uploadStream.end();
+      return new Promise((resolve, reject) => {
+        uploadStream.on("finish", () => resolve(uploadStream.id.toString()));
+        uploadStream.on("error", reject);
+      });
+    } catch (error) {
+      uploadStream.abort();
+      throw error;
+    }
+  }
+  /**
+   * 串流下載檔案
+   *
+   * 返回 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) {
+    return new ReadableStream({
+      start: async (controller) => {
+        try {
+          await this.ensureBucket();
+          const { ObjectId } = await import("mongodb");
+          const downloadStream = this.bucket.openDownloadStream(new ObjectId(fileId));
+          downloadStream.on("data", (chunk) => {
+            controller.enqueue(new Uint8Array(chunk));
+          });
+          downloadStream.on("end", () => {
+            controller.close();
+          });
+          downloadStream.on("error", (error) => {
+            controller.error(error);
+          });
+        } catch (error) {
+          controller.error(error);
+        }
+      },
+      cancel: async () => {
+      }
+    });
+  }
+  /**
+   * 分片上傳大檔案
+   *
+   * 支援進度追蹤的大檔案上傳，自動處理分片
+   *
+   * @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}`)
+   * })
+   * ```
+   */
+  async uploadLargeFile(file, options, onProgress) {
+    await this.ensureBucket();
+    const chunkSize = options.chunkSizeBytes ?? 255 * 1024;
+    const totalBytes = file.size;
+    let bytesWritten = 0;
+    const uploadStream = this.bucket.openUploadStream(options.filename, {
+      chunkSizeBytes: chunkSize,
+      metadata: { ...options.metadata, totalSize: totalBytes },
+      contentType: options.contentType
+    });
+    const stream = file.stream();
+    const reader = stream.getReader();
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          break;
+        }
+        uploadStream.write(Buffer.from(value));
+        bytesWritten += value.length;
+        if (onProgress) {
+          onProgress({
+            bytesWritten,
+            totalBytes,
+            percentage: Math.round(bytesWritten / totalBytes * 100)
+          });
+        }
+      }
+      uploadStream.end();
+      return new Promise((resolve, reject) => {
+        uploadStream.on("finish", () => resolve(uploadStream.id.toString()));
+        uploadStream.on("error", reject);
+      });
+    } catch (error) {
+      uploadStream.abort();
+      throw error;
+    }
+  }
+  /**
+   * 取得檔案中繼資料
+   *
+   * 查詢檔案資訊但不下載內容
+   *
+   * @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}`)
+   * }
+   * ```
+   */
+  async findById(fileId) {
+    await this.ensureBucket();
+    const { ObjectId } = await import("mongodb");
+    const cursor = this.bucket.find({ _id: new ObjectId(fileId) });
+    const files = await cursor.toArray();
+    return files.length > 0 ? files[0] : null;
+  }
   async ensureBucket() {
     if (!this.bucket) {
       throw new Error("GridFS bucket not initialized. Please wait a moment after creation.");
@@ -1656,6 +2055,254 @@ var MongoPoolMonitor = class {
     };
   }
 };
+
+// src/MongoSchemaBuilder.ts
+var MongoSchemaBuilder = class _MongoSchemaBuilder {
+  schema = {
+    bsonType: "object",
+    required: [],
+    properties: {}
+  };
+  /**
+   * 定義必填欄位
+   *
+   * @param fields - 必填欄位名稱列表
+   * @returns 當前 Schema Builder 實例
+   *
+   * @example
+   * ```typescript
+   * schema().required('name', 'email', 'age')
+   * ```
+   */
+  required(...fields) {
+    this.schema.required = [...this.schema.required, ...fields];
+    return 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, options) {
+    const property = { bsonType: "string" };
+    if (options?.minLength !== void 0) {
+      property.minLength = options.minLength;
+    }
+    if (options?.maxLength !== void 0) {
+      property.maxLength = options.maxLength;
+    }
+    if (options?.pattern) {
+      property.pattern = options.pattern;
+    }
+    if (options?.enum) {
+      property.enum = options.enum;
+    }
+    ;
+    this.schema.properties[field] = property;
+    return 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, options) {
+    const property = { bsonType: "number" };
+    if (options?.minimum !== void 0) {
+      property.minimum = options.minimum;
+    }
+    if (options?.maximum !== void 0) {
+      property.maximum = options.maximum;
+    }
+    if (options?.exclusiveMinimum) {
+      property.exclusiveMinimum = true;
+    }
+    if (options?.exclusiveMaximum) {
+      property.exclusiveMaximum = true;
+    }
+    ;
+    this.schema.properties[field] = property;
+    return this;
+  }
+  /**
+   * 定義整數欄位
+   *
+   * @param field - 欄位名稱
+   * @param options - 整數選項（最小值、最大值）
+   * @returns 當前 Schema Builder 實例
+   *
+   * @example
+   * ```typescript
+   * schema()
+   *   .integer('age', { minimum: 0, maximum: 150 })
+   *   .integer('count')
+   * ```
+   */
+  integer(field, options) {
+    const property = { bsonType: "int" };
+    if (options?.minimum !== void 0) {
+      property.minimum = options.minimum;
+    }
+    if (options?.maximum !== void 0) {
+      property.maximum = options.maximum;
+    }
+    ;
+    this.schema.properties[field] = property;
+    return this;
+  }
+  /**
+   * 定義布林欄位
+   *
+   * @param field - 欄位名稱
+   * @returns 當前 Schema Builder 實例
+   *
+   * @example
+   * ```typescript
+   * schema().boolean('isActive').boolean('verified')
+   * ```
+   */
+  boolean(field) {
+    ;
+    this.schema.properties[field] = {
+      bsonType: "bool"
+    };
+    return this;
+  }
+  /**
+   * 定義日期欄位
+   *
+   * @param field - 欄位名稱
+   * @returns 當前 Schema Builder 實例
+   *
+   * @example
+   * ```typescript
+   * schema().date('createdAt').date('updatedAt')
+   * ```
+   */
+  date(field) {
+    ;
+    this.schema.properties[field] = {
+      bsonType: "date"
+    };
+    return 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, itemType, options) {
+    const property = {
+      bsonType: "array",
+      items: { bsonType: itemType }
+    };
+    if (options?.minItems !== void 0) {
+      property.minItems = options.minItems;
+    }
+    if (options?.maxItems !== void 0) {
+      property.maxItems = options.maxItems;
+    }
+    if (options?.uniqueItems) {
+      property.uniqueItems = true;
+    }
+    ;
+    this.schema.properties[field] = property;
+    return 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, callback) {
+    const nestedBuilder = new _MongoSchemaBuilder();
+    callback(nestedBuilder);
+    this.schema.properties[field] = nestedBuilder.build();
+    return this;
+  }
+  /**
+   * 建構最終的 JSON Schema
+   *
+   * @returns JSON Schema 物件
+   *
+   * @example
+   * ```typescript
+   * const schema = schema()
+   *   .required('name')
+   *   .string('name')
+   *   .build()
+   * ```
+   */
+  build() {
+    return this.schema;
+  }
+  /**
+   * 轉換為 MongoDB 驗證選項
+   *
+   * @param options - 驗證選項（驗證等級、動作）
+   * @returns MongoDB Schema 驗證選項
+   *
+   * @example
+   * ```typescript
+   * const options = schema()
+   *   .required('name')
+   *   .string('name')
+   *   .toValidationOptions({ validationLevel: 'moderate' })
+   * ```
+   */
+  toValidationOptions(options) {
+    return {
+      validator: { $jsonSchema: this.schema },
+      validationLevel: options?.validationLevel ?? "strict",
+      validationAction: options?.validationAction ?? "error"
+    };
+  }
+};
+function schema() {
+  return new MongoSchemaBuilder();
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Mongo,
@@ -1664,5 +2311,7 @@ var MongoPoolMonitor = class {
   MongoGridFS,
   MongoManager,
   MongoPoolMonitor,
-  MongoQueryBuilder
+  MongoQueryBuilder,
+  MongoSchemaBuilder,
+  schema
 });