w-data-csv 1.0.19 → 1.0.21

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 Fri Aug 07 2026 23:52:25 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 Sat Aug 15 2026 17:02:41 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "w-data-csv",
-  "version": "1.0.19",
+  "version": "1.0.21",
   "main": "dist/w-data-csv.umd.js",
   "dependencies": {
     "csv-parser": "^3.2.1",
     "strip-bom-stream": "^5.0.0",
-    "wsemi": "^1.8.68"
+    "wsemi": "^1.8.70"
   },
   "devDependencies": {
     "w-package-tools": "^1.1.12"

package/src/WDataCsv.mjs

@@ -1,9 +1,11 @@
-import { Readable } from 'stream'
+import { Readable, Writable } from 'stream'
+import { pipeline } from 'stream/promises'
 import fs from 'fs'
 import csvParse from 'csv-parser'
 import stripBom from 'strip-bom-stream'
 import get from 'lodash-es/get.js'
 import fsIsFile from 'wsemi/src/fsIsFile.mjs'
+import haskey from 'wsemi/src/haskey.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
 import isstr from 'wsemi/src/isstr.mjs'
 import isbol from 'wsemi/src/isbol.mjs'
@@ -13,11 +15,89 @@ import genPm from 'wsemi/src/genPm.mjs'
 import ltdtkeysheads2mat from 'wsemi/src/ltdtkeysheads2mat.mjs'
 
 
+//csv-parser可透傳之選項
+//排除raw(其值回傳Buffer, 破壞ltdt與mat之字串契約)與outputByteOffset(其改變回傳形狀為{row,byteOffset})
+let ksOptCsvParse = [
+    'headers', 'skipLines', 'skipComments', 'separator', 'quote',
+    'escape', 'newline', 'strict', 'mapHeaders', 'mapValues', 'maxRowBytes',
+]
+
+
+//genOptCsvParse, 自opt取出csv-parser可用選項, 未給者不傳入以維持csv-parser之預設
+let genOptCsvParse = (opt) => {
+
+    //mode
+    let mode = get(opt, 'mode')
+    if (mode !== 'ltdt' && mode !== 'mat') {
+        mode = 'ltdt'
+    }
+
+    //透傳
+    let o = {}
+    for (let k of ksOptCsvParse) {
+        if (haskey(opt, k)) {
+            o[k] = opt[k]
+        }
+    }
+
+    //headers給true會使csv-parser之headers成為布林值, 各列鍵將全為_0,_1...之溢出鍵而成壞資料, 故一律視為未給
+    if (o.headers === true) {
+        delete o.headers
+    }
+
+    //mat模式固定關閉標頭, 否則第1列會被取為標頭
+    //且可避免headers給陣列時, 超出標頭數之欄位另生_N溢出鍵
+    if (mode === 'mat') {
+        o.headers = false
+    }
+
+    return { mode, optCsvParse: o }
+}
+
+
+//getRows, 以pipeline串接各段stream, 使來源與中段stream之錯誤皆能被捕獲
+let getRows = async (rs, opt) => {
+
+    let { mode, optCsvParse } = genOptCsvParse(opt)
+
+    let res = []
+
+    let ws = new Writable({
+        objectMode: true,
+        write(row, enc, cb) {
+
+            //mat模式時headers必為false, csv-parser依各列實際欄數自生0,1,2...之整數字串鍵,
+            //物件之整數字串鍵本就依數值升序排列, 故直接取值即為正確順序
+            res.push(mode === 'mat' ? Object.values(row) : row)
+
+            cb()
+        },
+    })
+
+    await pipeline(rs, stripBom(), csvParse(optCsvParse), ws)
+
+    return res
+}
+
+
 /**
  * 解析CSV字串
  *
- * @param {String} c 輸入CSV字串
- * @return {Promise} 回傳Promise，resolve回傳ltdt(各數據列為物件陣列)，reject回傳錯誤訊息
+ * @param {String} inp 輸入CSV字串
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.mode='ltdt'] 輸入回傳數據格式字串，可選ltdt(各數據列為物件)或mat(各數據列為陣列)，預設ltdt
+ * @param {Boolean|Array} [opt.headers] 輸入標頭設定，給false代表無標頭列，給陣列代表無標頭列且以此陣列為欄名，不給則取第1列為標頭。因csv-parser於給true時會使各列成為_0,_1等溢出鍵之壞數據，故給true時視為不給。另mode為mat時本設定固定為false
+ * @param {Number} [opt.skipLines] 輸入解析前跳過列數整數。因csv-parser之註解列不計入行號，故與skipComments併用時計數基準會位移，兩者不建議同時使用
+ * @param {Boolean|String} [opt.skipComments] 輸入忽略註解列設定，給true代表跳過#開頭之列，給字串代表以該字元為註解符
+ * @param {String} [opt.separator] 輸入欄位分隔字元，因csv-parser僅取首個byte，故須為單字元
+ * @param {String} [opt.quote] 輸入引號字元，因csv-parser僅取首個byte，故須為單字元
+ * @param {String} [opt.escape] 輸入逃逸字元，因csv-parser僅取首個byte，故須為單字元
+ * @param {String} [opt.newline] 輸入行尾字元，因csv-parser僅取首個byte，故須為單字元
+ * @param {Boolean} [opt.strict] 輸入各列欄數是否須與標頭數相符布林值。因csv-parser於headers為false時會強制關閉本設定，故mode為mat時本設定無效
+ * @param {Function} [opt.mapHeaders] 輸入標頭轉換函式。因csv-parser僅於解析標頭列時呼叫，故mode為mat時不會被呼叫。另回傳null時該欄將被整欄丟棄
+ * @param {Function} [opt.mapValues] 輸入欄值轉換函式。mode為mat時其header參數恆為undefined
+ * @param {Number} [opt.maxRowBytes] 輸入單列位元組數上限整數
+ * @return {Promise} 回傳Promise，resolve回傳ltdt(各數據列為物件陣列)或mat(二維陣列)，reject回傳錯誤訊息
  * @example
  *
  * import wdc from './src/WDataCsv.mjs'
@@ -35,32 +115,28 @@ import ltdtkeysheads2mat from 'wsemi/src/ltdtkeysheads2mat.mjs'
  *         console.log(err)
  *     })
  *
+ * await wdc.parseCsv(c, { mode: 'mat' })
+ *     .then((mat) => {
+ *         console.log(mat)
+ *         // => [ [ 'NAME', 'AGE' ], [ 'Daffy Duck', '24' ], [ 'Bugs 邦妮', '22' ] ]
+ *     })
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
  */
-async function parseCsv(inp) {
-    let res = []
-
-    let pm = genPm()
+async function parseCsv(inp, opt = {}) {
 
     //check
     if (!isestr(inp)) {
         return Promise.reject(`inp is not an effective string`)
     }
 
-    Readable.from([inp])
-        .pipe(csvParse())
-        .on('data', (chunk) => {
-            // console.log('data', chunk)
-            res.push(chunk)
-        })
-        .on('end', () => {
-            pm.resolve(res)
-        })
-        .on('error', (err) => {
+    return getRows(Readable.from([inp]), opt)
+        .catch((err) => {
             console.log(err)
-            pm.reject(err)
+            return Promise.reject(err)
         })
-
-    return pm
 }
 
 
@@ -68,7 +144,20 @@ async function parseCsv(inp) {
  * 讀取CSV檔，自動清除BOM
  *
  * @param {String} fp 輸入檔案位置字串
- * @return {Promise} 回傳Promise，resolve回傳ltdt(各數據列為物件陣列)，reject回傳錯誤訊息
+ * @param {Object} [opt={}] 輸入設定物件，預設{}
+ * @param {String} [opt.mode='ltdt'] 輸入回傳數據格式字串，可選ltdt(各數據列為物件)或mat(各數據列為陣列)，預設ltdt
+ * @param {Boolean|Array} [opt.headers] 輸入標頭設定，給false代表無標頭列，給陣列代表無標頭列且以此陣列為欄名，不給則取第1列為標頭。因csv-parser於給true時會使各列成為_0,_1等溢出鍵之壞數據，故給true時視為不給。另mode為mat時本設定固定為false
+ * @param {Number} [opt.skipLines] 輸入解析前跳過列數整數。因csv-parser之註解列不計入行號，故與skipComments併用時計數基準會位移，兩者不建議同時使用
+ * @param {Boolean|String} [opt.skipComments] 輸入忽略註解列設定，給true代表跳過#開頭之列，給字串代表以該字元為註解符
+ * @param {String} [opt.separator] 輸入欄位分隔字元，因csv-parser僅取首個byte，故須為單字元
+ * @param {String} [opt.quote] 輸入引號字元，因csv-parser僅取首個byte，故須為單字元
+ * @param {String} [opt.escape] 輸入逃逸字元，因csv-parser僅取首個byte，故須為單字元
+ * @param {String} [opt.newline] 輸入行尾字元，因csv-parser僅取首個byte，故須為單字元
+ * @param {Boolean} [opt.strict] 輸入各列欄數是否須與標頭數相符布林值。因csv-parser於headers為false時會強制關閉本設定，故mode為mat時本設定無效
+ * @param {Function} [opt.mapHeaders] 輸入標頭轉換函式。因csv-parser僅於解析標頭列時呼叫，故mode為mat時不會被呼叫。另回傳null時該欄將被整欄丟棄
+ * @param {Function} [opt.mapValues] 輸入欄值轉換函式。mode為mat時其header參數恆為undefined
+ * @param {Number} [opt.maxRowBytes] 輸入單列位元組數上限整數
+ * @return {Promise} 回傳Promise，resolve回傳ltdt(各數據列為物件陣列)或mat(二維陣列)，reject回傳錯誤訊息
  * @example
  *
  * import wdc from './src/WDataCsv.mjs'
@@ -84,33 +173,28 @@ async function parseCsv(inp) {
  *         console.log(err)
  *     })
  *
+ * wdc.readCsv(fp, { mode: 'mat' })
+ *     .then((mat) => {
+ *         console.log(mat)
+ *         // => [ [ 'NAME', 'AGE' ], [ 'Daffy Duck', '24' ], [ 'Bugs 邦妮', '22' ] ]
+ *     })
+ *     .catch((err) => {
+ *         console.log(err)
+ *     })
+ *
  */
-async function readCsv(fp) {
-    let res = []
-
-    let pm = genPm()
+async function readCsv(fp, opt = {}) {
 
     //check
     if (!fsIsFile(fp)) {
         return Promise.reject(`fp[${fp}] is not exist`)
     }
 
-    fs.createReadStream(fp)
-        .pipe(stripBom())
-        .pipe(csvParse())
-        .on('data', (chunk) => {
-            // console.log('data', chunk)
-            res.push(chunk)
-        })
-        .on('end', () => {
-            pm.resolve(res)
-        })
-        .on('error', (err) => {
+    return getRows(fs.createReadStream(fp), opt)
+        .catch((err) => {
             console.log(err)
-            pm.reject(err)
+            return Promise.reject(err)
         })
-
-    return pm
 }
 
 

package/test/readOpt.test.mjs

@@ -0,0 +1,143 @@
+import fs from 'fs'
+import assert from 'assert'
+import wdc from '../src/WDataCsv.mjs'
+
+
+//監測站原始CSV之結構: 前12列為儀器metadata, 第13列為#標記, 第14列為欄位名稱, 第15列起為量測數據
+//另含短列, 空白列與長列, 用於驗證mat模式反映各列實際欄數
+let csvSite = [
+    '1,v22.08.22,,,,,',
+    '2025ST1,,,,,,',
+    '1000,1000,,,,,',
+    'Chiayi,,,,,,',
+    '1,,,,,,',
+    '1,,,,,,',
+    '1,,,,,,',
+    '0.408,0,Piezo1,kg/cm2,,,',
+    '0.408,0,Piezo2,kg/cm2,,,',
+    '0.408,0,EXT,kg/cm2,,,',
+    '0.408,0,5V,kg/cm2,,,',
+    'x,,,,,,',
+    '#,,,,,,',
+    'X(gal),Y(gal),Z(gal),Piezo1,Piezo2,EXT,5V',
+    '0.214,0.143,-0.158,1.187,2.642,2.356,4.928',
+    '0.1,0.2,0.3',
+    '',
+    '"a,b",c,d,e,f,g,h,i',
+].join('\r\n')
+
+
+describe('readOpt', function() {
+
+    it('test opt undefined, 回歸至無opt之行為', async function() {
+        let rout = [{ NAME: 'Daffy Duck', AGE: '24' }, { NAME: 'Bugs 邦妮', AGE: '22' }]
+
+        let rRead = await wdc.readCsv('./g-test-in.csv')
+        assert.strict.deepEqual(rRead, rout)
+
+        let c = fs.readFileSync('./g-test-in.csv', 'utf8')
+        let rParse = await wdc.parseCsv(c)
+        assert.strict.deepEqual(rParse, rout)
+    })
+
+    it('test mode mat with skipLines, 跳過儀器metadata後自欄位名稱列起回傳二維陣列', async function() {
+        let fp = './g-test-site.csv'
+        fs.writeFileSync(fp, csvSite, 'utf8')
+
+        let mat = await wdc.readCsv(fp, { mode: 'mat', skipLines: 13 })
+
+        //第1列為欄位名稱
+        assert.strict.deepEqual(mat[0], ['X(gal)', 'Y(gal)', 'Z(gal)', 'Piezo1', 'Piezo2', 'EXT', '5V'])
+
+        //第2列為7欄量測數據
+        assert.strict.deepEqual(mat[1], ['0.214', '0.143', '-0.158', '1.187', '2.642', '2.356', '4.928'])
+
+        //短列保留其實際欄數, 不補空
+        assert.strict.deepEqual(mat[2], ['0.1', '0.2', '0.3'])
+
+        //空白列為空陣列
+        assert.strict.deepEqual(mat[3], [])
+
+        //長列保留其實際欄數不截斷, 且引號內之逗號不被視為分隔字元
+        assert.strict.deepEqual(mat[4], ['a,b', 'c', 'd', 'e', 'f', 'g', 'h', 'i'])
+
+        //各列皆為陣列, 無_N溢出鍵
+        assert.strict.deepEqual(mat.length, 5)
+        assert.strict.deepEqual(mat.every((v) => Array.isArray(v)), true)
+
+        fs.unlinkSync(fp)
+    })
+
+    it('test headers true, 視為未給而非產生_N溢出鍵之壞數據', async function() {
+        let r = await wdc.parseCsv('a,b\n1,2', { headers: true })
+        assert.strict.deepEqual(r, [{ a: '1', b: '2' }])
+    })
+
+    it('test mode mat with headers, headers固定為false故給陣列時不生_N溢出鍵', async function() {
+        let r = await wdc.parseCsv('1,2,3,4,5', { mode: 'mat', headers: ['h0', 'h1', 'h2'] })
+        assert.strict.deepEqual(r, [['1', '2', '3', '4', '5']])
+    })
+
+    it('test mode ltdt with headers, 給陣列代表無標頭列故第1列為數據', async function() {
+        let r = await wdc.parseCsv('a,b\n1,2', { headers: ['h0', 'h1'] })
+        assert.strict.deepEqual(r, [{ h0: 'a', h1: 'b' }, { h0: '1', h1: '2' }])
+    })
+
+    it('test raw and outputByteOffset, 不透傳以維持字串契約與回傳形狀', async function() {
+        let rRaw = await wdc.parseCsv('a,b\n1,2', { mode: 'mat', raw: true })
+        assert.strict.deepEqual(typeof rRaw[0][0], 'string')
+
+        let rOff = await wdc.parseCsv('a,b\n1,2', { mode: 'mat', outputByteOffset: true })
+        assert.strict.deepEqual(rOff[0], ['a', 'b'])
+    })
+
+    it('test skipComments with skipLines, 註解列不計入行號故兩者併用時計數基準位移', async function() {
+        let c = 'm1,m2\nm3,m4\nm5,m6\n#,x\nA,B\n1,2'
+
+        let r1 = await wdc.parseCsv(c, { mode: 'mat', skipLines: 4 })
+        assert.strict.deepEqual(r1, [['A', 'B'], ['1', '2']])
+
+        let r2 = await wdc.parseCsv(c, { mode: 'mat', skipLines: 4, skipComments: true })
+        assert.strict.deepEqual(r2, [['1', '2']])
+    })
+
+    it('test bom, parseCsv與readCsv對含BOM內容之結果一致', async function() {
+        let c = 'NAME,AGE\r\nDaffy Duck,24\r\n'
+        let fp = './g-test-bom.csv'
+        fs.writeFileSync(fp, c, 'utf8')
+
+        let rParse = await wdc.parseCsv(c)
+        let rRead = await wdc.readCsv(fp)
+
+        assert.strict.deepEqual(rParse, rRead)
+        assert.strict.deepEqual(rParse, [{ NAME: 'Daffy Duck', AGE: '24' }])
+
+        fs.unlinkSync(fp)
+    })
+
+    it('test error, stream錯誤轉為reject且不拋出未捕獲例外', async function() {
+        let err = null
+        await wdc.readCsv('./g-test-in.csv', { maxRowBytes: 1 })
+            .catch((e) => {
+                err = e
+            })
+        assert.strict.deepEqual(err !== null, true)
+    })
+
+    it('test reject payload, 檢核失敗時仍reject字串', async function() {
+        let e1 = null
+        await wdc.parseCsv('')
+            .catch((e) => {
+                e1 = e
+            })
+        assert.strict.deepEqual(e1, 'inp is not an effective string')
+
+        let e2 = null
+        await wdc.readCsv('./no-such-file.csv')
+            .catch((e) => {
+                e2 = e
+            })
+        assert.strict.deepEqual(e2, 'fp[./no-such-file.csv] is not exist')
+    })
+
+})