@onezlinks/session-logger 1.0.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@onezlinks/session-logger",
+  "version": "1.0.0",
+  "description": "Session-based file logger with AsyncLocalStorage context propagation for Node.js microservices",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./src/index.js",
+      "types": "./types/index.d.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "types/",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "test:ci": "jest --coverage --ci --forceExit",
+    "lint": "eslint src/ __tests__/",
+    "lint:fix": "eslint src/ __tests__/ --fix",
+    "prepublishOnly": "npm run lint && npm test"
+  },
+  "keywords": [
+    "logger",
+    "session",
+    "async-local-storage",
+    "file-logger",
+    "structured-logging",
+    "microservices",
+    "correlation-id",
+    "dual-output",
+    "log-rotation"
+  ],
+  "author": "Onez <onezlinks>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/onezlinks/session-logger.git"
+  }
+}

package/src/cleanup.js

@@ -0,0 +1,82 @@
+/**
+ * Log Cleanup & Rotation
+ * Removes old log files beyond retention period
+ *
+ * @module @onezlinks/session-logger/cleanup
+ */
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { CONFIG } = require('./constants')
+
+/**
+ * Clean up old log files beyond retention period
+ * @param {string} [category] - Specific category to clean (if omitted, clean all)
+ * @param {number} [daysToKeep] - Days to retain logs (default from CONFIG)
+ * @returns {Promise<{deleted: string[], errors: string[]}>}
+ */
+async function cleanOldLogs(category, daysToKeep) {
+  const retentionDays = daysToKeep ?? CONFIG.LOG_RETENTION_DAYS
+  const baseDir = path.join(process.cwd(), CONFIG.LOG_BASE_DIR)
+  const deleted = []
+  const errors = []
+
+  // Check if base directory exists
+  if (!fs.existsSync(baseDir)) {
+    return { deleted, errors }
+  }
+
+  // Calculate cutoff date
+  const cutoffDate = new Date()
+  cutoffDate.setDate(cutoffDate.getDate() - retentionDays)
+  const cutoffTimestamp = cutoffDate.getTime()
+
+  try {
+    // Get categories to process
+    const categories = category
+      ? [category]
+      : fs.readdirSync(baseDir).filter((name) => {
+        const stat = fs.statSync(path.join(baseDir, name))
+        return stat.isDirectory()
+      })
+
+    // Process each category
+    for (const cat of categories) {
+      const categoryPath = path.join(baseDir, cat)
+
+      if (!fs.existsSync(categoryPath)) continue
+
+      // Get date folders (YYYY-MM-DD format)
+      const dateFolders = fs.readdirSync(categoryPath).filter((name) => {
+        const folderPath = path.join(categoryPath, name)
+        const stat = fs.statSync(folderPath)
+        return stat.isDirectory() && /^\d{4}-\d{2}-\d{2}$/.test(name)
+      })
+
+      // Check each date folder
+      for (const dateFolder of dateFolders) {
+        try {
+          const folderDate = new Date(dateFolder)
+
+          if (folderDate.getTime() < cutoffTimestamp) {
+            const folderPath = path.join(categoryPath, dateFolder)
+
+            // Remove folder and contents
+            fs.rmSync(folderPath, { recursive: true, force: true })
+            deleted.push(`${cat}/${dateFolder}`)
+          }
+        } catch (err) {
+          errors.push(`${cat}/${dateFolder}: ${err.message}`)
+        }
+      }
+    }
+  } catch (err) {
+    errors.push(`Cleanup error: ${err.message}`)
+  }
+
+  return { deleted, errors }
+}
+
+module.exports = {
+  cleanOldLogs
+}

package/src/constants.js

@@ -0,0 +1,74 @@
+/**
+ * Session Logger Configuration & Constants
+ * Global defaults (override via environment variables)
+ *
+ * @module @onezlinks/session-logger/constants
+ */
+
+/**
+ * Configuration object with lazy environment variable evaluation
+ * Values are read from env at access time for testability
+ */
+const CONFIG = {
+  get LOG_BASE_DIR() {
+    return process.env.SESSION_LOG_DIR || 'logs'
+  },
+
+  get LOG_RETENTION_DAYS() {
+    return parseInt(process.env.SESSION_LOG_RETENTION_DAYS || '30', 10)
+  },
+
+  get ENABLE_FILE() {
+    return process.env.SESSION_LOG_TO_FILE !== 'false'
+  },
+
+  get ENABLE_STDOUT() {
+    return process.env.SESSION_LOG_TO_STDOUT !== 'false'
+  }
+}
+
+/**
+ * Common tag suggestions (reference only — not enforced)
+ * แต่ละ use case สามารถกำหนด custom tags ได้เอง
+ */
+const COMMON_TAGS = {
+  // AI Pipeline
+  PIPELINE: 'Pipeline',
+  QUALITY: 'Quality',
+  OCR: 'OCR',
+  OPENAI: 'OpenAI',
+  CLIENT: 'Client',
+
+  // Reward Redemption
+  REDEMPTION: 'Redemption',
+  POINTS: 'Points',
+  VALIDATION: 'Validation',
+  NOTIFICATION: 'Notification',
+
+  // Survey
+  SURVEY: 'Survey',
+  STORAGE: 'Storage',
+  ANALYTICS: 'Analytics',
+
+  // Order Processing
+  ORDER: 'Order',
+  PAYMENT: 'Payment',
+  INVENTORY: 'Inventory',
+  SHIPPING: 'Shipping',
+
+  // Messaging
+  MESSAGE: 'Message',
+  WEBHOOK: 'Webhook',
+  RESPONSE: 'Response',
+  BROADCAST: 'Broadcast',
+
+  // Generic
+  DATABASE: 'Database',
+  CACHE: 'Cache',
+  WORKER: 'Worker'
+}
+
+module.exports = {
+  CONFIG,
+  COMMON_TAGS
+}

package/src/context.js

@@ -0,0 +1,343 @@
+/**
+ * Session Logger Context Management
+ * AsyncLocalStorage-based context with Hybrid API (Wrapper + Manual patterns)
+ *
+ * @module @onezlinks/session-logger/context
+ */
+
+const { AsyncLocalStorage } = require('async_hooks')
+const { createFileLogger } = require('./file-logger')
+const { formatCost, formatDuration, formatMetric } = require('./formatter')
+const { CONFIG } = require('./constants')
+
+// Global AsyncLocalStorage instance (singleton per process)
+const sessionContext = new AsyncLocalStorage()
+
+/**
+ * Initialize session (shared by both patterns)
+ * @private
+ */
+function initializeSession(options) {
+  const {
+    sessionId,
+    category,
+    metadata = {},
+    logDir,
+    enableFile = CONFIG.ENABLE_FILE,
+    enableStdout = CONFIG.ENABLE_STDOUT
+  } = options
+
+  // Create unique file identifier: {sessionId_first7}_{ISO8601_compact}_{random3digit}
+  const sessionIdShort = sessionId.substring(0, 7)
+  const timestamp = new Date()
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d{3}Z$/, '')
+  const random = Math.floor(Math.random() * 1000)
+    .toString()
+    .padStart(3, '0')
+  const fileId = `${sessionIdShort}_${timestamp}_${random}`
+
+  // Create file logger
+  const fileLogger = enableFile ? createFileLogger(category, fileId, { baseDir: logDir }) : null
+
+  // Create store
+  const store = {
+    sessionId,
+    category,
+    metadata,
+    fileConsole: fileLogger?.fileConsole || null,
+    logPath: fileLogger?.logPath || null,
+    errLogPath: fileLogger?.errLogPath || null,
+    startTime: Date.now(),
+    stats: { logs: 0, errors: 0, warnings: 0 },
+    _fileLogger: fileLogger, // For cleanup
+    _enableStdout: enableStdout
+  }
+
+  // Write header
+  if (fileLogger) {
+    writeHeader(store)
+  }
+
+  return store
+}
+
+/**
+ * Write session header
+ * @private
+ */
+function writeHeader(store) {
+  const { fileConsole, category, sessionId, metadata } = store
+  if (!fileConsole) return
+
+  const headerLines = [
+    '═══════════════════════════════════════════════════════════════',
+    `  ${category
+      .split('-')
+      .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+      .join(' ')} Session`,
+    '═══════════════════════════════════════════════════════════════',
+    `  Session ID  : ${sessionId}`,
+    `  Category    : ${category}`
+  ]
+
+  // Add metadata fields
+  Object.entries(metadata).forEach(([key, value]) => {
+    const label = key.charAt(0).toUpperCase() + key.slice(1).replace(/([A-Z])/g, ' $1')
+    headerLines.push(`  ${label.padEnd(12)}: ${value}`)
+  })
+
+  headerLines.push(`  Started     : ${new Date().toISOString()}`)
+  headerLines.push('═══════════════════════════════════════════════════════════════')
+  headerLines.push('') // Empty line after header
+
+  fileConsole.log(headerLines.join('\n'))
+}
+
+/**
+ * Finalize session and write summary
+ * @private
+ */
+async function finalizeSession(store) {
+  if (!store) return
+
+  const { fileConsole, _fileLogger, startTime, stats } = store
+  const duration = Date.now() - startTime
+
+  // Write summary
+  if (fileConsole) {
+    const summaryLines = [
+      '',
+      '═══════════════════════════════════════════════════════════════',
+      '  Session Summary',
+      '═══════════════════════════════════════════════════════════════',
+      '  Status      : SUCCESS',
+      `  Duration    : ${formatDuration(duration)}`,
+      `  Log Stats   : ${stats.logs} info, ${stats.errors} errors, ${stats.warnings} warnings`,
+      '═══════════════════════════════════════════════════════════════'
+    ]
+
+    fileConsole.log(summaryLines.join('\n'))
+  }
+
+  // Close file streams
+  if (_fileLogger && typeof _fileLogger.close === 'function') {
+    _fileLogger.close()
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// PUBLIC API — Wrapper Pattern (Recommended)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Run async function within session logger context (WRAPPER PATTERN)
+ * @param {Object} options - Session configuration
+ * @param {string} options.sessionId - Unique session identifier
+ * @param {string} options.category - Log category/subdirectory
+ * @param {Object} [options.metadata={}] - Additional metadata for header
+ * @param {string} [options.logDir] - Override base log directory
+ * @param {boolean} [options.enableFile=true] - Enable file logging
+ * @param {boolean} [options.enableStdout=true] - Enable stdout output
+ * @param {Function} asyncFn - Async function to execute within context
+ * @returns {Promise<*>} Return value of asyncFn
+ */
+async function withSession(options, asyncFn) {
+  const store = initializeSession(options)
+
+  try {
+    return await sessionContext.run(store, async () => {
+      return await asyncFn()
+    })
+  } finally {
+    await finalizeSession(store)
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// PUBLIC API — Manual Pattern (Advanced)
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Start a session logger context (MANUAL PATTERN)
+ * ⚠️ Must call endSession() in finally block
+ * @param {Object} options - Session configuration
+ * @param {string} options.sessionId - Unique session identifier
+ * @param {string} options.category - Log category/subdirectory
+ * @param {Object} [options.metadata={}] - Additional metadata for header
+ * @param {string} [options.logDir] - Override base log directory
+ * @param {boolean} [options.enableFile=true] - Enable file logging
+ * @param {boolean} [options.enableStdout=true] - Enable stdout output
+ */
+function startSession(options) {
+  const store = initializeSession(options)
+  sessionContext.enterWith(store)
+}
+
+/**
+ * End current session logger context (MANUAL PATTERN)
+ * ⚠️ Must be called in finally block after startSession()
+ * @returns {Promise<void>}
+ */
+async function endSession() {
+  const store = sessionContext.getStore()
+  if (store) {
+    await finalizeSession(store)
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// PUBLIC API — Context Inspection
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Get current session context
+ * @returns {Object|null} Current session context or null
+ */
+function getSessionContext() {
+  return sessionContext.getStore() || null
+}
+
+// ═══════════════════════════════════════════════════════════════
+// PUBLIC API — Logging Functions
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Log info message
+ * @param {string} tag - Module/component tag
+ * @param {string} message - Log message
+ * @param {...*} args - Additional arguments
+ */
+function log(tag, message, ...args) {
+  const store = sessionContext.getStore()
+  const timestamp = new Date().toISOString().substring(11, 23) // HH:mm:ss.SSS
+  const formatted = `[${timestamp}] [${tag.padEnd(12)}] ${message}`
+
+  // Write to file if in context
+  if (store?.fileConsole) {
+    store.fileConsole.log(formatted, ...args)
+    store.stats.logs++
+  }
+
+  // Always write to stdout (dual output)
+  if (!store || store._enableStdout) {
+    console.log(formatted, ...args)
+  }
+}
+
+/**
+ * Alias for log() — semantic clarity
+ */
+const info = log
+
+/**
+ * Log error message
+ * @param {string} tag - Module/component tag
+ * @param {string} message - Error message
+ * @param {...*} args - Additional arguments
+ */
+function error(tag, message, ...args) {
+  const store = sessionContext.getStore()
+  const timestamp = new Date().toISOString().substring(11, 23)
+  const formatted = `[${timestamp}] [${tag.padEnd(12)}] ${message}`
+
+  // Write to error file if in context
+  if (store?.fileConsole) {
+    store.fileConsole.error(formatted, ...args)
+    store.stats.errors++
+  }
+
+  // Always write to stderr (dual output)
+  if (!store || store._enableStdout) {
+    console.error(formatted, ...args)
+  }
+}
+
+/**
+ * Log warning message
+ * @param {string} tag - Module/component tag
+ * @param {string} message - Warning message
+ * @param {...*} args - Additional arguments
+ */
+function warn(tag, message, ...args) {
+  const store = sessionContext.getStore()
+  const timestamp = new Date().toISOString().substring(11, 23)
+  const formatted = `[${timestamp}] [${tag.padEnd(12)}] ${message}`
+
+  // Write to file if in context
+  if (store?.fileConsole) {
+    store.fileConsole.log(formatted, ...args)
+    store.stats.warnings++
+  }
+
+  // Always write to stdout (dual output)
+  if (!store || store._enableStdout) {
+    console.warn(formatted, ...args)
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// PUBLIC API — Special Formatters
+// ═══════════════════════════════════════════════════════════════
+
+/**
+ * Log cost/billing data with consistent formatting
+ * @param {string} tag - Module tag
+ * @param {Object} costData - Cost data
+ * @param {number} costData.totalUSD - Total cost in USD
+ * @param {number} costData.totalTHB - Total cost in THB
+ * @param {number} [inputUnits=0] - Input units
+ * @param {number} [outputUnits=0] - Output units
+ * @param {number} [cachedUnits=0] - Cached units
+ */
+function logCost(tag, costData, inputUnits = 0, outputUnits = 0, cachedUnits = 0) {
+  const formatted = formatCost(costData, inputUnits, outputUnits, cachedUnits)
+  log(tag, formatted)
+}
+
+/**
+ * Log duration/performance metrics
+ * @param {string} tag - Module tag
+ * @param {number} durationMs - Duration in milliseconds
+ * @param {string} [label='Duration'] - Metric label
+ */
+function logDuration(tag, durationMs, label = 'Duration') {
+  const formatted = `⏱️  ${label}: ${formatDuration(durationMs)}`
+  log(tag, formatted)
+}
+
+/**
+ * Log custom metrics
+ * @param {string} tag - Module tag
+ * @param {string} metricName - Metric name
+ * @param {number|string} value - Metric value
+ * @param {string} [unit] - Optional unit
+ */
+function logMetric(tag, metricName, value, unit) {
+  const formatted = formatMetric(metricName, value, unit)
+  log(tag, formatted)
+}
+
+module.exports = {
+  // Wrapper Pattern (Recommended)
+  withSession,
+
+  // Manual Pattern (Advanced)
+  startSession,
+  endSession,
+
+  // Context Inspection
+  getSessionContext,
+
+  // Logging Functions
+  log,
+  info,
+  error,
+  warn,
+
+  // Special Formatters
+  logCost,
+  logDuration,
+  logMetric
+}

package/src/file-logger.js

@@ -0,0 +1,76 @@
+/**
+ * File Logger Factory
+ * Creates file-based console.Console instances for session logging
+ *
+ * @module @onezlinks/session-logger/file-logger
+ */
+
+const { Console } = require('node:console')
+const fs = require('node:fs')
+const path = require('node:path')
+const { CONFIG } = require('./constants')
+
+/**
+ * Create a file logger for a specific session
+ * @param {string} category - Log category (subdirectory name)
+ * @param {string} fileId - Unique file identifier (e.g., sessionId_timestamp)
+ * @param {Object} [options={}] - Configuration options
+ * @param {string} [options.baseDir] - Override base log directory
+ * @returns {Object|null} Logger object or null if creation fails
+ * @returns {Console} returns.fileConsole - console.Console instance
+ * @returns {string} returns.logPath - Path to main log file
+ * @returns {string} returns.errLogPath - Path to error log file
+ * @returns {Function} returns.close - Function to close streams
+ */
+function createFileLogger(category, fileId, options = {}) {
+  const baseDir = options.baseDir || CONFIG.LOG_BASE_DIR
+  const dateFolder = new Date().toISOString().split('T')[0] // YYYY-MM-DD
+  const dir = path.join(process.cwd(), baseDir, category, dateFolder)
+
+  // Create directory structure (recursive)
+  try {
+    fs.mkdirSync(dir, { recursive: true })
+  } catch (err) {
+    console.error('[Session Logger] Failed to create log directory:', err.message)
+    return null // Fallback: no file logging
+  }
+
+  // Create file paths
+  const logPath = path.join(dir, `${fileId}.log`)
+  const errLogPath = path.join(dir, `${fileId}.err.log`)
+
+  // Create write streams
+  let logStream, errStream
+  try {
+    logStream = fs.createWriteStream(logPath, { flags: 'a' })
+    errStream = fs.createWriteStream(errLogPath, { flags: 'a' })
+
+    // Prevent unhandled error events from crashing the process
+    logStream.on('error', () => {})
+    errStream.on('error', () => {})
+  } catch (err) {
+    console.error('[Session Logger] Failed to create write streams:', err.message)
+    return null // Fallback: no file logging
+  }
+
+  // Create console.Console instance
+  const fileConsole = new Console({
+    stdout: logStream,
+    stderr: errStream,
+    inspectOptions: { depth: 4, colors: false }
+  })
+
+  return {
+    fileConsole,
+    logPath,
+    errLogPath,
+    close() {
+      logStream.end()
+      errStream.end()
+    }
+  }
+}
+
+module.exports = {
+  createFileLogger
+}

package/src/formatter.js

@@ -0,0 +1,55 @@
+/**
+ * Log Formatting Utilities
+ * Provides consistent formatting for cost, duration, and metrics
+ *
+ * @module @onezlinks/session-logger/formatter
+ */
+
+/**
+ * Format cost data for consistent output
+ * @param {Object} costData - Cost information
+ * @param {number} costData.totalUSD - Total cost in USD
+ * @param {number} costData.totalTHB - Total cost in THB
+ * @param {number} [inputUnits=0] - Input units (tokens, API calls, etc.)
+ * @param {number} [outputUnits=0] - Output units
+ * @param {number} [cachedUnits=0] - Cached units
+ * @returns {string} Formatted cost string
+ */
+function formatCost(costData, inputUnits = 0, outputUnits = 0, cachedUnits = 0) {
+  const { totalUSD, totalTHB } = costData
+  const usd = totalUSD.toFixed(6)
+  const thb = totalTHB.toFixed(4)
+  const units =
+    cachedUnits > 0 ? `${inputUnits}+${outputUnits} (cached: ${cachedUnits})` : `${inputUnits}+${outputUnits}`
+
+  return `💰 Cost: $${usd} (~฿${thb}) | Units: ${units}`
+}
+
+/**
+ * Format duration for readable output
+ * @param {number} durationMs - Duration in milliseconds
+ * @returns {string} Formatted duration string
+ */
+function formatDuration(durationMs) {
+  if (durationMs < 1000) {
+    return `${durationMs}ms`
+  }
+  return `${durationMs}ms (${(durationMs / 1000).toFixed(2)}s)`
+}
+
+/**
+ * Format metric with optional unit
+ * @param {string} name - Metric name
+ * @param {number|string} value - Metric value
+ * @param {string} [unit] - Optional unit (e.g., 'items', '%', 'MB')
+ * @returns {string} Formatted metric string
+ */
+function formatMetric(name, value, unit) {
+  return unit ? `${name}: ${value} ${unit}` : `${name}: ${value}`
+}
+
+module.exports = {
+  formatCost,
+  formatDuration,
+  formatMetric
+}