feat: add injectable logger system

Author: RomainLanz

src/logger.ts

@@ -0,0 +1,114 @@
+export interface LogObject {
+  [key: string]: unknown
+}
+
+export interface ErrorObject extends LogObject {
+  err?: Error
+}
+
+export interface Logger {
+  trace(msg: string): void
+  trace(obj: LogObject, msg: string): void
+
+  debug(msg: string): void
+  debug(obj: LogObject, msg: string): void
+
+  info(msg: string): void
+  info(obj: LogObject, msg: string): void
+
+  warn(msg: string): void
+  warn(obj: LogObject, msg: string): void
+
+  error(msg: string): void
+  error(obj: ErrorObject, msg: string): void
+
+  child(obj: LogObject): Logger
+}
+
+/**
+ * A simple logger that writes to console.
+ */
+class ConsoleLogger implements Logger {
+  #prefix: string
+
+  constructor(prefix: string = 'queue') {
+    this.#prefix = prefix
+  }
+
+  #format(level: string, msgOrObj: string | LogObject, msg?: string): [string, LogObject?] {
+    const prefix = `[${this.#prefix}] ${level}:`
+
+    if (typeof msgOrObj === 'object') {
+      return [`${prefix} ${msg}`, msgOrObj]
+    }
+
+    return [`${prefix} ${msgOrObj}`]
+  }
+
+  trace(msg: string): void
+  trace(obj: LogObject, msg: string): void
+  trace(msgOrObj: string | LogObject, msg?: string): void {
+    const [message, obj] = this.#format('TRACE', msgOrObj, msg)
+
+    if (obj) {
+      return console.log(message, obj)
+    }
+
+    console.log(message)
+  }
+
+  debug(msg: string): void
+  debug(obj: LogObject, msg: string): void
+  debug(msgOrObj: string | LogObject, msg?: string): void {
+    const [message, obj] = this.#format('DEBUG', msgOrObj, msg)
+
+    if (obj) {
+      return console.log(message, obj)
+    }
+
+    console.log(message)
+  }
+
+  info(msg: string): void
+  info(obj: LogObject, msg: string): void
+  info(msgOrObj: string | LogObject, msg?: string): void {
+    const [message, obj] = this.#format('INFO', msgOrObj, msg)
+
+    if (obj) {
+      return console.log(message, obj)
+    }
+
+    console.log(message)
+  }
+
+  warn(msg: string): void
+  warn(obj: LogObject, msg: string): void
+  warn(msgOrObj: string | LogObject, msg?: string): void {
+    const [message, obj] = this.#format('WARN', msgOrObj, msg)
+
+    if (obj) {
+      return console.warn(message, obj)
+    }
+
+    console.warn(message)
+  }
+
+  error(msg: string): void
+  error(obj: ErrorObject, msg: string): void
+  error(msgOrObj: string | ErrorObject, msg?: string): void {
+    const [message, obj] = this.#format('ERROR', msgOrObj, msg)
+
+    if (obj) {
+      return console.error(message, obj)
+    }
+
+    console.error(message)
+  }
+
+  child(obj: LogObject): Logger {
+    const childPrefix = obj.pkg ? String(obj.pkg) : this.#prefix
+    return new ConsoleLogger(childPrefix)
+  }
+}
+
+export const consoleLogger = new ConsoleLogger()

src/queue_manager.ts

@@ -1,6 +1,7 @@
 import * as errors from './exceptions.js'
 import debug from './debug.js'
 import { Locator } from './locator.js'
+import { consoleLogger, type Logger } from './logger.js'
 import type { Adapter } from './contracts/adapter.js'
 import type { AdapterFactory, QueueConfig, QueueManagerConfig, RetryConfig } from './types/main.js'
 
@@ -10,6 +11,7 @@ class QueueManagerSingleton {
   #adapterInstances: Map<string, Adapter> = new Map()
   #globalRetryConfig?: RetryConfig
   #queueConfigs: Map<string, QueueConfig> = new Map()
+  #logger: Logger = consoleLogger
 
   async init(config: QueueManagerConfig) {
     debug('initializing queue manager with config: %O', config)
@@ -21,6 +23,7 @@ class QueueManagerSingleton {
     this.#defaultAdapter = config.default
     this.#adapters = config.adapters
     this.#globalRetryConfig = config.retry
+    this.#logger = config.logger ?? consoleLogger
 
     if (config.queues) {
       for (const [queue, queueConfig] of Object.entries(config.queues)) {

src/types/index.ts

@@ -11,6 +11,7 @@ export type {
   WorkerCycle,
   AdapterFactory,
   QueueManagerConfig,
+  Logger,
 } from './main.js'
 
 export type { Adapter, AcquiredJob } from '../contracts/adapter.js'

src/types/main.ts

@@ -1,7 +1,10 @@
 import type { BackoffStrategy as BackoffStrategyClass } from '../strategies/backoff_strategy.js'
 import type { Adapter } from '../contracts/adapter.js'
+import type { Logger } from '../logger.js'
 import { Job } from '../job.js'
 
+export type { Logger }
+
 export type Duration = number | string
 
 export interface JobData {
@@ -103,4 +106,5 @@ export interface QueueManagerConfig {
   queues?: Record<string, QueueConfig>
   worker?: WorkerConfig
   locations?: string[]
+  logger?: Logger
 }

tests/_mocks/memory_logger.ts

@@ -0,0 +1,57 @@
+import type { Logger, LogObject, ErrorObject } from '../../src/logger.js'
+
+export interface LogEntry {
+  level: 'trace' | 'debug' | 'info' | 'warn' | 'error'
+  message: string
+  obj?: LogObject
+}
+
+export class MemoryLogger implements Logger {
+  logs: LogEntry[] = []
+
+  trace(msg: string): void
+  trace(obj: LogObject, msg: string): void
+  trace(msgOrObj: string | LogObject, msg?: string): void {
+    this.#log('trace', msgOrObj, msg)
+  }
+
+  debug(msg: string): void
+  debug(obj: LogObject, msg: string): void
+  debug(msgOrObj: string | LogObject, msg?: string): void {
+    this.#log('debug', msgOrObj, msg)
+  }
+
+  info(msg: string): void
+  info(obj: LogObject, msg: string): void
+  info(msgOrObj: string | LogObject, msg?: string): void {
+    this.#log('info', msgOrObj, msg)
+  }
+
+  warn(msg: string): void
+  warn(obj: LogObject, msg: string): void
+  warn(msgOrObj: string | LogObject, msg?: string): void {
+    this.#log('warn', msgOrObj, msg)
+  }
+
+  error(msg: string): void
+  error(obj: ErrorObject, msg: string): void
+  error(msgOrObj: string | ErrorObject, msg?: string): void {
+    this.#log('error', msgOrObj, msg)
+  }
+
+  child(_obj: LogObject): Logger {
+    return this
+  }
+
+  clear(): void {
+    this.logs = []
+  }
+
+  #log(level: LogEntry['level'], msgOrObj: string | LogObject, msg?: string): void {
+    if (typeof msgOrObj === 'object') {
+      this.logs.push({ level, message: msg!, obj: msgOrObj })
+    } else {
+      this.logs.push({ level, message: msgOrObj })
+    }
+  }
+}

tests/queue_manager.spec.ts

@@ -3,6 +3,7 @@ import * as errors from '../src/exceptions.js'
 import { QueueManager } from '../src/queue_manager.js'
 import { sync } from '../src/drivers/sync_adapter.js'
 import { exponentialBackoff } from '../src/strategies/backoff_strategy.js'
+import { MemoryLogger } from './_mocks/memory_logger.js'
 
 test.group('QueueManager', () => {
   test('should validate adapter presence', async ({ assert }) => {
@@ -78,7 +79,7 @@ test.group('QueueManager', () => {
     await QueueManager.init({
       default: 'sync',
       adapters: { sync: sync() },
-      locations: ['./jobs/**/*'],
+      locations: ['./examples/jobs/**/*'],
       retry: { maxRetries: 5, backoff: exponentialBackoff() },
     })
 
@@ -90,7 +91,7 @@ test.group('QueueManager', () => {
     await QueueManager.init({
       default: 'sync',
       adapters: { sync: sync() },
-      locations: ['./jobs/**/*'],
+      locations: ['./examples/jobs/**/*'],
       retry: { maxRetries: 5, backoff: exponentialBackoff() },
       queues: {
         email: { retry: { maxRetries: 3 } },
@@ -105,7 +106,7 @@ test.group('QueueManager', () => {
     await QueueManager.init({
       default: 'sync',
       adapters: { sync: sync() },
-      locations: ['./jobs/**/*'],
+      locations: ['./examples/jobs/**/*'],
       retry: { maxRetries: 5, backoff: exponentialBackoff() },
       queues: {
         email: { retry: { maxRetries: 3 } },
@@ -115,4 +116,60 @@ test.group('QueueManager', () => {
     let config = QueueManager.getMergedRetryConfig('email', { maxRetries: 2 })
     assert.equal(config.maxRetries, 2)
   })
+
+  test('should throw E_QUEUE_NOT_INITIALIZED when use() called before init()', async ({
+    assert,
+  }) => {
+    assert.plan(2)
+
+    await QueueManager.destroy()
+
+    try {
+      QueueManager.use()
+    } catch (error) {
+      assert.instanceOf(error, errors.E_QUEUE_NOT_INITIALIZED)
+      assert.equal(
+        error.message,
+        'QueueManager is not initialized. Call QueueManager.init() before using it.'
+      )
+    }
+  })
+
+  test('should throw E_ADAPTER_INIT_ERROR when adapter factory throws', async ({ assert }) => {
+    assert.plan(2)
+
+    await QueueManager.init({
+      default: 'broken',
+      adapters: {
+        broken: () => {
+          throw new Error('Connection failed')
+        },
+      },
+    })
+
+    try {
+      QueueManager.use()
+    } catch (error) {
+      assert.instanceOf(error, errors.E_ADAPTER_INIT_ERROR)
+      assert.equal(
+        error.message,
+        'Failed to initialize adapter "broken". Reason: Connection failed'
+      )
+    }
+  })
+
+  test('should log warning when locations match no jobs', async ({ assert }) => {
+    const logger = new MemoryLogger()
+
+    await QueueManager.init({
+      default: 'sync',
+      adapters: { sync: sync() },
+      locations: ['./non-existent-path/**/*.ts'],
+      logger,
+    })
+
+    assert.equal(logger.logs.length, 1)
+    assert.equal(logger.logs[0].level, 'warn')
+    assert.include(logger.logs[0].message, 'No jobs found for locations')
+  })
 })