w-dwdata-hub 1.0.0

package/test/fetchWithRetry.test.mjs

@@ -0,0 +1,174 @@
+import assert from 'assert'
+import fetchWithRetry from '../src/fetchWithRetry.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchWithRetry', function() {
+
+    let svr = null
+
+    //optFast, 令重試等待縮至10毫秒, 避免測試耗時
+    let optFast = { baseDelayMs: 10, maxDelayMs: 10, showLog: false }
+
+    before(async function() {
+        svr = await serverForTest()
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('非有效字串網址拋錯', async function() {
+        let r = []
+        for (let url of [null, undefined, '', 123, {}]) {
+            await fetchWithRetry(url)
+                .then(() => {
+                    r.push('resolved')
+                })
+                .catch((err) => {
+                    r.push(err.message.startsWith('url須為有效字串'))
+                })
+        }
+        let rr = [true, true, true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('responseType預設為json並回傳物件', async function() {
+        let r = await fetchWithRetry(svr.url('/json/ok'), optFast)
+        let rr = { ok: true, value: 1 }
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('responseType為text時回傳原始字串', async function() {
+        let t = await fetchWithRetry(svr.url('/rss/feed.xml'), { ...optFast, responseType: 'text' })
+        let r = [typeof t, t.includes('<title>測試訂閱源</title>')]
+        let rr = ['string', true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('responseType為text且指定encoding時以該編碼解碼', async function() {
+        let r = await fetchWithRetry(svr.url('/text/big5'), { ...optFast, responseType: 'text', encoding: 'big5' })
+        let rr = '中文測試,Big5編碼'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('responseType為text但未指定encoding時以utf-8解碼, Big5內容會解出亂碼', async function() {
+        let t = await fetchWithRetry(svr.url('/text/big5'), { ...optFast, responseType: 'text' })
+        let r = t === '中文測試,Big5編碼'
+        let rr = false
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('responseType為arrayBuffer時回傳ArrayBuffer', async function() {
+        let t = await fetchWithRetry(svr.url('/text/big5'), { ...optFast, responseType: 'arrayBuffer' })
+        let r = [t instanceof ArrayBuffer, new TextDecoder('big5').decode(t)]
+        let rr = [true, '中文測試,Big5編碼']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('回傳非JSON時拋出可讀錯誤而非裸SyntaxError', async function() {
+        let r = null
+        await fetchWithRetry(svr.url('/json/bad'), optFast)
+            .then(() => {
+                r = 'resolved'
+            })
+            .catch((err) => {
+                r = [err.message.startsWith('回傳非JSON格式'), err instanceof SyntaxError]
+            })
+        let rr = [true, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('HTTP 404不重試, 僅執行1次且錯誤帶statusCode', async function() {
+        let c0 = svr.getCount('/status/404')
+        let e = null
+        await fetchWithRetry(svr.url('/status/404'), { ...optFast, maxRetries: 5 })
+            .catch((err) => {
+                e = err
+            })
+        let r = [e.statusCode, svr.getCount('/status/404') - c0]
+        let rr = [404, 1]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('HTTP 403預設不重試', async function() {
+        let c0 = svr.getCount('/status/403')
+        await fetchWithRetry(svr.url('/status/403'), { ...optFast, maxRetries: 3 })
+            .catch(() => {})
+        let r = svr.getCount('/status/403') - c0
+        let rr = 1
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('HTTP 403於retryStatus指定時會重試, 含初始共執行maxRetries+1次', async function() {
+        let c0 = svr.getCount('/status/403')
+        await fetchWithRetry(svr.url('/status/403'), { ...optFast, maxRetries: 3, retryStatus: [403] })
+            .catch(() => {})
+        let r = svr.getCount('/status/403') - c0
+        let rr = 4
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('HTTP 500重試至次數用盡, 含初始共執行maxRetries+1次', async function() {
+        let c0 = svr.getCount('/status/500')
+        let e = null
+        await fetchWithRetry(svr.url('/status/500'), { ...optFast, maxRetries: 2 })
+            .catch((err) => {
+                e = err
+            })
+        let r = [e.statusCode, svr.getCount('/status/500') - c0]
+        let rr = [500, 3]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('HTTP 429會重試', async function() {
+        let c0 = svr.getCount('/status/429')
+        await fetchWithRetry(svr.url('/status/429'), { ...optFast, maxRetries: 2 })
+            .catch(() => {})
+        let r = svr.getCount('/status/429') - c0
+        let rr = 3
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('暫時性失敗於重試後成功', async function() {
+        await fetchWithRetry(svr.url('/flaky/reset'), optFast)
+        let t = await fetchWithRetry(svr.url('/flaky/503?n=2'), { ...optFast, maxRetries: 5 })
+        let r = [t.ok, t.failed]
+        let rr = [true, 2]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('連線不到之埠號視為網路層錯誤並重試', async function() {
+        let e = null
+        await fetchWithRetry('http://127.0.0.1:1/abc', { ...optFast, maxRetries: 1, timeout: 2000 })
+            .catch((err) => {
+                e = err
+            })
+        let r = e !== null
+        let rr = true
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('逾時視為可重試錯誤, maxRetries為0時僅執行1次', async function() {
+        let c0 = svr.getCount('/slow')
+        let e = null
+        await fetchWithRetry(svr.url('/slow?ms=300'), { ...optFast, maxRetries: 0, timeout: 50 })
+            .catch((err) => {
+                e = err
+            })
+        let r = [e !== null, svr.getCount('/slow') - c0]
+        let rr = [true, 1]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('未指定User-Agent時自動補預設值, 指定時以指定者為準', async function() {
+        let t1 = await fetchWithRetry(svr.url('/echo'), optFast)
+        let t2 = await fetchWithRetry(svr.url('/echo'), { ...optFast, headers: { 'User-Agent': 'my-ua' } })
+        let r = [t1.headers['user-agent'].includes('Mozilla/5.0'), t2.headers['user-agent']]
+        let rr = [true, 'my-ua']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/htmlToMarkdown.test.mjs

@@ -0,0 +1,71 @@
+import assert from 'assert'
+import htmlToMarkdown from '../src/htmlToMarkdown.mjs'
+
+
+describe('htmlToMarkdown', function() {
+
+    it('段落轉為空行分隔', function() {
+        let r = htmlToMarkdown('<p>第一段</p><p>第二段</p>')
+        let rr = '第一段\n\n第二段'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('粗體與斜體轉為Markdown標記', function() {
+        let r = htmlToMarkdown('<p>a<b>粗</b>b<strong>體</strong>c<i>斜</i>d<em>體</em></p>')
+        let rr = 'a**粗**b**體**c*斜*d*體*'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('標題轉為粗體段落', function() {
+        let r = htmlToMarkdown('<h1>標題</h1><p>內文</p>')
+        let rr = '**標題**\n\n內文'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('連結轉為Markdown連結, 無文字之連結被移除', function() {
+        let r = [
+            htmlToMarkdown('<p><a href="https://a.example/">連結</a></p>'),
+            htmlToMarkdown('<p>x<a href="https://a.example/"></a>y</p>'),
+        ]
+        let rr = ['[連結](https://a.example/)', 'xy']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('br轉為換行', function() {
+        let r = htmlToMarkdown('<p>一<br/>二<br>三</p>')
+        let rr = '一\n二\n三'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('移除script、style與註解', function() {
+        let r = htmlToMarkdown('<p>前</p><script>var a=1</script><style>.a{}</style><!--註解--><p>後</p>')
+        let rr = '前\n\n後'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('解碼HTML實體並收斂多重空行', function() {
+        let r = htmlToMarkdown('<p>a&amp;b</p><p></p><p></p><p>c</p>')
+        let rr = 'a&b\n\nc'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('預設移除img, image為true時轉為Markdown圖片', function() {
+        let r = [
+            htmlToMarkdown('<p><img src="https://a.example/1.png" />文字</p>'),
+            htmlToMarkdown('<p><img src="https://a.example/1.png" />文字</p>', { image: true }),
+        ]
+        let rr = ['文字', '![](https://a.example/1.png)文字']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('非字串回傳空字串', function() {
+        let r = [
+            htmlToMarkdown(null),
+            htmlToMarkdown(undefined),
+            htmlToMarkdown(123),
+        ]
+        let rr = ['', '', '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/isYmd.test.mjs

@@ -0,0 +1,56 @@
+import assert from 'assert'
+import isYmd from '../src/isYmd.mjs'
+
+
+describe('isYmd', function() {
+
+    it('合法之YYYYMMDD字串為true', function() {
+        let r = [
+            isYmd('20260807'),
+            isYmd('20000229'),
+            isYmd('19110101'),
+            isYmd('20261231'),
+        ]
+        let rr = [true, true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('格式為8碼數字但日曆不存在之日期為false', function() {
+        let r = [
+            isYmd('20260230'),
+            isYmd('20260231'),
+            isYmd('20261301'),
+            isYmd('20260732'),
+            isYmd('20260000'),
+            isYmd('21000229'),
+        ]
+        let rr = [false, false, false, false, false, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('非8碼數字格式為false', function() {
+        let r = [
+            isYmd('2026-08-07'),
+            isYmd('2026080'),
+            isYmd('202608071'),
+            isYmd('2026080a'),
+            isYmd(' 20260807'),
+        ]
+        let rr = [false, false, false, false, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('非有效字串為false', function() {
+        let r = [
+            isYmd(''),
+            isYmd(null),
+            isYmd(undefined),
+            isYmd(20260807),
+            isYmd({}),
+            isYmd([]),
+        ]
+        let rr = [false, false, false, false, false, false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/parseIntComma.test.mjs

@@ -0,0 +1,38 @@
+import assert from 'assert'
+import parseIntComma from '../src/parseIntComma.mjs'
+
+
+describe('parseIntComma', function() {
+
+    it('去除千分位逗號後轉整數', function() {
+        let r = [
+            parseIntComma('1,234,567'),
+            parseIntComma('1000'),
+            parseIntComma('-1,500'),
+            parseIntComma('0'),
+        ]
+        let rr = [1234567, 1000, -1500, 0]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('證交所與櫃買中心之缺值表示法轉為0', function() {
+        let r = [
+            parseIntComma('-'),
+            parseIntComma(''),
+            parseIntComma('N/A'),
+        ]
+        let rr = [0, 0, 0]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('非字串原樣回傳', function() {
+        let r = [
+            parseIntComma(12),
+            parseIntComma(null),
+            parseIntComma(undefined),
+        ]
+        let rr = [12, null, undefined]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/safeFilename.test.mjs

@@ -0,0 +1,35 @@
+import assert from 'assert'
+import safeFilename from '../src/safeFilename.mjs'
+
+
+describe('safeFilename', function() {
+
+    it('替換Windows與POSIX不允許之字元為底線', function() {
+        let r = safeFilename('a\\b/c:d*e?f"g<h>i|j')
+        let rr = 'a_b_c_d_e_f_g_h_i_j'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('保留中文與一般字元', function() {
+        let r = safeFilename('葛兆光：禅宗与中国文化 (2026)')
+        let rr = '葛兆光：禅宗与中国文化 (2026)'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('截斷至200字元', function() {
+        let r = safeFilename('a'.repeat(300)).length
+        let rr = 200
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('非字串轉為字串處理, null與undefined轉為空字串', function() {
+        let r = [
+            safeFilename(null),
+            safeFilename(undefined),
+            safeFilename(123),
+        ]
+        let rr = ['', '', '123']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/toDatetimeUTC8.test.mjs

@@ -0,0 +1,65 @@
+import assert from 'assert'
+import toDatetimeUTC8 from '../src/toDatetimeUTC8.mjs'
+
+
+describe('toDatetimeUTC8', function() {
+
+    it('ISO時間字串轉UTC+8', function() {
+        let r = [
+            toDatetimeUTC8('2026-08-07T01:02:03Z'),
+            toDatetimeUTC8('2026-08-06T16:00:00Z'),
+            toDatetimeUTC8('2026-12-31T20:00:00Z'),
+        ]
+        let rr = ['2026-08-07 09:02:03', '2026-08-07 00:00:00', '2027-01-01 04:00:00']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('RFC822時間字串轉UTC+8', function() {
+        let r = [
+            toDatetimeUTC8('Fri, 07 Aug 2026 01:02:03 GMT'),
+            toDatetimeUTC8('Fri, 07 Aug 2026 02:03:04 GMT'),
+        ]
+        let rr = ['2026-08-07 09:02:03', '2026-08-07 10:03:04']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('數值視為unix秒數轉UTC+8', function() {
+        let r = [
+            toDatetimeUTC8(1786000000),
+            toDatetimeUTC8(1786000060),
+        ]
+        let rr = ['2026-08-06 15:06:40', '2026-08-06 15:07:40']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('Date物件轉UTC+8', function() {
+        let r = toDatetimeUTC8(new Date('2026-08-07T01:02:03Z'))
+        let rr = '2026-08-07 09:02:03'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('不受執行環境時區影響, 一律以UTC+8輸出', function() {
+        //以UTC+0與UTC+8之等價時刻做交叉驗證, 兩者應得相同結果
+        let r = [
+            toDatetimeUTC8('2026-08-07T01:02:03Z'),
+            toDatetimeUTC8('2026-08-07T09:02:03+08:00'),
+        ]
+        let rr = ['2026-08-07 09:02:03', '2026-08-07 09:02:03']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('無法解析或為空時回傳空字串', function() {
+        let r = [
+            toDatetimeUTC8('not-a-date'),
+            toDatetimeUTC8(''),
+            toDatetimeUTC8(0),
+            toDatetimeUTC8(null),
+            toDatetimeUTC8(undefined),
+            toDatetimeUTC8({}),
+            toDatetimeUTC8([]),
+        ]
+        let rr = ['', '', '', '', '', '', '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/toRocDate.test.mjs

@@ -0,0 +1,38 @@
+import assert from 'assert'
+import toRocDate from '../src/toRocDate.mjs'
+
+
+describe('toRocDate', function() {
+
+    it('西元轉民國且月日保留原始2碼', function() {
+        let r = [
+            toRocDate('20260807'),
+            toRocDate('20260101'),
+            toRocDate('20261231'),
+        ]
+        let rr = ['115/08/07', '115/01/01', '115/12/31']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('民國元年與元年前之邊界', function() {
+        let r = [
+            toRocDate('19120101'),
+            toRocDate('19110101'),
+            toRocDate('19100101'),
+        ]
+        let rr = ['1/01/01', '0/01/01', '-1/01/01']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('非有效字串回傳空字串', function() {
+        let r = [
+            toRocDate(''),
+            toRocDate(null),
+            toRocDate(undefined),
+            toRocDate(20260807),
+        ]
+        let rr = ['', '', '', '']
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/tools/encodeBig5.mjs

@@ -0,0 +1,80 @@
+//由TextDecoder('big5')反推之編碼表, 首次呼叫時建立後快取
+let mapChar2Bytes = null
+
+
+/**
+ * 建立Big5編碼表
+ *
+ * node內建TextDecoder可解Big5但TextEncoder僅支援utf-8, 故以TextDecoder逐一解碼合法雙位元組序列反推編碼表,
+ * 令測試不需額外相依即可產生Big5位元組(期交所CSV為Big5編碼)
+ *
+ * @returns {Map} 回傳字元對應位元組陣列之Map
+ */
+function buildMap() {
+
+    let m = new Map()
+    let dec = new TextDecoder('big5')
+
+    //單位元組(ASCII)
+    for (let b = 0; b < 0x80; b++) {
+        m.set(String.fromCharCode(b), [b])
+    }
+
+    //雙位元組, lead為0x81-0xFE, trail為0x40-0x7E與0xA1-0xFE
+    for (let lead = 0x81; lead <= 0xFE; lead++) {
+        for (let trail = 0x40; trail <= 0xFE; trail++) {
+            if (trail > 0x7E && trail < 0xA1) {
+                continue
+            }
+            let s = dec.decode(new Uint8Array([lead, trail]))
+            if (s.length !== 1 || s === '�') {
+                continue
+            }
+            if (!m.has(s)) {
+                m.set(s, [lead, trail])
+            }
+        }
+    }
+
+    return m
+}
+
+
+/**
+ * 字串編碼為Big5位元組
+ *
+ * 供測試伺服器產生期交所風格之Big5 CSV, 無對應碼位之字元以'?'替代
+ *
+ * @param {String} str 輸入字串
+ * @returns {Buffer} 回傳Big5編碼之Buffer
+ * @example
+ *
+ * import encodeBig5 from './tools/encodeBig5.mjs'
+ *
+ * let buf = encodeBig5('契約')
+ * console.log(new TextDecoder('big5').decode(buf))
+ * // => '契約'
+ *
+ */
+function encodeBig5(str) {
+
+    if (mapChar2Bytes === null) {
+        mapChar2Bytes = buildMap()
+    }
+
+    let bytes = []
+    for (let ch of String(str)) {
+        let bs = mapChar2Bytes.get(ch)
+        if (bs === undefined) {
+            bytes.push(0x3F) //'?'
+        }
+        else {
+            bytes.push(...bs)
+        }
+    }
+
+    return Buffer.from(bytes)
+}
+
+
+export default encodeBig5