w-serv-orm 1.1.17 → 1.1.18

package/docs/WServOrm.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#isOrmFail">isOrmFail</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
     
 </nav>
 
@@ -78,6 +78,8 @@
 <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時其餘筆數已寫入。
+寫入類函數之回傳凡可表達失敗者一律檢查，失敗即reject或拋錯，不當成功(規則帳本R-ORM-RESULT-01)：save、del與mix之del、diff若ORM改回聚合物件而ok為0(非契約形狀，無從逐筆列出)亦視為失敗，以固定字串'failed to save data'、'failed to delete data'、'failed to update data'reject，mix之del、diff遇此視為整批性錯誤而立即reject，後續步驟不執行；delAll依契約回傳聚合物件且ok恆為1(錯誤皆整批reject)，ok為0(或回傳逐筆陣列而任一筆ok為0)以固定字串'failed to delete data'reject；讀取類select之回傳為數據列(列內欄位可能名為ok)，失敗只以reject表達，不檢查ok。
+insert(含mix之新增)依ORM契約回傳聚合物件且ok恆為1(錯誤皆整批reject)；ORM若resolve聚合物件而ok為0，或回傳逐筆陣列(非insert契約形狀)而任一筆ok為0(違約或他種後端)，亦視為失敗，以固定字串'failed to insert data'reject(錯誤原文另由console.log輸出)，已寫入之筆無從回復；mix之新增遇此視為整批性錯誤而立即reject，後續del、diff步驟不執行。回傳undefined、null、無ok鍵之物件、空陣列或逐筆皆ok非0之陣列者不檢查，維持舊行為；略過既有主鍵(n為0、ok為1)為正常結果。備份還原(recover)之逐表insert同此判準，失敗時於該表停止並以Error reject(訊息為'failed to recover data into table[表名]: '接ORM回傳原文，逐筆陣列則列失敗筆{k,id,err}，至多前10筆並附總筆數，另列先前已寫入之表)，之後之表不寫入，先前之表與該表已被ORM寫入之筆無從回復。
 mix之各步驟遇單筆失敗不中斷後續步驟，待全部步驟完成後一併reject；遇整批性錯誤則立即reject，後續步驟不執行。mix於resolve時回傳各步驟所處理之列之id(依add、del、diff之序串接，del之列不分是否命中)。</p>
 <p>insert、save與mix之新增、修改，數據未帶有效主鍵(未給、null、空字串，或非字串非數字之值，含NaN與±Infinity)者，若資料表之主鍵欄為id且為字串型(或型別未知；型別如STRING(36)者以括號前之字判定)，由本套件產生主鍵(同各ORM之genIDSeq)並於resolve時回傳；單一空物件與只含一個空物件之陣列不補(ORM視為無效輸入而不寫入)，多筆批次中之空物件列則補。
 主鍵欄為字串型(或型別未知)之資料表，主鍵為有限數字者一律以其字串形式處置(如123視為'123')：寫入、resolve回傳、del與mix之刪除，以及select、delAll條件中主鍵之比較($eq、$ne、$gt、$gte、$lt、$lte、$in、$nin，含$and、$or之內)皆同，故以數字或其字串形式寫入、查詢與刪除者為同一筆，範圍比較依字串之字典序；主鍵欄為整數型者不轉型。轉型只作用於procOrm，經woItems直接操作者不轉型。舊版w-orm-mongodb(2025-04-29以前)保留之數字主鍵資料，以數字查詢將查不到。
@@ -109,7 +111,7 @@ insert、save與mix之新增、修改，寫入前各欄位之字串皆經wsemi
     
     <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#line141">line 141</a>
+        <a href="WServOrm.mjs.html">WServOrm.mjs</a>, <a href="WServOrm.mjs.html#line143">line 143</a>
     </li></ul></dd>
     
 
@@ -452,7 +454,7 @@ insert、save與mix之新增、修改，寫入前各欄位之字串皆經wsemi
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 23 2026 00:29:00 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 Fri Oct 23 2026 14:34:16 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WServOrm.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#isOrmFail">isOrmFail</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
     
 </nav>
 
@@ -92,6 +92,8 @@ function mkErrBaseline(c) {
  *
  * procOrm之save、del與mix，於ORM回傳之逐筆結果有任一筆ok為0(單筆失敗)時reject，訊息列出失敗筆之主鍵，如'failed to save data: id[b]'(超過100字元者截斷顯示；無有效主鍵者以data[k]列其於輸入內之位置，k自0起；超過10筆者只列前10筆並附總筆數)，錯誤原文另由console.log輸出。
  * 單筆失敗不中斷整批，故reject時其餘筆數已寫入。
+ * 寫入類函數之回傳凡可表達失敗者一律檢查，失敗即reject或拋錯，不當成功(規則帳本R-ORM-RESULT-01)：save、del與mix之del、diff若ORM改回聚合物件而ok為0(非契約形狀，無從逐筆列出)亦視為失敗，以固定字串'failed to save data'、'failed to delete data'、'failed to update data'reject，mix之del、diff遇此視為整批性錯誤而立即reject，後續步驟不執行；delAll依契約回傳聚合物件且ok恆為1(錯誤皆整批reject)，ok為0(或回傳逐筆陣列而任一筆ok為0)以固定字串'failed to delete data'reject；讀取類select之回傳為數據列(列內欄位可能名為ok)，失敗只以reject表達，不檢查ok。
+ * insert(含mix之新增)依ORM契約回傳聚合物件且ok恆為1(錯誤皆整批reject)；ORM若resolve聚合物件而ok為0，或回傳逐筆陣列(非insert契約形狀)而任一筆ok為0(違約或他種後端)，亦視為失敗，以固定字串'failed to insert data'reject(錯誤原文另由console.log輸出)，已寫入之筆無從回復；mix之新增遇此視為整批性錯誤而立即reject，後續del、diff步驟不執行。回傳undefined、null、無ok鍵之物件、空陣列或逐筆皆ok非0之陣列者不檢查，維持舊行為；略過既有主鍵(n為0、ok為1)為正常結果。備份還原(recover)之逐表insert同此判準，失敗時於該表停止並以Error reject(訊息為'failed to recover data into table[表名]: '接ORM回傳原文，逐筆陣列則列失敗筆{k,id,err}，至多前10筆並附總筆數，另列先前已寫入之表)，之後之表不寫入，先前之表與該表已被ORM寫入之筆無從回復。
  * mix之各步驟遇單筆失敗不中斷後續步驟，待全部步驟完成後一併reject；遇整批性錯誤則立即reject，後續步驟不執行。mix於resolve時回傳各步驟所處理之列之id(依add、del、diff之序串接，del之列不分是否命中)。
  *
  * insert、save與mix之新增、修改，數據未帶有效主鍵(未給、null、空字串，或非字串非數字之值，含NaN與±Infinity)者，若資料表之主鍵欄為id且為字串型(或型別未知；型別如STRING(36)者以括號前之字判定)，由本套件產生主鍵(同各ORM之genIDSeq)並於resolve時回傳；單一空物件與只含一個空物件之陣列不補(ORM視為無效輸入而不寫入)，多筆批次中之空物件列則補。
@@ -290,7 +292,7 @@ export default WServOrm
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 23 2026 00:29:00 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 Fri Oct 23 2026 14:34:16 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/baseline.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#isOrmFail">isOrmFail</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
     
 </nav>
 
@@ -611,7 +611,7 @@ export { BASELINE_VERSION, BASELINE_REJECT, cyrb53, checkContract, digestRow, bu
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 23 2026 00:29:00 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 Fri Oct 23 2026 14:34:16 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/global.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#isOrmFail">isOrmFail</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
     
 </nav>
 
@@ -1409,6 +1409,170 @@ rowsNow 內之主鍵缺漏或重複拋 key 為 'rowsInvalid' 之Error(庫內資
 
     
 
+    <h4 class="name" id="isOrmFail"><span class="type-signature"></span>isOrmFail<span class="signature">(r)</span><span class="type-signature"> &rarr; {Boolean}</span></h4>
+
+    
+
+
+
+
+<dl class="details">
+    
+    <dt class="tag-description">Description:</dt>
+    <dd class="tag-description"><ul class="dummy"><li><p>判斷ORM寫入類函數(insert、save、del、delAll)之回傳結果是否回報失敗</p>
+<p>依w-orm系列規格，insert與delAll回傳聚合物件且ok恆為1，save與del回傳逐筆陣列，錯誤皆整批reject；單筆失敗者(save、del)於該筆以ok為0回報。
+本函數不論函數與形狀一律判讀：回傳為聚合物件(非null、非陣列之物件)而ok為0者(ORM違約或他種後端)視為失敗；
+回傳為逐筆陣列而任一筆ok為0者(同getItemsFail之判讀)視為失敗。
+其餘(undefined、null、無ok鍵之物件、空陣列、元素皆ok非0或非物件之陣列、ok為1含略過既有主鍵或未命中之n為0)不視為失敗，維持舊行為。
+讀取函數(select)之回傳為數據列，列內欄位可能名為ok，不得以本函數判讀。
+供procOrm之寫入類各模式、mix之各步驟、備份還原與測試數據寫入共用。</p></li></ul></dd>
+    
+
+    
+    <dt class="tag-source">Source:</dt>
+    <dd class="tag-source"><ul class="dummy"><li>
+        <a href="isOrmFail.mjs.html">isOrmFail.mjs</a>, <a href="isOrmFail.mjs.html#line18">line 18</a>
+    </li></ul></dd>
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+
+    
+</dl>
+
+
+
+
+
+
+
+
+
+
+
+
+
+    <h5 class="h5-parameters">Parameters:</h5>
+    
+
+<table class="params">
+    <thead>
+    <tr>
+        
+        <th>Name</th>
+        
+
+        <th>Type</th>
+
+        
+
+        
+
+        <th class="last">Description</th>
+    </tr>
+    </thead>
+
+    <tbody>
+    
+
+        <tr>
+            
+                <td class="name"><code>r</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">*</span>
+
+
+
+            
+            </td>
+
+            
+
+            
+
+            <td class="description last"><p>輸入ORM寫入類函數之回傳結果</p></td>
+        </tr>
+
+    
+    </tbody>
+</table>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+<h5 class="h5-returns">Returns:</h5>
+
+        
+<div class="param-desc">
+    <p>回傳是否回報失敗</p>
+</div>
+
+
+
+<dl class="param-type">
+    <dt>
+        Type
+    </dt>
+    <dd>
+        
+<span class="param-type">Boolean</span>
+
+
+
+    </dd>
+</dl>
+
+    
+
+
+
+        
+            
+
+    
+
     <h4 class="name" id="pickWriteRow"><span class="type-signature"></span>pickWriteRow<span class="signature">(row, contract)</span><span class="type-signature"> &rarr; {Object}</span></h4>
 
     
@@ -1609,7 +1773,7 @@ rowsNow 內之主鍵缺漏或重複拋 key 為 'rowsInvalid' 之Error(庫內資
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 23 2026 00:29:00 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 Fri Oct 23 2026 14:34:16 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#isOrmFail">isOrmFail</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
     
 </nav>
 
@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 23 2026 00:29:00 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 Fri Oct 23 2026 14:34:16 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/isOrmFail.mjs.html

@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    
+    <meta charset="utf-8">
+    <title>isOrmFail.mjs - Documentation</title>
+    
+    
+    <script src="scripts/prettify/prettify.js"></script>
+    <script src="scripts/prettify/lang-css.js"></script>
+    <!--[if lt IE 9]>
+      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
+    <![endif]-->
+    <link type="text/css" rel="stylesheet" href="styles/prettify.css">
+    <link type="text/css" rel="stylesheet" href="styles/jsdoc.css">
+    <script src="scripts/nav.js" defer></script>
+    
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+</head>
+<body>
+
+<input type="checkbox" id="nav-trigger" class="nav-trigger" />
+<label for="nav-trigger" class="navicon-button x">
+  <div class="navicon"></div>
+</label>
+
+<label for="nav-trigger" class="overlay"></label>
+
+<nav >
+    
+    
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WServOrm.html">WServOrm</a></li></ul><h3>Global</h3><ul><li><a href="global.html#buildBaseline">buildBaseline</a></li><li><a href="global.html#checkContract">checkContract</a></li><li><a href="global.html#compareBaseline">compareBaseline</a></li><li><a href="global.html#cyrb53">cyrb53</a></li><li><a href="global.html#digestRow">digestRow</a></li><li><a href="global.html#getRejectKey">getRejectKey</a></li><li><a href="global.html#isBaselineValid">isBaselineValid</a></li><li><a href="global.html#isOrmFail">isOrmFail</a></li><li><a href="global.html#pickWriteRow">pickWriteRow</a></li></ul>
+    
+</nav>
+
+<div id="main">
+    
+    <h1 class="page-title">isOrmFail.mjs</h1>
+    
+
+    
+
+
+
+    
+    <section>
+        <article>
+            <pre class="prettyprint source linenums"><code>import size from 'lodash-es/size.js'
+import getItemsFail from 'w-data-collector/src/getItemsFail.mjs'
+
+
+/**
+ * 判斷ORM寫入類函數(insert、save、del、delAll)之回傳結果是否回報失敗
+ *
+ * 依w-orm系列規格，insert與delAll回傳聚合物件且ok恆為1，save與del回傳逐筆陣列，錯誤皆整批reject；單筆失敗者(save、del)於該筆以ok為0回報。
+ * 本函數不論函數與形狀一律判讀：回傳為聚合物件(非null、非陣列之物件)而ok為0者(ORM違約或他種後端)視為失敗；
+ * 回傳為逐筆陣列而任一筆ok為0者(同getItemsFail之判讀)視為失敗。
+ * 其餘(undefined、null、無ok鍵之物件、空陣列、元素皆ok非0或非物件之陣列、ok為1含略過既有主鍵或未命中之n為0)不視為失敗，維持舊行為。
+ * 讀取函數(select)之回傳為數據列，列內欄位可能名為ok，不得以本函數判讀。
+ * 供procOrm之寫入類各模式、mix之各步驟、備份還原與測試數據寫入共用。
+ *
+ * @param {*} r 輸入ORM寫入類函數之回傳結果
+ * @returns {Boolean} 回傳是否回報失敗
+ */
+function isOrmFail(r) {
+
+    //check, 逐筆陣列
+    if (Array.isArray(r)) {
+        return size(getItemsFail(r, [])) > 0
+    }
+
+    //check, 聚合物件
+    return r !== null &amp;&amp; typeof r === 'object' &amp;&amp; r.ok === 0
+}
+
+
+export default isOrmFail
+</code></pre>
+        </article>
+    </section>
+
+
+
+
+    
+    
+</div>
+
+<br class="clear">
+
+<footer>
+    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Fri Oct 23 2026 14:34:16 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
+</footer>
+
+<script>prettyPrint();</script>
+<script src="scripts/polyfill.js"></script>
+<script src="scripts/linenumber.js"></script>
+
+
+
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-serv-orm",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "main": "dist/w-serv-orm.umd.js",
   "dependencies": {
     "json5": "^2.2.3",

package/src/WServOrm.mjs

@@ -45,6 +45,8 @@ function mkErrBaseline(c) {
  *
  * procOrm之save、del與mix，於ORM回傳之逐筆結果有任一筆ok為0(單筆失敗)時reject，訊息列出失敗筆之主鍵，如'failed to save data: id[b]'(超過100字元者截斷顯示；無有效主鍵者以data[k]列其於輸入內之位置，k自0起；超過10筆者只列前10筆並附總筆數)，錯誤原文另由console.log輸出。
  * 單筆失敗不中斷整批，故reject時其餘筆數已寫入。
+ * 寫入類函數之回傳凡可表達失敗者一律檢查，失敗即reject或拋錯，不當成功(規則帳本R-ORM-RESULT-01)：save、del與mix之del、diff若ORM改回聚合物件而ok為0(非契約形狀，無從逐筆列出)亦視為失敗，以固定字串'failed to save data'、'failed to delete data'、'failed to update data'reject，mix之del、diff遇此視為整批性錯誤而立即reject，後續步驟不執行；delAll依契約回傳聚合物件且ok恆為1(錯誤皆整批reject)，ok為0(或回傳逐筆陣列而任一筆ok為0)以固定字串'failed to delete data'reject；讀取類select之回傳為數據列(列內欄位可能名為ok)，失敗只以reject表達，不檢查ok。
+ * insert(含mix之新增)依ORM契約回傳聚合物件且ok恆為1(錯誤皆整批reject)；ORM若resolve聚合物件而ok為0，或回傳逐筆陣列(非insert契約形狀)而任一筆ok為0(違約或他種後端)，亦視為失敗，以固定字串'failed to insert data'reject(錯誤原文另由console.log輸出)，已寫入之筆無從回復；mix之新增遇此視為整批性錯誤而立即reject，後續del、diff步驟不執行。回傳undefined、null、無ok鍵之物件、空陣列或逐筆皆ok非0之陣列者不檢查，維持舊行為；略過既有主鍵(n為0、ok為1)為正常結果。備份還原(recover)之逐表insert同此判準，失敗時於該表停止並以Error reject(訊息為'failed to recover data into table[表名]: '接ORM回傳原文，逐筆陣列則列失敗筆{k,id,err}，至多前10筆並附總筆數，另列先前已寫入之表)，之後之表不寫入，先前之表與該表已被ORM寫入之筆無從回復。
  * mix之各步驟遇單筆失敗不中斷後續步驟，待全部步驟完成後一併reject；遇整批性錯誤則立即reject，後續步驟不執行。mix於resolve時回傳各步驟所處理之列之id(依add、del、diff之序串接，del之列不分是否命中)。
  *
  * insert、save與mix之新增、修改，數據未帶有效主鍵(未給、null、空字串，或非字串非數字之值，含NaN與±Infinity)者，若資料表之主鍵欄為id且為字串型(或型別未知；型別如STRING(36)者以括號前之字判定)，由本套件產生主鍵(同各ORM之genIDSeq)並於resolve時回傳；單一空物件與只含一個空物件之陣列不補(ORM視為無效輸入而不寫入)，多筆批次中之空物件列則補。

package/src/genTestData.mjs

@@ -4,6 +4,7 @@ import isbol from 'wsemi/src/isbol.mjs'
 import isfun from 'wsemi/src/isfun.mjs'
 import pmSeries from 'wsemi/src/pmSeries.mjs'
 import getItemsFail from 'w-data-collector/src/getItemsFail.mjs'
+import isOrmFail from './isOrmFail.mjs'
 
 
 async function genTestData(ds, woItems, opt = {}) {
@@ -54,6 +55,11 @@ async function genTestData(ds, woItems, opt = {}) {
                 throw new Error(`failed to write test data into table[${k}]: ${JSON.stringify(fails)}`)
             }
 
+            //check, 回傳聚合物件而ok為0(非契約形狀)者無從逐筆列出, 仍視為失敗, 內文列ORM回傳原文(R-ORM-RESULT-01)
+            if (isOrmFail(rss)) {
+                throw new Error(`failed to write test data into table[${k}]: ${JSON.stringify(rss)}`)
+            }
+
             if (bLog) {
                 console.log(`${k}.funTest and save`, rs)
             }

package/src/getDb.mjs

@@ -109,7 +109,7 @@ async function backup(woItems, opt = {}) {
 
 
 async function recover(woItems, fp, opt = {}) {
-    //由備份檔以insert還原各資料表; 主鍵已存在者略過, 故資料表須先清空; 逐表寫入, 中途失敗時先前之表已寫入
+    //由備份檔以insert還原各資料表; 主鍵已存在者略過, 故資料表須先清空; 逐表寫入, 中途失敗(含insert回報ok為0, 見isOrmFail)時先前之表已寫入, 之後之表不寫入
     //失敗時印log後reject原錯誤; bRela為true時須提供opt.ds與opt.genModelsByTabs以產生model
 
     //bRela, 是否為關聯資料庫

package/src/getDbBackupAndRecover.mjs

@@ -4,6 +4,8 @@ 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 join from 'lodash-es/join.js'
+import take from 'lodash-es/take.js'
 import pmSeries from 'wsemi/src/pmSeries.mjs'
 import fsIsFile from 'wsemi/src/fsIsFile.mjs'
 import iseobj from 'wsemi/src/iseobj.mjs'
@@ -12,6 +14,37 @@ import isestr from 'wsemi/src/isestr.mjs'
 import isfun from 'wsemi/src/isfun.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
 import j2o from 'wsemi/src/j2o.mjs'
+import getItemsFail from 'w-data-collector/src/getItemsFail.mjs'
+import isOrmFail from './isOrmFail.mjs'
+
+
+function getMsgFail(name, r, data, written) {
+    //還原失敗之訊息(Error.message, 伺服器端工具, 同genTestData含ORM回傳原文): 失敗表名, 聚合物件則列其原文, 逐筆陣列則列失敗筆{k,id,err}(僅前nShow筆並附總筆數), 另列先前已寫入之表
+
+    //nShow
+    let nShow = 10
+
+    //detail
+    let detail = null
+    if (Array.isArray(r)) {
+        let fails = getItemsFail(r, data)
+        detail = JSON.stringify(take(fails, nShow))
+        if (size(fails) > nShow) {
+            detail += `, ... (${size(fails)} in total)`
+        }
+    }
+    else {
+        detail = JSON.stringify(r)
+    }
+
+    //msg
+    let msg = `failed to recover data into table[${name}]: ${detail}`
+    if (size(written) > 0) {
+        msg += `; tables already written: ${join(written, ', ')}`
+    }
+
+    return msg
+}
 
 
 async function backup(woItems) {
@@ -87,6 +120,9 @@ async function recover(fp, woItems, genModels, needCreateStorage = false) {
         genModels()
     }
 
+    //written, 已完成insert之資料表(逐表寫入, 中途失敗時先前之表已寫入, 失敗訊息列出供營運者清理)
+    let written = []
+
     //funTest
     await pmSeries(rs, async (v) => {
         console.log('recover...', v.name)
@@ -98,6 +134,14 @@ async function recover(fp, woItems, genModels, needCreateStorage = false) {
         let r = null
         if (size(v.data) > 0) {
             r = await woItems[v.name].insert(v.data) //需人工先清空資料庫, 用insert匯入比較快
+
+            //check, ORM回報失敗(聚合物件ok為0, 或逐筆陣列任一筆ok為0)不得當成功: 於此表停止, 之後之表不寫入; 此表已被ORM寫入之筆與先前之表無從回復
+            if (isOrmFail(r)) {
+                console.log(`${v.name}.insert fail`, r)
+                throw new Error(getMsgFail(v.name, r, v.data, written))
+            }
+
+            written.push(v.name)
         }
         return r
     })

package/src/getMapOrm.mjs

@@ -16,6 +16,7 @@ import isestr from 'wsemi/src/isestr.mjs'
 import isnum from 'wsemi/src/isnum.mjs'
 import clearXSS from 'wsemi/src/clearXSS.mjs'
 import getItemsFail from 'w-data-collector/src/getItemsFail.mjs'
+import isOrmFail from './isOrmFail.mjs'
 
 
 function getMsgFail(msg, fails) {
@@ -1299,8 +1300,13 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
             return Promise.reject(err)
         }
 
+        //check, insert之錯誤皆屬整批性而reject, 其回傳為聚合物件且ok恆為1; 聚合結果ok為0或逐筆陣列任一筆ok為0者(ORM違約, 見isOrmFail)視為失敗, 不可回成功, 以固定字串整批reject
+        if (mode === 'insert' && isOrmFail(r)) {
+            console.log(`${woName}.insert fail`, r)
+            return Promise.reject('failed to insert data')
+        }
+
         //check, save單筆失敗時整批仍resolve並以該筆ok為0回報, 須逐筆檢查
-        //insert之錯誤皆屬整批性而reject, 其回傳為聚合物件而非逐筆陣列, 故不須檢查
         if (mode === 'save') {
             let fails = getItemsFail(r, input)
             if (size(fails) > 0) {
@@ -1308,6 +1314,12 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
                 return Promise.reject(getMsgFail('failed to save data', getItemsFail(r, inputOrig)))
             }
 
+            //check, 回傳聚合物件而ok為0(非契約形狀)者無從逐筆列出, 仍視為失敗, 固定字串reject(R-ORM-RESULT-01); 陣列形之失敗已於上方列出
+            if (isOrmFail(r)) {
+                console.log(`${woName}.save fail`, r)
+                return Promise.reject('failed to save data')
+            }
+
             //check, 只改不增者之事後偵測: 逐筆n為0表檢查後、寫入前該列被他方刪除(表鎖紀律被破壞), 已寫入之筆無從回復, 仍回報rowNotFound
             if (optProc.mustExist && hasNoHit(r, null)) {
                 console.log(`${woName}.save row not found after check`)
@@ -1380,6 +1392,11 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
                 console.log(`${woName}.del fail`, fails)
                 err = getMsgFail('failed to delete data', fails)
             }
+            else if (isOrmFail(r)) {
+                //回傳聚合物件而ok為0(非契約形狀)者無從逐筆列出, 仍視為失敗, 固定字串(R-ORM-RESULT-01)
+                console.log(`${woName}.del fail`, r)
+                err = 'failed to delete data'
+            }
         }
 
         //check, 刪除回報未命中者之事後偵測: 逐筆nDeleted或n為0表檢查後、刪除前該列被他方刪除(表鎖紀律被破壞), 已刪除之筆無從回復, 仍回報rowNotFound
@@ -1405,6 +1422,12 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
                 err = 'failed to delete data'
             })
 
+        //check, delAll契約為聚合物件且ok恆為1(錯誤皆整批reject); ok為0或逐筆陣列任一筆ok為0者(ORM違約, 見isOrmFail)視為失敗, 不可回成功(R-ORM-RESULT-01)
+        if (!isestr(err) && isOrmFail(r)) {
+            console.log(`${woName}.delAll fail`, r)
+            err = 'failed to delete data'
+        }
+
     }
     else if (mode === 'mix') {
 
@@ -1539,7 +1562,7 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
             }
 
             //insert
-            await wo.insert(add)
+            let rsAdd = await wo.insert(add)
                 .catch((msg) => {
                     console.log(`${woName}.insert catch`, msg)
                     err = 'failed to insert data'
@@ -1550,6 +1573,12 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
                 return Promise.reject(err)
             }
 
+            //check, 同單獨insert, 回報失敗者(isOrmFail)視為整批性失敗, 立即reject, 後續步驟不執行
+            if (isOrmFail(rsAdd)) {
+                console.log(`${woName}.insert fail`, rsAdd)
+                return Promise.reject('failed to insert data')
+            }
+
             //r
             rt = map(add, (v) => {
                 return { id: v.id } //僅回傳id避免大量數據時造成負擔
@@ -1578,6 +1607,11 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
                 console.log(`${woName}.del fail`, fails)
                 msgsFail.push(getMsgFail('failed to delete data', fails))
             }
+            else if (isOrmFail(rs)) {
+                //回傳聚合物件而ok為0(非契約形狀)者無從逐筆列出, 視為該步驟整批性失敗, 立即reject, 後續步驟不執行(R-ORM-RESULT-01)
+                console.log(`${woName}.del fail`, rs)
+                return Promise.reject('failed to delete data')
+            }
 
             //r
             rt = map(del, (v) => {
@@ -1613,6 +1647,11 @@ async function execMapOrm(ds, woItems, userId, woName, mode, input, opt) {
                 console.log(`${woName}.save fail`, fails)
                 msgsFail.push(getMsgFail('failed to update data', getItemsFail(rs, diffOrig)))
             }
+            else if (isOrmFail(rs)) {
+                //同上, 回傳聚合物件而ok為0(非契約形狀)者立即reject(R-ORM-RESULT-01)
+                console.log(`${woName}.save fail`, rs)
+                return Promise.reject('failed to update data')
+            }
 
             //r
             rt = map(diff, (v) => {