w-serv-orm 1.1.15 → 1.1.16

package/docs/WServOrm.html

@@ -84,9 +84,10 @@ mix之各步驟遇單筆失敗不中斷後續步驟，待全部步驟完成後
 reject時不回傳補出之主鍵，故重送未帶主鍵之數據會再產生新主鍵而重複寫入，需冪等重送者請自帶主鍵(非空字串或有限數字)；save帶主鍵者重送以主鍵覆寫，del重送時已刪除者為主鍵未命中。
 回傳之id為本套件依輸入(含補值與轉型)所得之主鍵，非ORM之寫入結果；ORM之比對規則較寬者(如w-orm-mdb之Jet不分大小寫、忽略尾端空白)，insert略過或save命中之對象可能與回傳之id不同。lmdb、lowdb、level、mongodb等主鍵固定為字串id之ORM，其資料表之id須為字串型pk或不標型別；本套件以id為主鍵，主鍵欄非id之ORM(如w-orm-postgresql預設為time)之回傳id不具主鍵意義。
 輸入之形狀：insert與save之各筆、mix之新增與修改之各筆須為物件，mix之add、del、diff若給予須為陣列，select與delAll之條件若給予須為純物件(原型為null或Object.prototype；未給、undefined與空物件{}為無條件：select回全部、delAll刪除全部；null、陣列、字串、數字、布林、函數、Date、RegExp、Map、Set與類別實例皆reject)，否則於任何寫入或查詢之前reject，如'failed to insert data, not an object: data[0]'、'invalid find of select, need an object'、'invalid find of delAll, need an object'。
-條件(find)：select與delAll之條件僅支援系列白名單，由各w-orm-*依相同規則檢核(須為已實作該白名單之w-orm-*版本；舊版或尚未更新者仍可能接受白名單外之運算子，不在下述保證內)，本套件不依運算子放行或攔截(僅轉型主鍵條件，見上)：欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與$in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)；純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date，null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $all $where $expr $like $ilike等)、欄位層$and/$or、函數值、undefined值、空的$nin/$and/$or等，由ORM整批reject，procOrm以固定字串回傳(select為'failed to select data'，delAll為'failed to delete data')，ORM之錯誤原文只由console.log輸出，delAll不刪除任何數據。select未給、為undefined或{}時回傳全部數據；select(find)命中之數據即delAll(find)刪除之數據。
+條件(find)：select與delAll之條件僅支援系列白名單，由各w-orm-*依相同規則檢核(須為已實作該白名單之w-orm-<em>版本；舊版或尚未更新者仍可能接受白名單外之運算子，不在下述保證內)，本套件不依運算子放行或攔截(僅轉型主鍵條件，見上)：欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與$in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)；純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date，null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $all $where $expr $like $ilike等)、欄位層$and/$or、函數值、undefined值、空的$nin/$and/$or等，由ORM整批reject，procOrm以固定字串回傳(select為'failed to select data'，delAll為'failed to delete data')，ORM之錯誤原文只由console.log輸出，delAll不刪除任何數據。select未給、為undefined或{}時回傳全部數據；select(find)命中之數據即delAll(find)刪除之數據。
 delAll(破壞性操作，須審慎使用，非必要不用；刪除單筆請用del)：不給條件(未給、undefined或{})即刪除全部數據，不另行確認，給了條件才是部分刪除；傳了值卻不是條件物件(null、陣列含[]與[{...}]、字串、數值、布林、函數、Date、RegExp、Map、Set、類別實例等)一律整批reject，不視為{}，不刪除任何數據。經資料通道(前端直接操作資料表，如w-serv-webdata)呼叫之delAll與此語意一致，不另加通道專屬限制，以免用法歧異造成誤解；通道端若另有更窄之條件限縮，未通過者由通道端拒絕，授權仍由開放處負責；通訊內容經JSON序列化時，顯式傳入之undefined會成為null而被reject，前端須省略參數或傳{}。條件值若來自可能為undefined、null或空陣列之變數，呼叫端須先自行判斷(undefined值會reject而非被忽略，空的$nin會reject，$in:[]則為恆假而刪除0筆)；建議先以select(find)確認命中範圍再刪除(ORM啟用快取而他方已寫入時，select可能回傳快取，而delAll一律直讀資料庫，預覽不保證即實際刪除之集合)。n與nDeleted皆為實際刪除筆數，條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。
-資料表名(procOrm之woName)須為本實例資料表之自有名稱，否則reject 'can not find table[x] in ORM'(原型鏈上之名稱如constructor、toString與路徑字串如tests.select亦然)；select與delAll之條件之巢狀深度(物件與陣列各算一層)超過64層者reject 'invalid find of select, too deep'。條件與寫入列(insert、save、mix之新增與修改)之任何深度(一般物件之值、陣列之元素)含自有__proto__鍵(JSON.parse、Object.fromEntries、structuredClone等可產生；物件字面量之__proto__為設原型而不算)或存取器屬性(getter、setter)者整批reject，如'invalid find of select, unsupported key[<strong>proto</strong>]'、'failed to insert data, unsupported accessor property: data[0]'，訊息不回顯客戶端之值。select與delAll之條件另拒絕複製時會被洗掉之結構，整批reject：Symbol鍵或不可列舉鍵('invalid find of select, unsupported symbol key or non-enumerable property')；Proxy(含已撤銷者、原型為Proxy者)、帶Symbol.toStringTag者(自有或繼承，含Map、Set等內建品牌物件)、內建品牌物件(含原型被改為null者)、非純物件(類別實例、偽原型等)、有空洞或額外屬性或不可列舉元素之陣列、帶自有屬性之Date、函數值與Symbol值('invalid find of select, unsupported irregular object or array')，使後端所見之條件同呼叫端所給者，且檢查期間與拒收後之診斷輸出皆不執行使用端程式(陷阱、getter、Symbol.toStringTag與util.inspect.custom；被拒條件以本層建立之純資料快照輸出至console.log，字串長度、層數與項數有上限)；以Proxy包裝之條件(如Vue響應式物件)與Mongoose等文件須先轉為純物件(寫入列不在此限)。跨realm之純物件照常：於字串型主鍵表之複製位置(頂層、$and/$or元素、id之運算子物件)被複製為本realm物件，其餘位置原樣交後端，現行後端白名單要求本realm物件而reject。含整數length鍵之條件與寫入列本身依其自有鍵處置，不被當成陣列樣物件；欄位值內之巢狀物件之XSS清除由wsemi之clearXSS進行，不在此限(見規則帳本R-OBJ-01之已知限制)。mix之del各筆與單獨del之各筆不做上述檢查。
+資料表名(procOrm之woName)須為本實例資料表之自有名稱，否則reject 'can not find table[x] in ORM'(原型鏈上之名稱如constructor、toString與路徑字串如tests.select亦然)；select與delAll之條件之巢狀深度(物件與陣列各算一層，共用子結構與循環以最長路徑計)超過64層者reject 'invalid find of select, too deep'，共用子結構依出現次數展開後之物件總數(不含陣列)超過100000(與後端maxNodes同值，本層只計物件、為其子集)者reject 'invalid find of select, too large'(同一子條件被重用於多處之合理寫法不受影響)；物件或陣列之原型鏈長度超過65層者視為不乾淨而reject 'unsupported irregular object or array'。條件與寫入列(insert、save、mix之新增與修改)之任何深度(一般物件之值、陣列之元素)含自有__proto__鍵(JSON.parse、Object.fromEntries、structuredClone等可產生；物件字面量之__proto__為設原型而不算)或存取器屬性(getter、setter)者整批reject，如'invalid find of select, unsupported key[<strong>proto</strong>]'、'failed to insert data, unsupported accessor property: data[0]'，訊息不回顯客戶端之值。select與delAll之條件另拒絕複製時會被洗掉之結構，整批reject：Symbol鍵或不可列舉鍵('invalid find of select, unsupported symbol key or non-enumerable property')；Proxy(含已撤銷者、原型為Proxy者)、帶Symbol.toStringTag者(自有或繼承，含Map、Set等內建品牌物件)、內建品牌物件(含原型被改為null者)、非純物件(類別實例、偽原型等)、有空洞或額外屬性或不可列舉元素之陣列、帶自有屬性之Date、函數值與Symbol值('invalid find of select, unsupported irregular object or array')，使後端所見之條件同呼叫端所給者，且檢查期間與拒收後之診斷輸出皆不執行使用端程式(陷阱、getter、Symbol.toStringTag與util.inspect.custom；被拒條件以本層建立之純資料快照輸出至console.log，字串長度、層數與項數有上限)；以Proxy包裝之條件(如Vue響應式物件)與Mongoose等文件須先轉為純物件(寫入列不在此限)。跨realm之純物件照常：於字串型主鍵表之複製位置(頂層、$and/$or元素、id之運算子物件)被複製為本realm物件，其餘位置原樣交後端，現行後端白名單要求本realm物件而reject。含整數length鍵之條件與寫入列本身依其自有鍵處置，不被當成陣列樣物件；欄位值內之巢狀物件之XSS清除由wsemi之clearXSS進行，不在此限(見規則帳本R-OBJ-01之已知限制)。mix之del各筆與單獨del之各筆不做上述各項檢查(交ORM逐筆處置)，惟批次容器與mix.del列之id另受下一點限制。
+寫入列(insert、save、mix之新增與修改)、del與批次容器(通過檢查之後，本層不再執行使用端程式：不呼叫getter、setter與Proxy陷阱，複製只取已驗證之資料)：列之主鍵(id)只認自有、可列舉之資料屬性(以屬性描述子讀取，不執行getter)，通過鍵檢查後不可列舉、繼承或經存取器者視為未提供(寫入列由本套件補主鍵，與直接呼叫ORM寫入不可列舉之id時一致)，自有可列舉之存取器id則先整批reject('unsupported accessor property: data[0]')；列本身為Proxy(含Vue響應式物件與已撤銷者)、函數(含callable Proxy與宣稱Symbol.toStringTag之函數)、原型鏈上有Symbol.toStringTag、或util.types可辨識之內建品牌物件(如原型被改為null之Map、Set；WeakRef、FinalizationRegistry、Intl.</em>、KeyObject、Blob、URL等宿主物件不辨識，結果與直接呼叫ORM一致)者整批reject，如'failed to insert data, unsupported irregular object or array: data[0]'，且不觸發Proxy陷阱；以Proxy包裝之列或陣列(如Vue響應式)須先轉為純物件；類別實例含自有欄位之物件、Object.create(proto)、跨realm與null原型之列照常(僅複製自有可列舉鍵)。insert、save、del之輸入陣列與mix之add、del、diff須為乾淨之真密陣列且各索引為自有資料屬性：Proxy(含已撤銷者)、原型鏈有標籤、有空洞、索引為存取器者整批reject，如'failed to insert data, unsupported sparse array: data[1]'(稀疏巨陣列如new Array(2**32-1)於首個空洞即被拒，不逐索引迴圈)，列內巢狀陣列有空洞者亦然；偽造Symbol.toStringTag為Array之類陣列物件不視為陣列。mix之輸入物件本身須為乾淨之一般物件，add、del、diff只取其自有資料屬性；mix之del列另須其id若存在為自有、可列舉之資料屬性(不得為存取器、繼承而來、不可列舉，列不得為Proxy、函數宣稱標籤或帶標籤)，否則整批reject 'failed to delete data, unsupported irregular object or array: data[0]'，使同鍵比對所見之id即ORM刪除所用之id。單獨del之各筆不做列檢查(交ORM逐筆處置)。稽核欄位(userId、timeCreate、userIdUpdate、timeUpdate)以defineProperty寫入，類別DTO原型上之setter不被執行。列內欄位值為共用子結構(DAG)者，其展開由wsemi之clearXSS進行，本套件之走訪為線性(見規則帳本R-OBJ-01規則7)。
 mix之add與del、del與diff含同一主鍵(依上述轉型後)者，於任何步驟之前整批reject且不寫入任何一筆，訊息列其位置而不回顯主鍵，如'invalid input of mix, same id in add and del: add[0], del[1]'；因mix依add、del、diff之序執行，同鍵將使新增因已存在而略過後即被刪除。
 insert(含mix之新增)為主鍵已存在即略過之冪等新增，回傳之id含被略過者；recover亦以insert還原，故資料表須先清空。
 insert、save與mix之新增、修改，寫入前各欄位之字串皆經wsemi之clearXSS清除(白名單外之標籤轉義，白名單內之標籤刪除白名單外之屬性與危險網址，標籤外之文字只轉義會開始標籤之&lt;，故'a &lt; b'等數學式不改寫)；select與del不經清除。
@@ -103,7 +104,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#line103">line 103</a>
+        <a href="WServOrm.mjs.html">WServOrm.mjs</a>, <a href="WServOrm.mjs.html#line104">line 104</a>
     </li></ul></dd>
     
 
@@ -446,7 +447,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 Tue Oct 20 2026 04:25:02 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 Tue Oct 20 2026 11:25:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WServOrm.mjs.html

@@ -70,7 +70,8 @@ import getProc from './getProc.mjs'
  * 輸入之形狀：insert與save之各筆、mix之新增與修改之各筆須為物件，mix之add、del、diff若給予須為陣列，select與delAll之條件若給予須為純物件(原型為null或Object.prototype；未給、undefined與空物件{}為無條件：select回全部、delAll刪除全部；null、陣列、字串、數字、布林、函數、Date、RegExp、Map、Set與類別實例皆reject)，否則於任何寫入或查詢之前reject，如'failed to insert data, not an object: data[0]'、'invalid find of select, need an object'、'invalid find of delAll, need an object'。
  * 條件(find)：select與delAll之條件僅支援系列白名單，由各w-orm-*依相同規則檢核(須為已實作該白名單之w-orm-*版本；舊版或尚未更新者仍可能接受白名單外之運算子，不在下述保證內)，本套件不依運算子放行或攔截(僅轉型主鍵條件，見上)：欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與$in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)；純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date，null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $all $where $expr $like $ilike等)、欄位層$and/$or、函數值、undefined值、空的$nin/$and/$or等，由ORM整批reject，procOrm以固定字串回傳(select為'failed to select data'，delAll為'failed to delete data')，ORM之錯誤原文只由console.log輸出，delAll不刪除任何數據。select未給、為undefined或{}時回傳全部數據；select(find)命中之數據即delAll(find)刪除之數據。
  * delAll(破壞性操作，須審慎使用，非必要不用；刪除單筆請用del)：不給條件(未給、undefined或{})即刪除全部數據，不另行確認，給了條件才是部分刪除；傳了值卻不是條件物件(null、陣列含[]與[{...}]、字串、數值、布林、函數、Date、RegExp、Map、Set、類別實例等)一律整批reject，不視為{}，不刪除任何數據。經資料通道(前端直接操作資料表，如w-serv-webdata)呼叫之delAll與此語意一致，不另加通道專屬限制，以免用法歧異造成誤解；通道端若另有更窄之條件限縮，未通過者由通道端拒絕，授權仍由開放處負責；通訊內容經JSON序列化時，顯式傳入之undefined會成為null而被reject，前端須省略參數或傳{}。條件值若來自可能為undefined、null或空陣列之變數，呼叫端須先自行判斷(undefined值會reject而非被忽略，空的$nin會reject，$in:[]則為恆假而刪除0筆)；建議先以select(find)確認命中範圍再刪除(ORM啟用快取而他方已寫入時，select可能回傳快取，而delAll一律直讀資料庫，預覽不保證即實際刪除之集合)。n與nDeleted皆為實際刪除筆數，條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。
- * 資料表名(procOrm之woName)須為本實例資料表之自有名稱，否則reject 'can not find table[x] in ORM'(原型鏈上之名稱如constructor、toString與路徑字串如tests.select亦然)；select與delAll之條件之巢狀深度(物件與陣列各算一層)超過64層者reject 'invalid find of select, too deep'。條件與寫入列(insert、save、mix之新增與修改)之任何深度(一般物件之值、陣列之元素)含自有__proto__鍵(JSON.parse、Object.fromEntries、structuredClone等可產生；物件字面量之__proto__為設原型而不算)或存取器屬性(getter、setter)者整批reject，如'invalid find of select, unsupported key[__proto__]'、'failed to insert data, unsupported accessor property: data[0]'，訊息不回顯客戶端之值。select與delAll之條件另拒絕複製時會被洗掉之結構，整批reject：Symbol鍵或不可列舉鍵('invalid find of select, unsupported symbol key or non-enumerable property')；Proxy(含已撤銷者、原型為Proxy者)、帶Symbol.toStringTag者(自有或繼承，含Map、Set等內建品牌物件)、內建品牌物件(含原型被改為null者)、非純物件(類別實例、偽原型等)、有空洞或額外屬性或不可列舉元素之陣列、帶自有屬性之Date、函數值與Symbol值('invalid find of select, unsupported irregular object or array')，使後端所見之條件同呼叫端所給者，且檢查期間與拒收後之診斷輸出皆不執行使用端程式(陷阱、getter、Symbol.toStringTag與util.inspect.custom；被拒條件以本層建立之純資料快照輸出至console.log，字串長度、層數與項數有上限)；以Proxy包裝之條件(如Vue響應式物件)與Mongoose等文件須先轉為純物件(寫入列不在此限)。跨realm之純物件照常：於字串型主鍵表之複製位置(頂層、$and/$or元素、id之運算子物件)被複製為本realm物件，其餘位置原樣交後端，現行後端白名單要求本realm物件而reject。含整數length鍵之條件與寫入列本身依其自有鍵處置，不被當成陣列樣物件；欄位值內之巢狀物件之XSS清除由wsemi之clearXSS進行，不在此限(見規則帳本R-OBJ-01之已知限制)。mix之del各筆與單獨del之各筆不做上述檢查。
+ * 資料表名(procOrm之woName)須為本實例資料表之自有名稱，否則reject 'can not find table[x] in ORM'(原型鏈上之名稱如constructor、toString與路徑字串如tests.select亦然)；select與delAll之條件之巢狀深度(物件與陣列各算一層，共用子結構與循環以最長路徑計)超過64層者reject 'invalid find of select, too deep'，共用子結構依出現次數展開後之物件總數(不含陣列)超過100000(與後端maxNodes同值，本層只計物件、為其子集)者reject 'invalid find of select, too large'(同一子條件被重用於多處之合理寫法不受影響)；物件或陣列之原型鏈長度超過65層者視為不乾淨而reject 'unsupported irregular object or array'。條件與寫入列(insert、save、mix之新增與修改)之任何深度(一般物件之值、陣列之元素)含自有__proto__鍵(JSON.parse、Object.fromEntries、structuredClone等可產生；物件字面量之__proto__為設原型而不算)或存取器屬性(getter、setter)者整批reject，如'invalid find of select, unsupported key[__proto__]'、'failed to insert data, unsupported accessor property: data[0]'，訊息不回顯客戶端之值。select與delAll之條件另拒絕複製時會被洗掉之結構，整批reject：Symbol鍵或不可列舉鍵('invalid find of select, unsupported symbol key or non-enumerable property')；Proxy(含已撤銷者、原型為Proxy者)、帶Symbol.toStringTag者(自有或繼承，含Map、Set等內建品牌物件)、內建品牌物件(含原型被改為null者)、非純物件(類別實例、偽原型等)、有空洞或額外屬性或不可列舉元素之陣列、帶自有屬性之Date、函數值與Symbol值('invalid find of select, unsupported irregular object or array')，使後端所見之條件同呼叫端所給者，且檢查期間與拒收後之診斷輸出皆不執行使用端程式(陷阱、getter、Symbol.toStringTag與util.inspect.custom；被拒條件以本層建立之純資料快照輸出至console.log，字串長度、層數與項數有上限)；以Proxy包裝之條件(如Vue響應式物件)與Mongoose等文件須先轉為純物件(寫入列不在此限)。跨realm之純物件照常：於字串型主鍵表之複製位置(頂層、$and/$or元素、id之運算子物件)被複製為本realm物件，其餘位置原樣交後端，現行後端白名單要求本realm物件而reject。含整數length鍵之條件與寫入列本身依其自有鍵處置，不被當成陣列樣物件；欄位值內之巢狀物件之XSS清除由wsemi之clearXSS進行，不在此限(見規則帳本R-OBJ-01之已知限制)。mix之del各筆與單獨del之各筆不做上述各項檢查(交ORM逐筆處置)，惟批次容器與mix.del列之id另受下一點限制。
+ * 寫入列(insert、save、mix之新增與修改)、del與批次容器(通過檢查之後，本層不再執行使用端程式：不呼叫getter、setter與Proxy陷阱，複製只取已驗證之資料)：列之主鍵(id)只認自有、可列舉之資料屬性(以屬性描述子讀取，不執行getter)，通過鍵檢查後不可列舉、繼承或經存取器者視為未提供(寫入列由本套件補主鍵，與直接呼叫ORM寫入不可列舉之id時一致)，自有可列舉之存取器id則先整批reject('unsupported accessor property: data[0]')；列本身為Proxy(含Vue響應式物件與已撤銷者)、函數(含callable Proxy與宣稱Symbol.toStringTag之函數)、原型鏈上有Symbol.toStringTag、或util.types可辨識之內建品牌物件(如原型被改為null之Map、Set；WeakRef、FinalizationRegistry、Intl.*、KeyObject、Blob、URL等宿主物件不辨識，結果與直接呼叫ORM一致)者整批reject，如'failed to insert data, unsupported irregular object or array: data[0]'，且不觸發Proxy陷阱；以Proxy包裝之列或陣列(如Vue響應式)須先轉為純物件；類別實例含自有欄位之物件、Object.create(proto)、跨realm與null原型之列照常(僅複製自有可列舉鍵)。insert、save、del之輸入陣列與mix之add、del、diff須為乾淨之真密陣列且各索引為自有資料屬性：Proxy(含已撤銷者)、原型鏈有標籤、有空洞、索引為存取器者整批reject，如'failed to insert data, unsupported sparse array: data[1]'(稀疏巨陣列如new Array(2**32-1)於首個空洞即被拒，不逐索引迴圈)，列內巢狀陣列有空洞者亦然；偽造Symbol.toStringTag為Array之類陣列物件不視為陣列。mix之輸入物件本身須為乾淨之一般物件，add、del、diff只取其自有資料屬性；mix之del列另須其id若存在為自有、可列舉之資料屬性(不得為存取器、繼承而來、不可列舉，列不得為Proxy、函數宣稱標籤或帶標籤)，否則整批reject 'failed to delete data, unsupported irregular object or array: data[0]'，使同鍵比對所見之id即ORM刪除所用之id。單獨del之各筆不做列檢查(交ORM逐筆處置)。稽核欄位(userId、timeCreate、userIdUpdate、timeUpdate)以defineProperty寫入，類別DTO原型上之setter不被執行。列內欄位值為共用子結構(DAG)者，其展開由wsemi之clearXSS進行，本套件之走訪為線性(見規則帳本R-OBJ-01規則7)。
  * mix之add與del、del與diff含同一主鍵(依上述轉型後)者，於任何步驟之前整批reject且不寫入任何一筆，訊息列其位置而不回顯主鍵，如'invalid input of mix, same id in add and del: add[0], del[1]'；因mix依add、del、diff之序執行，同鍵將使新增因已存在而略過後即被刪除。
  * insert(含mix之新增)為主鍵已存在即略過之冪等新增，回傳之id含被略過者；recover亦以insert還原，故資料表須先清空。
  * insert、save與mix之新增、修改，寫入前各欄位之字串皆經wsemi之clearXSS清除(白名單外之標籤轉義，白名單內之標籤刪除白名單外之屬性與危險網址，標籤外之文字只轉義會開始標籤之<，故'a < b'等數學式不改寫)；select與del不經清除。
@@ -198,7 +199,7 @@ export default WServOrm
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Tue Oct 20 2026 04:25:02 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 Tue Oct 20 2026 11:25:14 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 Tue Oct 20 2026 04:25:02 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 Tue Oct 20 2026 11:25:14 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

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

package/src/WServOrm.mjs

@@ -23,7 +23,8 @@ import getProc from './getProc.mjs'
  * 輸入之形狀：insert與save之各筆、mix之新增與修改之各筆須為物件，mix之add、del、diff若給予須為陣列，select與delAll之條件若給予須為純物件(原型為null或Object.prototype；未給、undefined與空物件{}為無條件：select回全部、delAll刪除全部；null、陣列、字串、數字、布林、函數、Date、RegExp、Map、Set與類別實例皆reject)，否則於任何寫入或查詢之前reject，如'failed to insert data, not an object: data[0]'、'invalid find of select, need an object'、'invalid find of delAll, need an object'。
  * 條件(find)：select與delAll之條件僅支援系列白名單，由各w-orm-*依相同規則檢核(須為已實作該白名單之w-orm-*版本；舊版或尚未更新者仍可能接受白名單外之運算子，不在下述保證內)，本套件不依運算子放行或攔截(僅轉型主鍵條件，見上)：欄位等值{欄:純量}(多欄為AND)、欄位運算子$eq $ne $gt $gte $lt $lte(值為純量)與$in $nin(值為純量陣列)、文件層$and $or(值為條件物件之非空陣列)；純量為字串(不含NUL字元與孤立代理字元)、有限數字、布林、有效Date，null僅可用於欄位等值、$eq、$ne。白名單外之運算子($not $nor $regex $options $exists $all $where $expr $like $ilike等)、欄位層$and/$or、函數值、undefined值、空的$nin/$and/$or等，由ORM整批reject，procOrm以固定字串回傳(select為'failed to select data'，delAll為'failed to delete data')，ORM之錯誤原文只由console.log輸出，delAll不刪除任何數據。select未給、為undefined或{}時回傳全部數據；select(find)命中之數據即delAll(find)刪除之數據。
  * delAll(破壞性操作，須審慎使用，非必要不用；刪除單筆請用del)：不給條件(未給、undefined或{})即刪除全部數據，不另行確認，給了條件才是部分刪除；傳了值卻不是條件物件(null、陣列含[]與[{...}]、字串、數值、布林、函數、Date、RegExp、Map、Set、類別實例等)一律整批reject，不視為{}，不刪除任何數據。經資料通道(前端直接操作資料表，如w-serv-webdata)呼叫之delAll與此語意一致，不另加通道專屬限制，以免用法歧異造成誤解；通道端若另有更窄之條件限縮，未通過者由通道端拒絕，授權仍由開放處負責；通訊內容經JSON序列化時，顯式傳入之undefined會成為null而被reject，前端須省略參數或傳{}。條件值若來自可能為undefined、null或空陣列之變數，呼叫端須先自行判斷(undefined值會reject而非被忽略，空的$nin會reject，$in:[]則為恆假而刪除0筆)；建議先以select(find)確認命中範圍再刪除(ORM啟用快取而他方已寫入時，select可能回傳快取，而delAll一律直讀資料庫，預覽不保證即實際刪除之集合)。n與nDeleted皆為實際刪除筆數，條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。
- * 資料表名(procOrm之woName)須為本實例資料表之自有名稱，否則reject 'can not find table[x] in ORM'(原型鏈上之名稱如constructor、toString與路徑字串如tests.select亦然)；select與delAll之條件之巢狀深度(物件與陣列各算一層)超過64層者reject 'invalid find of select, too deep'。條件與寫入列(insert、save、mix之新增與修改)之任何深度(一般物件之值、陣列之元素)含自有__proto__鍵(JSON.parse、Object.fromEntries、structuredClone等可產生；物件字面量之__proto__為設原型而不算)或存取器屬性(getter、setter)者整批reject，如'invalid find of select, unsupported key[__proto__]'、'failed to insert data, unsupported accessor property: data[0]'，訊息不回顯客戶端之值。select與delAll之條件另拒絕複製時會被洗掉之結構，整批reject：Symbol鍵或不可列舉鍵('invalid find of select, unsupported symbol key or non-enumerable property')；Proxy(含已撤銷者、原型為Proxy者)、帶Symbol.toStringTag者(自有或繼承，含Map、Set等內建品牌物件)、內建品牌物件(含原型被改為null者)、非純物件(類別實例、偽原型等)、有空洞或額外屬性或不可列舉元素之陣列、帶自有屬性之Date、函數值與Symbol值('invalid find of select, unsupported irregular object or array')，使後端所見之條件同呼叫端所給者，且檢查期間與拒收後之診斷輸出皆不執行使用端程式(陷阱、getter、Symbol.toStringTag與util.inspect.custom；被拒條件以本層建立之純資料快照輸出至console.log，字串長度、層數與項數有上限)；以Proxy包裝之條件(如Vue響應式物件)與Mongoose等文件須先轉為純物件(寫入列不在此限)。跨realm之純物件照常：於字串型主鍵表之複製位置(頂層、$and/$or元素、id之運算子物件)被複製為本realm物件，其餘位置原樣交後端，現行後端白名單要求本realm物件而reject。含整數length鍵之條件與寫入列本身依其自有鍵處置，不被當成陣列樣物件；欄位值內之巢狀物件之XSS清除由wsemi之clearXSS進行，不在此限(見規則帳本R-OBJ-01之已知限制)。mix之del各筆與單獨del之各筆不做上述檢查。
+ * 資料表名(procOrm之woName)須為本實例資料表之自有名稱，否則reject 'can not find table[x] in ORM'(原型鏈上之名稱如constructor、toString與路徑字串如tests.select亦然)；select與delAll之條件之巢狀深度(物件與陣列各算一層，共用子結構與循環以最長路徑計)超過64層者reject 'invalid find of select, too deep'，共用子結構依出現次數展開後之物件總數(不含陣列)超過100000(與後端maxNodes同值，本層只計物件、為其子集)者reject 'invalid find of select, too large'(同一子條件被重用於多處之合理寫法不受影響)；物件或陣列之原型鏈長度超過65層者視為不乾淨而reject 'unsupported irregular object or array'。條件與寫入列(insert、save、mix之新增與修改)之任何深度(一般物件之值、陣列之元素)含自有__proto__鍵(JSON.parse、Object.fromEntries、structuredClone等可產生；物件字面量之__proto__為設原型而不算)或存取器屬性(getter、setter)者整批reject，如'invalid find of select, unsupported key[__proto__]'、'failed to insert data, unsupported accessor property: data[0]'，訊息不回顯客戶端之值。select與delAll之條件另拒絕複製時會被洗掉之結構，整批reject：Symbol鍵或不可列舉鍵('invalid find of select, unsupported symbol key or non-enumerable property')；Proxy(含已撤銷者、原型為Proxy者)、帶Symbol.toStringTag者(自有或繼承，含Map、Set等內建品牌物件)、內建品牌物件(含原型被改為null者)、非純物件(類別實例、偽原型等)、有空洞或額外屬性或不可列舉元素之陣列、帶自有屬性之Date、函數值與Symbol值('invalid find of select, unsupported irregular object or array')，使後端所見之條件同呼叫端所給者，且檢查期間與拒收後之診斷輸出皆不執行使用端程式(陷阱、getter、Symbol.toStringTag與util.inspect.custom；被拒條件以本層建立之純資料快照輸出至console.log，字串長度、層數與項數有上限)；以Proxy包裝之條件(如Vue響應式物件)與Mongoose等文件須先轉為純物件(寫入列不在此限)。跨realm之純物件照常：於字串型主鍵表之複製位置(頂層、$and/$or元素、id之運算子物件)被複製為本realm物件，其餘位置原樣交後端，現行後端白名單要求本realm物件而reject。含整數length鍵之條件與寫入列本身依其自有鍵處置，不被當成陣列樣物件；欄位值內之巢狀物件之XSS清除由wsemi之clearXSS進行，不在此限(見規則帳本R-OBJ-01之已知限制)。mix之del各筆與單獨del之各筆不做上述各項檢查(交ORM逐筆處置)，惟批次容器與mix.del列之id另受下一點限制。
+ * 寫入列(insert、save、mix之新增與修改)、del與批次容器(通過檢查之後，本層不再執行使用端程式：不呼叫getter、setter與Proxy陷阱，複製只取已驗證之資料)：列之主鍵(id)只認自有、可列舉之資料屬性(以屬性描述子讀取，不執行getter)，通過鍵檢查後不可列舉、繼承或經存取器者視為未提供(寫入列由本套件補主鍵，與直接呼叫ORM寫入不可列舉之id時一致)，自有可列舉之存取器id則先整批reject('unsupported accessor property: data[0]')；列本身為Proxy(含Vue響應式物件與已撤銷者)、函數(含callable Proxy與宣稱Symbol.toStringTag之函數)、原型鏈上有Symbol.toStringTag、或util.types可辨識之內建品牌物件(如原型被改為null之Map、Set；WeakRef、FinalizationRegistry、Intl.*、KeyObject、Blob、URL等宿主物件不辨識，結果與直接呼叫ORM一致)者整批reject，如'failed to insert data, unsupported irregular object or array: data[0]'，且不觸發Proxy陷阱；以Proxy包裝之列或陣列(如Vue響應式)須先轉為純物件；類別實例含自有欄位之物件、Object.create(proto)、跨realm與null原型之列照常(僅複製自有可列舉鍵)。insert、save、del之輸入陣列與mix之add、del、diff須為乾淨之真密陣列且各索引為自有資料屬性：Proxy(含已撤銷者)、原型鏈有標籤、有空洞、索引為存取器者整批reject，如'failed to insert data, unsupported sparse array: data[1]'(稀疏巨陣列如new Array(2**32-1)於首個空洞即被拒，不逐索引迴圈)，列內巢狀陣列有空洞者亦然；偽造Symbol.toStringTag為Array之類陣列物件不視為陣列。mix之輸入物件本身須為乾淨之一般物件，add、del、diff只取其自有資料屬性；mix之del列另須其id若存在為自有、可列舉之資料屬性(不得為存取器、繼承而來、不可列舉，列不得為Proxy、函數宣稱標籤或帶標籤)，否則整批reject 'failed to delete data, unsupported irregular object or array: data[0]'，使同鍵比對所見之id即ORM刪除所用之id。單獨del之各筆不做列檢查(交ORM逐筆處置)。稽核欄位(userId、timeCreate、userIdUpdate、timeUpdate)以defineProperty寫入，類別DTO原型上之setter不被執行。列內欄位值為共用子結構(DAG)者，其展開由wsemi之clearXSS進行，本套件之走訪為線性(見規則帳本R-OBJ-01規則7)。
  * mix之add與del、del與diff含同一主鍵(依上述轉型後)者，於任何步驟之前整批reject且不寫入任何一筆，訊息列其位置而不回顯主鍵，如'invalid input of mix, same id in add and del: add[0], del[1]'；因mix依add、del、diff之序執行，同鍵將使新增因已存在而略過後即被刪除。
  * insert(含mix之新增)為主鍵已存在即略過之冪等新增，回傳之id含被略過者；recover亦以insert還原，故資料表須先清空。
  * insert、save與mix之新增、修改，寫入前各欄位之字串皆經wsemi之clearXSS清除(白名單外之標籤轉義，白名單內之標籤刪除白名單外之屬性與危險網址，標籤外之文字只轉義會開始標籤之<，故'a < b'等數學式不改寫)；select與del不經清除。