w-dwdata-hub 1.0.0

package/test/fetchTaifex.test.mjs

@@ -0,0 +1,99 @@
+import assert from 'assert'
+import fetchTaifex from '../src/fetchTaifex.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchTaifex', function() {
+
+    let svr = null
+    let optFast = null
+
+    before(async function() {
+        svr = await serverForTest()
+        optFast = { baseUrl: svr.url(''), baseDelayMs: 10, maxDelayMs: 10, interRequestDelayMs: 0, showLog: false }
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('日期格式錯誤與日期不合法之訊息不同', async function() {
+        let r = []
+        await fetchTaifex('2026-08-07', optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        await fetchTaifex('20260230', optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        let rr = [
+            'dateStr 須為 YYYYMMDD 字串，得到: 2026-08-07',
+            'dateStr 非合法日期: 20260230',
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('Big5編碼之CSV可正確解碼與解析', async function() {
+        let t = await fetchTaifex('20260807', optFast)
+        let r = [t.date, t.errors, t.futures.tx.contractMonth]
+        let rr = ['20260807', [], '202608']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('台指期取近月合約, 排除到期月份含斜線之價差合約', async function() {
+        let t = await fetchTaifex('20260807', optFast)
+        let rr = {
+            contractMonth: '202608',
+            open: 23000,
+            high: 23200,
+            low: 22900,
+            close: 23150,
+            settlement: 23160,
+            volume: 80000,
+            afterHoursClose: 23250,
+            afterHoursSettlement: 23260,
+            afterHoursVolume: 20000,
+        }
+        assert.strict.deepEqual(t.futures.tx, rr)
+    })
+
+    it('三大法人期貨未平倉依身份別轉為foreign、trust與dealers', async function() {
+        let t = await fetchTaifex('20260807', optFast)
+        let r = [
+            Object.keys(t.institutional).sort(),
+            t.institutional.foreign.netContracts,
+            t.institutional.trust.netContracts,
+            t.institutional.dealers.netContracts,
+        ]
+        let rr = [['dealers', 'foreign', 'trust'], 20000, 1500, 1000]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('Put/Call Ratio解析為數值', async function() {
+        let t = await fetchTaifex('20260807', optFast)
+        let rr = {
+            putVolume: 100000,
+            callVolume: 90000,
+            ratio: 111.11,
+            putOpenInterest: 50000,
+            callOpenInterest: 60000,
+            openInterestRatio: 83.33,
+        }
+        assert.strict.deepEqual(t.pcRatio, rr)
+    })
+
+    it('三支資料全失敗時reject並帶errors', async function() {
+        let e = null
+        await fetchTaifex('20260807', { ...optFast, baseUrl: svr.url('/no-data') })
+            .catch((err) => {
+                e = err
+            })
+        let r = [e.message.startsWith('所有資料抓取失敗'), e.errors.length]
+        let rr = [true, 3]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/fetchTpex3insti.test.mjs

@@ -0,0 +1,90 @@
+import assert from 'assert'
+import fetchTpex3insti from '../src/fetchTpex3insti.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchTpex3insti', function() {
+
+    let svr = null
+    let optFast = null
+
+    before(async function() {
+        svr = await serverForTest()
+        optFast = { baseUrl: svr.url(''), baseDelayMs: 10, maxDelayMs: 10, showLog: false }
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('日期格式錯誤與日期不合法之訊息不同', async function() {
+        let r = []
+        await fetchTpex3insti('2026-08-07', [], optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        await fetchTpex3insti('20260230', [], optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        let rr = [
+            'dateStr must be YYYYMMDD, got: 2026-08-07',
+            'dateStr 不是合法日期: 20260230',
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('以固定位置還原7組明細欄名, 不因裸欄名重複而塌成1組', async function() {
+        let t = await fetchTpex3insti('20260807', ['6488'], optFast)
+        let rr = {
+            '代號': '6488',
+            '名稱': '環球晶',
+            '外陸資買進股數(不含外資自營商)': '100',
+            '外陸資賣出股數(不含外資自營商)': '50',
+            '外陸資買賣超股數(不含外資自營商)': '50',
+            '外資自營商買進股數': '10',
+            '外資自營商賣出股數': '5',
+            '外資自營商買賣超股數': '5',
+            '外資及陸資買進股數': '110',
+            '外資及陸資賣出股數': '55',
+            '外資及陸資買賣超股數': '55',
+            '投信買進股數': '200',
+            '投信賣出股數': '100',
+            '投信買賣超股數': '100',
+            '自營商買進股數(自行買賣)': '30',
+            '自營商賣出股數(自行買賣)': '10',
+            '自營商買賣超股數(自行買賣)': '20',
+            '自營商買進股數(避險)': '40',
+            '自營商賣出股數(避險)': '20',
+            '自營商買賣超股數(避險)': '20',
+            '自營商買進股數': '70',
+            '自營商賣出股數': '30',
+            '自營商買賣超股數': '40',
+            '三大法人買賣超股數合計': '195',
+        }
+        assert.strict.deepEqual(t.data[0], rr)
+    })
+
+    it('未指定個股時回傳全市場', async function() {
+        let t = await fetchTpex3insti('20260807', [], optFast)
+        let r = [t.source, t.date, t.data.length]
+        let rr = ['tpex', '20260807', 2]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('欄序已變時fail-loud, 避免把外資數字貼到投信頭上', async function() {
+        let r = null
+        await fetchTpex3insti('20260807', [], { ...optFast, baseUrl: svr.url('/bad-shape') })
+            .then(() => {
+                r = 'resolved'
+            })
+            .catch((err) => {
+                r = err.message
+            })
+        let rr = 'TPEX 3insti: 欄數異常，預期 24 得 6（疑似 API 改版，請重新校準 TPEX_FIELD_MAP）'
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/fetchTpexMargin.test.mjs

@@ -0,0 +1,94 @@
+import assert from 'assert'
+import fetchTpexMargin from '../src/fetchTpexMargin.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchTpexMargin', function() {
+
+    let svr = null
+    let optFast = null
+
+    before(async function() {
+        svr = await serverForTest()
+        optFast = { baseUrl: svr.url(''), baseDelayMs: 10, maxDelayMs: 10, showLog: false }
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('日期格式錯誤與日期不合法之訊息不同', async function() {
+        let r = []
+        await fetchTpexMargin('2026-08-07', [], optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        await fetchTpexMargin('20260230', [], optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        let rr = [
+            '日期參數無效：格式須為 YYYYMMDD (收到 "2026-08-07")',
+            '日期參數無效：不合法的日期 (20260230)',
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('依固定欄序解析融資融券並算出增減', async function() {
+        let t = await fetchTpexMargin('20260807', ['6488'], optFast)
+        let rr = {
+            code: '6488',
+            name: '環球晶',
+            marginBuy: 300,
+            marginSell: 200,
+            marginCashRepay: 50,
+            marginPrevBalance: 5000,
+            marginBalance: 5050,
+            marginChange: 50,
+            marginLimit: 400000,
+            shortSell: 100,
+            shortBuy: 80,
+            shortCashRepay: 20,
+            shortPrevBalance: 1000,
+            shortBalance: 1000,
+            shortChange: 0,
+            shortLimit: 400000,
+            offset: 30,
+            note: '',
+        }
+        assert.strict.deepEqual(t.data[0], rr)
+    })
+
+    it('未指定個股時回傳全市場', async function() {
+        let t = await fetchTpexMargin('20260807', [], optFast)
+        let r = [t.source, t.date, t.count]
+        let rr = ['tpex_margin', '20260807', 2]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('欄位佈局與預期不符時fail-loud, 不產生錯誤資料', async function() {
+        let r = null
+        await fetchTpexMargin('20260807', [], { ...optFast, baseUrl: svr.url('/bad-shape') })
+            .then(() => {
+                r = 'resolved'
+            })
+            .catch((err) => {
+                r = err.message.startsWith('TPEX 融資融券資料欄位佈局與預期不符')
+            })
+        let rr = true
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('指定個股查無資料時reject', async function() {
+        let r = null
+        await fetchTpexMargin('20260807', ['2330'], optFast)
+            .catch((err) => {
+                r = err.message
+            })
+        let rr = '指定個股 2330 不在上櫃融資融券資料中（可能為上市股或代碼有誤）'
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/fetchTpexStock.test.mjs

@@ -0,0 +1,68 @@
+import assert from 'assert'
+import fetchTpexStock from '../src/fetchTpexStock.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchTpexStock', function() {
+
+    let svr = null
+    let optFast = null
+
+    before(async function() {
+        svr = await serverForTest()
+        optFast = { baseUrl: svr.url(''), baseDelayMs: 10, maxDelayMs: 10, showLog: false }
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('日期非合法YYYYMMDD時拋錯', async function() {
+        let r = []
+        for (let dateStr of ['', null, '2026-08-07', '20260230']) {
+            await fetchTpexStock(dateStr, [], optFast)
+                .then(() => {
+                    r.push('resolved')
+                })
+                .catch((err) => {
+                    r.push(err.message.startsWith('dateStr 須為合法之 YYYYMMDD 字串'))
+                })
+        }
+        let rr = [true, true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('未指定個股時回傳全市場', async function() {
+        let t = await fetchTpexStock('20260807', undefined, optFast)
+        let r = [t.source, t.date, t.count, t.data[0][0]]
+        let rr = ['tpex', '20260807', 2, '6488']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('選表優先取標題含「行情」者而非第一張有資料表', async function() {
+        let t = await fetchTpexStock('20260807', [], optFast)
+        let r = [t.count, t.data[0].length >= 8]
+        let rr = [2, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('指定個股時過濾為該個股', async function() {
+        let t = await fetchTpexStock('20260807', ['6510'], optFast)
+        let r = [t.count, t.data[0][0], t.data[0][1]]
+        let rr = [1, '6510', '精測']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('指定個股查無資料時reject且訊息與整體無資料明確區分', async function() {
+        let r = null
+        await fetchTpexStock('20260807', ['2330'], optFast)
+            .catch((err) => {
+                r = err.message
+            })
+        let rr = '指定個股 2330 在 20260807 之上櫃資料中查無資料（可能為上市股、代碼有誤、或當日無交易）'
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/fetchTwDataHoliday.test.mjs

@@ -0,0 +1,100 @@
+import assert from 'assert'
+import fetchTwDataHoliday from '../src/fetchTwDataHoliday.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchTwDataHoliday', function() {
+
+    let svr = null
+    let optFast = null
+
+    before(async function() {
+        svr = await serverForTest()
+        optFast = { url: svr.url('/v1/holidaySchedule/holidaySchedule'), baseDelayMs: 10, maxDelayMs: 10, showLog: false }
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('民國日期轉西元並依日期排序, 交易日標記與結算作業日被排除且同日去重', async function() {
+        let t = await fetchTwDataHoliday(undefined, optFast)
+        let rr = {
+            dataYear: '2026',
+            totalHolidays: 2,
+            holidays: [
+                {
+                    date: '20260101',
+                    rocDate: '1150101',
+                    name: '中華民國開國紀念日',
+                    weekday: '四',
+                    description: '1月1日(星期四)為假日。',
+                },
+                {
+                    date: '20260216',
+                    rocDate: '1150216',
+                    name: '農曆春節',
+                    weekday: '一',
+                    description: '2月16日放假',
+                },
+            ],
+        }
+        assert.strict.deepEqual(t, rr)
+    })
+
+    it('checkDate為休市日時回傳isHoliday為true與假日名稱', async function() {
+        let t = await fetchTwDataHoliday('20260101', optFast)
+        let r = [t.checkDate, t.isHoliday, t.holidayName]
+        let rr = ['20260101', true, '中華民國開國紀念日']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('checkDate非休市日時回傳isHoliday為false與null', async function() {
+        let t = await fetchTwDataHoliday('20260102', optFast)
+        let r = [t.checkDate, t.isHoliday, t.holidayName]
+        let rr = ['20260102', false, null]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('checkDate非合法YYYYMMDD時略過單日比對, 不誤標isHoliday', async function() {
+        let r = []
+        for (let checkDate of ['', null, undefined, '2026-01-01', 20260101]) {
+            let t = await fetchTwDataHoliday(checkDate, optFast)
+            r.push([t.checkDate, t.isHoliday, t.holidayName])
+        }
+        let rr = [
+            [undefined, undefined, undefined],
+            [undefined, undefined, undefined],
+            [undefined, undefined, undefined],
+            [undefined, undefined, undefined],
+            [undefined, undefined, undefined],
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('API回傳非JSON時給出友善訊息而非裸SyntaxError', async function() {
+        let r = null
+        await fetchTwDataHoliday(undefined, { ...optFast, url: svr.url('/json/bad') })
+            .then(() => {
+                r = 'resolved'
+            })
+            .catch((err) => {
+                r = [err.message, err instanceof SyntaxError]
+            })
+        let rr = ['API 回傳非 JSON 格式（可能為維護頁面或網路中介），請稍後再試', false]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('API回傳非陣列時reject', async function() {
+        let r = null
+        await fetchTwDataHoliday(undefined, { ...optFast, url: svr.url('/json/ok') })
+            .catch((err) => {
+                r = err.message
+            })
+        let rr = 'API 回傳空陣列或格式異常'
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/fetchTwseMargin.test.mjs

@@ -0,0 +1,81 @@
+import assert from 'assert'
+import fetchTwseMargin from '../src/fetchTwseMargin.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchTwseMargin', function() {
+
+    let svr = null
+    let optFast = null
+
+    before(async function() {
+        svr = await serverForTest()
+        optFast = { baseUrl: svr.url(''), baseDelayMs: 10, maxDelayMs: 10, showLog: false }
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('日期格式錯誤與日期不合法之訊息不同', async function() {
+        let r = []
+        await fetchTwseMargin('2026-08-07', [], optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        await fetchTwseMargin('20260230', [], optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        let rr = [
+            '日期參數無效：格式須為 YYYYMMDD (收到 "2026-08-07")',
+            '日期參數無效：不合法的日期 (20260230)',
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('以標題「融資融券彙總」選表, 不誤取第一張有資料表', async function() {
+        let t = await fetchTwseMargin('20260807', [], optFast)
+        let r = [t.source, t.date, t.count, t.data[0].code, t.data[0].name]
+        let rr = ['twse_margin', '20260807', 2, '2330', '台積電']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('依固定欄序解析融資融券並算出增減', async function() {
+        let t = await fetchTwseMargin('20260807', ['2330'], optFast)
+        let rr = {
+            code: '2330',
+            name: '台積電',
+            marginBuy: 1000,
+            marginSell: 500,
+            marginCashRepay: 100,
+            marginPrevBalance: 10000,
+            marginBalance: 10400,
+            marginChange: 400,
+            marginLimit: 99999,
+            shortSell: 300,
+            shortBuy: 200,
+            shortCashRepay: 50,
+            shortPrevBalance: 2000,
+            shortBalance: 2250,
+            shortChange: 250,
+            shortLimit: 88888,
+            offset: 10,
+            note: '',
+        }
+        assert.strict.deepEqual(t.data[0], rr)
+    })
+
+    it('指定個股查無資料時reject', async function() {
+        let r = null
+        await fetchTwseMargin('20260807', ['6488'], optFast)
+            .catch((err) => {
+                r = err.message
+            })
+        let rr = '指定個股 6488 不在上市融資融券資料中（可能為上櫃股或代碼有誤）'
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/fetchTwseStock.test.mjs

@@ -0,0 +1,80 @@
+import assert from 'assert'
+import fetchTwseStock from '../src/fetchTwseStock.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchTwseStock', function() {
+
+    let svr = null
+    let optFast = null
+
+    before(async function() {
+        svr = await serverForTest()
+        optFast = { baseUrl: svr.url(''), baseDelayMs: 10, maxDelayMs: 10, showLog: false }
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('日期非合法YYYYMMDD時拋錯', async function() {
+        let r = []
+        for (let dateStr of ['', null, undefined, '2026-08-07', '20260230', 20260807]) {
+            await fetchTwseStock(dateStr, '2330', optFast)
+                .then(() => {
+                    r.push('resolved')
+                })
+                .catch((err) => {
+                    r.push(err.message.startsWith('dateStr 須為合法之 YYYYMMDD 字串'))
+                })
+        }
+        let rr = [true, true, true, true, true, true]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('指定個股走STOCK_DAY並過濾為指定日單筆', async function() {
+        let t = await fetchTwseStock('20260807', '2330', optFast)
+        let r = [t.stat, t.data.length, t.data[0][0], t.data[0][6], t.fields.length]
+        let rr = ['OK', 1, '115/08/07', '1,115.00', 9]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('未指定個股或指定all時走MI_INDEX取全市場', async function() {
+        let t1 = await fetchTwseStock('20260807', undefined, optFast)
+        let t2 = await fetchTwseStock('20260807', 'all', optFast)
+        let t3 = await fetchTwseStock('20260807', 'ALL', optFast)
+        let r = [t1.tables[0].data.length, t2.tables[0].data.length, t3.tables[0].data.length]
+        let rr = [2, 2, 2]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('指定日無交易資料時reject並與整體無資料區分', async function() {
+        let r = null
+        await fetchTwseStock('20260808', '2330', optFast)
+            .then(() => {
+                r = 'resolved'
+            })
+            .catch((err) => {
+                r = err.message
+            })
+        let rr = 'TWSE 個股 2330 於 20260808 無交易資料（可能為假日或停盤）'
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('API回傳stat非OK時reject且不重試', async function() {
+        let c0 = svr.getCount('/exchangeReport/STOCK_DAY')
+        let r = null
+        await fetchTwseStock('20090101', '2330', { ...optFast, maxRetries: 3 })
+            .then(() => {
+                r = 'resolved'
+            })
+            .catch((err) => {
+                r = [err.message.startsWith('TWSE API returned:'), svr.getCount('/exchangeReport/STOCK_DAY') - c0]
+            })
+        let rr = [true, 1]
+        assert.strict.deepEqual(r, rr)
+    })
+
+})

package/test/fetchTwseT86.test.mjs

@@ -0,0 +1,76 @@
+import assert from 'assert'
+import fetchTwseT86 from '../src/fetchTwseT86.mjs'
+import serverForTest from './tools/serverForTest.mjs'
+
+
+describe('fetchTwseT86', function() {
+
+    let svr = null
+    let optFast = null
+
+    before(async function() {
+        svr = await serverForTest()
+        optFast = { baseUrl: svr.url(''), baseDelayMs: 10, maxDelayMs: 10, showLog: false }
+    })
+
+    after(async function() {
+        if (svr) {
+            await svr.close()
+        }
+    })
+
+    it('日期格式錯誤與日期不合法之訊息不同', async function() {
+        let r = []
+        await fetchTwseT86('2026-08-07', [], optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        await fetchTwseT86('20260230', [], optFast)
+            .catch((err) => {
+                r.push(err.message)
+            })
+        let rr = [
+            'dateStr must be YYYYMMDD, got: 2026-08-07',
+            'dateStr 不是合法日期: 20260230',
+        ]
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('以API回傳之fields為key轉為物件陣列並去除欄位前後空白', async function() {
+        let t = await fetchTwseT86('20260807', [], optFast)
+        let rr = {
+            source: 'twse',
+            date: '20260807',
+            data: [
+                {
+                    '證券代號': '2330',
+                    '證券名稱': '台積電',
+                    '外陸資買進股數(不含外資自營商)': '1,000,000',
+                    '三大法人買賣超股數': '500,000',
+                },
+                {
+                    '證券代號': '2317',
+                    '證券名稱': '鴻海',
+                    '外陸資買進股數(不含外資自營商)': '800,000',
+                    '三大法人買賣超股數': '-200,000',
+                },
+            ],
+        }
+        assert.strict.deepEqual(t, rr)
+    })
+
+    it('指定個股時以證券代號欄過濾', async function() {
+        let t = await fetchTwseT86('20260807', ['2317'], optFast)
+        let r = [t.data.length, t.data[0]['證券代號']]
+        let rr = [1, '2317']
+        assert.strict.deepEqual(r, rr)
+    })
+
+    it('指定個股皆不存在時回傳空陣列', async function() {
+        let t = await fetchTwseT86('20260807', ['9999'], optFast)
+        let r = t.data
+        let rr = []
+        assert.strict.deepEqual(r, rr)
+    })
+
+})