w-serv-orm 1.1.6 → 1.1.8

package/docs/WServOrm.html

@@ -74,13 +74,27 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>產生伺服器ORM的支援物件</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>產生伺服器ORM的支援物件</p>
+<p>每次呼叫各自建立資料表ORM、設定與擴充函數，同一行程內之多個實例互不干擾；同一url與db之資料庫資源能否並存，依所用ORM而定。</p>
+<p>procOrm之save、del與mix，於ORM回傳之逐筆結果有任一筆ok為0(單筆失敗)時reject，訊息列出失敗筆之主鍵，如'failed to save data: id[b]'(超過100字元者截斷顯示；無有效主鍵者以data[k]列其於輸入內之位置，k自0起；超過10筆者只列前10筆並附總筆數)，錯誤原文另由console.log輸出。
+單筆失敗不中斷整批，故reject時其餘筆數已寫入。
+mix之各步驟遇單筆失敗不中斷後續步驟，待全部步驟完成後一併reject；遇整批性錯誤則立即reject，後續步驟不執行。</p>
+<p>insert、save與mix之新增、修改，數據未帶有效主鍵(非空字串或數字)者，若資料表之主鍵欄為id且為字串型(或型別未知)，由本套件產生主鍵(同各ORM之genIDSeq)並於resolve時回傳；無欄位之數據不補。
+reject時不回傳補出之主鍵，故重送未帶主鍵之數據會再產生新主鍵而重複寫入，需冪等重送者請自帶主鍵；save帶主鍵者重送以主鍵覆寫，del重送時已刪除者為主鍵未命中。
+insert(含mix之新增)為主鍵已存在即略過之冪等新增，回傳之id含被略過者；recover亦以insert還原，故資料表須先清空。
+insert、save與mix之新增、修改，寫入前各欄位之字串皆經wsemi之clearXSS清除(白名單外之標籤轉義，白名單內之標籤刪除白名單外之屬性與危險網址，標籤外之文字只轉義會開始標籤之&lt;，故'a &lt; b'等數學式不改寫)；select與del不經清除。
+字串主鍵若會被清除改寫(含HTML標記，如&lt;後緊接英文字母)，整批reject且不寫入任何一筆(mix於任何步驟之前檢查新增與修改)，訊息列其位置而不回顯主鍵，如'failed to save data, id contains HTML markup: data[1]'；否則改寫後之主鍵與呼叫端所持者不同，以原主鍵查詢與刪除皆找不到。</p>
+<p>擴充函數(addFunCheck、addFunPreProcessing、addFunPostProcessing)屬於各實例，重建實例後須重新註冊；註冊時須傳入函數，否則立即拋錯(addFunCheck另令該實例之procOrm一律reject)；註冊後約1毫秒(以計時器)才生效，在此之前之procOrm呼叫不會套用。
+呼叫契約：check以reject或拋錯阻擋，回傳值不影響結果，且早於前處理執行；前處理逐一呼叫，各收新建之參數物件{woName,userId,isAdmin,mode,input}，input為前一個回傳之input，回傳須為含input之物件否則reject；後處理逐一呼叫，各收新建之參數物件且其output為前一個之回傳值，最後之回傳值即為procOrm之回傳值。
+後處理只在使用者檢查、check、前處理與ORM操作皆成功後執行，逐筆失敗(含del)或mix部分寫入後reject者皆不執行；後處理自身亦可reject。後處理之input為呼叫端傳入之數據，不含本套件補出之主鍵，主鍵見output。
+如需觀察ORM實際寫入，可另監聽woItems內各ORM之change與error事件；惟事件由ORM發出，不含userId與isAdmin，mix會依步驟分次發出，經woItems直接寫入者亦會發出，insert之結果為聚合計數而非逐筆。
+錯誤型別：procOrm由本套件產生之reject一律為英文訊息字串(供前端顯示或對應多語系；ORM之錯誤原文另由console.log輸出而不轉出)，呼叫端提供之函數(getUserById與擴充函數)自身之reject或拋錯則原樣轉出；建構(設定或ORM無效)、擴充函數註冊、backup與recover由本套件產生之錯誤一律為Error，ORM之錯誤則原樣轉出。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WServOrm.mjs.html">WServOrm.mjs</a>, <a href="WServOrm.mjs.html#line82">line 82</a>
+        <a href="WServOrm.mjs.html">WServOrm.mjs</a>, <a href="WServOrm.mjs.html#line100">line 100</a>
     </li></ul></dd>
     
 
@@ -441,7 +455,7 @@
                 </td>
             
 
-            <td class="description last"><p>輸入當useCheckUser=true時依照使用者ID取得使用者資訊物件函數，預設null</p></td>
+            <td class="description last"><p>輸入當useCheckUser=true時依照使用者ID取得使用者資訊物件函數，預設null；建構時不檢查，未給或非函數時useCheckUser為true之procOrm呼叫一律reject</p></td>
         </tr>
 
     
@@ -481,7 +495,7 @@
                 </td>
             
 
-            <td class="description last"><p>輸入使用ORM的select方法時是否自動刪除數據內isActive欄位之布林值，預設true</p></td>
+            <td class="description last"><p>輸入非管理者使用procOrm之select時是否濾除isActive為'n'之數據布林值，預設true</p></td>
         </tr>
 
     
@@ -514,7 +528,7 @@
 
         
 <div class="param-desc">
-    <p>回傳通訊物件，可監聽事件open、error、clientChange、execute、broadcast、deliver，可使用函數broadcast</p>
+    <p>回傳伺服器ORM支援物件，含woItems(各資料表ORM實例)、procOrm(資料操作函數，輸入為userId、woName、mode、input)、addFunCheck、addFunPreProcessing、addFunPostProcessing、closeAll(逐一關閉各資料表ORM之連線)，以及backup(woItems)與recover(fp, woItems, genModels, needCreateStorage)；後兩者不綁定本實例，須自行傳入woItems(須為非空物件，否則reject)，其參數順序與getDb之recover(woItems, fp, opt)不同；recover於寫入前驗證備份內容(須為非空陣列且各筆之name為woItems內之資料表)，失敗時reject，逐表寫入時中途失敗則先前之表已寫入</p>
 </div>
 
 
@@ -573,7 +587,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Oct 11 2026 15:00:09 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Oct 12 2026 13:45:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WServOrm.mjs.html

@@ -56,6 +56,24 @@ import getProc from './getProc.mjs'
 /**
  * 產生伺服器ORM的支援物件
  *
+ * 每次呼叫各自建立資料表ORM、設定與擴充函數，同一行程內之多個實例互不干擾；同一url與db之資料庫資源能否並存，依所用ORM而定。
+ *
+ * procOrm之save、del與mix，於ORM回傳之逐筆結果有任一筆ok為0(單筆失敗)時reject，訊息列出失敗筆之主鍵，如'failed to save data: id[b]'(超過100字元者截斷顯示；無有效主鍵者以data[k]列其於輸入內之位置，k自0起；超過10筆者只列前10筆並附總筆數)，錯誤原文另由console.log輸出。
+ * 單筆失敗不中斷整批，故reject時其餘筆數已寫入。
+ * mix之各步驟遇單筆失敗不中斷後續步驟，待全部步驟完成後一併reject；遇整批性錯誤則立即reject，後續步驟不執行。
+ *
+ * insert、save與mix之新增、修改，數據未帶有效主鍵(非空字串或數字)者，若資料表之主鍵欄為id且為字串型(或型別未知)，由本套件產生主鍵(同各ORM之genIDSeq)並於resolve時回傳；無欄位之數據不補。
+ * reject時不回傳補出之主鍵，故重送未帶主鍵之數據會再產生新主鍵而重複寫入，需冪等重送者請自帶主鍵；save帶主鍵者重送以主鍵覆寫，del重送時已刪除者為主鍵未命中。
+ * insert(含mix之新增)為主鍵已存在即略過之冪等新增，回傳之id含被略過者；recover亦以insert還原，故資料表須先清空。
+ * insert、save與mix之新增、修改，寫入前各欄位之字串皆經wsemi之clearXSS清除(白名單外之標籤轉義，白名單內之標籤刪除白名單外之屬性與危險網址，標籤外之文字只轉義會開始標籤之<，故'a < b'等數學式不改寫)；select與del不經清除。
+ * 字串主鍵若會被清除改寫(含HTML標記，如<後緊接英文字母)，整批reject且不寫入任何一筆(mix於任何步驟之前檢查新增與修改)，訊息列其位置而不回顯主鍵，如'failed to save data, id contains HTML markup: data[1]'；否則改寫後之主鍵與呼叫端所持者不同，以原主鍵查詢與刪除皆找不到。
+ *
+ * 擴充函數(addFunCheck、addFunPreProcessing、addFunPostProcessing)屬於各實例，重建實例後須重新註冊；註冊時須傳入函數，否則立即拋錯(addFunCheck另令該實例之procOrm一律reject)；註冊後約1毫秒(以計時器)才生效，在此之前之procOrm呼叫不會套用。
+ * 呼叫契約：check以reject或拋錯阻擋，回傳值不影響結果，且早於前處理執行；前處理逐一呼叫，各收新建之參數物件{woName,userId,isAdmin,mode,input}，input為前一個回傳之input，回傳須為含input之物件否則reject；後處理逐一呼叫，各收新建之參數物件且其output為前一個之回傳值，最後之回傳值即為procOrm之回傳值。
+ * 後處理只在使用者檢查、check、前處理與ORM操作皆成功後執行，逐筆失敗(含del)或mix部分寫入後reject者皆不執行；後處理自身亦可reject。後處理之input為呼叫端傳入之數據，不含本套件補出之主鍵，主鍵見output。
+ * 如需觀察ORM實際寫入，可另監聽woItems內各ORM之change與error事件；惟事件由ORM發出，不含userId與isAdmin，mix會依步驟分次發出，經woItems直接寫入者亦會發出，insert之結果為聚合計數而非逐筆。
+ * 錯誤型別：procOrm由本套件產生之reject一律為英文訊息字串(供前端顯示或對應多語系；ORM之錯誤原文另由console.log輸出而不轉出)，呼叫端提供之函數(getUserById與擴充函數)自身之reject或拋錯則原樣轉出；建構(設定或ORM無效)、擴充函數註冊、backup與recover由本套件產生之錯誤一律為Error，ORM之錯誤則原樣轉出。
+ *
  * @class
  * @param {Object} ds 輸入資料表設定物件
  * @param {Object} WOrm 輸入資料庫ORM物件
@@ -63,9 +81,9 @@ import getProc from './getProc.mjs'
  * @param {String} db 輸入資料庫名稱字串
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {Boolean} [opt.useCheckUser=true] 輸入是否檢查使用者資訊布林值，預設true
- * @param {Function} [opt.getUserById=null] 輸入當useCheckUser=true時依照使用者ID取得使用者資訊物件函數，預設null
- * @param {Boolean} [opt.useExcludeWhenNotAdmin=true] 輸入使用ORM的select方法時是否自動刪除數據內isActive欄位之布林值，預設true
- * @returns {Object} 回傳通訊物件，可監聽事件open、error、clientChange、execute、broadcast、deliver，可使用函數broadcast
+ * @param {Function} [opt.getUserById=null] 輸入當useCheckUser=true時依照使用者ID取得使用者資訊物件函數，預設null；建構時不檢查，未給或非函數時useCheckUser為true之procOrm呼叫一律reject
+ * @param {Boolean} [opt.useExcludeWhenNotAdmin=true] 輸入非管理者使用procOrm之select時是否濾除isActive為'n'之數據布林值，預設true
+ * @returns {Object} 回傳伺服器ORM支援物件，含woItems(各資料表ORM實例)、procOrm(資料操作函數，輸入為userId、woName、mode、input)、addFunCheck、addFunPreProcessing、addFunPostProcessing、closeAll(逐一關閉各資料表ORM之連線)，以及backup(woItems)與recover(fp, woItems, genModels, needCreateStorage)；後兩者不綁定本實例，須自行傳入woItems(須為非空物件，否則reject)，其參數順序與getDb之recover(woItems, fp, opt)不同；recover於寫入前驗證備份內容(須為非空陣列且各筆之name為woItems內之資料表)，失敗時reject，逐表寫入時中途失敗則先前之表已寫入
  * @example
  *
  * // import WOrm from 'w-orm-mongodb/src/WOrmMongodb.mjs' //自行選擇引用ORM
@@ -174,7 +192,7 @@ export default WServOrm
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Oct 11 2026 15:00:09 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Oct 12 2026 13:45:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Oct 11 2026 15:00:09 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Oct 12 2026 13:45:56 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g-mOrm.mjs

@@ -47,6 +47,7 @@ console.log(r) //回傳server用orm相關函數
 //       [Symbol(kCapture)]: false
 //     }
 //   },
+//   closeAll: [AsyncFunction: closeAll],
 //   addFunCheck: [Function: addFunCheck],
 //   addFunPreProcessing: [Function: addFunPreProcessing],
 //   addFunPostProcessing: [Function: addFunPostProcessing],

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "w-serv-orm",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "main": "dist/w-serv-orm.umd.js",
   "dependencies": {
     "json5": "^2.2.3",
-    "wsemi": "^1.9.12"
+    "w-data-collector": "^1.0.46",
+    "wsemi": "^1.9.13"
   },
   "devDependencies": {
-    "w-data-collector": "^1.0.43",
     "w-orm-lowdb": "^1.0.31",
     "w-package-tools": "^1.1.16"
   },

package/schema/tables/tests.mjs

@@ -60,7 +60,7 @@ let funTest = () => {
         v = dtpick(v, keys(settings))
         return v
     })
-    console.log(`已產生: {keyTable} 測試資料`, rs)
+    console.log(`generated test data for table[${keyTable}]`, rs)
     return rs
 }
 

package/src/WServOrm.mjs

@@ -9,6 +9,24 @@ import getProc from './getProc.mjs'
 /**
  * 產生伺服器ORM的支援物件
  *
+ * 每次呼叫各自建立資料表ORM、設定與擴充函數，同一行程內之多個實例互不干擾；同一url與db之資料庫資源能否並存，依所用ORM而定。
+ *
+ * procOrm之save、del與mix，於ORM回傳之逐筆結果有任一筆ok為0(單筆失敗)時reject，訊息列出失敗筆之主鍵，如'failed to save data: id[b]'(超過100字元者截斷顯示；無有效主鍵者以data[k]列其於輸入內之位置，k自0起；超過10筆者只列前10筆並附總筆數)，錯誤原文另由console.log輸出。
+ * 單筆失敗不中斷整批，故reject時其餘筆數已寫入。
+ * mix之各步驟遇單筆失敗不中斷後續步驟，待全部步驟完成後一併reject；遇整批性錯誤則立即reject，後續步驟不執行。
+ *
+ * insert、save與mix之新增、修改，數據未帶有效主鍵(非空字串或數字)者，若資料表之主鍵欄為id且為字串型(或型別未知)，由本套件產生主鍵(同各ORM之genIDSeq)並於resolve時回傳；無欄位之數據不補。
+ * reject時不回傳補出之主鍵，故重送未帶主鍵之數據會再產生新主鍵而重複寫入，需冪等重送者請自帶主鍵；save帶主鍵者重送以主鍵覆寫，del重送時已刪除者為主鍵未命中。
+ * insert(含mix之新增)為主鍵已存在即略過之冪等新增，回傳之id含被略過者；recover亦以insert還原，故資料表須先清空。
+ * insert、save與mix之新增、修改，寫入前各欄位之字串皆經wsemi之clearXSS清除(白名單外之標籤轉義，白名單內之標籤刪除白名單外之屬性與危險網址，標籤外之文字只轉義會開始標籤之<，故'a < b'等數學式不改寫)；select與del不經清除。
+ * 字串主鍵若會被清除改寫(含HTML標記，如<後緊接英文字母)，整批reject且不寫入任何一筆(mix於任何步驟之前檢查新增與修改)，訊息列其位置而不回顯主鍵，如'failed to save data, id contains HTML markup: data[1]'；否則改寫後之主鍵與呼叫端所持者不同，以原主鍵查詢與刪除皆找不到。
+ *
+ * 擴充函數(addFunCheck、addFunPreProcessing、addFunPostProcessing)屬於各實例，重建實例後須重新註冊；註冊時須傳入函數，否則立即拋錯(addFunCheck另令該實例之procOrm一律reject)；註冊後約1毫秒(以計時器)才生效，在此之前之procOrm呼叫不會套用。
+ * 呼叫契約：check以reject或拋錯阻擋，回傳值不影響結果，且早於前處理執行；前處理逐一呼叫，各收新建之參數物件{woName,userId,isAdmin,mode,input}，input為前一個回傳之input，回傳須為含input之物件否則reject；後處理逐一呼叫，各收新建之參數物件且其output為前一個之回傳值，最後之回傳值即為procOrm之回傳值。
+ * 後處理只在使用者檢查、check、前處理與ORM操作皆成功後執行，逐筆失敗(含del)或mix部分寫入後reject者皆不執行；後處理自身亦可reject。後處理之input為呼叫端傳入之數據，不含本套件補出之主鍵，主鍵見output。
+ * 如需觀察ORM實際寫入，可另監聽woItems內各ORM之change與error事件；惟事件由ORM發出，不含userId與isAdmin，mix會依步驟分次發出，經woItems直接寫入者亦會發出，insert之結果為聚合計數而非逐筆。
+ * 錯誤型別：procOrm由本套件產生之reject一律為英文訊息字串(供前端顯示或對應多語系；ORM之錯誤原文另由console.log輸出而不轉出)，呼叫端提供之函數(getUserById與擴充函數)自身之reject或拋錯則原樣轉出；建構(設定或ORM無效)、擴充函數註冊、backup與recover由本套件產生之錯誤一律為Error，ORM之錯誤則原樣轉出。
+ *
  * @class
  * @param {Object} ds 輸入資料表設定物件
  * @param {Object} WOrm 輸入資料庫ORM物件
@@ -16,9 +34,9 @@ import getProc from './getProc.mjs'
  * @param {String} db 輸入資料庫名稱字串
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {Boolean} [opt.useCheckUser=true] 輸入是否檢查使用者資訊布林值，預設true
- * @param {Function} [opt.getUserById=null] 輸入當useCheckUser=true時依照使用者ID取得使用者資訊物件函數，預設null
- * @param {Boolean} [opt.useExcludeWhenNotAdmin=true] 輸入使用ORM的select方法時是否自動刪除數據內isActive欄位之布林值，預設true
- * @returns {Object} 回傳通訊物件，可監聽事件open、error、clientChange、execute、broadcast、deliver，可使用函數broadcast
+ * @param {Function} [opt.getUserById=null] 輸入當useCheckUser=true時依照使用者ID取得使用者資訊物件函數，預設null；建構時不檢查，未給或非函數時useCheckUser為true之procOrm呼叫一律reject
+ * @param {Boolean} [opt.useExcludeWhenNotAdmin=true] 輸入非管理者使用procOrm之select時是否濾除isActive為'n'之數據布林值，預設true
+ * @returns {Object} 回傳伺服器ORM支援物件，含woItems(各資料表ORM實例)、procOrm(資料操作函數，輸入為userId、woName、mode、input)、addFunCheck、addFunPreProcessing、addFunPostProcessing、closeAll(逐一關閉各資料表ORM之連線)，以及backup(woItems)與recover(fp, woItems, genModels, needCreateStorage)；後兩者不綁定本實例，須自行傳入woItems(須為非空物件，否則reject)，其參數順序與getDb之recover(woItems, fp, opt)不同；recover於寫入前驗證備份內容(須為非空陣列且各筆之name為woItems內之資料表)，失敗時reject，逐表寫入時中途失敗則先前之表已寫入
  * @example
  *
  * // import WOrm from 'w-orm-mongodb/src/WOrmMongodb.mjs' //自行選擇引用ORM

package/src/genTestData.mjs

@@ -1,7 +1,9 @@
-import get from 'lodash-es/get.js'
+import get from 'lodash-es/get.js'
+import size from 'lodash-es/size.js'
 import isbol from 'wsemi/src/isbol.mjs'
-import isfun from 'wsemi/src/isfun.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
 import pmSeries from 'wsemi/src/pmSeries.mjs'
+import getItemsFail from 'w-data-collector/src/getItemsFail.mjs'
 
 
 async function genTestData(ds, woItems, opt = {}) {
@@ -44,7 +46,13 @@ async function genTestData(ds, woItems, opt = {}) {
             }
 
             //save
-            await woItems[k].save(rs)
+            let rss = await woItems[k].save(rs)
+
+            //check, 單筆失敗時整批仍resolve並以該筆ok為0回報, 須逐筆檢查
+            let fails = getItemsFail(rss, rs)
+            if (size(fails) > 0) {
+                throw new Error(`failed to write test data into table[${k}]: ${JSON.stringify(fails)}`)
+            }
 
             if (bLog) {
                 console.log(`${k}.funTest and save`, rs)

package/src/getDb.mjs

@@ -1,11 +1,12 @@
 import path from 'path'
 import fs from 'fs'
-import get from 'lodash-es/get.js'
-import each from 'lodash-es/each.js'
-import keys from 'lodash-es/keys.js'
+import get from 'lodash-es/get.js'
+import each from 'lodash-es/each.js'
+import keys from 'lodash-es/keys.js'
 import iseobj from 'wsemi/src/iseobj.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
+import isfun from 'wsemi/src/isfun.mjs'
 import o2j from 'wsemi/src/o2j.mjs'
 import now2strp from 'wsemi/src/now2strp.mjs'
 import haskey from 'wsemi/src/haskey.mjs'
@@ -38,13 +39,13 @@ function genModels(ds, genModelsByTabs, opt = {}) {
 
         //check
         if (!haskey(ds[name], 'settings')) {
-            console.log(`資料表[${name}]無settings資訊`)
+            console.log(`table[${name}] has no settings`)
             return true //跳出換下一個
         }
 
         //check
         if (!iseobj(ds[name].settings)) {
-            console.log(`ds[${name}].settings非有效物件`)
+            console.log(`invalid ds[${name}].settings`)
             return true //跳出換下一個
         }
 
@@ -66,6 +67,7 @@ function genModels(ds, genModelsByTabs, opt = {}) {
 
 
 async function backup(woItems, opt = {}) {
+    //備份各資料表至cwd(模組載入時之工作目錄)下之backup-時間.json; 失敗時印log後reject原錯誤, 令呼叫端(含未await之頂層腳本)可偵測
 
     //bLog
     let bLog = get(opt, 'bLog')
@@ -80,6 +82,11 @@ async function backup(woItems, opt = {}) {
             //o2j
             let j = o2j(res)
 
+            //check, o2j無法序列化時回空字串, 不得寫出空備份而回報成功
+            if (!isestr(j)) {
+                throw new Error('backup data can not be serialized')
+            }
+
             //fn
             let fn = `backup-${now2strp()}.json`
 
@@ -95,12 +102,15 @@ async function backup(woItems, opt = {}) {
         })
         .catch((err) => {
             console.log(err)
+            throw err
         })
 
 }
 
 
 async function recover(woItems, fp, opt = {}) {
+    //由備份檔以insert還原各資料表; 主鍵已存在者略過, 故資料表須先清空; 逐表寫入, 中途失敗時先前之表已寫入
+    //失敗時印log後reject原錯誤; bRela為true時須提供opt.ds與opt.genModelsByTabs以產生model
 
     //bRela, 是否為關聯資料庫
     let bRela = get(opt, 'bRela')
@@ -115,10 +125,20 @@ async function recover(woItems, fp, opt = {}) {
     }
 
     //funGenModels and bNeedCreateStorage, 若為關聯資料庫則需使用genModels與needCreateStorage=true
+    //genModels須以ds與genModelsByTabs產生model, 低階recover則以無參數呼叫, 故以閉包帶入; 缺則於任何寫入之前reject
     let funGenModels = null
     let bNeedCreateStorage = false
     if (bRela) {
-        funGenModels = genModels
+        let ds = get(opt, 'ds')
+        let genModelsByTabs = get(opt, 'genModelsByTabs')
+        if (!iseobj(ds) || !isfun(genModelsByTabs)) {
+            let err = new Error('bRela needs opt.ds and opt.genModelsByTabs')
+            console.log(err)
+            return Promise.reject(err)
+        }
+        funGenModels = () => {
+            genModels(ds, genModelsByTabs, opt)
+        }
         bNeedCreateStorage = true
     }
 
@@ -131,6 +151,7 @@ async function recover(woItems, fp, opt = {}) {
         })
         .catch((err) => {
             console.log(err)
+            throw err
         })
 
 }

package/src/getDbBackupAndRecover.mjs

@@ -1,10 +1,15 @@
 // import path from 'path'
 import fs from 'fs'
-import trim from 'lodash-es/trim.js'
-import size from 'lodash-es/size.js'
+import trim from 'lodash-es/trim.js'
+import size from 'lodash-es/size.js'
+import get from 'lodash-es/get.js'
+import each from 'lodash-es/each.js'
 import pmSeries from 'wsemi/src/pmSeries.mjs'
 import fsIsFile from 'wsemi/src/fsIsFile.mjs'
 import iseobj from 'wsemi/src/iseobj.mjs'
+import isearr from 'wsemi/src/isearr.mjs'
+import isestr from 'wsemi/src/isestr.mjs'
+import haskey from 'wsemi/src/haskey.mjs'
 import isfun from 'wsemi/src/isfun.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
 import j2o from 'wsemi/src/j2o.mjs'
@@ -12,6 +17,12 @@ import j2o from 'wsemi/src/j2o.mjs'
 
 async function backup(woItems) {
 
+    //check, 同recover; 否則無效值由pmSeries以字串reject, 而空物件或空陣列會產出recover拒收之空備份
+    if (!iseobj(woItems)) {
+        console.log('woItems', woItems)
+        throw new Error('invalid woItems')
+    }
+
     //rs
     let rs = await pmSeries(woItems, async (v, k) => {
         console.log('backup...', k)
@@ -58,6 +69,20 @@ async function recover(fp, woItems, genModels, needCreateStorage = false) {
     let rs = j2o(j)
     // console.log('recover rs', rs)
 
+    //check, 備份內容須為非空陣列, 且各筆之name為woItems內之資料表; 於任何寫入之前驗證, 避免空檔或壞檔(j2o解析失敗回{})假成功, 亦避免部分還原
+    if (!isearr(rs)) {
+        throw new Error('invalid backup data, need a non-empty array')
+    }
+    each(rs, (v, k) => {
+        let name = get(v, 'name')
+        if (!isestr(name)) {
+            throw new Error(`invalid backup data, rs[${k}].name is not a string`)
+        }
+        if (!haskey(woItems, name)) {
+            throw new Error(`invalid backup data, table[${name}] is not in woItems`)
+        }
+    })
+
     //genModels
     if (isfun(genModels)) {
         genModels()

package/src/getItemsFail.mjs

@@ -0,0 +1,5 @@
+import getItemsFail from 'w-data-collector/src/getItemsFail.mjs'
+
+
+//相容檔: 本套件1.1.7曾以此路徑提供getItemsFail, 使用端有以深層路徑引用者(如w-web-sso之server/ormWrite.mjs), 故保留並轉出w-data-collector之實作
+export default getItemsFail