w-orm-reladb 1.1.10 → 1.1.12

package/src/cvFind.mjs

@@ -19,6 +19,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 }
@@ -311,15 +315,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 && y <= 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 && y <= 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 && 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 && 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 && Object.prototype.hasOwnProperty.call(rec, c.k)) {
+                rec[c.k] = r.v
+            }
+        }
+        return null
+    }
 }
 
 
@@ -752,5 +873,5 @@ function cvFind(find, ctx) {
 }
 
 
-export { getColKind, getColScale, normPk, chkFindShape }
+export { getColKind, getColScale, normPk, chkFindShape, inDateRange, genDateChecker }
 export default cvFind

package/test/api-date-write.mjs

@@ -0,0 +1,467 @@
+import assert from 'assert'
+import cloneDeep from 'lodash-es/cloneDeep.js'
+import Sequelize from 'sequelize'
+import wo from '../src/WOrmReladb.mjs'
+
+
+//本檔為mssql與sqlite共用之寫入側DATE範圍檢核測試套組(CLAUDE_rulebook.md之R12), 由api-sqlite.test.mjs與api-mssql.test.mjs引入
+//規格句(R12, dspec〈一之三〉8.): 以文字儲存日期之後端, 寫入拒收範圍外Date——DATE/DATEONLY欄之值須為年份在1–9999之有效時間,
+//範圍外與無效時間(Invalid Date、NaN、垃圾字串…, sqlite會存為字典序大於任何年份之文字Invalid date)皆使insert、insertBulk、save整批reject且資料庫不變;
+//訊息不回顯值; error事件於reject前恰一次、change不發; 兩方言行為一致(mssql於送出前即拒); 檢查之值即使用之值(具狀態之valueOf不得於二次求值時存入範圍外年份)
+//檢核優先序: 已關閉 → 初始化 → procPk(缺主鍵) → normPks(主鍵型別不符) → 日期檢核
+//model為models/tdate.js: d、d2為DATE, o為DATEONLY, n為STRING(非日期欄不檢); models/tdatei.js: 整數主鍵 + DATE欄d(測檢核優先序)
+
+
+let msgOf = (err) => String(err && err.message !== undefined ? err.message : err)
+
+let settle = (pm) => pm.then((v) => ({ ok: true, v })).catch((err) => ({ err }))
+
+let byId = (a, b) => (a.id < b.id ? -1 : 1)
+
+//期望之訊息: 不回顯值, 只含索引與欄名
+let want = (i, col) => `invalid data: date is not a valid time in years 1-9999 at [data[${i}].${col}]`
+
+//normD, 讀回之DATE值統一為ISO字串: sqlite讀回為文字'YYYY-MM-DD HH:mm:ss.SSS +00:00', mssql為Date
+let normD = (x) => {
+    if (x === null || x === undefined) {
+        return null
+    }
+    if (x instanceof Date) {
+        return x.toISOString()
+    }
+    let m = String(x).match(/^(\d{4,6})-(\d{2})-(\d{2}) (\d{2}:\d{2}:\d{2}\.\d{3}) \+00:00$/)
+    return m ? `${m[1]}-${m[2]}-${m[3]}T${m[4]}Z` : String(x)
+}
+
+//normO, 讀回之DATEONLY值統一為'YYYY-MM-DD': sqlite為文字, mssql可能為Date(UTC午夜)
+let normO = (x) => {
+    if (x === null || x === undefined) {
+        return null
+    }
+    if (x instanceof Date) {
+        return x.toISOString().slice(0, 10)
+    }
+    return String(x).slice(0, 10)
+}
+
+
+/**
+ * 定義共用測試套組
+ *
+ * @param {String} label 輸入後端名稱字串('sqlite'或'mssql'), 供describe標題使用
+ * @param {Function} getOpt 輸入取得建構設定之函數, 於hook內呼叫以取得當下有效之連線資訊
+ */
+export function defineDateWriteSuites(label, getOpt) {
+
+
+    describe(`${label} 寫入側DATE範圍: 入口 × 拒收值 × 欄位`, function() {
+
+        let w = null
+        let ins = null
+        let cs = null
+
+        //種子: 3列合法數據, 供「資料庫不變」與save更新既有之用
+        let seed = () => [
+            { id: 's1', n: 'a', d: new Date('2000-01-01T00:00:00Z'), d2: null, o: '2000-01-01' },
+            { id: 's2', n: 'b', d: new Date('2010-06-15T12:30:00Z'), d2: new Date('2011-01-01T00:00:00Z'), o: null },
+            { id: 's3', n: 'c', d: null, d2: null, o: '2020-12-31' },
+        ]
+
+        let dump = async () => {
+            let rs = await w.select({}, cs)
+            return rs.sort(byId)
+        }
+
+        let reset = async () => {
+            await w.delAll({}, cs)
+            let r = await w.insert(seed(), cs)
+            assert.strictEqual(r.nInserted, 3)
+        }
+
+        before(async function() {
+            w = wo(getOpt({ cl: 'tdate' }))
+            await w.createStorage()
+            ins = await w.init()
+            cs = { instance: ins }
+        })
+
+        after(async function() {
+            await ins.close()
+        })
+
+        //入口: [名稱, 事件mode, 呼叫函數, 是否針對既有主鍵]
+        let entries = [
+            ['insert', 'insert', (rs) => w.insert(rs, cs), false],
+            ['insertBulk', 'insertBulk', (rs) => w.insertBulk(rs, cs), false],
+            ['save(自動插入)', 'save', (rs) => w.save(rs, { ...cs, autoInsert: true }), false],
+            ['save(更新既有)', 'save', (rs) => w.save(rs, { ...cs, autoInsert: true }), true],
+            ['save(autoInsert:false且主鍵不存在)', 'save', (rs) => w.save(rs, { ...cs, autoInsert: false }), false],
+        ]
+
+        //mk, 產生3筆記錄, patches為[[筆索引, 欄名, 值]…]; 其餘欄與其餘筆皆合法
+        let mk = (existing, patches) => {
+            let ids = existing ? ['s1', 's2', 's3'] : ['x1', 'x2', 'x3']
+            let rs = ids.map((id) => ({ id, n: 'new', d: new Date('2030-01-01T00:00:00Z'), o: '2030-01-01' }))
+            for (let [p, col, v] of patches) {
+                rs[p][col] = v
+            }
+            return rs
+        }
+
+        //runReject, 呼叫入口並斷言: reject、訊息(不回顯值)、error事件於reject前恰一次且mode/err一致、change不發、資料庫逐列不變、呼叫端數據不變
+        let runReject = async (entry, rs, msg) => {
+            let [, mode, fn] = entry
+            await reset()
+            let before = await dump()
+            let snap = cloneDeep(rs)
+            let evs = []
+            let errs = []
+            let fnE = (m, data, e) => {
+                evs.push(`error:${m}`)
+                errs.push(e)
+            }
+            let fnC = (m) => evs.push(`change:${m}`)
+            w.on('error', fnE)
+            w.on('change', fnC)
+            let r
+            try {
+                r = await settle(fn(rs))
+                evs.push('reject')
+            }
+            finally {
+                w.off('error', fnE)
+                w.off('change', fnC)
+            }
+            assert.ok(r.err !== undefined, `未reject: ${JSON.stringify(r.v)}`)
+            assert.strictEqual(msgOf(r.err), msg)
+            assert.deepStrictEqual(evs, [`error:${mode}`, 'reject'], 'error事件於reject前恰一次, change不發')
+            assert.deepStrictEqual(errs, [msg], 'error事件之err與reject訊息一致')
+            assert.deepStrictEqual(await dump(), before, '資料庫逐列不變')
+            assert.deepStrictEqual(rs, snap, '呼叫端數據不變')
+        }
+
+        // ---- DATE欄之拒收值 × 5入口: 中間筆(第2筆)違規, 其餘合法筆亦不得寫入 ----
+        let badDate = [
+            ['Date 年0末刻', () => new Date('0000-12-31T23:59:59.999Z')],
+            ['Date 年10000首刻', () => new Date('+010000-01-01T00:00:00.000Z')],
+            ['Date 8.64e15', () => new Date(8.64e15)],
+            ['Date -8.64e15', () => new Date(-8.64e15)],
+            ['epoch 8.64e15', () => 8.64e15],
+            ['epoch -8.64e15', () => -8.64e15],
+            ['ISO字串 年0末刻', () => '0000-12-31T23:59:59.999Z'],
+            ['ISO字串 年10000首刻', () => '+010000-01-01T00:00:00Z'],
+            ['Number包裝物件 8.64e15', () => Object(8.64e15)],
+        ]
+        for (let entry of entries) {
+            for (let [lab, gen] of badDate) {
+                it(`${entry[0]} × DATE欄 ${lab}: 整批reject、資料不變`, async function() {
+                    await runReject(entry, mk(entry[3], [[1, 'd', gen()]]), want(1, 'd'))
+                })
+            }
+        }
+
+        // ---- DATEONLY欄之拒收值 × 5入口 ----
+        let badOnly = [
+            ['Date 8.64e15', () => new Date(8.64e15)],
+            ['Date -8.64e15', () => new Date(-8.64e15)],
+            ['Date 年10000年中', () => new Date('+010000-06-15T12:00:00Z')],
+            ['Date 年0年中', () => new Date('0000-06-15T12:00:00Z')],
+            ['epoch 8.64e15', () => 8.64e15],
+            ['ISO字串 年10000', () => '+010000-01-01'],
+            ['ISO字串 年0', () => '0000-12-31'],
+        ]
+        for (let entry of entries) {
+            for (let [lab, gen] of badOnly) {
+                it(`${entry[0]} × DATEONLY欄 ${lab}: 整批reject、資料不變`, async function() {
+                    await runReject(entry, mk(entry[3], [[1, 'o', gen()]]), want(1, 'o'))
+                })
+            }
+        }
+
+        // ---- 無效時間(sqlite會存為文字Invalid date, mssql由資料庫報錯)亦整批reject × 5入口 ----
+        let badInvalid = [
+            ['Invalid Date', () => new Date(NaN)],
+            ['NaN', () => NaN],
+            ['空字串', () => ''],
+            ['垃圾字串', () => 'garbage'],
+            ['超出Date範圍之epoch 1e16', () => 1e16],
+            ['false', () => false],
+        ]
+        for (let entry of entries) {
+            for (let [lab, gen] of badInvalid) {
+                it(`${entry[0]} × DATE欄 無效時間 ${lab}: 整批reject、資料不變`, async function() {
+                    await runReject(entry, mk(entry[3], [[1, 'd', gen()]]), want(1, 'd'))
+                })
+            }
+            it(`${entry[0]} × DATEONLY欄 無效時間 垃圾字串: 整批reject、資料不變`, async function() {
+                await runReject(entry, mk(entry[3], [[1, 'o', 'garbage']]), want(1, 'o'))
+            })
+        }
+
+        // ---- 位置與多欄 × 5入口 ----
+        let bad = () => new Date(8.64e15)
+        let positions = [
+            ['首筆', (e) => mk(e, [[0, 'd', bad()]]), want(0, 'd')],
+            ['末筆', (e) => mk(e, [[2, 'd', bad()]]), want(2, 'd')],
+            ['第二個DATE欄(d2)', (e) => mk(e, [[1, 'd2', bad()]]), want(1, 'd2')],
+            ['同筆多欄違規: 回報model屬性定義順序之第一個(d先於d2先於o)', (e) => mk(e, [[1, 'o', bad()], [1, 'd2', bad()], [1, 'd', bad()]]), want(1, 'd')],
+            ['同筆d2與o違規: 回報d2', (e) => mk(e, [[1, 'o', bad()], [1, 'd2', bad()]]), want(1, 'd2')],
+            ['多筆違規: 回報索引最小者', (e) => mk(e, [[2, 'd', bad()], [1, 'd2', bad()]]), want(1, 'd2')],
+        ]
+        for (let entry of entries) {
+            for (let [lab, gen, msg] of positions) {
+                it(`${entry[0]} × 位置 ${lab}`, async function() {
+                    await runReject(entry, gen(entry[3]), msg)
+                })
+            }
+        }
+
+        // ---- 單一物件(非陣列)輸入 × 5入口 ----
+        for (let entry of entries) {
+            it(`${entry[0]} × 單一物件(非陣列): 路徑索引為0`, async function() {
+                let one = mk(entry[3], [[0, 'd', bad()]])[0]
+                await runReject(entry, one, want(0, 'd'))
+            })
+        }
+
+        // ---- 接受值 × 5入口: 邊界內合法、讀回等於寫入之值 ----
+        let okCases = [
+            ['Date 年1首刻', { d: new Date('0001-01-01T00:00:00.000Z') }, { d: '0001-01-01T00:00:00.000Z' }],
+            ['Date 年9999末刻', { d: new Date('9999-12-31T23:59:59.999Z') }, { d: '9999-12-31T23:59:59.999Z' }],
+            ['epoch 年1首刻與年9999末刻(d與d2)', { d: Date.parse('0001-01-01T00:00:00.000Z'), d2: Date.parse('9999-12-31T23:59:59.999Z') }, { d: '0001-01-01T00:00:00.000Z', d2: '9999-12-31T23:59:59.999Z' }],
+            ['ISO字串 年1首刻與年9999末刻', { d: '0001-01-01T00:00:00.000Z', d2: '9999-12-31T23:59:59.999Z' }, { d: '0001-01-01T00:00:00.000Z', d2: '9999-12-31T23:59:59.999Z' }],
+            ['DATEONLY 年1首日(字串)', { o: '0001-01-01' }, { o: '0001-01-01' }],
+            ['DATEONLY 年9999末日(字串)', { o: '9999-12-31' }, { o: '9999-12-31' }],
+            ['DATEONLY Date年中', { o: new Date('2026-06-15T12:00:00Z') }, { o: '2026-06-15' }],
+            ['null與非日期欄形似範圍外日期之字串', { d: null, d2: null, o: null, n: '275760-09-13 +275760-09-13T00:00:00.000Z' }, { d: null, d2: null, o: null, n: '275760-09-13 +275760-09-13T00:00:00.000Z' }],
+        ]
+        for (let entry of entries) {
+            if (entry[0] === 'save(autoInsert:false且主鍵不存在)') {
+                continue //此入口不會寫入, 接受側以另案斷言resolve
+            }
+            for (let [lab, patch, exp] of okCases) {
+                it(`${entry[0]} × 接受 ${lab}`, async function() {
+                    await reset()
+                    let ids = entry[3] ? ['s1', 's2', 's3'] : ['x1', 'x2', 'x3']
+                    let rs = ids.map((id, k) => ({ id, ...(k === 1 ? patch : { n: 'other' }) }))
+                    let r = await settle(entry[2](rs))
+                    assert.ok(r.err === undefined, `不應reject: ${msgOf(r.err)}`)
+                    let row = (await dump()).find((v) => v.id === ids[1])
+                    for (let [k, v] of Object.entries(exp)) {
+                        let got = k === 'o' ? normO(row[k]) : (k === 'n' ? row[k] : normD(row[k]))
+                        assert.strictEqual(got, v, `${k} 讀回`)
+                    }
+                })
+            }
+        }
+
+        it('save(autoInsert:false且主鍵不存在)接受合法邊界值: resolve且不寫入', async function() {
+            await reset()
+            let before = await dump()
+            let r = await settle(w.save([{ id: 'x9', d: new Date('9999-12-31T23:59:59.999Z') }], { ...cs, autoInsert: false }))
+            assert.ok(r.err === undefined, msgOf(r.err))
+            assert.deepStrictEqual(r.v, [{ n: 0, nInserted: 0, nModified: 0, ok: 1 }])
+            assert.deepStrictEqual(await dump(), before)
+        })
+
+        it('無日期值或日期欄為undefined之記錄不受影響', async function() {
+            await reset()
+            let r = await w.insert([{ id: 'u1', n: 'x' }, { id: 'u2', d: undefined, o: undefined }], cs)
+            assert.deepStrictEqual(r, { n: 2, nInserted: 2, ok: 1 })
+        })
+
+    })
+
+
+    describe(`${label} 寫入側DATE範圍: 情境與接縫`, function() {
+
+        let w = null
+        let ins = null
+        let cs = null
+
+        before(async function() {
+            w = wo(getOpt({ cl: 'tdate' }))
+            await w.createStorage()
+            ins = await w.init()
+            cs = { instance: ins }
+        })
+
+        after(async function() {
+            await ins.close()
+        })
+
+        beforeEach(async function() {
+            await w.delAll({}, cs)
+        })
+
+        it('修前紅之原始場景: 哨兵new Date(8.64e15)寫入即reject, 其後delAll({d:{$lt:日期}})只刪過期列, 永不過期之替代寫法(9999年末與null)不被刪', async function() {
+            //規格句(R12): 「永不過期」哨兵寫入範圍外Date會於sqlite以文字比較被$lt誤中而遭delAll刪除; 現於寫入即拒收
+            let r = await settle(w.insert({ id: 'sentinel', d: new Date(8.64e15) }, cs))
+            assert.ok(r.err !== undefined, '哨兵須reject')
+            await w.insert([
+                { id: 'old', d: new Date('2000-01-01T00:00:00Z') },
+                { id: 'never1', d: new Date('9999-12-31T23:59:59.999Z') },
+                { id: 'never2', d: null },
+            ], cs)
+            assert.deepStrictEqual((await w.select({}, cs)).map((v) => v.id).sort(), ['never1', 'never2', 'old'])
+            let rd = await w.delAll({ d: { $lt: new Date('3000-01-01T00:00:00Z') } }, cs)
+            assert.deepStrictEqual(rd, { n: 1, nDeleted: 1, ok: 1 })
+            assert.deepStrictEqual((await w.select({}, cs)).map((v) => v.id).sort(), ['never1', 'never2'])
+            let rs = await w.select({ d: { $gt: new Date('3000-01-01T00:00:00Z') } }, cs)
+            assert.deepStrictEqual(rs.map((v) => v.id), ['never1'])
+        })
+
+        it('不給instance之呼叫(內部自行初始化): 範圍外值reject、error事件恰一次, 連線已關閉且其後合法呼叫照常', async function() {
+            let w2 = wo(getOpt({ cl: 'tdate' }))
+            let evs = []
+            w2.on('error', (m) => evs.push(m))
+            let r = await settle(w2.insertBulk([{ id: 'a', d: new Date(8.64e15) }]))
+            assert.strictEqual(msgOf(r.err), want(0, 'd'))
+            assert.deepStrictEqual(evs, ['insertBulk'])
+            let r2 = await w2.insertBulk([{ id: 'a', d: new Date('9999-12-31T23:59:59.999Z') }])
+            assert.deepStrictEqual(r2, { n: 1, nInserted: 1, ok: 1 })
+            assert.deepStrictEqual(evs, ['insertBulk'], '合法呼叫不發error')
+        })
+
+        it('呼叫端交易內: 範圍外值reject不影響交易, 同一交易其後合法寫入與commit照常', async function() {
+            let transaction = await w.genTransaction()
+            let ct = { instance: ins, transaction }
+            let done = false
+            try {
+                let r = await settle(w.insertBulk([{ id: 't1', d: new Date('2001-01-01T00:00:00Z') }, { id: 't2', d: new Date(-8.64e15) }], ct))
+                assert.strictEqual(msgOf(r.err), want(1, 'd'))
+                let r2 = await w.insertBulk([{ id: 't3', d: new Date('2003-01-01T00:00:00Z') }], ct)
+                assert.deepStrictEqual(r2, { n: 1, nInserted: 1, ok: 1 })
+                await transaction.commit()
+                done = true
+            }
+            finally {
+                if (!done) {
+                    await transaction.rollback().catch(() => {}) //斷言失敗時不留開啟中之交易(sqlite會鎖庫而連累後續案)
+                }
+            }
+            assert.deepStrictEqual((await w.select({}, cs)).map((v) => v.id), ['t3'])
+        })
+
+        it('save更新既有列: 範圍外值reject後該列維持舊值, 合法值照常更新', async function() {
+            await w.insert({ id: 'k', d: new Date('2000-01-01T00:00:00Z') }, cs)
+            let r = await settle(w.save({ id: 'k', d: new Date(8.64e15) }, cs))
+            assert.strictEqual(msgOf(r.err), want(0, 'd'))
+            assert.strictEqual(normD((await w.selectByPk('k', cs)).d), '2000-01-01T00:00:00.000Z')
+            let r2 = await w.save({ id: 'k', d: new Date('9999-12-31T23:59:59.999Z') }, cs)
+            assert.deepStrictEqual(r2, [{ n: 1, nInserted: 0, nModified: 1, ok: 1 }])
+            assert.strictEqual(normD((await w.selectByPk('k', cs)).d), '9999-12-31T23:59:59.999Z')
+        })
+
+        it('insert回傳逐筆結果模式(returnList)亦整批reject', async function() {
+            let r = await settle(w.insert([{ id: 'a', d: new Date('2001-01-01T00:00:00Z') }, { id: 'b', d: new Date(8.64e15) }], { ...cs, returnList: true }))
+            assert.strictEqual(msgOf(r.err), want(1, 'd'))
+            assert.deepStrictEqual(await w.select({}, cs), [])
+        })
+
+        it('訊息不回顯值, 且不隨值而變: 各種範圍外值之訊息逐字相同', async function() {
+            let vals = [new Date(8.64e15), new Date(-8.64e15), 8.64e15, '+010000-01-01T00:00:00Z', '0000-12-31T23:59:59.999Z']
+            for (let v of vals) {
+                let r = await settle(w.insert({ id: 'a', d: v }, cs))
+                assert.strictEqual(msgOf(r.err), want(0, 'd'))
+            }
+        })
+
+        it('缺主鍵(autoGenPk為false)之錯誤先於日期檢核(既有優先序不變): insert、insertBulk、save', async function() {
+            let w2 = wo(getOpt({ cl: 'tdate', autoGenPk: false }))
+            for (let [name, fn] of [['insert', (rs) => w2.insert(rs)], ['insertBulk', (rs) => w2.insertBulk(rs)], ['save', (rs) => w2.save(rs)]]) {
+                let r = await settle(fn([{ d: new Date(8.64e15) }]))
+                assert.ok(r.err !== undefined, name)
+                assert.ok(msgOf(r.err).indexOf('autoGenPk is false') >= 0, `${name}: ${msgOf(r.err)}`)
+            }
+        })
+
+        it('主鍵型別不符之錯誤先於日期檢核(既有優先序不變): 整數主鍵給\'abc\'且日期範圍外, insert、insertBulk、save', async function() {
+            let wi = wo(getOpt({ cl: 'tdatei' }))
+            await wi.createStorage()
+            for (let [name, fn] of [['insert', (rs) => wi.insert(rs)], ['insertBulk', (rs) => wi.insertBulk(rs)], ['save', (rs) => wi.save(rs)]]) {
+                let r = await settle(fn([{ id: 'abc', d: new Date(8.64e15) }]))
+                assert.ok(r.err !== undefined, name)
+                assert.ok(msgOf(r.err).indexOf('type does not match pk column') >= 0, `${name}: ${msgOf(r.err)}`)
+            }
+        })
+
+        it('整數主鍵model之日期檢核照常: 主鍵合法而日期範圍外則整批reject', async function() {
+            let wi = wo(getOpt({ cl: 'tdatei' }))
+            await wi.createStorage()
+            await wi.delAll()
+            let r = await settle(wi.insert([{ id: 1, d: new Date('2001-01-01T00:00:00Z') }, { id: 2, d: new Date(-8.64e15) }]))
+            assert.strictEqual(msgOf(r.err), want(1, 'd'))
+            assert.deepStrictEqual(await wi.select({}), [])
+        })
+
+        // 規格句(R12): 檢查之值即使用之值——具狀態之valueOf第一次回傳合法值、其後回傳範圍外值者, 存入的是檢核時之值(物件值已換成標準值)
+        let stateful = (a, b) => {
+            let n = 0
+            return {
+                valueOf() {
+                    return n++ === 0 ? a : b
+                },
+            }
+        }
+
+        it('檢查之值即使用之值(DATE, 具狀態valueOf): insert、insertBulk、save(更新既有)皆存入檢核時之值而非範圍外值', async function() {
+            await w.insert({ id: 'upd', d: new Date('2000-01-01T00:00:00Z') }, cs)
+            let entriesS = [
+                ['insert', 'si', (r) => w.insert(r, cs)],
+                ['insertBulk', 'sb', (r) => w.insertBulk(r, cs)],
+                ['save(更新既有)', 'upd', (r) => w.save(r, cs)],
+            ]
+            for (let [name, id, fn] of entriesS) {
+                let r = await settle(fn([{ id, d: stateful(0, 8.64e15) }]))
+                assert.ok(r.err === undefined, `${name}: ${msgOf(r.err)}`)
+                let row = await w.selectByPk(id, cs)
+                assert.strictEqual(normD(row.d), '1970-01-01T00:00:00.000Z', name)
+            }
+        })
+
+        it('檢查之值即使用之值(DATEONLY, 陣列元素具狀態toString): 存入檢核時之日期而非範圍外值', async function() {
+            let n = 0
+            let el = {
+                toString() {
+                    return n++ === 0 ? '2026' : '10000'
+                },
+            }
+            let r = await settle(w.insert({ id: 'do1', o: [el, 0, 1] }, cs))
+            assert.ok(r.err === undefined, msgOf(r.err))
+            assert.strictEqual(normO((await w.selectByPk('do1', cs)).o), '2026-01-01')
+        })
+
+        it('Sequelize.literal等SQL運算式不被檢核或換值(照常交資料庫求值)', async function() {
+            if (label !== 'sqlite') {
+                return //運算式文法依方言
+            }
+            let r = await settle(w.insert({ id: 'lit', d: Sequelize.literal('\'2020-02-02 00:00:00.000 +00:00\'') }, cs))
+            assert.ok(r.err === undefined, msgOf(r.err))
+            assert.strictEqual(normD((await w.selectByPk('lit', cs)).d), '2020-02-02T00:00:00.000Z')
+        })
+
+        if (label === 'sqlite') {
+            //README之清理範例: 庫內既有之範圍外日期文字(本版前寫入)可由save改寫為範圍內值或null; 以原生SQL模擬舊資料(修前寫入入口已被擋)
+            it('既有資料不遷移: 庫內舊的範圍外日期文字不受影響, 可由save改寫為null與9999年末', async function() {
+                let sq = new Sequelize({ dialect: 'sqlite', storage: getOpt().storage, logging: false })
+                try {
+                    await sq.query('INSERT INTO tdate (id, d) VALUES (?, ?)', { replacements: ['legacy', '275760-09-13 00:00:00.000 +00:00'] })
+                }
+                finally {
+                    await sq.close()
+                }
+                let row = await w.selectByPk('legacy', cs)
+                assert.strictEqual(normD(row.d), '275760-09-13T00:00:00.000Z', '舊資料維持原樣(不遷移)')
+                await w.save({ id: 'legacy', d: null }, cs)
+                assert.strictEqual((await w.selectByPk('legacy', cs)).d, null)
+                await w.save({ id: 'legacy', d: new Date('9999-12-31T23:59:59.999Z') }, cs)
+                assert.strictEqual(normD((await w.selectByPk('legacy', cs)).d), '9999-12-31T23:59:59.999Z')
+                let r = await settle(w.save({ id: 'legacy', d: new Date(8.64e15) }, cs))
+                assert.strictEqual(msgOf(r.err), want(0, 'd'), '以Date再寫範圍外仍被拒')
+            })
+        }
+
+    })
+
+}

package/test/api-mssql.test.mjs

@@ -3,6 +3,7 @@ import { execFile } from 'child_process'
 import { promisify } from 'util'
 import { defineSuites } from './api-suite.mjs'
 import { defineWhitelistSuites } from './api-find-whitelist.mjs'
+import { defineDateWriteSuites } from './api-date-write.mjs'
 
 
 //測試自行創建docker容器供MSSQL服務, 測試結束即銷毀, 故僅需環境已安裝docker
@@ -115,3 +116,4 @@ after(async function() {
 
 defineSuites('mssql', getOpt)
 defineWhitelistSuites('mssql', getOpt)
+defineDateWriteSuites('mssql', getOpt)

package/test/api-sqlite.test.mjs

@@ -1,6 +1,7 @@
 import fs from 'fs'
 import { defineSuites } from './api-suite.mjs'
 import { defineWhitelistSuites } from './api-find-whitelist.mjs'
+import { defineDateWriteSuites } from './api-date-write.mjs'
 
 
 //sqlite使用獨立暫存storage檔測試, 不使用專案根目錄之worm.sqlite
@@ -42,3 +43,4 @@ after(function() {
 
 defineSuites('sqlite', getOpt)
 defineWhitelistSuites('sqlite', getOpt)
+defineDateWriteSuites('sqlite', getOpt)