w-syslog 1.0.7 → 1.0.8

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#line55">line 55</a>
     </li></ul></dd>
     
 
@@ -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清理計時器函數</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 May 08 2026 16:56:20 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,15 @@
     
     <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 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 +69,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清理計時器函數
  * @example
  * import fs from 'fs'
  * import _ from 'lodash-es'
@@ -94,6 +101,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 +119,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 +149,7 @@ function WSyslog(opt = {}) {
                 options: {
                     interval,
                     fdLog,
+                    timeZone,
                 },
 
             },
@@ -134,7 +160,82 @@ 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
+    let clear = () => {
+        clearInterval(t)
+    }
+
+    //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 +254,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 May 08 2026 16:56:20 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 May 08 2026 16:56:20 GMT+0800 (台北標準時間) using the <a href="https://github.com/clenemt/docdash">docdash</a> theme.
 </footer>
 
 <script>prettyPrint();</script>

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "w-syslog",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "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.51"
   },
   "devDependencies": {
-    "w-package-tools": "^1.1.2"
+    "w-package-tools": "^1.1.5"
   },
   "scripts": {
     "test": "mocha --parallel --timeout 60000",

package/src/WSyslog.mjs

@@ -1,7 +1,12 @@
+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 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 +22,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清理計時器函數
  * @example
  * import fs from 'fs'
  * import _ from 'lodash-es'
@@ -47,6 +54,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 +72,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 +102,7 @@ function WSyslog(opt = {}) {
                 options: {
                     interval,
                     fdLog,
+                    timeZone,
                 },
 
             },
@@ -87,7 +113,82 @@ 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
+    let clear = () => {
+        clearInterval(t)
+    }
+
+    //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)

package/test/{WSyslog.test.mjs → basic.test.mjs}

@@ -47,4 +47,11 @@ describe('WSyslog', function() {
         assert.strict.deepEqual(r, rr)
     })
 
+    after(async function() {
+        //稍候pino worker flush, 避免Windows上EBUSY
+        await w.delay(200)
+        //完全移除測試資料夾, 不留空殼
+        w.fsDeleteFolder('./_logs')
+    })
+
 })