WOrmMongodb

WOrmMongodb

new WOrmMongodb(optopt) → {Object}

Description:

  • 操作資料庫(MongoDB)

    本套件之主鍵欄位固定為id，尚未支援由呼叫端指定。id為無業務語義之識別碼。 opt.autoGenPk預設為true，insert、save與insertGfs於輸入未帶有效id時自動產生；del於任一設定下皆不補值。 opt.autoGenPk為false時套件一律不產生id，未帶有效id者以reject拋出，且id之唯一性與格式皆由呼叫端自負。

Source:
Parameters:
Name Type Attributes Default Description
opt Object <optional>
 {}

輸入設定物件，預設{}

Properties
Name Type Attributes Default Description
url String <optional>
 'mongodb://127.0.0.1:27017'

輸入連接資料庫字串，預設'mongodb://127.0.0.1:27017'
db String <optional>
 'worm'

輸入使用資料庫名稱字串，預設'worm'
cl String <optional>
 'test'

輸入使用資料表名稱字串，預設'test'
autoGenPk Boolean <optional>
 true

輸入是否於輸入未帶有效主鍵時自動產生主鍵值，預設true。為false時主鍵須由呼叫端自備，屬依賴注入之定位，主鍵之唯一性、格式與是否與既有資料衝突皆由呼叫端自負。本設定為建構層設定，不得於insert與save之option逐次覆寫
Returns:

回傳操作資料庫物件，各事件功能詳見說明

Type
Object

Methods

(async, static) del(data) → {Promise}

Description:

  • 刪除數據 註: n為id命中筆數；未帶有效id者視為本筆無法處理，不送查詢條件且以ok為0並附err回報； 判斷本筆是否真的被刪除一律以nDeleted為準

Source:
Parameters:
Name Type Description
data Object | Array

輸入數據物件或陣列
Returns:

回傳Promise，resolve回傳與輸入等長之刪除結果陣列，reject回傳錯誤訊息

Type
Promise

(async, static) delAll(findopt) → {Promise}

Description:

  • 刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表 註: n為實際刪除筆數，恆等於nDeleted；條件無命中時回傳0亦屬正常結果

Source:
Parameters:
Name Type Attributes Default Description
find Object <optional>
 {}

輸入刪除條件物件
Returns:

回傳Promise，resolve回傳刪除結果，reject回傳錯誤訊息

Type
Promise

(async, static) delAllGfs(findopt) → {Promise}

Description:

  • 使用GridFS，刪除全部數據，需與delGfs分開，避免未傳數據導致直接刪除全部 註: n為實際刪除筆數，恆等於nDeleted；條件無命中時回傳0亦屬正常結果 本函數不建立唯一索引，以免既有數據尚存重複id時無法清除

Source:
Parameters:
Name Type Attributes Default Description
find Object <optional>
 {}

輸入刪除條件物件
Returns:

回傳Promise，resolve回傳刪除結果，reject回傳錯誤訊息

Type
Promise

(async, static) delGfs(data) → {Promise}

Description:

  • 使用GridFS，刪除數據 註: n為id命中筆數；未帶有效id者視為本筆無法處理，以ok為0並附err回報； 判斷本筆是否真的被刪除一律以nDeleted為準

Source:
Parameters:
Name Type Description
data Object | Array

輸入數據物件或陣列，各數據物件須帶id
Returns:

回傳Promise，resolve回傳與輸入等長之刪除結果陣列，reject回傳錯誤訊息

Type
Promise

(async, static) insert(data, optionopt) → {Promise}

Description:

  • 插入數據，僅於id不存在時寫入，已存在者跳過且不覆寫 由MongoDB於唯一索引上原子完成[檢查id未存在]與[寫入]，併發時同一id僅有一次成功 註: 預設回傳單一聚合物件，n為輸入筆數，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果 註: option.returnList為true時改回與輸入等長且保序之逐筆陣列，供呼叫端得知[是哪幾筆]為新數據， 聚合計數僅能回答[有幾筆]，而去重類呼叫端須知何者為新方能對其執行下游動作 註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入

Source:
Parameters:
Name Type Attributes Default Description
data Object | Array

輸入數據物件或陣列
option Object <optional>
 {}

輸入設定物件，預設為{}

Properties
Name Type Attributes Default Description
returnList Boolean <optional>
 false

輸入是否改回逐筆結果陣列，預設為false。為true時回傳與輸入等長且保序之陣列，各元素為{ n, nInserted, ok }，已插入者nInserted為1、已存在而跳過者為0
Returns:

回傳Promise，resolve回傳插入結果，returnList為true時回傳逐筆結果陣列，reject回傳錯誤訊息

Type
Promise

(async, static) insertBulk(data) → {Promise}

Description:

  • 批次插入數據，全批視為一個單位：全部插入成功，或一筆都不寫入 任一筆之id已存在(含同批含重複id)即以reject拋出整批性錯誤，且不寫入任何一筆 註: 本函數非insert之加速版，兩者衝突政策不同——insert跳過已存在者而整批ok為1， 本函數則整批reject；需要逐筆處置者改用insert 註: n為輸入筆數，nInserted於成功時恆等於n；不提供逐筆結果，故不出現ok為0與err 註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入 註: 全有全無之達成方式依部署而異——具replica set或分片叢集者以交易包覆， standalone無交易可用而以補償動作達成，其限制詳見_insertBulkByCompensate

Source:
Parameters:
Name Type Description
data Object | Array

輸入數據物件或陣列
Returns:

回傳Promise，resolve回傳插入結果，reject回傳錯誤訊息

Type
Promise

(async, static) insertGfs(data) → {Promise}

Description:

  • 使用GridFS，插入數據，僅於id不存在時寫入，已存在者跳過且不覆寫 數據物件形狀為{ id, u8a }，u8a須為Uint8Array 註: n為輸入筆數，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果 註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入

Source:
Parameters:
Name Type Description
data Object | Array

輸入數據物件或陣列，各數據物件形狀為{ id, u8a }
Returns:

回傳Promise，resolve回傳插入結果，reject回傳錯誤訊息

Type
Promise

(async, static) save(data, optionopt) → {Promise}

Description:

  • 儲存數據，以id為準更新既有數據，未給之欄位會保留；id不存在且option.autoInsert為true時改為插入 註: n為id命中筆數，命中或經插入而產生皆為1；[內容相同]之判定基準為將待儲存物件合併進現值後結果與現值相同， 相同者不寫入而nModified為0；本筆失敗不中斷整批，該筆以ok為0並附err回報 註: opt.autoGenPk為true(預設)時未帶有效id者自動產生，為false時未帶有效id即reject且同批皆不寫入

Source:
Parameters:
Name Type Attributes Default Description
data Object | Array

輸入數據物件或陣列
option Object <optional>
 {}

輸入設定物件，預設為{}

Properties
Name Type Attributes Default Description
autoInsert boolean <optional>
 true

輸入是否於儲存時發現原本無數據，則自動改以插入處理，預設為true
Returns:

回傳Promise，resolve回傳與輸入等長之儲存結果陣列，reject回傳錯誤訊息

Type
Promise

(async, static) select(findopt) → {Promise}

Description:

  • 查詢數據

Source:
Parameters:
Name Type Attributes Default Description
find Object <optional>
 {}

輸入查詢條件物件
Returns:

回傳Promise，resolve回傳數據陣列，無符合數據回傳空陣列，reject回傳錯誤訊息

Type
Promise

(async, static) selectByPk(pk) → {Promise}

Description:

  • 由主鍵查詢單筆數據，因由MongoDB查找且僅回傳單筆，不需如select提取全部符合數據再處理，故數據量大時效能較佳 註: 本套件之主鍵欄位固定為id，尚未支援由呼叫端指定 註: 本函數不得有副作用，故不建立唯一索引

Source:
Parameters:
Name Type Description
pk String

輸入主鍵值字串，即數據之id
Returns:

回傳Promise，resolve回傳數據物件，若無此主鍵或主鍵值無效則回傳null，reject回傳錯誤訊息

Type
Promise

(async, static) selectByPkGfs(pk) → {Promise}

Description:

  • 使用GridFS，由主鍵查詢單筆數據 註: 查無數據或主鍵值無效時回傳null，判定基準與selectByPk一致 註: 本套件之主鍵欄位固定為id，尚未支援由呼叫端指定 本函數不得有副作用，故不建立唯一索引

Source:
Parameters:
Name Type Description
pk String

輸入主鍵值字串，即數據之id
Returns:

回傳Promise，resolve回傳數據物件{ id, u8a }，若無此主鍵或主鍵值無效則回傳null，reject回傳錯誤訊息

Type
Promise