w-syslog 1.0.7 → 1.0.9

package/docs/WSyslog.html

@@ -80,7 +80,7 @@
     
     <dt class="tag-source">Source:</dt>
     <dd class="tag-source"><ul class="dummy"><li>
-        <a href="WSyslog.mjs.html">WSyslog.mjs</a>, <a href="WSyslog.mjs.html#line48">line 48</a>
+        <a href="WSyslog.mjs.html">WSyslog.mjs</a>, <a href="WSyslog.mjs.html#line56">line 56</a>
     </li></ul></dd>
     
 
@@ -127,7 +127,7 @@
 
     <h5 class="h5-examples">Example</h5>
     
-    <pre class="prettyprint"><code>import fs from 'fs'
+    <pre class="prettyprint"><code>import fs from 'fs'
 
 
 
@@ -301,6 +301,84 @@
         </tr>
 
     
+
+        <tr>
+            
+                <td class="name"><code>timeZone</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">String</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                    <code>null</code>
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入時區字串（IANA格式如'Asia/Taipei'、'UTC'），用於決定切檔邊界與檔名，預設null代表使用系統時區</p></td>
+        </tr>
+
+    
+
+        <tr>
+            
+                <td class="name"><code>numKeep</code></td>
+            
+
+            <td class="type">
+            
+                
+<span class="param-type">Number</span>
+
+
+
+            
+            </td>
+
+            
+                <td class="attributes">
+                
+                    &lt;optional><br>
+                
+
+                
+
+                
+                </td>
+            
+
+            
+                <td class="default">
+                
+                </td>
+            
+
+            <td class="description last"><p>輸入保留log檔案數量整數，超出最舊檔將被自動刪除，預設於day模式為365、hr模式為365*24（約等同保留一年）</p></td>
+        </tr>
+
+    
     </tbody>
 </table>
 
@@ -330,7 +408,7 @@
 
         
 <div class="param-desc">
-    <p>回傳log物件，提供info、warn、error紀錄函數</p>
+    <p>回傳log物件，提供fatal、error、warn、info、debug、trace紀錄函數，cleanLogs手動清理函數，及clear顯式關閉函數（回傳Promise，將殘餘log全部寫出後終止transport worker並停止清理計時器，附逾時保險預設60000ms可由opt.timeLimit調整，冪等；clear之後不可再呼叫任何log方法）</p>
 </div>
 
 
@@ -389,7 +467,7 @@
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a> on Mon Aug 25 2025 14:33:18 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 Fri Jul 17 2026 23:54:28 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/docs/WSyslog.mjs.html

@@ -45,10 +45,16 @@
     
     <section>
         <article>
-            <pre class="prettyprint source linenums"><code>import path from 'path'
+            <pre class="prettyprint source linenums"><code>import fs from 'fs'
+import path from 'path'
 import { fileURLToPath } from 'url'
 import get from 'lodash-es/get.js'
+import evem from 'wsemi/src/evem.mjs'
+import genPm from 'wsemi/src/genPm.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import fsIsFolder from 'wsemi/src/fsIsFolder.mjs'
 import pino from 'pino'
 
 
@@ -64,7 +70,9 @@ let __dirname = path.dirname(__filename)
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {String} [opt.fdLog='./_logs'] 輸入儲存log資料夾字串，預設'./_logs'
  * @param {String} [opt.interval='day'] 輸入儲存log時分檔模式字串，可選'day'、'hr'，分別代表每日或每時分檔，預設'day'
- * @returns {Object} 回傳log物件，提供info、warn、error紀錄函數
+ * @param {String} [opt.timeZone=null] 輸入時區字串（IANA格式如'Asia/Taipei'、'UTC'），用於決定切檔邊界與檔名，預設null代表使用系統時區
+ * @param {Number} [opt.numKeep] 輸入保留log檔案數量整數，超出最舊檔將被自動刪除，預設於day模式為365、hr模式為365*24（約等同保留一年）
+ * @returns {Object} 回傳log物件，提供fatal、error、warn、info、debug、trace紀錄函數，cleanLogs手動清理函數，及clear顯式關閉函數（回傳Promise，將殘餘log全部寫出後終止transport worker並停止清理計時器，附逾時保險預設60000ms可由opt.timeLimit調整，冪等；clear之後不可再呼叫任何log方法）
  * @example
  * import fs from 'fs'
  * import _ from 'lodash-es'
@@ -78,7 +86,7 @@ let __dirname = path.dirname(__filename)
  * log.warn({ event: 'monitor-memory', msg: 'usage-high', ratio: 85.4 })
  * log.error({ event: 'crash', msg: 'db connection', code: 500 })
  *
- * await w.delay(2000) //等待2秒讓pino能flush數據
+ * await log.clear() //顯式關閉, flush殘餘log並終止transport worker, 之後不可再呼叫log方法
  *
  * let vpfs = w.fsTreeFolder('./_logs')
  * // console.log('vpfs', vpfs)
@@ -94,6 +102,12 @@ let __dirname = path.dirname(__filename)
  */
 function WSyslog(opt = {}) {
 
+    //ev
+    let ev = evem()
+
+    //timeZone, 'Asia/Taipei'
+    let timeZone = get(opt, 'timeZone', null)
+
     //fdLog
     let fdLog = get(opt, 'fdLog')
     if (!isestr(fdLog)) {
@@ -106,6 +120,18 @@ function WSyslog(opt = {}) {
         interval = 'day'
     }
 
+    //numKeep
+    let numKeep = get(opt, 'numKeep')
+    if (!ispint(numKeep)) {
+        if (interval === 'day') {
+            numKeep = 365
+        }
+        else {
+            numKeep = 365 * 24
+        }
+    }
+    numKeep = cint(numKeep)
+
     // 建立 logger，使用自訂 transport
     let transport = pino.transport({
         targets: [
@@ -124,6 +150,7 @@ function WSyslog(opt = {}) {
                 options: {
                     interval,
                     fdLog,
+                    timeZone,
                 },
 
             },
@@ -134,7 +161,127 @@ function WSyslog(opt = {}) {
     let log = pino(transport)
     // console.log('log', log)
 
-    return log
+    //cleanLogs, 依numKeep保留最新N個檔, 超出的最舊檔刪除
+    let cleanLogs = () => {
+        try {
+            if (!fsIsFolder(fdLog)) {
+                return
+            }
+            //pattern, day模式為'YYYY-MM-DD.log', hr模式為'YYYY-MM-DDTHH.log'
+            let pattern = (interval === 'hr')
+                ? /^\d{4}-\d{2}-\d{2}T\d{2}\.log$/
+                : /^\d{4}-\d{2}-\d{2}\.log$/
+            let files = fs.readdirSync(fdLog).filter((fn) => pattern.test(fn))
+            //ISO日期格式字典序等同時間序, 排序後最舊在前
+            files.sort()
+            let nDel = files.length - numKeep
+            if (nDel &lt;= 0) {
+                return
+            }
+            let toDelete = files.slice(0, nDel)
+            for (let fn of toDelete) {
+                let fp = path.join(fdLog, fn)
+                try {
+                    fs.unlinkSync(fp)
+                    ev.emit('delete', { fp, fn })
+                }
+                catch (err) {
+                    //容忍其他process同時刪除或檔案被佔用之情況
+                }
+            }
+        }
+        catch (err) {
+            console.error('WSyslog cleanLogs error:', err)
+        }
+    }
+
+    //啟動時立刻清理一次, 確保短命腳本也能執行清理
+    cleanLogs()
+
+    //之後每小時清理一次, 足以跟上day/hr切檔節奏
+    let t = setInterval(cleanLogs, 60 * 60 * 1000)
+    //unref不阻塞process結束
+    t.unref()
+
+    //clear, 顯式關閉: flush殘餘log -> 終止transport worker -> 停止cleanLogs計時器, 附逾時保險保證必定resolve
+    //clear之後不可再呼叫任何log方法(pino會非同步丟the worker has exited)
+    let pm = null
+    let clear = (optClear = {}) => {
+        if (pm !== null) {
+            return pm //冪等
+        }
+        let timeLimit = get(optClear, 'timeLimit')
+        if (!ispint(timeLimit)) {
+            timeLimit = 60 * 1000
+        }
+        pm = genPm()
+        let done = false
+        let fin = () => {
+            if (!done) {
+                done = true
+                clearInterval(t) //併停cleanLogs計時器
+                pm.resolve()
+            }
+        }
+        let tt = setTimeout(() => {
+            try {
+                transport.worker.terminate() //保險: 逾時直接終結worker
+            }
+            catch (err) {}
+            fin()
+        }, timeLimit)
+        try {
+            log.flush((err) => {
+                //worker已亡或transport已關閉時'close'事件可能已發過, 直接收尾避免空等逾時
+                if (err || transport.closed) {
+                    clearTimeout(tt)
+                    fin()
+                    return
+                }
+                //'close'事件於worker真正退出(MessagePort釋放)後才發出, 等'finish'不足以保證
+                transport.once('close', () => {
+                    clearTimeout(tt)
+                    fin()
+                })
+                transport.end()
+            })
+        }
+        catch (err) {
+            clearTimeout(tt)
+            fin()
+        }
+        return pm
+    }
+
+    //wrap, 包裝pino各等級method, 於寫log前先觸發'log'事件, 使外部可監聽進行console輸出或轉送其他記錄器
+    // fatal: 60
+    // error: 50
+    // warn: 40
+    // info: 30
+    // debug: 20
+    // trace: 10
+    let wrap = (level) => {
+        let fn = log[level].bind(log)
+        return (...args) => {
+            try {
+                ev.emit(level, { args })
+            }
+            catch (err) {
+                //容忍listener內部錯誤, 避免影響pino寫log
+            }
+            fn(...args)
+        }
+    }
+    ev.fatal = wrap('fatal')
+    ev.error = wrap('error')
+    ev.warn = wrap('warn')
+    ev.info = wrap('info')
+    ev.debug = wrap('debug')
+    ev.trace = wrap('trace')
+    ev.cleanLogs = cleanLogs
+    ev.clear = clear
+
+    return ev
 }
 
 
@@ -153,7 +300,7 @@ export default WSyslog
 <br class="clear">
 
 <footer>
-    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 4.0.4</a> on Mon Aug 25 2025 14:33:18 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 Fri Jul 17 2026 23:54:28 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.4</a> on Mon Aug 25 2025 14:33:18 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 Fri Jul 17 2026 23:54:28 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/g.mjs

@@ -15,7 +15,7 @@ log.info({ event: 'runner', msg: 'start' })
 log.warn({ event: 'monitor-memory', msg: 'usage-high', ratio: 85.4 })
 log.error({ event: 'crash', msg: 'db connection', code: 500 })
 
-await w.delay(2000) //等待2秒讓pino能flush數據
+await log.clear() //顯式關閉, flush殘餘log並終止transport worker, 之後不可再呼叫log方法
 
 let vpfs = w.fsTreeFolder(fdLog)
 // console.log('vpfs', vpfs)

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "w-syslog",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "main": "dist/w-syslog.umd.js",
   "dependencies": {
-    "lodash-es": "^4.17.21",
-    "pino": "^9.9.0",
-    "wsemi": "^1.8.19"
+    "lodash-es": "^4.18.1",
+    "pino": "^10.3.1",
+    "wsemi": "^1.8.65"
   },
   "devDependencies": {
-    "w-package-tools": "^1.1.2"
+    "w-package-tools": "^1.1.10"
   },
   "scripts": {
     "test": "mocha --parallel --timeout 60000",

package/src/WSyslog.mjs

@@ -1,7 +1,13 @@
+import fs from 'fs'
 import path from 'path'
 import { fileURLToPath } from 'url'
 import get from 'lodash-es/get.js'
+import evem from 'wsemi/src/evem.mjs'
+import genPm from 'wsemi/src/genPm.mjs'
 import isestr from 'wsemi/src/isestr.mjs'
+import ispint from 'wsemi/src/ispint.mjs'
+import cint from 'wsemi/src/cint.mjs'
+import fsIsFolder from 'wsemi/src/fsIsFolder.mjs'
 import pino from 'pino'
 
 
@@ -17,7 +23,9 @@ let __dirname = path.dirname(__filename)
  * @param {Object} [opt={}] 輸入設定物件，預設{}
  * @param {String} [opt.fdLog='./_logs'] 輸入儲存log資料夾字串，預設'./_logs'
  * @param {String} [opt.interval='day'] 輸入儲存log時分檔模式字串，可選'day'、'hr'，分別代表每日或每時分檔，預設'day'
- * @returns {Object} 回傳log物件，提供info、warn、error紀錄函數
+ * @param {String} [opt.timeZone=null] 輸入時區字串（IANA格式如'Asia/Taipei'、'UTC'），用於決定切檔邊界與檔名，預設null代表使用系統時區
+ * @param {Number} [opt.numKeep] 輸入保留log檔案數量整數，超出最舊檔將被自動刪除，預設於day模式為365、hr模式為365*24（約等同保留一年）
+ * @returns {Object} 回傳log物件，提供fatal、error、warn、info、debug、trace紀錄函數，cleanLogs手動清理函數，及clear顯式關閉函數（回傳Promise，將殘餘log全部寫出後終止transport worker並停止清理計時器，附逾時保險預設60000ms可由opt.timeLimit調整，冪等；clear之後不可再呼叫任何log方法）
  * @example
  * import fs from 'fs'
  * import _ from 'lodash-es'
@@ -31,7 +39,7 @@ let __dirname = path.dirname(__filename)
  * log.warn({ event: 'monitor-memory', msg: 'usage-high', ratio: 85.4 })
  * log.error({ event: 'crash', msg: 'db connection', code: 500 })
  *
- * await w.delay(2000) //等待2秒讓pino能flush數據
+ * await log.clear() //顯式關閉, flush殘餘log並終止transport worker, 之後不可再呼叫log方法
  *
  * let vpfs = w.fsTreeFolder('./_logs')
  * // console.log('vpfs', vpfs)
@@ -47,6 +55,12 @@ let __dirname = path.dirname(__filename)
  */
 function WSyslog(opt = {}) {
 
+    //ev
+    let ev = evem()
+
+    //timeZone, 'Asia/Taipei'
+    let timeZone = get(opt, 'timeZone', null)
+
     //fdLog
     let fdLog = get(opt, 'fdLog')
     if (!isestr(fdLog)) {
@@ -59,6 +73,18 @@ function WSyslog(opt = {}) {
         interval = 'day'
     }
 
+    //numKeep
+    let numKeep = get(opt, 'numKeep')
+    if (!ispint(numKeep)) {
+        if (interval === 'day') {
+            numKeep = 365
+        }
+        else {
+            numKeep = 365 * 24
+        }
+    }
+    numKeep = cint(numKeep)
+
     // 建立 logger，使用自訂 transport
     let transport = pino.transport({
         targets: [
@@ -77,6 +103,7 @@ function WSyslog(opt = {}) {
                 options: {
                     interval,
                     fdLog,
+                    timeZone,
                 },
 
             },
@@ -87,7 +114,127 @@ function WSyslog(opt = {}) {
     let log = pino(transport)
     // console.log('log', log)
 
-    return log
+    //cleanLogs, 依numKeep保留最新N個檔, 超出的最舊檔刪除
+    let cleanLogs = () => {
+        try {
+            if (!fsIsFolder(fdLog)) {
+                return
+            }
+            //pattern, day模式為'YYYY-MM-DD.log', hr模式為'YYYY-MM-DDTHH.log'
+            let pattern = (interval === 'hr')
+                ? /^\d{4}-\d{2}-\d{2}T\d{2}\.log$/
+                : /^\d{4}-\d{2}-\d{2}\.log$/
+            let files = fs.readdirSync(fdLog).filter((fn) => pattern.test(fn))
+            //ISO日期格式字典序等同時間序, 排序後最舊在前
+            files.sort()
+            let nDel = files.length - numKeep
+            if (nDel <= 0) {
+                return
+            }
+            let toDelete = files.slice(0, nDel)
+            for (let fn of toDelete) {
+                let fp = path.join(fdLog, fn)
+                try {
+                    fs.unlinkSync(fp)
+                    ev.emit('delete', { fp, fn })
+                }
+                catch (err) {
+                    //容忍其他process同時刪除或檔案被佔用之情況
+                }
+            }
+        }
+        catch (err) {
+            console.error('WSyslog cleanLogs error:', err)
+        }
+    }
+
+    //啟動時立刻清理一次, 確保短命腳本也能執行清理
+    cleanLogs()
+
+    //之後每小時清理一次, 足以跟上day/hr切檔節奏
+    let t = setInterval(cleanLogs, 60 * 60 * 1000)
+    //unref不阻塞process結束
+    t.unref()
+
+    //clear, 顯式關閉: flush殘餘log -> 終止transport worker -> 停止cleanLogs計時器, 附逾時保險保證必定resolve
+    //clear之後不可再呼叫任何log方法(pino會非同步丟the worker has exited)
+    let pm = null
+    let clear = (optClear = {}) => {
+        if (pm !== null) {
+            return pm //冪等
+        }
+        let timeLimit = get(optClear, 'timeLimit')
+        if (!ispint(timeLimit)) {
+            timeLimit = 60 * 1000
+        }
+        pm = genPm()
+        let done = false
+        let fin = () => {
+            if (!done) {
+                done = true
+                clearInterval(t) //併停cleanLogs計時器
+                pm.resolve()
+            }
+        }
+        let tt = setTimeout(() => {
+            try {
+                transport.worker.terminate() //保險: 逾時直接終結worker
+            }
+            catch (err) {}
+            fin()
+        }, timeLimit)
+        try {
+            log.flush((err) => {
+                //worker已亡或transport已關閉時'close'事件可能已發過, 直接收尾避免空等逾時
+                if (err || transport.closed) {
+                    clearTimeout(tt)
+                    fin()
+                    return
+                }
+                //'close'事件於worker真正退出(MessagePort釋放)後才發出, 等'finish'不足以保證
+                transport.once('close', () => {
+                    clearTimeout(tt)
+                    fin()
+                })
+                transport.end()
+            })
+        }
+        catch (err) {
+            clearTimeout(tt)
+            fin()
+        }
+        return pm
+    }
+
+    //wrap, 包裝pino各等級method, 於寫log前先觸發'log'事件, 使外部可監聽進行console輸出或轉送其他記錄器
+    // fatal: 60
+    // error: 50
+    // warn: 40
+    // info: 30
+    // debug: 20
+    // trace: 10
+    let wrap = (level) => {
+        let fn = log[level].bind(log)
+        return (...args) => {
+            try {
+                ev.emit(level, { args })
+            }
+            catch (err) {
+                //容忍listener內部錯誤, 避免影響pino寫log
+            }
+            fn(...args)
+        }
+    }
+    ev.fatal = wrap('fatal')
+    ev.error = wrap('error')
+    ev.warn = wrap('warn')
+    ev.info = wrap('info')
+    ev.debug = wrap('debug')
+    ev.trace = wrap('trace')
+    ev.cleanLogs = cleanLogs
+    ev.clear = clear
+
+    return ev
 }
 
 

package/src/formatter.mjs

@@ -2,9 +2,16 @@ import fs from 'fs'
 import path from 'path'
 import { Writable } from 'stream'
 import ot from 'dayjs'
+import utc from 'dayjs/plugin/utc.js'
+import timezone from 'dayjs/plugin/timezone.js'
 import get from 'lodash-es/get.js'
 import isestr from 'wsemi/src/isestr.mjs'
 import strleft from 'wsemi/src/strleft.mjs'
+import fsCreateFolder from 'wsemi/src/fsCreateFolder.mjs'
+
+
+ot.extend(utc)
+ot.extend(timezone)
 
 
 async function formatter(opt) {
@@ -22,17 +29,19 @@ async function formatter(opt) {
         interval = 'day'
     }
 
-    // 建立 logs 資料夾
-    if (!fs.existsSync(fdLog)) {
-        fs.mkdirSync(fdLog, { recursive: true })
-    }
+    //timeZone, IANA時區字串如'Asia/Taipei', 為null時使用系統時區
+    let timeZone = get(opt, 'timeZone', null)
+
+    //建立logs資料夾, 已存在則視為成功, 不存在則自動建立
+    fsCreateFolder(fdLog)
 
     let streamCurr = null
     let keyCurr = ''
 
     let getTimeKey = () => {
-        // let d = new Date()
-        let t = ot().format('YYYY-MM-DDTHH:mm:ss.SSSZ')
+        //依timeZone決定時區基準, 確保跨機器切檔邊界與檔名一致
+        let d = isestr(timeZone) ? ot().tz(timeZone) : ot()
+        let t = d.format('YYYY-MM-DDTHH:mm:ss.SSSZ')
         if (interval === 'hr') {
             // return d.toISOString().slice(0, 13).replace(/:/g, '-') //例如2025-07-06T14
             t = strleft(t, 13)
@@ -78,6 +87,15 @@ async function formatter(opt) {
             catch (err) {
                 callback(err)
             }
+        },
+        final(callback) {
+            //顯式關閉時將當前fs write stream flush並關閉, 確保worker退出前資料落盤且fd釋放
+            if (streamCurr) {
+                streamCurr.end(callback)
+            }
+            else {
+                callback()
+            }
         }
     })