WOrmMdb - Documentation

new WOrmMdb(optopt) → {Object}

Description:

操作Access mdb資料庫

註: 主鍵欄位取自opt.pk，預設為id，支援由呼叫端指定註: 本套件經connMDB.exe操作Windows內建之Jet 4.0引擎，僅支援.mdb(Jet4)不支援.accdb 註: Jet引擎之字串比對不分大小寫，故主鍵之[命中]認定亦不分大小寫，且select之記憶體過濾層已一併對齊(見queryMemory.mjs)，令兩者判定一致註: sqlite之NOCASE僅折疊ASCII之A-Z，與Jet對部分非ASCII字元之折疊不同，故僅大小寫相異之非ASCII主鍵於select與selectByPk仍可能判定不一致註: insert與save之原子性倚賴資料表主鍵欄位具唯一約束(PRIMARY KEY)，資料表建立時須含之

Source:

WOrmMdb.mjs, line 75

Parameters:

Name Type Attributes Default Description

opt

Object

{}

輸入設定物件，預設{}

Properties

Name	Type	Attributes	Default	Description
`url`	String	<optional>	`'mdb://username:password'`	輸入連接資料庫字串，資料庫僅可選'mdb'，預設'mdb://username:password'
`storage`	String	<optional>	`'./worm.mdb'`	輸入mdb資料庫檔案位置字串，預設'./worm.mdb'
`useEncryption`	Boolean	<optional>	`false`	輸入是否使用加密保護，型別為布林值，預設false
`db`	String	<optional>	`'worm'`	輸入使用資料庫名稱字串，mdb並不需要給只是配合w-orm系列統一設定，預設'worm'
`cl`	String	<optional>	`'test'`	輸入使用資料表名稱字串，預設'test'
`fdModels`	String	<optional>	`'./models'`	輸入資料表設定檔所在資料夾字串，預設'./models'
`modelType`	String	<optional>	`'js'`	輸入資料表設定檔類型字串，可有'js'、'json'，預設'js'
`logging`	Boolean	<optional>	`false`	輸入是否輸出實際執行的sql指令布林值，預設false
`pk`	String	<optional>	`'id'`	輸入數據主鍵字串，預設'id'
`autoGenPk`	Boolean	<optional>	`true`	輸入若數據主鍵欄位沒給時則自動給予隨機uuid，型別為布林值，預設true
`useStable`	Boolean	<optional>	`true`	輸入是否使用穩定模式，使用佇列管理同時只能進行一種操作故會犧牲效能，型別為布林值，預設true

Returns:

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

Type: Object

Methods

(async, static) closeSequelize() → {Promise}

Description:

關閉sequelize

Source:

WOrmMdb.mjs, line 371

Returns:

回傳Promise，resolve代表關閉成功，reject回傳錯誤訊息

Type: Promise

(async, static) createStorage() → {Promise}

Description:

創建mdb資料庫檔案

註: 建出者為空庫，資料表需另建

Source:

WOrmMdb.mjs, line 1611

Returns:

回傳Promise，resolve回傳創建結果，reject回傳錯誤訊息

Type: Promise

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

Description:

刪除數據

註: 回傳陣列恆與輸入等長，各筆之n與nDeleted皆為主鍵命中筆數，值為0或1，未命中為0且屬正常結果註: 判斷某筆是否真的被刪除一律以nDeleted為準註: 未帶有效主鍵者為該筆之輸入問題，回ok為0與err且不送查詢條件(以免無效值被轉為null而誤中其他數據)，不中斷其餘筆數，以此與[主鍵未命中]之ok為1區辨註: 本函數不受opt.autoGenPk影響，於任一設定下皆不補值註: 由DELETE語句自身之影響列數判定命中，不另行查詢以免多一次往返且與刪除間存在競態

Source:

WOrmMdb.mjs, line 1325

Parameters:

Name Type Attributes Default Description

data

Object | Array

輸入數據物件或陣列，會查找各數據的opt.pk值，有存在者就刪除

option

Object

{}

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

Properties

Name	Type	Attributes	Default	Description
`instance`	Object	<optional>	`null`	輸入實例instance物件，預設為null

Returns:

回傳Promise，resolve回傳與輸入等長之刪除結果陣列[{n,nDeleted,ok}]，reject回傳錯誤訊息

Type: Promise

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

Description:

依條件刪除多筆數據，需與del分開，避免未傳數據導致直接刪除全表

註: n與nDeleted皆為實際刪除筆數，兩者恆相等，n不得取全表筆數註: find未給或為空物件時刪除全部數據；條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤註: 帶條件時先以與select相同之記憶體過濾取得命中數據之主鍵清單，再依主鍵清單刪除，令刪除範圍與select(find)之結果完全一致；若逕將條件送Jet，因Access不支援$in、$nin、$regex等運算子，會出現[select查得到但delAll刪不到]或反之之不一致註: 分批之DELETE以交易包覆，令任一批失敗時整體回滾而不留下部份刪除

Source:

WOrmMdb.mjs, line 1486

Parameters:

Name Type Attributes Default Description

find

Object

{}

輸入刪除條件物件，不給予find則代表刪除全部數據

option

Object

{}

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

Properties

Name	Type	Attributes	Default	Description
`instance`	Object	<optional>	`null`	輸入實例instance物件，預設為null

Returns:

回傳Promise，resolve回傳刪除結果{n,nDeleted,ok}，reject回傳錯誤訊息

Type: Promise

(static) genModelsByTabs(fdopt, tabsopt, optopt)

Description:

由資料表物件生成各資料表的models資料

Source:

WOrmMdb.mjs, line 1642

Parameters:

Name Type Attributes Default Description

fd

String

'./models'

輸入models儲存的資料夾名稱字串，預設'./models'

tabs

Object

{}

輸入各資料表物件，預設{}

opt

Object

{}

輸入設定物件，預設{}

Properties

Name	Type	Attributes	Default	Description
`type`	String	<optional>	`'js'`	輸入資料表類型字串，預設'js'

(async, static) initAdodb() → {Promise}

Description:

初始化操作實例

註: connMDB.exe為one-shot程序，每次呼叫各自開啟與關閉連線，故實例本身不持有資料庫連線； sequelize僅用於匯入models以取得欄位定義，不承載任何數據

Source:

WOrmMdb.mjs, line 336

Returns:

回傳Promise，resolve回傳實例物件，reject回傳錯誤訊息

Type: Promise

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

Description:

插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫

由Jet於主鍵之唯一約束上原子完成[檢查主鍵不存在]與[寫入]，併發時同一主鍵僅有一次成功

註: n為輸入筆數即本次嘗試插入之基準，nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果註: 同批含重複主鍵時僅首筆計入nInserted，其餘視為已存在註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入註: 全部插入語句於單次呼叫exe內循序送出且不因單筆衝突而中止，故一次往返即可取得精確之nInserted 註: option.returnList為true時改回傳與輸入等長且保序之逐筆陣列[{n,nInserted,ok}]，供呼叫端得知[是哪幾筆]為新資料而非僅[有幾筆]；逐筆元素之n與ok恆為1，因insert之任何錯誤皆屬整批性錯誤而reject，故不出現ok為0與err。回傳形式之切換為靜態，僅由本選項之取值決定，不因數據內容或執行結果而變

Source:

WOrmMdb.mjs, line 723

Parameters:

Name Type Attributes Default Description

data

Object | Array

輸入數據物件或陣列

option

Object

{}

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

Properties

Name	Type	Attributes	Default	Description
`instance`	Object	<optional>	`null`	輸入實例instance物件，預設為null
`returnList`	Boolean	<optional>	`false`	輸入是否改回傳與輸入等長之逐筆結果陣列，預設為false

Returns:

回傳Promise，resolve回傳插入結果{n,nInserted,ok}，或於option.returnList為true時回傳[{n,nInserted,ok}]，reject回傳錯誤訊息

Type: Promise

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

Description:

批次插入數據，全批視為一個單位：全部插入成功，或一筆都不寫入

本函數非insert之加速版，兩者衝突政策不同：insert於主鍵已存在時跳過該筆且整批ok為1，本函數則整批reject且不寫入任何一筆，同批含重複主鍵者亦視為衝突。確無衝突時兩者之可觀察結果完全相同，差異僅於有衝突時顯現。

註: n為輸入筆數即本次嘗試插入之基準；nInserted於成功時恆等於n，雖無額外資訊仍保留，令呼叫端得與insert共用同一段結果處理程式碼註: 不提供逐筆結果，故不出現ok為0與err；需要逐筆處置者改用insert 註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入註: [全有全無]以Jet之交易(OleDbTransaction)包覆全部插入語句達成，任一筆失敗即回滾，故reject之後資料庫狀態與呼叫前相同，無須補償動作；同批含重複主鍵者亦於交易內被偵測為衝突

Source:

WOrmMdb.mjs, line 894

Parameters:

Name Type Attributes Default Description

data

Object | Array

輸入數據物件或陣列

option

Object

{}

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

Properties

Name	Type	Attributes	Default	Description
`instance`	Object	<optional>	`null`	輸入實例instance物件，預設為null

Returns:

回傳Promise，resolve回傳插入結果{n,nInserted,ok}，reject回傳錯誤訊息

Type: Promise

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

Description:

儲存數據，以主鍵為準更新既有數據，未給之欄位保留；主鍵不存在且option.autoInsert為true(預設)時改為插入

採條件寫入配合衝突偵測與重試: 每次寫入本身為單一條件式原子語句——插入由主鍵之唯一約束判定、更新由WHERE主鍵之比對判定，皆非由預讀值決定其成敗；預讀僅用於選擇發出哪一條語句，選錯不會產生錯誤結果，只會被偵測並重試(插入撞既有主鍵、更新未命中任何列)，故縱使預讀值已過期，最終結果仍與該次操作單獨執行時相同。

註: 回傳陣列恆與輸入等長，輸入單一物件亦回傳長度1之陣列註: n為主鍵命中筆數，值為0或1，命中(不論內容有無變更)或經插入而產生皆為1；nInserted與nModified恆同時出現註: [內容相同]之判定基準為將待寫入物件合併進現值後與現值相同，非待寫入物件與現值全等，故只給部份欄位且該些欄位值皆與現值相同時，合併結果等於現值，nModified為0。合併取淺層以與Jet整欄取代之寫入行為一致，令nModified忠實反映資料庫端是否真的寫入註: 不以UPDATE之影響列數決定nModified，因Jet之影響列數為[符合WHERE之列數]而非[內容真的有變之列數] (已實測: 將欄位設為與現值相同之值仍回報影響1列) 註: 本筆失敗不中斷整批，該筆以ok為0並附err回報註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入註: 各回合之預讀與寫入皆整批送出，故N筆數據於無衝突時僅需2次呼叫exe而非2N次

Source:

WOrmMdb.mjs, line 1021

Parameters:

Name Type Attributes Default Description

data

Object | Array

輸入數據物件或陣列

option

Object

{}

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

Properties

Name	Type	Attributes	Default	Description
`instance`	Object	<optional>	`null`	輸入實例instance物件，預設為null
`autoInsert`	Boolean	<optional>	`true`	輸入是否於儲存時發現原本無數據，則自動改以插入處理，預設為true

Returns:

回傳Promise，resolve回傳與輸入等長之儲存結果陣列[{n,nInserted,nModified,ok}]，reject回傳錯誤訊息

Type: Promise

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

Description:

查詢數據

註: 恆回傳陣列，無符合數據回傳空陣列而不回傳null 註: find未給或為空物件時回傳全部數據註: 本函數不得有副作用，故不創建資料表

Source:

WOrmMdb.mjs, line 526

Parameters:

Name Type Attributes Default Description

find

Object

{}

輸入查詢條件物件

option

Object

{}

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

Properties

Name	Type	Attributes	Default	Description
`instance`	Object	<optional>	`null`	輸入實例instance物件，預設為null

Returns:

回傳Promise，resolve回傳數據陣列，reject回傳錯誤訊息

Type: Promise

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

Description:

由主鍵查詢單筆數據，因由Jet依主鍵取值且僅回傳單筆，不需如select提取全部數據再過濾，故數據量大時效能較佳

註: 主鍵欄位取自opt.pk，預設為id，支援由呼叫端指定註: 主鍵未命中或主鍵值無效皆回傳null而不reject，[命中]之判定基準與insert、save、del內對既有數據之認定一致註: Jet之字串比對不分大小寫，故主鍵之命中判定亦不分大小寫註: 本函數不得有副作用，故不創建資料表

Source:

WOrmMdb.mjs, line 592

Parameters:

Name Type Attributes Default Description

pk

String | Number

輸入主鍵值，即數據內opt.pk欄位之值

option

Object

{}

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

Properties

Name	Type	Attributes	Default	Description
`instance`	Object	<optional>	`null`	輸入實例instance物件，預設為null

Returns:

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

Type: Promise