@knowark/loggarkjs 0.3.11 → 0.5.0

package/README.md

@@ -1,2 +1,65 @@
 # loggark
 Utilitarian Logging Library
+
+## Logger output format
+
+`Logger` now emits a single JSON object per log line by default (JSON Lines). This format is easier to consume with `journalctl` pipelines (`jq`, `grep`, field selection).
+
+- Default: `format: 'json'`
+- Backward compatibility: `format: 'plain'`
+- Context flattening in JSON mode: `flat: true` (default)
+
+Example:
+
+```js
+import { Logger } from '@knowark/loggarkjs'
+
+const logger = new Logger({ namespace: 'api' })
+logger.info('User login', { userId: 'u-123' })
+```
+
+Outputs:
+
+```json
+{"timestamp":"2025-02-15T00:00:00.000Z","level":"info","namespace":"api","message":"User login","userId":"u-123"}
+```
+
+Additional object parameters are merged into the base log object. If keys collide, later merged values overwrite earlier keys.
+
+If you prefer context keys at top level (for simpler `jq` filters), enable flattening:
+
+```js
+const logger = new Logger({
+  namespace: 'api',
+  context: { correlationId: 'ABCD1234', interactor: 'Informer' },
+  flat: true
+})
+
+logger.info('User login')
+```
+
+```json
+{"timestamp":"2025-02-15T00:00:00.000Z","level":"info","namespace":"api","correlationId":"ABCD1234","interactor":"Informer","message":"User login"}
+```
+
+To keep nested context under `context`, disable flattening:
+
+```js
+const logger = new Logger({
+  context: { correlationId: 'ABCD1234' },
+  flat: false
+})
+```
+
+## Journald integration
+
+Set the boolean `globalThis.JOURNALD` flag to `true` and `Logger` will open `/run/systemd/journal/socket` for you. Every JSON record is translated into Journald fields (`PRIORITY`, `MESSAGE`, `LEVEL`, optional `SYSLOG_IDENTIFIER`, and uppercased context payloads), so you can pipe `logger.info()` calls directly into `journalctl` for centralized viewing.
+
+```js
+globalThis.JOURNALD = true
+const logger = new Logger({ namespace: 'api' })
+
+logger.info('User login', { userId: 'u-123', extra: undefined })
+```
+
+Undefined values are dropped, `null` turns into the string `'null'`, and functions/symbols are rendered so Journald receives a predictable payload. The socket connection is cached per process, so later `Logger` instances reuse the same transport without extra setup.

package/lib/index.d.ts

@@ -4,7 +4,9 @@ export declare class Logger {
   constructor (dependencies?: {
     namespace?: string,
     context?: object,
-    global?: object
+    global?: object,
+    format?: 'json' | 'plain',
+    flat?: boolean
   })
 
   context?: object | null
@@ -34,4 +36,4 @@ export declare class Translator {
 
 export declare function t(key: string, options?: object): string
 
-export declare function lt(key: string, options?: object): () => string
+export declare function lt(key: string, options?: object): () => string

package/lib/logger.js

@@ -1,3 +1,5 @@
+import { journaldSocket } from './utilities/journald-socket.js'
+
 export class Logger {
   static context () {
     return null
@@ -5,12 +7,16 @@ export class Logger {
 
   #context = {}
 
-  constructor ({ namespace = '', context = null, global = globalThis } = {}) {
+  constructor ({ namespace = '', context = null, global = globalThis, format = 'json', flat = true } = {}) {
     this.levels = ['error', 'warn', 'info', 'debug']
+    this.namespace = namespace
+    this.format = format
+    this.flat = flat
     this.logvar = [namespace, 'LOGLEVEL'].filter(
       Boolean).join('_').toUpperCase().replaceAll(' ', '_')
     this.global = global
     this.#context = context
+    this.journald = getJournaldTransport(this.global)
   }
 
   get context () {
@@ -24,28 +30,163 @@ export class Logger {
   }
 
   log (...args) {
-    if (this.logindex >= 0) log(this.global, 'log', this.context, args)
+    if (this.logindex >= 0) log(this.global, 'log', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 
   error (...args) {
-    if (this.logindex >= 0) log(this.global, 'error', this.context, args) 
+    if (this.logindex >= 0) log(this.global, 'error', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 
   warn (...args) {
-    if (this.logindex >= 1) log(this.global, 'warn', this.context, args)
+    if (this.logindex >= 1) log(this.global, 'warn', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 
   info (...args) {
-    if (this.logindex >= 2) log(this.global, 'info', this.context, args)
+    if (this.logindex >= 2) log(this.global, 'info', this.context, args, this.namespace, this.format, this.flat, this.journald)
   }
 
   debug (...args) {
-    if (this.logindex >= 3) log(this.global, 'debug', this.context, args)
+    if (this.logindex >= 3) log(this.global, 'debug', this.context, args, this.namespace, this.format, this.flat, this.journald)
+  }
+}
+
+function parseArgs (args) {
+  const payload = {}
+
+  args.forEach((value, index) => {
+    if (index === 0 && typeof value === 'string') {
+      payload.message = value
+      return
+    }
+
+    Object.assign(payload, toLogFields(value, index))
+  })
+
+  return payload
+}
+
+function toLogFields (value, index) {
+  if (value instanceof Error) return toSerializableError(value)
+  if (value && typeof value === 'object' && !Array.isArray(value)) return value
+  return { [`arg${index}`]: value }
+}
+
+function toSerializableError (error) {
+  return {
+    name: error.name,
+    message: error.message,
+    stack: error.stack,
+    ...error
   }
 }
 
-function log (global, level, context, args) {
-  return global.console[level](
-  `${new global.Date().toISOString()} [${level.toUpperCase()}]`,
-  ...[context ? JSON.stringify(context) : false, ...args].filter(Boolean))
-}
+function stringifyJson (payload) {
+  const seen = new WeakSet()
+  return JSON.stringify(payload, (_key, value) => {
+    if (typeof value === 'bigint') return value.toString()
+    if (typeof value === 'function') return `[Function ${value.name || 'anonymous'}]`
+    if (typeof value === 'symbol') return value.toString()
+    if (value instanceof Error) return toSerializableError(value)
+
+    if (value && typeof value === 'object') {
+      if (seen.has(value)) return '[Circular]'
+      seen.add(value)
+    }
+
+    return value
+  })
+}
+
+export const JOURNAL_PRIORITY = {
+  log: 6,
+  error: 3,
+  warn: 4,
+  info: 6,
+  debug: 7
+}
+
+function toJournaldFields (record) {
+  const entry = {
+    PRIORITY: JOURNAL_PRIORITY[record.level] ?? 6,
+    MESSAGE: serializeJournaldValue(record.message) ?? '',
+    TIMESTAMP: record.timestamp,
+    LEVEL: record.level
+  }
+
+  if (record.namespace) {
+    entry.SYSLOG_IDENTIFIER = record.namespace
+  }
+
+  for (const [key, value] of Object.entries(record)) {
+    if (['timestamp', 'level', 'namespace', 'message'].includes(key)) continue
+    const normalized = serializeJournaldValue(value)
+    if (normalized !== undefined) {
+      entry[key.toUpperCase()] = normalized
+    }
+  }
+
+  return entry
+}
+
+function serializeJournaldValue (value) {
+  if (value === undefined) return undefined
+  if (value === null) return 'null'
+  if (typeof value === 'function') return `[Function ${value.name || 'anonymous'}]`
+  if (typeof value === 'symbol') return value.toString()
+  if (typeof value === 'object') return stringifyJson(value)
+  return String(value)
+}
+
+let defaultJournaldTransport = null
+
+function getJournaldTransport (global) {
+  if (!global?.JOURNALD) return null
+  if (defaultJournaldTransport) return defaultJournaldTransport
+  defaultJournaldTransport = journaldSocket.createTransport()
+  return defaultJournaldTransport
+}
+
+function sendToJournald (journald, fields) {
+  if (typeof journald === 'function') {
+    journald(fields)
+    return
+  }
+
+  if (journald && typeof journald.send === 'function') {
+    journald.send(fields)
+    return
+  }
+
+  if (journald && typeof journald.log === 'function') {
+    journald.log(fields)
+  }
+}
+
+function log (global, level, context, args, namespace, format, flat, journald) {
+  const timestamp = new global.Date().toISOString()
+  const record = {
+    ...(flat && context ? context : {}),
+    timestamp,
+    level,
+    ...(namespace ? { namespace } : {}),
+    ...(!flat && context ? { context } : {}),
+    ...parseArgs(args)
+  }
+
+  let consoleResult
+
+  if (format === 'plain') {
+    const message = [`${timestamp} [${level.toUpperCase()}]`]
+    if (context) message.push(stringifyJson(context))
+    message.push(...args)
+    consoleResult = global.console[level](...message)
+  } else {
+    consoleResult = global.console[level](stringifyJson(record))
+  }
+
+  if (journald) {
+    sendToJournald(journald, toJournaldFields(record))
+  }
+
+  return consoleResult
+}

package/lib/logger.test.js

@@ -1,5 +1,20 @@
-import { it, expect } from '@jest/globals'
-import { Logger } from './logger.js'
+import assert from 'node:assert/strict'
+import test, { it } from 'node:test'
+
+const journaldTransportState = { lastFields: null }
+
+const journaldSocketModule = await import('./utilities/journald-socket.js')
+const { journaldSocket } = journaldSocketModule
+test.mock.method(journaldSocket, 'createTransport', () => {
+  return {
+    send (fields) {
+      journaldTransportState.lastFields = fields
+    }
+  }
+})
+
+const loggerModule = await import('./logger.js')
+const { Logger, JOURNAL_PRIORITY } = loggerModule
 
 function setup () {
   const mockGlobal = {
@@ -11,22 +26,29 @@ function setup () {
       debug (...args) { mockGlobal.debugArgs = args }
     },
     Date: class {
-      toISOString() {
+      toISOString () {
         return new Date('2025-02-15').toISOString()
       }
     }
   }
-  return {mockGlobal}
+
+  return { mockGlobal }
+}
+
+function parseRecord (args) {
+  assert.ok(args)
+  assert.strictEqual(args.length, 1)
+  return JSON.parse(args[0])
 }
 
 it('can be instantiated', () => {
   const logger = new Logger()
-  expect(logger).toBeTruthy()
+  assert.ok(logger)
 })
 
-it('can be instantiated', () => {
+it('returns null context when no static or instance context is available', () => {
   const logger = new Logger()
-  expect(logger).toBeTruthy()
+  assert.strictEqual(logger.context, null)
 })
 
 it('is disabled by default', () => {
@@ -34,98 +56,537 @@ it('is disabled by default', () => {
   const logger = new Logger({ global: mockGlobal })
 
   logger.log('Logging something...')
-  expect(mockGlobal.logArgs).toBeFalsy()
+  assert.ok(!mockGlobal.logArgs)
 
   logger.error('Logging something...')
-  expect(mockGlobal.errorArgs).toBeFalsy()
+  assert.ok(!mockGlobal.errorArgs)
 
   logger.warn('Logging something...')
-  expect(mockGlobal.warnArgs).toBeFalsy()
+  assert.ok(!mockGlobal.warnArgs)
 
   logger.info('Logging something...')
-  expect(mockGlobal.infoArgs).toBeFalsy()
+  assert.ok(!mockGlobal.infoArgs)
 
   logger.debug('Logging something...')
-  expect(mockGlobal.debugArgs).toBeFalsy()
+  assert.ok(!mockGlobal.debugArgs)
 })
 
-it('adds a prefix to the logging methods according to loglevel', () => {
+it('emits JSON logs by default according to loglevel', () => {
   const { mockGlobal } = setup()
   mockGlobal.LOGLEVEL = 'debug'
   const logger = new Logger({ global: mockGlobal })
 
   logger.log('Logging something...')
-  expect(mockGlobal.logArgs).toEqual(
-    ['2025-02-15T00:00:00.000Z [LOG]', 'Logging something...'])
+  assert.deepStrictEqual(parseRecord(mockGlobal.logArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'log',
+    message: 'Logging something...'
+  })
 
   logger.error('Logging something...')
-  expect(mockGlobal.errorArgs).toEqual(
-    ['2025-02-15T00:00:00.000Z [ERROR]', 'Logging something...'])
+  assert.deepStrictEqual(parseRecord(mockGlobal.errorArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'error',
+    message: 'Logging something...'
+  })
 
   logger.warn('Logging something...')
-  expect(mockGlobal.warnArgs).toEqual(
-    ['2025-02-15T00:00:00.000Z [WARN]', 'Logging something...'])
+  assert.deepStrictEqual(parseRecord(mockGlobal.warnArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'warn',
+    message: 'Logging something...'
+  })
 
   logger.info('Logging something...')
-  expect(mockGlobal.infoArgs).toEqual(
-    ['2025-02-15T00:00:00.000Z [INFO]', 'Logging something...'])
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    message: 'Logging something...'
+  })
 
   logger.debug('Logging something...')
-  expect(mockGlobal.debugArgs).toEqual(
-    ['2025-02-15T00:00:00.000Z [DEBUG]', 'Logging something...'])
+  assert.deepStrictEqual(parseRecord(mockGlobal.debugArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'debug',
+    message: 'Logging something...'
+  })
 })
 
-it('adds the provided logging context labels to its final output', () => {
+it('merges object parameters into the base JSON log object', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  logger.info('Logging something...', { action: 'create', entity: 'product' })
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    message: 'Logging something...',
+    action: 'create',
+    entity: 'product'
+  })
+})
+
+it('can emit JSON logs without message arguments', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  logger.info()
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info'
+  })
+})
+
+it('can emit JSON logs without context when flat is disabled', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal, flat: false })
+
+  logger.info('Logging something...')
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    message: 'Logging something...'
+  })
+})
+
+it('flattens provided logging context labels by default', () => {
   const { mockGlobal } = setup()
   mockGlobal.LOGLEVEL = 'debug'
   const context = { correlationId: 'ABCD1234', interactor: 'Informer' }
   const logger = new Logger({ global: mockGlobal, context })
 
-  logger.log('Logging something...')
-  expect(mockGlobal.logArgs).toEqual([
-    '2025-02-15T00:00:00.000Z [LOG]',
-    JSON.stringify({ correlationId: 'ABCD1234', interactor: 'Informer' }),
-    'Logging something...'])
+  logger.info('Logging something...')
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    correlationId: 'ABCD1234',
+    interactor: 'Informer',
+    message: 'Logging something...'
+  })
+})
 
-  logger.error('Logging something...')
-  expect(mockGlobal.errorArgs).toEqual([
-    '2025-02-15T00:00:00.000Z [ERROR]', 
-    JSON.stringify({ correlationId: 'ABCD1234', interactor: 'Informer' }),
-    'Logging something...'])
+it('can flatten context labels into top-level JSON fields with flat option', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const context = { correlationId: 'ABCD1234', interactor: 'Informer' }
+  const logger = new Logger({ global: mockGlobal, context, flat: true })
 
-  logger.warn('Logging something...')
-  expect(mockGlobal.warnArgs).toEqual([
-    '2025-02-15T00:00:00.000Z [WARN]', 
-    JSON.stringify({ correlationId: 'ABCD1234', interactor: 'Informer' }),
-    'Logging something...'])
+  logger.info('Logging something...')
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    correlationId: 'ABCD1234',
+    interactor: 'Informer',
+    message: 'Logging something...'
+  })
+})
+
+it('can keep nested context when flat option is disabled', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const context = { correlationId: 'ABCD1234', interactor: 'Informer' }
+  const logger = new Logger({ global: mockGlobal, context, flat: false })
 
   logger.info('Logging something...')
-  expect(mockGlobal.infoArgs).toEqual([
-    '2025-02-15T00:00:00.000Z [INFO]', 
-    JSON.stringify({ correlationId: 'ABCD1234', interactor: 'Informer' }),
-    'Logging something...'])
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    context,
+    message: 'Logging something...'
+  })
+})
 
-  logger.debug('Logging something...')
-  expect(mockGlobal.debugArgs).toEqual([
-    '2025-02-15T00:00:00.000Z [DEBUG]',
-    JSON.stringify({ correlationId: 'ABCD1234', interactor: 'Informer' }),
-    'Logging something...'])
+it('keeps log metadata and payload fields over flat context collisions', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.CORE_LOGLEVEL = 'info'
+  const context = {
+    timestamp: 'old',
+    level: 'fatal',
+    namespace: 'context-namespace',
+    message: 'context message',
+    args: ['context args'],
+    correlationId: 'ABCD1234'
+  }
+  const logger = new Logger({
+    global: mockGlobal,
+    namespace: 'core',
+    context,
+    flat: true
+  })
+
+  logger.info('real message', 'value')
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    namespace: 'core',
+    message: 'real message',
+    args: ['context args'],
+    correlationId: 'ABCD1234',
+    arg1: 'value'
+  })
 })
 
 it('supports including static context labels', () => {
+  const originalContext = Logger.context
   Logger.context = () => {
     return { correlationId: 'ABCD1234' }
   }
 
+  try {
+    const { mockGlobal } = setup()
+    mockGlobal.LOGLEVEL = 'debug'
+    const context = { model: 'Product' }
+    const logger = new Logger({ global: mockGlobal, context })
+
+    logger.info('Logging something...')
+    assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+      timestamp: '2025-02-15T00:00:00.000Z',
+      level: 'info',
+      correlationId: 'ABCD1234',
+      model: 'Product',
+      message: 'Logging something...'
+    })
+  } finally {
+    Logger.context = originalContext
+  }
+})
+
+it('includes namespace in JSON output and uses the namespace loglevel variable', () => {
   const { mockGlobal } = setup()
-  mockGlobal.LOGLEVEL = 'debug'
-  const context = { model: 'Product' }
-  const logger = new Logger({ global: mockGlobal, context })
+  mockGlobal.CORE_LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal, namespace: 'core' })
 
   logger.info('Logging something...')
-  expect(mockGlobal.infoArgs).toEqual([
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    namespace: 'core',
+    message: 'Logging something...'
+  })
+})
+
+it('merges non-string object payloads into the JSON record', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  logger.info({ code: 'E_UNEXPECTED' })
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    code: 'E_UNEXPECTED'
+  })
+})
+
+it('stores null payloads as positional fields in JSON format', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  logger.info(null)
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    arg0: null
+  })
+})
+
+it('serializes Error payloads in JSON format', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'error'
+  const logger = new Logger({ global: mockGlobal })
+  const error = new Error('Unexpected failure')
+  error.code = 'E_UNEXPECTED'
+
+  logger.error(error)
+  const record = parseRecord(mockGlobal.errorArgs)
+
+  assert.strictEqual(record.level, 'error')
+  assert.strictEqual(record.name, 'Error')
+  assert.strictEqual(record.message, 'Unexpected failure')
+  assert.strictEqual(record.code, 'E_UNEXPECTED')
+  assert.match(record.stack, /Unexpected failure/)
+})
+
+it('serializes nested Error values inside object payloads', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+  const nested = new Error('Nested failure')
+  nested.code = 'E_NESTED'
+
+  logger.info({ nested })
+  const record = parseRecord(mockGlobal.infoArgs)
+
+  assert.strictEqual(record.nested.name, 'Error')
+  assert.strictEqual(record.nested.message, 'Nested failure')
+  assert.strictEqual(record.nested.code, 'E_NESTED')
+  assert.match(record.nested.stack, /Nested failure/)
+})
+
+it('lets additional payload fields overwrite previously defined keys', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+  const error = new TypeError('Bad input')
+  error.field = 'name'
+
+  logger.info('Validation failed', error)
+  const record = parseRecord(mockGlobal.infoArgs)
+
+  assert.strictEqual(record.message, 'Bad input')
+  assert.strictEqual(record.name, 'TypeError')
+  assert.strictEqual(record.field, 'name')
+  assert.match(record.stack, /Bad input/)
+})
+
+it('serializes special values and circular references in merged JSON fields', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+  const payload = {
+    count: 10n,
+    token: Symbol('auth')
+  }
+  payload.self = payload
+
+  logger.info('Special payload', (function () {}), function namedFn () {}, payload)
+  const record = parseRecord(mockGlobal.infoArgs)
+
+  assert.strictEqual(record.message, 'Special payload')
+  assert.strictEqual(record.arg1, '[Function anonymous]')
+  assert.strictEqual(record.arg2, '[Function namedFn]')
+  assert.strictEqual(record.count, '10')
+  assert.strictEqual(record.token, 'Symbol(auth)')
+  assert.strictEqual(record.self.count, '10')
+  assert.strictEqual(record.self.token, 'Symbol(auth)')
+  assert.strictEqual(record.self.self, '[Circular]')
+})
+
+it('stores array payloads as positional fields in JSON format', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  logger.info('Array payload', [1, 2, 3])
+  assert.deepStrictEqual(parseRecord(mockGlobal.infoArgs), {
+    timestamp: '2025-02-15T00:00:00.000Z',
+    level: 'info',
+    message: 'Array payload',
+    arg1: [1, 2, 3]
+  })
+})
+
+it('supports plain formatting for backward compatibility', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const context = { correlationId: 'ABCD1234' }
+  const logger = new Logger({ global: mockGlobal, context, format: 'plain' })
+
+  logger.info('Logging something...', 0, false)
+  assert.deepStrictEqual(mockGlobal.infoArgs, [
     '2025-02-15T00:00:00.000Z [INFO]',
-    JSON.stringify({ correlationId: 'ABCD1234', model: 'Product' }),
-    'Logging something...'])
+    JSON.stringify(context),
+    'Logging something...',
+    0,
+    false
+  ])
+})
+
+it('supports plain formatting without context labels', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal, format: 'plain' })
+
+  logger.info()
+  assert.deepStrictEqual(mockGlobal.infoArgs, [
+    '2025-02-15T00:00:00.000Z [INFO]'
+  ])
+})
+
+it('reports JSON records to Journald when the global flag is enabled', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  journaldTransportState.lastFields = null
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal })
+
+  logger.info('Journald event', { action: 'create' })
+
+  const fields = journaldTransportState.lastFields
+  assert.ok(fields)
+  assert.deepStrictEqual(fields, {
+    PRIORITY: 6,
+    MESSAGE: 'Journald event',
+    TIMESTAMP: '2025-02-15T00:00:00.000Z',
+    LEVEL: 'info',
+    ACTION: 'create'
+  })
+
+  delete mockGlobal.JOURNALD
+})
+
+it('serializes nested context for Journald when flattening is disabled', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const context = { correlationId: 'ABCD1234', nested: { role: 'admin' } }
+  journaldTransportState.lastFields = null
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal, context, flat: false })
+
+  logger.info('Nested context')
+
+  const fields = journaldTransportState.lastFields
+  assert.ok(fields)
+  assert.strictEqual(fields.CONTEXT, JSON.stringify(context))
+  assert.strictEqual(fields.MESSAGE, 'Nested context')
+  assert.strictEqual(fields.PRIORITY, 6)
+
+  delete mockGlobal.JOURNALD
+})
+
+it('defaults Journald MESSAGE to an empty string when no message is provided', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal })
+  let recorded
+  logger.journald = (fields) => { recorded = fields }
+
+  const payload = { action: 'create', detail: undefined }
+  logger.info(payload)
+
+  assert.ok(recorded)
+  assert.strictEqual(recorded.MESSAGE, '')
+  assert.strictEqual(recorded.ACTION, 'create')
+  assert.ok(!('DETAIL' in recorded))
+
+  delete mockGlobal.JOURNALD
+})
+
+it('falls back to the default Journald priority when the level is missing', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal })
+  let recorded
+  logger.journald = (fields) => { recorded = fields }
+
+  const original = JOURNAL_PRIORITY.info
+  delete JOURNAL_PRIORITY.info
+
+  try {
+    logger.info('Fallback priority')
+    assert.ok(recorded)
+    assert.strictEqual(recorded.PRIORITY, 6)
+  } finally {
+    JOURNAL_PRIORITY.info = original
+    delete mockGlobal.JOURNALD
+  }
+})
+
+it('serializes null, function, and symbol values for Journald payloads', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  mockGlobal.JOURNALD = true
+  const logger = new Logger({ global: mockGlobal })
+  let recorded
+  logger.journald = (fields) => { recorded = fields }
+
+  const symbol = Symbol('token')
+  function namedFn () {}
+  const anonymousFn = Object.defineProperty(function () {}, 'name', { value: '' })
+  const payload = {
+    value: null,
+    handler: namedFn,
+    key: symbol,
+    unused: undefined,
+    data: { detail: 'rich' },
+    shadowed: anonymousFn
+  }
+  logger.info('Special types', payload)
+
+  assert.ok(recorded)
+  assert.strictEqual(recorded.VALUE, 'null')
+  assert.strictEqual(recorded.HANDLER, '[Function namedFn]')
+  assert.strictEqual(recorded.KEY, 'Symbol(token)')
+  assert.strictEqual(recorded.DATA, JSON.stringify(payload.data))
+  assert.strictEqual(recorded.SHADOWED, '[Function anonymous]')
+  assert.ok(!('UNUSED' in recorded))
+
+  delete mockGlobal.JOURNALD
+})
+
+it('includes the namespace as SYSLOG_IDENTIFIER in Journald payloads', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.CORE_LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal, namespace: 'core' })
+
+  let recorded
+  logger.journald = (fields) => {
+    recorded = fields
+  }
+
+  logger.info('Namespaced event', { module: 'inventory' })
+
+  assert.ok(recorded)
+  assert.strictEqual(recorded.SYSLOG_IDENTIFIER, 'core')
+  assert.strictEqual(recorded.MESSAGE, 'Namespaced event')
+  assert.strictEqual(recorded.MODULE, 'inventory')
+})
+
+it('calls journald transports that are functions directly', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  const payloads = []
+  logger.journald = (fields) => {
+    payloads.push(fields)
+  }
 
-})
+  logger.info('Function transport')
+
+  assert.strictEqual(payloads.length, 1)
+  assert.strictEqual(payloads[0].LEVEL, 'info')
+  assert.strictEqual(payloads[0].MESSAGE, 'Function transport')
+})
+
+it('prefers send() when the Journald transport exposes it', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  const payloads = []
+  logger.journald = {
+    send (fields) {
+      payloads.push(fields)
+    }
+  }
+
+  logger.info('Send transport')
+
+  assert.strictEqual(payloads.length, 1)
+  assert.strictEqual(payloads[0].MESSAGE, 'Send transport')
+})
+
+it('falls back to log() when send() is unavailable', () => {
+  const { mockGlobal } = setup()
+  mockGlobal.LOGLEVEL = 'info'
+  const logger = new Logger({ global: mockGlobal })
+
+  const payloads = []
+  logger.journald = {
+    log (fields) {
+      payloads.push(fields)
+    }
+  }
+
+  logger.info('Log transport')
+
+  assert.strictEqual(payloads.length, 1)
+  assert.strictEqual(payloads[0].MESSAGE, 'Log transport')
+})

package/lib/translator.test.js

@@ -1,9 +1,10 @@
-import { it, expect } from '@jest/globals'
+import assert from 'node:assert/strict'
+import { it } from 'node:test'
 import { Translator, t, lt } from './translator.js'
 
 it('can be instantiated', () => {
   const translator = new Translator()
-  expect(translator).toBeTruthy()
+  assert.ok(translator)
 })
 
 it('defines a translate function with options', () => {
@@ -11,7 +12,7 @@ it('defines a translate function with options', () => {
 
   const result = translator.translate('any.key') 
 
-  expect(result).toBe('any.key')
+  assert.strictEqual(result, 'any.key')
 })
 
 it('defines a t shortcut for function translate', () => {
@@ -19,30 +20,36 @@ it('defines a t shortcut for function translate', () => {
 
   const result = t('any.key') 
 
-  expect(result).toBe('any.key')
+  assert.strictEqual(result, 'any.key')
 })
 
 it('defines a global t shortcut translate', () => {
   const originalTranslate = Translator.translate
-  Translator.translate = (key, _options) => {
-    return `translated:${key}`
-  }
+  try {
+    Translator.translate = (key, _options) => {
+      return `translated:${key}`
+    }
 
-  const result = t('any.key') 
+    const result = t('any.key') 
 
-  expect(result).toBe('translated:any.key')
-  Translator.translate = originalTranslate
+    assert.strictEqual(result, 'translated:any.key')
+  } finally {
+    Translator.translate = originalTranslate
+  }
 })
 
 it('defines a global lt lazy-translation function', () => {
   const originalTranslate = Translator.translate
-  Translator.translate = (key, _options) => {
-    return `translated:${key}`
-  }
+  try {
+    Translator.translate = (key, _options) => {
+      return `translated:${key}`
+    }
 
-  const result = lt('any.key') 
+    const result = lt('any.key') 
 
-  expect(result).toBeInstanceOf(Function)
-  expect(result()).toBe('translated:any.key')
-  Translator.translate = originalTranslate
+    assert.ok(result instanceof Function)
+    assert.strictEqual(result(), 'translated:any.key')
+  } finally {
+    Translator.translate = originalTranslate
+  }
 })

package/lib/utilities/journald-socket.js

@@ -0,0 +1,51 @@
+import { createSocket } from 'node:dgram'
+
+const JOURNAL_SOCKET_PATH = '/run/systemd/journal/socket'
+
+function buildTransport (createSocketImplementation) {
+  try {
+    const socket = createSocketImplementation({ type: 'unix_dgram' })
+    let activeSocket = socket
+
+    const cleanup = () => {
+      if (!activeSocket) return
+      activeSocket.close()
+      activeSocket = null
+    }
+
+    socket.on('error', cleanup)
+    socket.on('close', cleanup)
+    socket.connect(JOURNAL_SOCKET_PATH, (error) => {
+      if (error) cleanup()
+    })
+    socket.unref?.()
+
+    return {
+      send (fields) {
+        if (!activeSocket) return
+        const payload = Buffer.from(
+          Object.entries(fields).map(
+            ([key, value]) => `${key}=${value}`).join('\n') + '\n')
+        activeSocket.send(payload, (error) => {
+          if (error) cleanup()
+        })
+      }
+    }
+  } catch (error) {
+    throw error
+  }
+}
+
+export function createJournaldTransport ({ createSocket: createSocketImplementation } = {}) {
+  try {
+    return buildTransport(createSocketImplementation ?? createSocket)
+  } catch (error) {
+    return null
+  }
+}
+
+export const journaldSocket = {
+  createTransport (options) {
+    return createJournaldTransport(options)
+  }
+}

package/lib/utilities/journald-socket.test.js

@@ -0,0 +1,105 @@
+import assert from 'node:assert/strict'
+import { it } from 'node:test'
+import { createJournaldTransport, journaldSocket } from './journald-socket.js'
+
+function createFakeSocket ({ connectError = null, sendError = null } = {}) {
+  const events = {}
+  return {
+    events,
+    connectedPath: null,
+    sentPayload: null,
+    sendCalls: 0,
+    closed: false,
+    on (event, callback) {
+      events[event] = callback
+    },
+    connect (path, callback) {
+      this.connectedPath = path
+      callback?.(connectError)
+    },
+    send (payload, callback) {
+      this.sentPayload = payload
+      this.sendCalls += 1
+      callback?.(sendError)
+    },
+    close () {
+      this.closed = true
+    },
+    unref () {}
+  }
+}
+
+it('falls back to the built-in socket factory when no override is supplied', () => {
+  const transport = createJournaldTransport()
+
+  assert.ok(transport === null || typeof transport.send === 'function')
+})
+
+it('establishes a journald socket and encodes payloads', () => {
+  const socket = createFakeSocket()
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  assert.ok(transport)
+  assert.strictEqual(socket.connectedPath, '/run/systemd/journal/socket')
+
+  transport.send({ foo: 'bar', baz: 'qux' })
+  assert.strictEqual(socket.sendCalls, 1)
+  assert.strictEqual(socket.sentPayload.toString(), 'foo=bar\nbaz=qux\n')
+})
+
+it('silently ignores send once cleanup runs after an error event', () => {
+  const socket = createFakeSocket()
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  socket.events.error?.(new Error('boom'))
+
+  transport.send({ foo: 'bar' })
+  assert.strictEqual(socket.sendCalls, 0)
+  assert.strictEqual(socket.closed, true)
+})
+
+it('returns null when the socket factory throws', () => {
+  const transport = createJournaldTransport({ createSocket: () => { throw new Error('failed') } })
+  assert.strictEqual(transport, null)
+})
+
+it('exposes the same transport via journaldSocket.createTransport', () => {
+  const socket = createFakeSocket()
+  const createSocket = () => socket
+  const transport = journaldSocket.createTransport({ createSocket })
+
+  assert.ok(transport)
+  assert.strictEqual(socket.connectedPath, '/run/systemd/journal/socket')
+})
+
+it('runs cleanup when connect reports an error', () => {
+  const socket = createFakeSocket({ connectError: new Error('connect fail') })
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  assert.ok(transport)
+  assert.strictEqual(socket.closed, true)
+
+  transport.send({ foo: 'bar' })
+  assert.strictEqual(socket.sendCalls, 0)
+})
+
+it('runs cleanup when send reports an error', () => {
+  const socket = createFakeSocket({ sendError: new Error('send fail') })
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  transport.send({ foo: 'bar' })
+  assert.strictEqual(socket.closed, true)
+  assert.strictEqual(socket.sendCalls, 1)
+})
+
+it('safely ignores repeated cleanup calls', () => {
+  const socket = createFakeSocket()
+  const transport = createJournaldTransport({ createSocket: () => socket })
+
+  socket.events.error?.(new Error('boom'))
+  socket.events.error?.(new Error('boom again'))
+
+  transport.send({ foo: 'bar' })
+  assert.strictEqual(socket.closed, true)
+  assert.strictEqual(socket.sendCalls, 0)
+})

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@knowark/loggarkjs",
-  "version": "0.3.11",
+  "version": "0.5.0",
   "description": "Utilitarian Logging Library",
   "main": "./lib/index.js",
   "type": "module",
   "scripts": {
-    "options": "NODE_OPTIONS='--experimental-vm-modules --no-warnings'",
-    "test": "npm run options -- npx jest --coverage"
+    "test": "node --test --experimental-test-coverage --test-coverage-exclude='**/*.test.js'"
   },
   "repository": {
     "type": "git",
@@ -21,8 +20,5 @@
   "bugs": {
     "url": "https://github.com/knowark/loggarkjs/issues"
   },
-  "homepage": "https://github.com/knowark/loggarkjs#readme",
-  "devDependencies": {
-    "jest": "^29.7.0"
-  }
+  "homepage": "https://github.com/knowark/loggarkjs#readme"
 }

package/.vscode/settings.json

@@ -1,7 +0,0 @@
-{
-  "workbench.colorCustomizations": {
-    "activityBar.background": "#2C2D34",
-    "titleBar.activeBackground": "#3E3F49",
-    "titleBar.activeForeground": "#FAFAFB"
-  }
-}