w-orm-postgresql 1.0.8 → 1.0.9

package/docs/WOrmPostgresql.html

@@ -672,13 +672,17 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>刪除數據</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>刪除數據</p>
+<p>回傳陣列恆與輸入等長，各筆之n與nDeleted皆為主鍵命中筆數，值為0或1，未命中為0且屬正常結果。
+判斷某筆是否真的被刪除一律以nDeleted為準。
+未帶有效time者為該筆之輸入問題，回ok:0與err且不送查詢，不中斷其餘筆數，
+以此與[主鍵未命中]之ok:1區辨。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line942">line 942</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line977">line 977</a>
     </li></ul></dd>
     
 
@@ -796,7 +800,7 @@
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳刪除結果，reject回傳錯誤訊息</p>
+    <p>回傳Promise，resolve回傳刪除結果陣列[{n,nDeleted,ok}]，reject回傳錯誤訊息</p>
 </div>
 
 
@@ -833,13 +837,15 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表</p>
+<p>n與nDeleted皆為實際刪除筆數，不取全表筆數。find未給或為空物件時刪除全部數據，
+條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1079">line 1079</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1127">line 1127</a>
     </li></ul></dd>
     
 
@@ -974,7 +980,7 @@
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳刪除結果，reject回傳錯誤訊息</p>
+    <p>回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，reject回傳錯誤訊息</p>
 </div>
 
 
@@ -1011,13 +1017,16 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>插入數據</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>插入數據，僅於主鍵time不存在時寫入，已存在者跳過且不覆寫</p>
+<p>n為輸入筆數，即本次嘗試插入之基準；nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果，
+不視為錯誤。同批含重複time時僅首筆計入nInserted。
+因主鍵time承載觀測時間之業務意義，未帶有效time時不自動補值，一律以reject回報。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line489">line 489</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line497">line 497</a>
     </li></ul></dd>
     
 
@@ -1135,7 +1144,7 @@
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳插入結果，reject回傳錯誤訊息</p>
+    <p>回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，reject回傳錯誤訊息</p>
 </div>
 
 
@@ -1172,13 +1181,20 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>儲存數據</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>儲存數據，以主鍵time為準更新既有數據，未給之欄位保留</p>
+<p>回傳陣列恆與輸入等長，輸入單一物件亦回傳長度1之陣列。
+各筆之n為主鍵命中筆數，值為0或1，命中(不論內容有無變更)或經插入而產生皆為1；
+nInserted與nModified恆同時出現，無對應行為時填0。
+[內容相同]之判定基準為待寫入物件合併進現值後與現值相同，非待寫入物件與現值全等，
+故只給部份欄位且該些欄位值皆與現值相同時，合併結果等於現值，nModified為0，
+令nModified忠實反映資料庫端是否真的寫入。
+因主鍵time承載觀測時間之業務意義，未帶有效time時不自動補值，一律以reject回報。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line618">line 618</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line634">line 634</a>
     </li></ul></dd>
     
 
@@ -1422,7 +1438,7 @@
 
         
 <div class="param-desc">
-    <p>回傳Promise，resolve回傳儲存結果，reject回傳錯誤訊息</p>
+    <p>回傳Promise，resolve回傳儲存結果陣列[{n,nInserted,nModified,ok}]，reject回傳錯誤訊息</p>
 </div>
 
 
@@ -1677,13 +1693,16 @@
 <dl class="details">
     
     <dt class="tag-description">Description:</dt>
-    <dd class="tag-description"><ul class="dummy"><li><p>由主鍵time查詢單筆數據，因直接由資料表主鍵索引取值，不需如select提取數據至前端再處理，故數據量大時效能較佳</p></li></ul></dd>
+    <dd class="tag-description"><ul class="dummy"><li><p>由主鍵time查詢單筆數據，因直接由資料表主鍵索引取值，不需如select提取數據至前端再處理，故數據量大時效能較佳</p>
+<p>函數名依主鍵欄位命名為selectByTime而不另掛selectById別名，因本套件之主鍵為具業務語義之time，
+與以無語義識別碼為主鍵者性質不同，該差異須由呼叫端知悉而非由別名掩蓋。
+主鍵未命中或主鍵值無效皆回傳null而不reject，命中之判定基準與insert、save、del內對既有數據之認定一致。</p></li></ul></dd>
     
 
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line377">line 377</a>
+        <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line381">line 381</a>
     </li></ul></dd>
     
 
@@ -1843,7 +1862,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 16 2026 17:59:38 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 Sun Aug 16 2026 22:57:35 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WOrmPostgresql.mjs.html

@@ -417,6 +417,10 @@ function WOrmPostgresql(opt = {}) {
     /**
      * 由主鍵time查詢單筆數據，因直接由資料表主鍵索引取值，不需如select提取數據至前端再處理，故數據量大時效能較佳
      *
+     * 函數名依主鍵欄位命名為selectByTime而不另掛selectById別名，因本套件之主鍵為具業務語義之time，
+     * 與以無語義識別碼為主鍵者性質不同，該差異須由呼叫端知悉而非由別名掩蓋。
+     * 主鍵未命中或主鍵值無效皆回傳null而不reject，命中之判定基準與insert、save、del內對既有數據之認定一致。
+     *
      * @memberOf WOrmPostgresql
      * @param {String|Date} time 輸入主鍵time值，本套件以time欄位為主鍵
      * @returns {Promise} 回傳Promise，resolve回傳數據物件，若無此time則回傳null，reject回傳錯誤訊息
@@ -527,11 +531,15 @@ function WOrmPostgresql(opt = {}) {
     }
 
     /**
-     * 插入數據
+     * 插入數據，僅於主鍵time不存在時寫入，已存在者跳過且不覆寫
+     *
+     * n為輸入筆數，即本次嘗試插入之基準；nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果，
+     * 不視為錯誤。同批含重複time時僅首筆計入nInserted。
+     * 因主鍵time承載觀測時間之業務意義，未帶有效time時不自動補值，一律以reject回報。
      *
      * @memberOf WOrmPostgresql
      * @param {Object|Array} data 輸入數據物件或陣列
-     * @returns {Promise} 回傳Promise，resolve回傳插入結果，reject回傳錯誤訊息
+     * @returns {Promise} 回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，reject回傳錯誤訊息
      */
     async function insert(data) {
         let isErr = false
@@ -654,13 +662,21 @@ function WOrmPostgresql(opt = {}) {
     }
 
     /**
-     * 儲存數據
+     * 儲存數據，以主鍵time為準更新既有數據，未給之欄位保留
+     *
+     * 回傳陣列恆與輸入等長，輸入單一物件亦回傳長度1之陣列。
+     * 各筆之n為主鍵命中筆數，值為0或1，命中(不論內容有無變更)或經插入而產生皆為1；
+     * nInserted與nModified恆同時出現，無對應行為時填0。
+     * [內容相同]之判定基準為待寫入物件合併進現值後與現值相同，非待寫入物件與現值全等，
+     * 故只給部份欄位且該些欄位值皆與現值相同時，合併結果等於現值，nModified為0，
+     * 令nModified忠實反映資料庫端是否真的寫入。
+     * 因主鍵time承載觀測時間之業務意義，未帶有效time時不自動補值，一律以reject回報。
      *
      * @memberOf WOrmPostgresql
      * @param {Object|Array} data 輸入數據物件或陣列
      * @param {Object} [option={}] 輸入設定物件，預設為{}
      * @param {boolean} [option.autoInsert=true] 輸入是否於儲存時發現原本無數據，則自動改以插入處理，預設為true
-     * @returns {Promise} 回傳Promise，resolve回傳儲存結果，reject回傳錯誤訊息
+     * @returns {Promise} 回傳Promise，resolve回傳儲存結果陣列[{n,nInserted,nModified,ok}]，reject回傳錯誤訊息
      */
     async function save(data, option = {}) {
         let isErr = false
@@ -760,16 +776,22 @@ function WOrmPostgresql(opt = {}) {
                     let _vt = omit(_v, 'time')
                     // console.log('_vt', _vt)
 
-                    //vt
-                    let vt = omit(v, 'time')
+                    //vt, [內容相同]之判定基準為[待寫入物件合併進現值後與現值相同],
+                    //非[待寫入物件與現值全等], 故只給部份欄位且該些欄位值皆與現值相同時視為相同而不寫入,
+                    //合併採淺層覆蓋, 與後端以EXCLUDED整欄取代之寫入行為一致
+                    let vt = {
+                        ..._vt,
+                        ...omit(v, 'time'),
+                    }
                     // console.log('vt', vt)
 
-                    if (isEqual(_vt, vt)) {
+                    if (isEqual(vt, _vt)) {
                         //相同時不更新
 
                         //rest
                         rest = {
                             n: 1,
+                            nInserted: 0,
                             nModified: 0,
                             ok: 1,
                         }
@@ -788,6 +810,7 @@ function WOrmPostgresql(opt = {}) {
                         //rest
                         rest = {
                             n: 0,
+                            nInserted: 0,
                             nModified: 0,
                             ok: 1,
                         }
@@ -838,18 +861,20 @@ function WOrmPostgresql(opt = {}) {
                                 //rest
                                 rest = {
                                     n: 1,
+                                    nInserted: 0,
                                     nModified: 0,
                                     ok: 1,
                                 }
 
                             }
                             else if (get(rows, '0.inserted') === true) {
-                                //原不存在而插入, 回傳形狀同insert
+                                //原不存在而插入
 
                                 //rest
                                 rest = {
                                     n: 1,
                                     nInserted: 1,
+                                    nModified: 0,
                                     ok: 1,
                                 }
                                 // console.log('之前不存在且可自動插入', rest, v)
@@ -861,6 +886,7 @@ function WOrmPostgresql(opt = {}) {
                                 //rest
                                 rest = {
                                     n: 1,
+                                    nInserted: 0,
                                     nModified: 1,
                                     ok: 1,
                                 }
@@ -875,6 +901,7 @@ function WOrmPostgresql(opt = {}) {
                             rest = {
                                 n: 1,
                                 nInserted: 0,
+                                nModified: 0,
                                 ok: 0,
                                 err: err.message,
                             }
@@ -910,6 +937,7 @@ function WOrmPostgresql(opt = {}) {
                                 //rest
                                 rest = {
                                     n: 1,
+                                    nInserted: 0,
                                     nModified: 1,
                                     ok: 1,
                                 }
@@ -922,6 +950,7 @@ function WOrmPostgresql(opt = {}) {
                                 //rest
                                 rest = {
                                     n: 0,
+                                    nInserted: 0,
                                     nModified: 0,
                                     ok: 1,
                                 }
@@ -934,6 +963,7 @@ function WOrmPostgresql(opt = {}) {
                             //rest
                             rest = {
                                 n: 1,
+                                nInserted: 0,
                                 nModified: 0,
                                 ok: 0,
                                 err: err.message,
@@ -982,9 +1012,14 @@ function WOrmPostgresql(opt = {}) {
     /**
      * 刪除數據
      *
+     * 回傳陣列恆與輸入等長，各筆之n與nDeleted皆為主鍵命中筆數，值為0或1，未命中為0且屬正常結果。
+     * 判斷某筆是否真的被刪除一律以nDeleted為準。
+     * 未帶有效time者為該筆之輸入問題，回ok:0與err且不送查詢，不中斷其餘筆數，
+     * 以此與[主鍵未命中]之ok:1區辨。
+     *
      * @memberOf WOrmPostgresql
      * @param {Object|Array} data 輸入數據物件或陣列
-     * @returns {Promise} 回傳Promise，resolve回傳刪除結果，reject回傳錯誤訊息
+     * @returns {Promise} 回傳Promise，resolve回傳刪除結果陣列[{n,nDeleted,ok}]，reject回傳錯誤訊息
      */
     async function del(data) {
         let isErr = false
@@ -1030,39 +1065,49 @@ function WOrmPostgresql(opt = {}) {
                 data = [data]
             }
 
-            //check time
-            data = map(data, function(v, k) {
-                if (!isDate(v.time)) {
-                    throw new Error(`invalid data[${k}].time[${v.time}]`)
-                }
-                return v
-            })
-
             //pmSeries
             res = await pmSeries(data, async(v) => {
 
                 //rest
                 let rest = null
 
+                //time
+                let time = get(v, 'time')
+
+                //check time, 未帶有效主鍵者不補值亦不送查詢,
+                //因mongo-sql會將無效值轉為null而誤中其他數據, 故直接視為該筆無法處理
+                if (!isDate(time)) {
+
+                    //rest
+                    rest = {
+                        n: 0,
+                        nDeleted: 0,
+                        ok: 0,
+                        err: `invalid time[${time}]`,
+                    }
+
+                    return rest
+                }
+
                 //mr
                 let mr = mongoSql.sql({
                     type: 'delete',
                     table: cl,
                     where: {
-                        time: v.time,
+                        time,
                     },
                 })
                 // console.log('mr', mr)
                 // console.log('mr.query', mr.query)
                 // console.log('mr.values', mr.values)
 
-                //del
+                //del, n與nDeleted皆為主鍵命中筆數, 未命中為0
                 await client.query(mr.query, mr.values)
                     .then((r) => {
 
                         //res
                         rest = {
-                            n: 1,
+                            n: r.rowCount,
                             nDeleted: r.rowCount,
                             ok: 1,
                         }
@@ -1119,9 +1164,12 @@ function WOrmPostgresql(opt = {}) {
     /**
      * 刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表
      *
+     * n與nDeleted皆為實際刪除筆數，不取全表筆數。find未給或為空物件時刪除全部數據，
+     * 條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。
+     *
      * @memberOf WOrmPostgresql
      * @param {Object} [find={}] 輸入刪除條件物件
-     * @returns {Promise} 回傳Promise，resolve回傳刪除結果，reject回傳錯誤訊息
+     * @returns {Promise} 回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，reject回傳錯誤訊息
      */
     async function delAll(find = {}) {
         let isErr = false
@@ -1252,7 +1300,7 @@ export default WOrmPostgresql
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 16 2026 17:59:38 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 Sun Aug 16 2026 22:57:35 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/index.html

@@ -71,7 +71,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 16 2026 17:59:38 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 Sun Aug 16 2026 22:57:35 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g-basic.mjs

@@ -300,11 +300,11 @@ test()
 // insert then { n: 13, nInserted: 13, ok: 1 }
 // change save
 // save then [
-//   { n: 1, nModified: 0, ok: 1 },
-//   { n: 1, nModified: 1, ok: 1 },
-//   { n: 1, nModified: 1, ok: 1 },
-//   { n: 1, nModified: 1, ok: 1 },
-//   { n: 0, nModified: 0, ok: 1 }
+//   { n: 1, nInserted: 0, nModified: 0, ok: 1 },
+//   { n: 1, nInserted: 0, nModified: 1, ok: 1 },
+//   { n: 1, nInserted: 0, nModified: 1, ok: 1 },
+//   { n: 1, nInserted: 0, nModified: 1, ok: 1 },
+//   { n: 0, nInserted: 0, nModified: 0, ok: 1 }
 // ]
 // select all [
 //   { time: 2025-01-01T00:00:00.000Z, name: 'peter', value: 123 },
@@ -370,9 +370,9 @@ test()
 //   }
 // ]
 // change save
-// save then [ { n: 1, nInserted: 1, ok: 1 } ]
+// save then [ { n: 1, nInserted: 1, nModified: 0, ok: 1 } ]
 // change del
-// del then [ { n: 1, nDeleted: 0, ok: 1 } ]
+// del then [ { n: 0, nDeleted: 0, ok: 1 } ]
 // change del
 // del then [
 //   { n: 1, nDeleted: 1, ok: 1 },
@@ -407,7 +407,7 @@ test()
 //   { time: 2025-01-01T00:01:00.000Z, name: 'rosemary', value: 123.456 },
 //   { time: 2025-01-01T00:02:00.000Z, name: 'kettle', value: 456 }
 // ]
-// save (invalidate cache) then [ { n: 1, nModified: 1, ok: 1 } ]
+// save (invalidate cache) then [ { n: 1, nInserted: 0, nModified: 1, ok: 1 } ]
 // select all 3rd (reload after save) [
 //   { time: 2025-01-01T00:00:00.000Z, name: 'peter', value: 123 },
 //   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "w-orm-postgresql",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "main": "dist/w-orm-postgresql.umd.js",
   "dependencies": {
     "mongo-sql": "^6.2.0",