w-orm-postgresql 1.0.8 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +16 -16
  2. package/dist/w-orm-postgresql.umd.js +2 -2
  3. package/dist/w-orm-postgresql.umd.js.map +1 -1
  4. package/docs/WOrmPostgresql.html +138 -27
  5. package/docs/WOrmPostgresql.mjs.html +148 -56
  6. package/docs/index.html +2 -2
  7. package/g-basic.mjs +16 -16
  8. package/package.json +1 -1
  9. package/src/WOrmPostgresql.mjs +146 -54
  10. package/test/api-postgresql.test.mjs +513 -46
package/docs/WOrmPostgresql.html CHANGED
@@ -29,7 +29,7 @@
29
29
  <nav >
30
30
 
31
31
 
32
- <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmPostgresql.html">WOrmPostgresql</a><ul class='methods'><li data-type='method'><a href="WOrmPostgresql.html#.createTable">createTable</a></li><li data-type='method'><a href="WOrmPostgresql.html#.del">del</a></li><li data-type='method'><a href="WOrmPostgresql.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insert">insert</a></li><li data-type='method'><a href="WOrmPostgresql.html#.save">save</a></li><li data-type='method'><a href="WOrmPostgresql.html#.select">select</a></li><li data-type='method'><a href="WOrmPostgresql.html#.selectByTime">selectByTime</a></li></ul></li></ul>
32
+ <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="WOrmPostgresql.html">WOrmPostgresql</a><ul class='methods'><li data-type='method'><a href="WOrmPostgresql.html#.createTable">createTable</a></li><li data-type='method'><a href="WOrmPostgresql.html#.del">del</a></li><li data-type='method'><a href="WOrmPostgresql.html#.delAll">delAll</a></li><li data-type='method'><a href="WOrmPostgresql.html#.insert">insert</a></li><li data-type='method'><a href="WOrmPostgresql.html#.save">save</a></li><li data-type='method'><a href="WOrmPostgresql.html#.select">select</a></li><li data-type='method'><a href="WOrmPostgresql.html#.selectByPk">selectByPk</a></li></ul></li></ul>
33
33
 
34
34
  </nav>
35
35
 
@@ -74,13 +74,16 @@
74
74
  <dl class="details">
75
75
 
76
76
  <dt class="tag-description">Description:</dt>
77
- <dd class="tag-description"><ul class="dummy"><li><p>操作資料庫(PostgreSQL)</p></li></ul></dd>
77
+ <dd class="tag-description"><ul class="dummy"><li><p>操作資料庫(PostgreSQL)</p>
78
+ <p>本套件之主鍵欄位由opt.pk指定，預設為time，select以外之五函數皆以此欄位認定主鍵。
79
+ 因主鍵得為承載業務語義之欄位(如時序資料之觀測時間)，insert與save於輸入未帶有效主鍵值時不自動補值，
80
+ 一律以reject回報；del亦不補值，該筆回ok:0與err。</p></li></ul></dd>
78
81
 
79
82
 
80
83
 
81
84
  <dt class="tag-source">Source:</dt>
82
85
  <dd class="tag-source"><ul class="dummy"><li>
83
- <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line37">line 37</a>
86
+ <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line42">line 42</a>
84
87
  </li></ul></dd>
85
88
 
86
89
 
@@ -337,6 +340,46 @@
337
340
 
338
341
 
339
342
 
343
+ <tr>
344
+
345
+ <td class="name"><code>pk</code></td>
346
+
347
+
348
+ <td class="type">
349
+
350
+
351
+ <span class="param-type">String</span>
352
+
353
+
354
+
355
+
356
+ </td>
357
+
358
+
359
+ <td class="attributes">
360
+
361
+ &lt;optional><br>
362
+
363
+
364
+
365
+
366
+
367
+ </td>
368
+
369
+
370
+
371
+ <td class="default">
372
+
373
+ <code>'time'</code>
374
+
375
+ </td>
376
+
377
+
378
+ <td class="description last"><p>輸入主鍵欄位名字串，預設'time'</p></td>
379
+ </tr>
380
+
381
+
382
+
340
383
  <tr>
341
384
 
342
385
  <td class="name"><code>useCache</code></td>
@@ -453,7 +496,7 @@
453
496
 
454
497
 
455
498
 
456
- <h4 class="name" id=".createTable"><span class="type-signature type-signature-async, static">(async, static) </span>createTable<span class="signature">(cl, pk, arr)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
499
+ <h4 class="name" id=".createTable"><span class="type-signature type-signature-async, static">(async, static) </span>createTable<span class="signature">(cl, pk<span class="signature-attributes">opt</span>, arr)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
457
500
 
458
501
 
459
502
 
@@ -463,13 +506,15 @@
463
506
  <dl class="details">
464
507
 
465
508
  <dt class="tag-description">Description:</dt>
466
- <dd class="tag-description"><ul class="dummy"><li><p>創建資料表</p></li></ul></dd>
509
+ <dd class="tag-description"><ul class="dummy"><li><p>創建資料表
510
+ 註: pk未給時採建構時之opt.pk。因insert與save倚賴主鍵之唯一約束達成原子性，
511
+ 若給予與opt.pk不同之欄位，將建出其餘函數無法正確操作之資料表，故一般應留空或給予相同值</p></li></ul></dd>
467
512
 
468
513
 
469
514
 
470
515
  <dt class="tag-source">Source:</dt>
471
516
  <dd class="tag-source"><ul class="dummy"><li>
472
- <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line200">line 200</a>
517
+ <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line227">line 227</a>
473
518
  </li></ul></dd>
474
519
 
475
520
 
@@ -529,8 +574,12 @@
529
574
  <th>Type</th>
530
575
 
531
576
 
577
+ <th>Attributes</th>
578
+
532
579
 
533
580
 
581
+ <th>Default</th>
582
+
534
583
 
535
584
  <th class="last">Description</th>
536
585
  </tr>
@@ -555,7 +604,19 @@
555
604
  </td>
556
605
 
557
606
 
607
+ <td class="attributes">
608
+
609
+
610
+
558
611
 
612
+
613
+ </td>
614
+
615
+
616
+
617
+ <td class="default">
618
+
619
+ </td>
559
620
 
560
621
 
561
622
  <td class="description last"><p>輸入資料表名字串</p></td>
@@ -579,10 +640,26 @@
579
640
  </td>
580
641
 
581
642
 
643
+ <td class="attributes">
644
+
645
+ &lt;optional><br>
646
+
647
+
648
+
649
+
650
+
651
+ </td>
652
+
582
653
 
583
654
 
655
+ <td class="default">
656
+
657
+ <code>opt.pk</code>
658
+
659
+ </td>
660
+
584
661
 
585
- <td class="description last"><p>輸入主鍵字串</p></td>
662
+ <td class="description last"><p>輸入主鍵欄位名字串，預設為建構時之opt.pk</p></td>
586
663
  </tr>
587
664
 
588
665
 
@@ -606,7 +683,19 @@
606
683
  </td>
607
684
 
608
685
 
686
+ <td class="attributes">
687
+
609
688
 
689
+
690
+
691
+
692
+ </td>
693
+
694
+
695
+
696
+ <td class="default">
697
+
698
+ </td>
610
699
 
611
700
 
612
701
  <td class="description last"><p>輸入數據物件陣列或數據物件</p></td>
@@ -672,13 +761,17 @@
672
761
  <dl class="details">
673
762
 
674
763
  <dt class="tag-description">Description:</dt>
675
- <dd class="tag-description"><ul class="dummy"><li><p>刪除數據</p></li></ul></dd>
764
+ <dd class="tag-description"><ul class="dummy"><li><p>刪除數據</p>
765
+ <p>回傳陣列恆與輸入等長，各筆之n與nDeleted皆為主鍵命中筆數，值為0或1，未命中為0且屬正常結果。
766
+ 判斷某筆是否真的被刪除一律以nDeleted為準。
767
+ 未帶有效主鍵值者為該筆之輸入問題，回ok:0與err且不送查詢，不中斷其餘筆數，
768
+ 以此與[主鍵未命中]之ok:1區辨。</p></li></ul></dd>
676
769
 
677
770
 
678
771
 
679
772
  <dt class="tag-source">Source:</dt>
680
773
  <dd class="tag-source"><ul class="dummy"><li>
681
- <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line942">line 942</a>
774
+ <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1021">line 1021</a>
682
775
  </li></ul></dd>
683
776
 
684
777
 
@@ -796,7 +889,7 @@
796
889
 
797
890
 
798
891
  <div class="param-desc">
799
- <p>回傳Promise，resolve回傳刪除結果，reject回傳錯誤訊息</p>
892
+ <p>回傳Promise，resolve回傳刪除結果陣列[{n,nDeleted,ok}]，reject回傳錯誤訊息</p>
800
893
  </div>
801
894
 
802
895
 
@@ -833,13 +926,15 @@
833
926
  <dl class="details">
834
927
 
835
928
  <dt class="tag-description">Description:</dt>
836
- <dd class="tag-description"><ul class="dummy"><li><p>刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表</p></li></ul></dd>
929
+ <dd class="tag-description"><ul class="dummy"><li><p>刪除全部數據，需與del分開，避免未傳數據導致直接刪除全表</p>
930
+ <p>n與nDeleted皆為實際刪除筆數，不取全表筆數。find未給或為空物件時刪除全部數據，
931
+ 條件無命中時回{n:0,nDeleted:0,ok:1}，不視為錯誤。</p></li></ul></dd>
837
932
 
838
933
 
839
934
 
840
935
  <dt class="tag-source">Source:</dt>
841
936
  <dd class="tag-source"><ul class="dummy"><li>
842
- <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1079">line 1079</a>
937
+ <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line1171">line 1171</a>
843
938
  </li></ul></dd>
844
939
 
845
940
 
@@ -974,7 +1069,7 @@
974
1069
 
975
1070
 
976
1071
  <div class="param-desc">
977
- <p>回傳Promise，resolve回傳刪除結果，reject回傳錯誤訊息</p>
1072
+ <p>回傳Promise，resolve回傳刪除結果物件{n,nDeleted,ok}，reject回傳錯誤訊息</p>
978
1073
  </div>
979
1074
 
980
1075
 
@@ -1011,13 +1106,16 @@
1011
1106
  <dl class="details">
1012
1107
 
1013
1108
  <dt class="tag-description">Description:</dt>
1014
- <dd class="tag-description"><ul class="dummy"><li><p>插入數據</p></li></ul></dd>
1109
+ <dd class="tag-description"><ul class="dummy"><li><p>插入數據，僅於主鍵不存在時寫入，已存在者跳過且不覆寫</p>
1110
+ <p>n為輸入筆數，即本次嘗試插入之基準；nInserted為實際插入筆數，全數已存在而nInserted為0屬正常結果，
1111
+ 不視為錯誤。同批含重複主鍵時僅首筆計入nInserted。
1112
+ 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。</p></li></ul></dd>
1015
1113
 
1016
1114
 
1017
1115
 
1018
1116
  <dt class="tag-source">Source:</dt>
1019
1117
  <dd class="tag-source"><ul class="dummy"><li>
1020
- <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line489">line 489</a>
1118
+ <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line538">line 538</a>
1021
1119
  </li></ul></dd>
1022
1120
 
1023
1121
 
@@ -1135,7 +1233,7 @@
1135
1233
 
1136
1234
 
1137
1235
  <div class="param-desc">
1138
- <p>回傳Promise，resolve回傳插入結果，reject回傳錯誤訊息</p>
1236
+ <p>回傳Promise，resolve回傳插入結果物件{n,nInserted,ok}，reject回傳錯誤訊息</p>
1139
1237
  </div>
1140
1238
 
1141
1239
 
@@ -1172,13 +1270,20 @@
1172
1270
  <dl class="details">
1173
1271
 
1174
1272
  <dt class="tag-description">Description:</dt>
1175
- <dd class="tag-description"><ul class="dummy"><li><p>儲存數據</p></li></ul></dd>
1273
+ <dd class="tag-description"><ul class="dummy"><li><p>儲存數據，以主鍵time為準更新既有數據，未給之欄位保留</p>
1274
+ <p>回傳陣列恆與輸入等長，輸入單一物件亦回傳長度1之陣列。
1275
+ 各筆之n為主鍵命中筆數，值為0或1，命中(不論內容有無變更)或經插入而產生皆為1；
1276
+ nInserted與nModified恆同時出現，無對應行為時填0。
1277
+ [內容相同]之判定基準為待寫入物件合併進現值後與現值相同，非待寫入物件與現值全等，
1278
+ 故只給部份欄位且該些欄位值皆與現值相同時，合併結果等於現值，nModified為0，
1279
+ 令nModified忠實反映資料庫端是否真的寫入。
1280
+ 因主鍵得承載業務語義，未帶有效主鍵值時不自動補值，一律以reject回報。</p></li></ul></dd>
1176
1281
 
1177
1282
 
1178
1283
 
1179
1284
  <dt class="tag-source">Source:</dt>
1180
1285
  <dd class="tag-source"><ul class="dummy"><li>
1181
- <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line618">line 618</a>
1286
+ <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line675">line 675</a>
1182
1287
  </li></ul></dd>
1183
1288
 
1184
1289
 
@@ -1422,7 +1527,7 @@
1422
1527
 
1423
1528
 
1424
1529
  <div class="param-desc">
1425
- <p>回傳Promise，resolve回傳儲存結果，reject回傳錯誤訊息</p>
1530
+ <p>回傳Promise，resolve回傳儲存結果陣列[{n,nInserted,nModified,ok}]，reject回傳錯誤訊息</p>
1426
1531
  </div>
1427
1532
 
1428
1533
 
@@ -1465,7 +1570,7 @@
1465
1570
 
1466
1571
  <dt class="tag-source">Source:</dt>
1467
1572
  <dd class="tag-source"><ul class="dummy"><li>
1468
- <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line286">line 286</a>
1573
+ <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line319">line 319</a>
1469
1574
  </li></ul></dd>
1470
1575
 
1471
1576
 
@@ -1667,7 +1772,7 @@
1667
1772
 
1668
1773
 
1669
1774
 
1670
- <h4 class="name" id=".selectByTime"><span class="type-signature type-signature-async, static">(async, static) </span>selectByTime<span class="signature">(time)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
1775
+ <h4 class="name" id=".selectByPk"><span class="type-signature type-signature-async, static">(async, static) </span>selectByPk<span class="signature">(pk)</span><span class="type-signature"> &rarr; {Promise}</span></h4>
1671
1776
 
1672
1777
 
1673
1778
 
@@ -1677,13 +1782,16 @@
1677
1782
  <dl class="details">
1678
1783
 
1679
1784
  <dt class="tag-description">Description:</dt>
1680
- <dd class="tag-description"><ul class="dummy"><li><p>由主鍵time查詢單筆數據，因直接由資料表主鍵索引取值，不需如select提取數據至前端再處理，故數據量大時效能較佳</p></li></ul></dd>
1785
+ <dd class="tag-description"><ul class="dummy"><li><p>由主鍵查詢單筆數據，因直接由資料表主鍵索引取值，不需如select提取數據至前端再處理，故數據量大時效能較佳
1786
+ 註: 本套件之主鍵欄位由建構時之opt.pk指定，預設為time</p>
1787
+ <p>主鍵未命中或主鍵值無效皆回傳null而不reject，命中之判定基準與insert、save、del內對既有數據之認定一致。
1788
+ 主鍵值之型別與欄位不符時PostgreSQL回報22P02或22007，亦屬主鍵值無效而回傳null。</p></li></ul></dd>
1681
1789
 
1682
1790
 
1683
1791
 
1684
1792
  <dt class="tag-source">Source:</dt>
1685
1793
  <dd class="tag-source"><ul class="dummy"><li>
1686
- <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line377">line 377</a>
1794
+ <a href="WOrmPostgresql.mjs.html">WOrmPostgresql.mjs</a>, <a href="WOrmPostgresql.mjs.html#line414">line 414</a>
1687
1795
  </li></ul></dd>
1688
1796
 
1689
1797
 
@@ -1755,7 +1863,7 @@
1755
1863
 
1756
1864
  <tr>
1757
1865
 
1758
- <td class="name"><code>time</code></td>
1866
+ <td class="name"><code>pk</code></td>
1759
1867
 
1760
1868
 
1761
1869
  <td class="type">
@@ -1764,6 +1872,9 @@
1764
1872
  <span class="param-type">String</span>
1765
1873
  |
1766
1874
 
1875
+ <span class="param-type">Number</span>
1876
+ |
1877
+
1767
1878
  <span class="param-type">Date</span>
1768
1879
 
1769
1880
 
@@ -1775,7 +1886,7 @@
1775
1886
 
1776
1887
 
1777
1888
 
1778
- <td class="description last"><p>輸入主鍵time值，本套件以time欄位為主鍵</p></td>
1889
+ <td class="description last"><p>輸入主鍵值，即數據之主鍵欄位值</p></td>
1779
1890
  </tr>
1780
1891
 
1781
1892
 
@@ -1801,7 +1912,7 @@
1801
1912
 
1802
1913
 
1803
1914
  <div class="param-desc">
1804
- <p>回傳Promise，resolve回傳數據物件，若無此time則回傳null，reject回傳錯誤訊息</p>
1915
+ <p>回傳Promise，resolve回傳數據物件，若無此主鍵則回傳null，reject回傳錯誤訊息</p>
1805
1916
  </div>
1806
1917
 
1807
1918
 
@@ -1843,7 +1954,7 @@
1843
1954
  <br class="clear">
1844
1955
 
1845
1956
  <footer>
1846
- 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.
1957
+ Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.5</a> on Sun Aug 16 2026 23:54:17 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
1847
1958
  </footer>
1848
1959
 
1849
1960
  <script>prettyPrint();</script>