w-orm-reladb 1.1.10 → 1.1.12

package/docs/WOrmReladb.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmReladb.html">WOrmReladb</a><ul class='methods'><li data-type='method'><a href="WOrmReladb.html#.closeSequelize">closeSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.createStorage">createStorage</a></li><li data-type='method'><a href="WOrmReladb.html#.del">del</a></li><li data-type='method'><a href="WOrmReladb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByDB">genModelsByDB</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByTabs">genModelsByTabs</a></li><li data-type='method'><a href="WOrmReladb.html#.genTransaction">genTransaction</a></li><li data-type='method'><a href="WOrmReladb.html#.initSequelize">initSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmReladb.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmReladb.html#.save">save</a></li><li data-type='method'><a href="WOrmReladb.html#.select">select</a></li><li data-type='method'><a href="WOrmReladb.html#.selectByPk">selectByPk</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#cvFind">cvFind</a></li><li><a href="global.html#getColKind">getColKind</a></li><li><a href="global.html#getColScale">getColScale</a></li><li><a href="global.html#importModels">importModels</a></li><li><a href="global.html#isKindOk">isKindOk</a></li><li><a href="global.html#normPk">normPk</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmReladb.html">WOrmReladb</a><ul class='methods'><li data-type='method'><a href="WOrmReladb.html#.closeSequelize">closeSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.createStorage">createStorage</a></li><li data-type='method'><a href="WOrmReladb.html#.del">del</a></li><li data-type='method'><a href="WOrmReladb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByDB">genModelsByDB</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByTabs">genModelsByTabs</a></li><li data-type='method'><a href="WOrmReladb.html#.genTransaction">genTransaction</a></li><li data-type='method'><a href="WOrmReladb.html#.initSequelize">initSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmReladb.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmReladb.html#.save">save</a></li><li data-type='method'><a href="WOrmReladb.html#.select">select</a></li><li data-type='method'><a href="WOrmReladb.html#.selectByPk">selectByPk</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#cvFind">cvFind</a></li><li><a href="global.html#genDateChecker">genDateChecker</a></li><li><a href="global.html#getColKind">getColKind</a></li><li><a href="global.html#getColScale">getColScale</a></li><li><a href="global.html#importModels">importModels</a></li><li><a href="global.html#inDateRange">inDateRange</a></li><li><a href="global.html#isKindOk">isKindOk</a></li><li><a href="global.html#normPk">normPk</a></li></ul>
     
 </nav>
 
@@ -750,7 +750,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line522">line 522</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line546">line 546</a>
     </li></ul></dd>
     
 
@@ -858,7 +858,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1747">line 1747</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1788">line 1788</a>
     </li></ul></dd>
     
 
@@ -972,7 +972,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1440">line 1440</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1481">line 1481</a>
     </li></ul></dd>
     
 
@@ -1318,7 +1318,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1642">line 1642</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1683">line 1683</a>
     </li></ul></dd>
     
 
@@ -1648,7 +1648,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1789">line 1789</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1830">line 1830</a>
     </li></ul></dd>
     
 
@@ -2176,7 +2176,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1837">line 1837</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1878">line 1878</a>
     </li></ul></dd>
     
 
@@ -2481,7 +2481,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line538">line 538</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line562">line 562</a>
     </li></ul></dd>
     
 
@@ -2589,7 +2589,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line455">line 455</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line479">line 479</a>
     </li></ul></dd>
     
 
@@ -2767,6 +2767,10 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
 註: 同批含重複主鍵時僅首筆計入nInserted，其餘視為已存在
 註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入
 註: 主鍵值依主鍵欄型別正規化後寫入(字串類主鍵欄之123存為'123')；型別不符(整數類主鍵欄給'012'等)即reject且同批皆不寫入，不以自動產生之主鍵取代
+註: DATE、DATEONLY欄之值(Date、epoch數值、日期字串)換算後年份須在1–9999(DATE依UTC，DATEONLY依存入之日期文字)，範圍外者(如new Date(8.64e15)、'+010000-01-01T00:00:00Z')即reject且同批皆不寫入，
+錯誤訊息為invalid data: date is not a valid time in years 1-9999 at [data[索引].欄名]，不回顯值；sqlite以文字存日期，範圍外年份之文字與時間序不一致，會使以日期為條件之delAll刪錯列，
+故兩方言一律於送出前拒收；無效時間(Invalid Date、NaN、無法解析之字串、空字串等，sqlite會存為字典序大於任何年份之文字Invalid date，mssql則由資料庫報錯)亦一併reject；
+庫內既有之範圍外日期不遷移，須自行清理或改寫(見README)
 註: option.returnList開啟時改回與輸入等長且保序之逐筆結果陣列[{n,nInserted,ok}]，
 聚合計數只答得出[有幾筆是新的]而答不出[是哪幾筆]，而後者正是去重之產出物；
 逐筆元素之n與ok恆為1，資訊由nInserted承載，不變式為
@@ -2776,7 +2780,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line815">line 815</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line843">line 843</a>
     </li></ul></dd>
     
 
@@ -3146,6 +3150,8 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
 註: 不提供逐筆結果，故不出現ok為0與err；需要逐筆處置者改用insert
 註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入
 註: 主鍵值依主鍵欄型別正規化後寫入(字串類主鍵欄之123存為'123')；型別不符(整數類主鍵欄給'012'等)即reject且同批皆不寫入
+註: DATE、DATEONLY欄之值換算後年份須在1–9999，範圍外或無效者(如new Date(8.64e15)、new Date(NaN))即reject且同批皆不寫入，訊息為invalid data: date is not a valid time in years 1-9999 at [data[索引].欄名]，
+不回顯值，兩方言一致於送出前拒收，規則同insert
 註: [全有全無]為獨立於T7之額外要求——T7僅保證每筆之[檢查主鍵不存在]與[寫入]為原子，不保證整批。
 mssql因綁定參數數量上限會由驅動層自動拆為多語句送出，實測1000筆之批次於末筆撞主鍵時已有946筆落盤，
 故一律以交易包覆並於失敗時回滾；呼叫端已給transaction時改以巢狀交易(SAVEPOINT)包覆，
@@ -3155,7 +3161,7 @@ mssql因綁定參數數量上限會由驅動層自動拆為多語句送出，實
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line991">line 991</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1024">line 1024</a>
     </li></ul></dd>
     
 
@@ -3483,13 +3489,15 @@ mssql因綁定參數數量上限會由驅動層自動拆為多語句送出，實
 故只給部份欄位且該些欄位值皆與現值相同時，合併結果等於現值，nModified為0
 註: 本筆失敗不中斷整批，該筆以ok為0並附err回報
 註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入
-註: 主鍵值依主鍵欄型別正規化(字串類主鍵欄之123即'123')；型別不符(整數類主鍵欄給'012'等)屬呼叫端未履行契約，整批reject且同批皆不寫入</p></li></ul></dd>
+註: 主鍵值依主鍵欄型別正規化(字串類主鍵欄之123即'123')；型別不符(整數類主鍵欄給'012'等)屬呼叫端未履行契約，整批reject且同批皆不寫入
+註: DATE、DATEONLY欄之值換算後年份須在1–9999，範圍外或無效者(如new Date(8.64e15)、new Date(NaN))屬呼叫端未履行契約，整批reject且同批皆不寫入(含autoInsert為false而不會寫入者；不降為該筆ok為0)，
+訊息為invalid data: date is not a valid time in years 1-9999 at [data[索引].欄名]，不回顯值，兩方言一致於送出前拒收，規則同insert</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1324">line 1324</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line1362">line 1362</a>
     </li></ul></dd>
     
 
@@ -3873,7 +3881,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line580">line 580</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line604">line 604</a>
     </li></ul></dd>
     
 
@@ -4206,7 +4214,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line685">line 685</a>
+        <a href="WOrmReladb.mjs.html">WOrmReladb.mjs</a>, <a href="WOrmReladb.mjs.html#line709">line 709</a>
     </li></ul></dd>
     
 
@@ -4532,7 +4540,7 @@ sequelize之Op Symbol、RegExp值、陣列值(請改用$in)、欄位層$and/$or
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Oct 19 2026 18:54:43 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 04:13:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WOrmReladb.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmReladb.html">WOrmReladb</a><ul class='methods'><li data-type='method'><a href="WOrmReladb.html#.closeSequelize">closeSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.createStorage">createStorage</a></li><li data-type='method'><a href="WOrmReladb.html#.del">del</a></li><li data-type='method'><a href="WOrmReladb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByDB">genModelsByDB</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByTabs">genModelsByTabs</a></li><li data-type='method'><a href="WOrmReladb.html#.genTransaction">genTransaction</a></li><li data-type='method'><a href="WOrmReladb.html#.initSequelize">initSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmReladb.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmReladb.html#.save">save</a></li><li data-type='method'><a href="WOrmReladb.html#.select">select</a></li><li data-type='method'><a href="WOrmReladb.html#.selectByPk">selectByPk</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#cvFind">cvFind</a></li><li><a href="global.html#getColKind">getColKind</a></li><li><a href="global.html#getColScale">getColScale</a></li><li><a href="global.html#importModels">importModels</a></li><li><a href="global.html#isKindOk">isKindOk</a></li><li><a href="global.html#normPk">normPk</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmReladb.html">WOrmReladb</a><ul class='methods'><li data-type='method'><a href="WOrmReladb.html#.closeSequelize">closeSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.createStorage">createStorage</a></li><li data-type='method'><a href="WOrmReladb.html#.del">del</a></li><li data-type='method'><a href="WOrmReladb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByDB">genModelsByDB</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByTabs">genModelsByTabs</a></li><li data-type='method'><a href="WOrmReladb.html#.genTransaction">genTransaction</a></li><li data-type='method'><a href="WOrmReladb.html#.initSequelize">initSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmReladb.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmReladb.html#.save">save</a></li><li data-type='method'><a href="WOrmReladb.html#.select">select</a></li><li data-type='method'><a href="WOrmReladb.html#.selectByPk">selectByPk</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#cvFind">cvFind</a></li><li><a href="global.html#genDateChecker">genDateChecker</a></li><li><a href="global.html#getColKind">getColKind</a></li><li><a href="global.html#getColScale">getColScale</a></li><li><a href="global.html#importModels">importModels</a></li><li><a href="global.html#inDateRange">inDateRange</a></li><li><a href="global.html#isKindOk">isKindOk</a></li><li><a href="global.html#normPk">normPk</a></li></ul>
     
 </nav>
 
@@ -72,7 +72,7 @@ import pmQueue from 'wsemi/src/pmQueue.mjs'
 import WAutoSequelize from 'w-auto-sequelize/src/WAutoSequelize.mjs'
 import importModels from './importModels.mjs'
 import _genModelsByTabs from './genModelsByTabs.mjs'
-import cvFind, { getColKind, getColScale, normPk, chkFindShape } from './cvFind.mjs'
+import cvFind, { getColKind, getColScale, normPk, chkFindShape, genDateChecker } from './cvFind.mjs'
 
 
 //放置於全域宣告, 若使用useStable=true才可於當創建多實例時仍能全域控管
@@ -429,6 +429,30 @@ function WOrmReladb(opt = {}) {
     }
 
 
+    /**
+     * 檢核各筆數據之DATE、DATEONLY欄值是否為年份在1–9999之有效時間(見cvFind.mjs之genDateChecker與inDateRange), 範圍外或無效者整批拋出
+     * 註: 通過檢核之物件值(Date及其子類別、包裝物件、陣列等)由檢核函數就地換成已檢核之標準值(Date或YYYY-MM-DD文字)，令檢查之值即使用之值；操作對象為cloneDeep後之複本，呼叫端數據不變
+     * 註: 須於normPks之後、任何寫入之前對全部筆數一次完成, 令拋錯時同批之有效筆數亦不會被寫入, 資料庫不變; 與條件側共用同一範圍判定
+     * 註: 訊息只含筆數索引與欄名, 不回顯值; 同筆多欄範圍外者回報model屬性定義順序之第一個, 多筆範圍外者回報索引最小者
+     * 註: sqlite以文字存DATE, 範圍外年份之文字與時間序不一致(哨兵new Date(8.64e15)存為275760-09-13…, 被$lt某日期誤中而遭delAll刪除), 故寫入時即拒收;
+     * mssql之datetimeoffset、date範圍亦為0001–9999, 本函數於送出前即拒, 不依賴資料庫報錯, 兩方言行為一致
+     *
+     * @ignore
+     * @param {Object} md 輸入資料表model物件
+     * @param {Array} data 輸入已補齊並正規化主鍵之數據陣列
+     * @returns {undefined} 無回傳值
+     */
+    function chkDates(md, data) {
+        let chk = genDateChecker(get(md, 'rawAttributes', {}))
+        data.forEach((v, k) => {
+            let col = chk(v)
+            if (col !== null) {
+                throw new Error(`invalid data: date is not a valid time in years 1-9999 at [data[${k}].${col}]`)
+            }
+        })
+    }
+
+
     /**
      * 依model之主鍵欄型別正規化主鍵值
      * 註: 規則見cvFind.mjs之normPk(與w-orm-mdb同一規則), 用於selectByPk、del、save、insert與insertBulk,
@@ -846,6 +870,10 @@ function WOrmReladb(opt = {}) {
      * 註: 同批含重複主鍵時僅首筆計入nInserted，其餘視為已存在
      * 註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入
      * 註: 主鍵值依主鍵欄型別正規化後寫入(字串類主鍵欄之123存為'123')；型別不符(整數類主鍵欄給'012'等)即reject且同批皆不寫入，不以自動產生之主鍵取代
+     * 註: DATE、DATEONLY欄之值(Date、epoch數值、日期字串)換算後年份須在1–9999(DATE依UTC，DATEONLY依存入之日期文字)，範圍外者(如new Date(8.64e15)、'+010000-01-01T00:00:00Z')即reject且同批皆不寫入，
+     * 錯誤訊息為invalid data: date is not a valid time in years 1-9999 at [data[索引].欄名]，不回顯值；sqlite以文字存日期，範圍外年份之文字與時間序不一致，會使以日期為條件之delAll刪錯列，
+     * 故兩方言一律於送出前拒收；無效時間(Invalid Date、NaN、無法解析之字串、空字串等，sqlite會存為字典序大於任何年份之文字Invalid date，mssql則由資料庫報錯)亦一併reject；
+     * 庫內既有之範圍外日期不遷移，須自行清理或改寫(見README)
      * 註: option.returnList開啟時改回與輸入等長且保序之逐筆結果陣列[{n,nInserted,ok}]，
      * 聚合計數只答得出[有幾筆是新的]而答不出[是哪幾筆]，而後者正是去重之產出物；
      * 逐筆元素之n與ok恆為1，資訊由nInserted承載，不變式為
@@ -930,6 +958,9 @@ function WOrmReladb(opt = {}) {
             //normPks, 主鍵值依主鍵欄型別正規化後寫回, 型別不符者整批reject且不寫入任何一筆, 令insert對既有數據之認定與selectByPk一致
             normPks(md, data)
 
+            //chkDates, DATE、DATEONLY欄之值須為年份在1–9999之有效時間, 範圍外或無效者整批reject且不寫入任何一筆(與條件側共用範圍判定, 見R12)
+            chkDates(md, data)
+
             //nAll, n之基準為輸入筆數
             let nAll = size(data)
 
@@ -1023,6 +1054,8 @@ function WOrmReladb(opt = {}) {
      * 註: 不提供逐筆結果，故不出現ok為0與err；需要逐筆處置者改用insert
      * 註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入
      * 註: 主鍵值依主鍵欄型別正規化後寫入(字串類主鍵欄之123存為'123')；型別不符(整數類主鍵欄給'012'等)即reject且同批皆不寫入
+     * 註: DATE、DATEONLY欄之值換算後年份須在1–9999，範圍外或無效者(如new Date(8.64e15)、new Date(NaN))即reject且同批皆不寫入，訊息為invalid data: date is not a valid time in years 1-9999 at [data[索引].欄名]，
+     * 不回顯值，兩方言一致於送出前拒收，規則同insert
      * 註: [全有全無]為獨立於T7之額外要求——T7僅保證每筆之[檢查主鍵不存在]與[寫入]為原子，不保證整批。
      * mssql因綁定參數數量上限會由驅動層自動拆為多語句送出，實測1000筆之批次於末筆撞主鍵時已有946筆落盤，
      * 故一律以交易包覆並於失敗時回滾；呼叫端已給transaction時改以巢狀交易(SAVEPOINT)包覆，
@@ -1100,6 +1133,9 @@ function WOrmReladb(opt = {}) {
             //normPks, 主鍵值依主鍵欄型別正規化後寫回, 型別不符者整批reject且不寫入任何一筆
             normPks(md, data)
 
+            //chkDates, DATE、DATEONLY欄之值須為年份在1–9999之有效時間, 範圍外或無效者整批reject且不寫入任何一筆(與條件側共用範圍判定, 見R12)
+            chkDates(md, data)
+
             //nAll, n之基準為輸入筆數
             let nAll = size(data)
 
@@ -1359,6 +1395,8 @@ function WOrmReladb(opt = {}) {
      * 註: 本筆失敗不中斷整批，該筆以ok為0並附err回報
      * 註: opt.autoGenPk為true(預設)時未帶有效主鍵者自動產生，為false時未帶有效主鍵即reject且同批皆不寫入
      * 註: 主鍵值依主鍵欄型別正規化(字串類主鍵欄之123即'123')；型別不符(整數類主鍵欄給'012'等)屬呼叫端未履行契約，整批reject且同批皆不寫入
+     * 註: DATE、DATEONLY欄之值換算後年份須在1–9999，範圍外或無效者(如new Date(8.64e15)、new Date(NaN))屬呼叫端未履行契約，整批reject且同批皆不寫入(含autoInsert為false而不會寫入者；不降為該筆ok為0)，
+     * 訊息為invalid data: date is not a valid time in years 1-9999 at [data[索引].欄名]，不回顯值，兩方言一致於送出前拒收，規則同insert
      *
      * @memberOf WOrmReladb
      * @param {Object|Array} data 輸入數據物件或陣列
@@ -1432,6 +1470,9 @@ function WOrmReladb(opt = {}) {
             //normPks, 主鍵值依主鍵欄型別正規化後寫回, 型別不符者整批reject且不寫入任何一筆
             normPks(md, data)
 
+            //chkDates, DATE、DATEONLY欄之值須為年份在1–9999之有效時間, 範圍外或無效者整批reject且不寫入任何一筆(含autoInsert為false而不會寫入者; 與條件側共用範圍判定, 見R12)
+            chkDates(md, data)
+
             //ks, model之欄位名, 供合併後比對時濾除非欄位之鍵
             let ks = keys(get(md, 'rawAttributes', {}))
 
@@ -1951,7 +1992,7 @@ export default WOrmReladb
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Oct 19 2026 18:54:43 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 04:13:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/cvFind.mjs.html

@@ -29,7 +29,7 @@
 <nav >
     
     
-    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmReladb.html">WOrmReladb</a><ul class='methods'><li data-type='method'><a href="WOrmReladb.html#.closeSequelize">closeSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.createStorage">createStorage</a></li><li data-type='method'><a href="WOrmReladb.html#.del">del</a></li><li data-type='method'><a href="WOrmReladb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByDB">genModelsByDB</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByTabs">genModelsByTabs</a></li><li data-type='method'><a href="WOrmReladb.html#.genTransaction">genTransaction</a></li><li data-type='method'><a href="WOrmReladb.html#.initSequelize">initSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmReladb.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmReladb.html#.save">save</a></li><li data-type='method'><a href="WOrmReladb.html#.select">select</a></li><li data-type='method'><a href="WOrmReladb.html#.selectByPk">selectByPk</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#cvFind">cvFind</a></li><li><a href="global.html#getColKind">getColKind</a></li><li><a href="global.html#getColScale">getColScale</a></li><li><a href="global.html#importModels">importModels</a></li><li><a href="global.html#isKindOk">isKindOk</a></li><li><a href="global.html#normPk">normPk</a></li></ul>
+    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmReladb.html">WOrmReladb</a><ul class='methods'><li data-type='method'><a href="WOrmReladb.html#.closeSequelize">closeSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.createStorage">createStorage</a></li><li data-type='method'><a href="WOrmReladb.html#.del">del</a></li><li data-type='method'><a href="WOrmReladb.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByDB">genModelsByDB</a></li><li data-type='method'><a href="WOrmReladb.html#.genModelsByTabs">genModelsByTabs</a></li><li data-type='method'><a href="WOrmReladb.html#.genTransaction">genTransaction</a></li><li data-type='method'><a href="WOrmReladb.html#.initSequelize">initSequelize</a></li><li data-type='method'><a href="WOrmReladb.html#.insert">insert</a></li><li data-type='method'><a href="WOrmReladb.html#.insertBulk">insertBulk</a></li><li data-type='method'><a href="WOrmReladb.html#.save">save</a></li><li data-type='method'><a href="WOrmReladb.html#.select">select</a></li><li data-type='method'><a href="WOrmReladb.html#.selectByPk">selectByPk</a></li></ul></li></ul><h3>Global</h3><ul><li><a href="global.html#cvFind">cvFind</a></li><li><a href="global.html#genDateChecker">genDateChecker</a></li><li><a href="global.html#getColKind">getColKind</a></li><li><a href="global.html#getColScale">getColScale</a></li><li><a href="global.html#importModels">importModels</a></li><li><a href="global.html#inDateRange">inDateRange</a></li><li><a href="global.html#isKindOk">isKindOk</a></li><li><a href="global.html#normPk">normPk</a></li></ul>
     
 </nav>
 
@@ -66,6 +66,10 @@ import cvOrmFind from 'wsemi/src/cvOrmFind.mjs'
 let Op = Sequelize.Op
 
 
+//SQL運算式(Sequelize.fn、literal、col等)之基底類別, 寫入DATE欄之值為此類者由呼叫端明示, 不檢(R12)
+let SM = Sequelize.Utils.SequelizeMethod
+
+
 //形狀檢核之上限(傳給cvOrmFind): $and/$or長度999——SQLite平鋪$or/$and恰1000項即Expression tree is too large(DB錯誤), 本套件使用SQLite故下調(預設1000);
 //其餘上限用預設: 邏輯巢狀深度32、$in/$nin長度10000、節點總數100000、欄名128
 let optShape = { maxList: 999 }
@@ -358,15 +362,132 @@ function resolveAttr(attrs, idx, field, path) {
 }
 
 
+//DATE可接受之年份範圍, 條件側(isKindOk、parseNoTzLocal)與寫入側(genDateChecker)共用之唯一定義(R4、R12)
+let yearMin = 1
+let yearMax = 9999
+
+
 /**
- * 判定時間(毫秒)換算UTC後年份是否在1–9999
- * 註: sequelize以YYYY格式化DATE, 年10000起為5位數, sqlite以文字比較致{d:{$gt:年10000}}命中全部日期列; mssql之datetimeoffset範圍亦為0001–9999
+ * 判定年份是否在1–9999
+ * 註: sequelize以YYYY格式化DATE, 年10000起為5位數、年0與負年份亦非4位數, sqlite以文字比較致時間序與字典序不一致(哨兵8.64e15被$lt某日期誤中、$gt漏中);
+ * mssql之datetimeoffset與date範圍亦為0001–9999
  *
  * @ignore
  */
+function inYearRange(y) {
+    return y >= yearMin &amp;&amp; y &lt;= yearMax
+}
+
+
+/**
+ * 判定時間(毫秒)換算UTC後年份是否在1–9999, 供條件側與寫入側共用(R4、R12); 無效時間(NaN、超出Date範圍)為false
+ *
+ * @param {Number} ms 輸入時間毫秒數
+ * @returns {Boolean} 回傳是否在範圍內
+ */
 function inDateRange(ms) {
-    let y = new Date(ms).getUTCFullYear()
-    return y >= 1 &amp;&amp; y &lt;= 9999
+    return inYearRange(new Date(ms).getUTCFullYear())
+}
+
+
+/**
+ * 取DATEONLY欄把值轉為實際存入之YYYY-MM-DD文字之函數(sequelize之DATEONLY._sanitize)
+ * 註: 真正之rawAttributes其type為型別實例; 手造attrs可能給型別建構子(如Sequelize.DATEONLY)或只有key之物件, 此時用sequelize內建DATEONLY之_sanitize(兩者同一函數);
+ * 取不到(sequelize版本漂移)時於換算時拋錯, 由chkWriteDate視為無效而拒收(fail-closed, 版本漂移另有單元測試之guard案)
+ *
+ * @ignore
+ */
+function getDateOnlySanitizer(type) {
+    let t = type &amp;&amp; typeof type._sanitize === 'function' ? type : DT.DATEONLY.prototype
+    return (v) => t._sanitize(v, {})
+}
+
+
+/**
+ * 檢核寫入DATE/DATEONLY欄之單一值(R12), 回傳{ok, v}: ok為是否為「年份在1–9999之有效時間」, v為建議寫回之標準值(undefined表示維持原值)
+ * 註: date——以sequelize之DATE._sanitize同一轉換取得時間(Date原樣, 其餘truthy值new Date(值)), 以inDateRange判定UTC年份;
+ * falsy值sequelize不轉換, 僅0(epoch 0)有效, 其餘('', false, NaN)會被存為文字Invalid date而拒收
+ * 註: dateonly——sequelize以moment(值)依主機本地時間格式化為YYYY-MM-DD文字存入, 以該型別之_sanitize所得之文字(= 實際存入者)判定:
+ * 須為4位數年且在1–9999(範圍外年份之文字形狀為5位以上、帶負號或年0000, 如new Date(8.64e15)得275760-09-13、new Date(-8.64e15)得-271821-04-20), Invalid date文字亦拒收
+ * 註: 無效時間(Invalid Date、NaN、無法解析之字串、超出Date範圍之數值、BigInt與Symbol…)一律拒收: sqlite存為文字Invalid date, 其字典序大於任何年份而使$gt命中、delAll誤刪,
+ * mssql則由資料庫報錯, 兩方言不一致(外審Argon F5; 與條件側無效Date一律reject同)
+ * 註: 檢查之值即使用之值——物件值(Date及其子類別、包裝物件、陣列、含自訂valueOf/toString者)可被sequelize再度求值而得不同結果, 故回傳已檢核之標準值(Date或YYYY-MM-DD文字)供呼叫端換上;
+ * 原始值(字串、數值)不可變, 不換
+ * 註: Sequelize.fn、literal、col等SQL運算式(SequelizeMethod)由呼叫端明示, sequelize不轉換, 不檢
+ *
+ * @ignore
+ */
+function chkWriteDate(v, kind, sanitize) {
+    if (v instanceof SM) {
+        return { ok: true, v: undefined }
+    }
+    if (!v) {
+        return { ok: v === 0, v: undefined }
+    }
+    if (typeof v === 'bigint' || typeof v === 'symbol') {
+        return { ok: false, v: undefined } //BigInt與Symbol不是時間(new Date(1n)拋錯, moment(1n)卻視為年2001), 一律拒收
+    }
+    try {
+        if (kind === 'date') {
+            let ms = (v instanceof Date ? v : new Date(v)).getTime()
+            if (!inDateRange(ms)) {
+                return { ok: false, v: undefined }
+            }
+            return { ok: true, v: typeof v === 'object' ? new Date(ms) : undefined }
+        }
+        let s = sanitize(v)
+        let m = typeof s === 'string' ? s.match(reDateOnly) : null
+        if (m === null || !inYearRange(Number(m[1]))) {
+            return { ok: false, v: undefined }
+        }
+        return { ok: true, v: typeof v === 'object' ? s : undefined }
+    }
+    catch (err) {
+        return { ok: false, v: undefined } //換算時拋錯(Symbol、BigInt、無原型物件等)亦非有效時間
+    }
+}
+
+
+/**
+ * 產生寫入數據之DATE/DATEONLY欄範圍檢核函數(R12): 回傳之函數對單筆數據(物件)檢核各DATE、DATEONLY屬性之值,
+ * 回傳第一個無效或範圍外(年份不在1–9999)之屬性名(依model屬性定義順序), 皆合法回傳null
+ * 註: 與條件側共用inDateRange; 只檢核model中型別為DATE(date)與DATEONLY(dateonly)之屬性, 值為null或undefined者不檢;
+ * 非物件之記錄回傳null(由呼叫端前段檢核負責)
+ * 註: 通過檢核之物件值(Date及其子類別、包裝物件、陣列等)就地換成已檢核之標準值(Date或YYYY-MM-DD文字), 令檢查之值即使用之值(見chkWriteDate);
+ * 僅換記錄自有屬性, 原型鏈上之屬性只讀不換(create與bulkCreate不讀原型鏈屬性, update會讀, 故原型鏈上具狀態之getter不在保證範圍)
+ *
+ * @param {Object} attrs 輸入model之rawAttributes, 非物件時回傳恆為null之檢核函數
+ * @returns {Function} 回傳檢核函數(rec)=>屬性名字串或null
+ */
+function genDateChecker(attrs) {
+    let cols = []
+    if (attrs !== null &amp;&amp; typeof attrs === 'object') {
+        for (let k of Object.keys(attrs)) {
+            let kind = getColKind(attrs, k)
+            if (kind === 'date' || kind === 'dateonly') {
+                cols.push({ k, kind, san: kind === 'dateonly' ? getDateOnlySanitizer(attrs[k].type) : null })
+            }
+        }
+    }
+    return (rec) => {
+        if (rec === null || typeof rec !== 'object') {
+            return null
+        }
+        for (let c of cols) {
+            let v = rec[c.k]
+            if (v === null || v === undefined) {
+                continue
+            }
+            let r = chkWriteDate(v, c.kind, c.san)
+            if (!r.ok) {
+                return c.k
+            }
+            if (r.v !== undefined &amp;&amp; Object.prototype.hasOwnProperty.call(rec, c.k)) {
+                rec[c.k] = r.v
+            }
+        }
+        return null
+    }
 }
 
 
@@ -799,7 +920,7 @@ function cvFind(find, ctx) {
 }
 
 
-export { getColKind, getColScale, normPk, chkFindShape }
+export { getColKind, getColScale, normPk, chkFindShape, inDateRange, genDateChecker }
 export default cvFind
 </code></pre>
         </article>
@@ -815,7 +936,7 @@ export default cvFind
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Mon Oct 19 2026 18:54:43 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 04:13:54 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>