@dxos/log 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

package/src/log-buffer.test.ts

@@ -0,0 +1,158 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { type LogConfig, LogEntry, type LogEntryInit, LogLevel } from './index';
+import { LogBuffer } from './log-buffer';
+
+const baseConfig: LogConfig = {
+  options: {},
+  filters: [{ level: LogLevel.DEBUG }],
+  processors: [],
+};
+
+const createEntry = (overrides: Partial<LogEntryInit> = {}): LogEntry =>
+  new LogEntry({
+    level: LogLevel.INFO,
+    message: 'test message',
+    ...overrides,
+  });
+
+describe('LogBuffer', () => {
+  test('pushes and serializes log entries', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ message: 'hello' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'world' }));
+
+    expect(buffer.size).toBe(2);
+    const lines = buffer.serialize().split('\n');
+    expect(lines).toHaveLength(2);
+
+    const first = JSON.parse(lines[0]);
+    expect(first.m).toBe('hello');
+    expect(first.l).toBe('I');
+    expect(first.t).toBeDefined();
+
+    const second = JSON.parse(lines[1]);
+    expect(second.m).toBe('world');
+  });
+
+  test('evicts oldest entries when buffer is full', ({ expect }) => {
+    const buffer = new LogBuffer(3);
+    buffer.logProcessor(baseConfig, createEntry({ message: 'a' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'b' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'c' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'd' }));
+
+    expect(buffer.size).toBe(3);
+    const lines = buffer.serialize().split('\n');
+    const messages = lines.map((line) => JSON.parse(line).m);
+    expect(messages).toEqual(['b', 'c', 'd']);
+  });
+
+  test('skips TRACE-level logs', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ level: LogLevel.TRACE, message: 'trace' }));
+    expect(buffer.size).toBe(0);
+  });
+
+  test('captures DEBUG-level and above', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ level: LogLevel.DEBUG, message: 'debug' }));
+    buffer.logProcessor(baseConfig, createEntry({ level: LogLevel.WARN, message: 'warn' }));
+    buffer.logProcessor(baseConfig, createEntry({ level: LogLevel.ERROR, message: 'error' }));
+
+    expect(buffer.size).toBe(3);
+    const lines = buffer.serialize().split('\n');
+    expect(JSON.parse(lines[0]).l).toBe('D');
+    expect(JSON.parse(lines[1]).l).toBe('W');
+    expect(JSON.parse(lines[2]).l).toBe('E');
+  });
+
+  test('captures file and line metadata', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(
+      baseConfig,
+      createEntry({
+        meta: { F: '/home/user/project/packages/sdk/test.ts', L: 42, S: undefined },
+      }),
+    );
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.f).toBe('packages/sdk/test.ts');
+    expect(record.n).toBe(42);
+  });
+
+  test('captures error stack', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    const error = new Error('boom');
+    buffer.logProcessor(baseConfig, createEntry({ error }));
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.e).toContain('boom');
+  });
+
+  test('truncates context to 500 chars', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    const longValue = 'x'.repeat(1000);
+    buffer.logProcessor(baseConfig, createEntry({ context: { data: longValue } }));
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.c).toBeDefined();
+    expect(record.c!.length).toBe(500);
+  });
+
+  test('skips Error context objects', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ context: new Error('ctx error') }));
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    expect(record.c).toBeUndefined();
+  });
+
+  test('handles non-serializable context gracefully', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    const circular: Record<string, any> = {};
+    circular.self = circular;
+    buffer.logProcessor(baseConfig, createEntry({ context: circular }));
+
+    const lines = buffer.serialize().split('\n');
+    const record = JSON.parse(lines[0]);
+    // Circular values fall back to String(value) rather than dropping the entry.
+    expect(record.c).toBeDefined();
+    expect(JSON.parse(record.c!).self).toBe('[object Object]');
+  });
+
+  test('serialize returns empty string for empty buffer', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    expect(buffer.serialize()).toBe('');
+  });
+
+  test('clear discards all entries', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ message: 'a' }));
+    buffer.logProcessor(baseConfig, createEntry({ message: 'b' }));
+    expect(buffer.size).toBe(2);
+
+    buffer.clear();
+    expect(buffer.size).toBe(0);
+    expect(buffer.serialize()).toBe('');
+  });
+
+  test('clear allows new entries', ({ expect }) => {
+    const buffer = new LogBuffer(10);
+    buffer.logProcessor(baseConfig, createEntry({ message: 'old' }));
+    buffer.clear();
+    buffer.logProcessor(baseConfig, createEntry({ message: 'new' }));
+
+    expect(buffer.size).toBe(1);
+    const record = JSON.parse(buffer.serialize());
+    expect(record.m).toBe('new');
+  });
+});

package/src/log-buffer.ts

@@ -0,0 +1,89 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { CircularBuffer } from '@dxos/util';
+
+import { type LogConfig, LogLevel, shortLevelName } from './config';
+import { type LogEntry, type LogProcessor } from './context';
+import { type LogRecord } from './jsonl';
+
+const DEFAULT_BUFFER_SIZE = 2_000;
+const MAX_CONTEXT_LENGTH = 500;
+
+/**
+ * Captures recent log entries in a circular buffer for debug log dump.
+ */
+export class LogBuffer {
+  private readonly _buffer: CircularBuffer<LogRecord>;
+
+  constructor(size = DEFAULT_BUFFER_SIZE) {
+    this._buffer = new CircularBuffer<LogRecord>(size);
+  }
+
+  /**
+   * Log processor that can be registered with `log.runtimeConfig.processors`.
+   * Captures every level except TRACE (does not apply `shouldLog` / filter; use for full debug dumps).
+   */
+  readonly logProcessor: LogProcessor = (_config: LogConfig, entry: LogEntry) => {
+    if (entry.level <= LogLevel.TRACE) {
+      return;
+    }
+
+    const { filename, line, context: scopeName } = entry.computedMeta;
+
+    const record: LogRecord = {
+      t: new Date(entry.timestamp).toISOString(),
+      l: shortLevelName[entry.level] ?? '?',
+      m: entry.message ?? '',
+    };
+
+    if (filename !== undefined) {
+      record.f = filename;
+    }
+    if (line !== undefined) {
+      record.n = line;
+    }
+    if (scopeName !== undefined) {
+      record.o = scopeName;
+    }
+
+    if (entry.computedError !== undefined) {
+      record.e = entry.computedError;
+    }
+
+    const computedContext = entry.computedContext;
+    if (Object.keys(computedContext).length > 0) {
+      try {
+        let json = JSON.stringify(computedContext);
+        if (json.length > MAX_CONTEXT_LENGTH) {
+          json = json.slice(0, MAX_CONTEXT_LENGTH);
+        }
+        record.c = json;
+      } catch {
+        // Skip context that throws or is non-serializable.
+      }
+    }
+
+    this._buffer.push(record);
+  };
+
+  /** Number of entries currently in the buffer. */
+  get size(): number {
+    return this._buffer.elementCount;
+  }
+
+  /** Discard all buffered entries. */
+  clear(): void {
+    this._buffer.clear();
+  }
+
+  /** Serialize buffer contents as NDJSON (newline-delimited JSON). */
+  serialize(): string {
+    const lines: string[] = [];
+    for (const record of this._buffer) {
+      lines.push(JSON.stringify(record));
+    }
+    return lines.join('\n');
+  }
+}

package/src/log.test.ts

@@ -3,10 +3,11 @@
 //
 
 import path from 'node:path';
-import { describe, test } from 'vitest';
+import { beforeEach, describe, test } from 'vitest';
 
 import { LogLevel } from './config';
-import { log } from './log';
+import { shouldLog } from './context';
+import { type Log, createLog } from './log';
 
 class LogError extends Error {
   constructor(
@@ -24,14 +25,53 @@ class LogError extends Error {
   }
 }
 
-log.config({
-  filter: LogLevel.DEBUG,
-});
+describe('log', () => {
+  let log!: Log;
+
+  beforeEach(() => {
+    log = createLog();
+    log.config({
+      filter: LogLevel.DEBUG,
+    });
+  });
 
-/* eslint-disable @stayradiated/prefer-arrow-functions/prefer-arrow-functions */
+  test('filters', ({ expect }) => {
+    const tests = [
+      { expected: 0, filter: 'ERROR' },
+      { expected: 2, filter: 'INFO' },
+      { expected: 1, filter: 'foo:INFO' },
+      { expected: 4, filter: 'DEBUG' },
+      { expected: 2, filter: 'DEBUG,-foo:*' },
+      { expected: 1, filter: 'INFO,-foo:*' },
+      { expected: 3, filter: 'DEBUG,-foo:INFO' },
+      { expected: 3, filter: 'foo:DEBUG,bar:INFO' },
+    ];
+
+    for (const test of tests) {
+      let count = 0;
+      const log = createLog();
+      const remove = log.addProcessor((config, entry) => {
+        if (shouldLog(entry, config.filters)) {
+          count++;
+        }
+      });
+      log.config({
+        filter: test.filter,
+      });
+
+      console.group(`Filter: "${test.filter}"`);
+      log.debug('line 1', {}, { F: 'foo.ts', L: 1, S: undefined });
+      log.info('line 2', {}, { F: 'foo.ts', L: 2, S: undefined });
+      log.debug('line 3', {}, { F: 'bar.ts', L: 3, S: undefined });
+      log.info('line 4', {}, { F: 'bar.ts', L: 4, S: undefined });
+      console.groupEnd();
+
+      expect(count, `Filter: "${test.filter}"`).toBe(test.expected);
+      remove();
+    }
+  });
 
-describe('log', function () {
-  test('throws an error', function () {
+  test('throws an error', () => {
     try {
       throw new LogError('Test failed', { value: 1 });
     } catch (err: any) {
@@ -39,7 +79,7 @@ describe('log', function () {
     }
   });
 
-  test('throws an error showing stacktrace', function () {
+  test('throws an error showing stacktrace', () => {
     try {
       throw new LogError('Test failed', { value: 2 });
     } catch (err: any) {
@@ -47,7 +87,7 @@ describe('log', function () {
     }
   });
 
-  test('catches an error', function () {
+  test('catches an error', () => {
     try {
       throw new LogError('ERROR ON LINE 21', { value: 3 });
     } catch (err: any) {
@@ -55,17 +95,7 @@ describe('log', function () {
     }
   });
 
-  test('config', function () {
-    log.config({
-      filter: LogLevel.INFO,
-    });
-
-    log.debug('Debug level log message');
-    log.info('Info level log message');
-    log.warn('Warn level log message');
-  });
-
-  test('config file', function () {
+  test('config file', () => {
     log.config({
       file: path.join('packages/common/log/test-config.yml'),
     });
@@ -75,7 +105,7 @@ describe('log', function () {
     log.warn('Warn level log message');
   });
 
-  test('levels', function () {
+  test('levels', () => {
     log('Default level log message');
     log.debug('Debug level log message');
     log.info('Info level log message');
@@ -83,10 +113,15 @@ describe('log', function () {
     log.error('Error level log message');
   });
 
-  test('context', function () {
+  test('context', () => {
     log.info('Message with context', {
       title: 'test',
       context: 123,
     });
   });
+
+  test('error', () => {
+    const myError = new Error('Test error', { cause: new Error('Cause') });
+    log.catch(myError);
+  });
 });

package/src/log.ts

@@ -3,10 +3,19 @@
 //
 
 import { type LogConfig, LogLevel, type LogOptions } from './config';
-import { type LogContext, type LogProcessor } from './context';
+import { type LogContext, LogEntry, type LogProcessor } from './context';
 import { createFunctionLogDecorator, createMethodLogDecorator } from './decorators';
 import { type CallMetadata } from './meta';
-import { getConfig, DEFAULT_PROCESSORS } from './options';
+import { createConfig } from './options';
+
+/**
+ * Accessible from browser console.
+ * Example: `DX_LOG.config({ filter: 'ERROR' })`
+ * NOTE: File level filtering isn't supported in storybooks.
+ */
+declare global {
+  const DX_LOG: Log;
+}
 
 /**
  * Logging function.
@@ -17,99 +26,185 @@ type LogFunction = (message: string, context?: LogContext, meta?: CallMetadata)
  * Logging methods.
  */
 export interface LogMethods {
+  config: (options?: LogOptions) => Log;
+  addProcessor: (processor: LogProcessor, addDefault?: boolean) => () => void;
+
+  /**
+   * Log at `trace` level.
+   *
+   * Generally not surfaced to the developer and not captured in a log file.
+   */
   trace: LogFunction;
+
+  /**
+   * Log at `debug` level.
+   * Generally not surfaced to the developer and captured in a log file.
+   */
   debug: LogFunction;
+
+  /**
+   * Log at `verbose` level.
+   * Generally not surfaced to the developer and not captured in a log file.
+   */
   verbose: LogFunction;
+
+  /**
+   * Log at `info` level.
+   * Generally surfaced to the developer and captured in a log file.
+   */
   info: LogFunction;
+
+  /**
+   * Log at `warn` level.
+   * Generally surfaced to the developer and captured in a log file.
+   */
   warn: LogFunction;
+
+  /**
+   * Log at `error` level.
+   * Generally surfaced to the developer and captured in a log file.
+   */
   error: LogFunction;
+
+  /**
+   * Log an error and its stack trace at an `error` level.
+   * Generally surfaced to the developer and captured in a log file.
+   */
   catch: (error: Error | any, context?: LogContext, meta?: CallMetadata) => void;
-  break: () => void;
-  stack: (message?: string, context?: never, meta?: CallMetadata) => void;
+
+  /**
+   * Decorator to log method parameters and return value at the `info` level.
+   */
   method: (arg0?: never, arg1?: never, meta?: CallMetadata) => MethodDecorator;
-  func: <F extends (...args: any[]) => any>(
+
+  /**
+   * Wrapper to log function parameters and return value at the `info` level.
+   */
+  function: <F extends (...args: any[]) => any>(
     name: string,
     fn: F,
-    opts?: { transformOutput?: (result: ReturnType<F>) => Promise<any> | any },
+    opts?: {
+      transformOutput?: (result: ReturnType<F>) => Promise<any> | any;
+    },
   ) => F;
+
+  /**
+   * Log a horizontal rule at the `info` level.
+   */
+  break: () => void;
+
+  /**
+   * Log a stack trace at the `info` level.
+   */
+  stack: (message?: string, context?: never, meta?: CallMetadata) => void;
 }
 
 /**
  * Properties accessible on the logging function.
+ * @internal
  */
-interface Log extends LogMethods, LogFunction {
-  config: (options: LogOptions) => void;
-  addProcessor: (processor: LogProcessor) => void;
-  runtimeConfig: LogConfig;
+export interface Log extends LogFunction, LogMethods {
+  readonly runtimeConfig: LogConfig;
 }
 
+/**
+ * @internal
+ */
 interface LogImp extends Log {
+  _id: string;
   _config: LogConfig;
 }
 
-const createLog = (): LogImp => {
-  const log: LogImp = ((...params) => processLog(LogLevel.DEBUG, ...params)) as LogImp;
-
-  log._config = getConfig();
-  Object.defineProperty(log, 'runtimeConfig', { get: () => log._config });
-
-  log.addProcessor = (processor: LogProcessor) => {
-    if (DEFAULT_PROCESSORS.filter((p) => p === processor).length === 0) {
-      DEFAULT_PROCESSORS.push(processor);
-    }
-    if (log._config.processors.filter((p) => p === processor).length === 0) {
-      log._config.processors.push(processor);
-    }
-  };
+let logCount = 0;
 
-  // Set config.
-  log.config = (options: LogOptions) => {
-    log._config = getConfig(options);
-  };
-
-  // TODO(burdon): API to set context and separate error object.
-  //  E.g., log.warn('failed', { key: 123 }, err);
-
-  log.trace = (...params) => processLog(LogLevel.TRACE, ...params);
-  log.debug = (...params) => processLog(LogLevel.DEBUG, ...params);
-  log.verbose = (...params) => processLog(LogLevel.VERBOSE, ...params);
-  log.info = (...params) => processLog(LogLevel.INFO, ...params);
-  log.warn = (...params) => processLog(LogLevel.WARN, ...params);
-  log.error = (...params) => processLog(LogLevel.ERROR, ...params);
-
-  // Catch only shows error message, not stacktrace.
-  log.catch = (error: Error | any, context, meta) =>
-    processLog(LogLevel.ERROR, error?.message ?? String(error), context, meta, error);
-
-  // Show break.
-  log.break = () => log.info('——————————————————————————————————————————————————');
+/**
+ * Create a logging function with properties.
+ * @internal
+ */
+export const createLog = (): LogImp => {
+  // Default function.
+  const log: LogImp = ((...params) => processLog(LogLevel.DEBUG, ...params)) as LogImp;
 
-  log.stack = (message, context, meta) =>
-    processLog(LogLevel.INFO, `${message ?? 'Stack Dump'}\n${getFormattedStackTrace()}`, context, meta);
+  // Add private properties.
+  Object.assign<LogImp, Partial<LogImp>>(log, {
+    _id: `log-${++logCount}`,
+    _config: createConfig(),
+  });
 
-  log.method = createMethodLogDecorator(log);
-  log.func = createFunctionLogDecorator(log);
+  // TODO(burdon): Document.
+  Object.defineProperty(log, 'runtimeConfig', {
+    get: () => log._config,
+  });
 
   /**
    * Process the current log call.
    */
   const processLog = (
     level: LogLevel,
-    message: string,
+    message: string | undefined,
     context: LogContext = {},
     meta?: CallMetadata,
     error?: Error,
   ) => {
-    log._config.processors.forEach((processor) => processor(log._config, { level, message, context, meta, error }));
+    // TODO(burdon): Do the filter matching upstream (here) rather than in each processor?
+    const entry = new LogEntry({ level, message, context, meta, error });
+    log._config.processors.forEach((processor) => processor(log._config, entry));
   };
 
+  /**
+   * API.
+   */
+  Object.assign<Log, LogMethods>(log, {
+    /**
+     * Update config.
+     * NOTE: Preserves any processors that were already added to this logger instance
+     * unless an explicit processor option is provided.
+     */
+    config: ({ processor, ...options } = {}) => {
+      const config = createConfig(options);
+      // TODO(burdon): This could be buggy since the behavior is not reentrant.
+      const processors = processor ? config.processors : log._config.processors;
+      log._config = { ...config, processors };
+      return log;
+    },
+
+    /**
+     * Adds a processor to the logger.
+     */
+    addProcessor: (processor) => {
+      if (log._config.processors.filter((p) => p === processor).length === 0) {
+        log._config.processors.push(processor);
+      }
+
+      return () => {
+        log._config.processors = log._config.processors.filter((p) => p !== processor);
+      };
+    },
+
+    trace: (...params) => processLog(LogLevel.TRACE, ...params),
+    debug: (...params) => processLog(LogLevel.DEBUG, ...params),
+    verbose: (...params) => processLog(LogLevel.VERBOSE, ...params),
+    info: (...params) => processLog(LogLevel.INFO, ...params),
+    warn: (...params) => processLog(LogLevel.WARN, ...params),
+    error: (...params) => processLog(LogLevel.ERROR, ...params),
+    catch: (error, context, meta) => processLog(LogLevel.ERROR, undefined, context, meta, error),
+
+    method: createMethodLogDecorator(log),
+    function: createFunctionLogDecorator(log),
+
+    break: () => log.info('-'.repeat(80)),
+    stack: (message, context, meta) => {
+      return processLog(LogLevel.INFO, `${message ?? 'Stack Dump'}\n${getFormattedStackTrace()}`, context, meta);
+    },
+  });
+
   return log;
 };
 
 /**
  * Global logging function.
  */
-export const log: Log = ((globalThis as any).dx_log ??= createLog());
+export const log: Log = ((globalThis as any).DX_LOG ??= createLog());
 
 const start = Date.now();
 let last = start;
@@ -129,12 +224,4 @@ export const debug = (label?: any, args?: any) => {
   last = Date.now();
 };
 
-/**
- * Accessible from browser console.
- */
-declare global {
-  // eslint-disable-next-line camelcase
-  const dx_log: Log;
-}
-
 const getFormattedStackTrace = () => new Error().stack!.split('\n').slice(3).join('\n');

package/src/meta.ts

@@ -3,11 +3,27 @@
 //
 
 /**
- * Metadata injected b y the log transform plugin.
+ * Marker key + value injected on every {@link CallMetadata} object by the log transform plugin.
+ * Used by {@link isLogMeta} to detect a log-meta argument at runtime (e.g. for variadic
+ * `param_index: 'last'` callees that don't have a fixed meta slot).
+ */
+export const LOG_META_MARKER = '~LogMeta';
+
+/**
+ * Metadata injected by the log transform plugin.
  *
  * Field names are intentionally short to reduce the size of the generated code.
  */
 export interface CallMetadata {
+  /**
+   * Marker tag — when present, equal to {@link LOG_META_MARKER} ({@link `'~LogMeta'`}).
+   * Injected by the log transform plugin on every emitted meta object so that {@link isLogMeta}
+   * can distinguish a meta argument from a regular user-supplied value at runtime.
+   * Optional because hand-written `CallMetadata` literals (decorators, RPC mappers, tests)
+   * don't need the marker — they are recognized by position in the call signature.
+   */
+  '~LogMeta'?: typeof LOG_META_MARKER;
+
   /**
    * File name.
    */
@@ -35,3 +51,15 @@ export interface CallMetadata {
    */
   A?: string[];
 }
+
+/**
+ * Type guard: `true` when `value` is a {@link CallMetadata} object emitted by the log transform plugin.
+ * Detection is based on the presence of the {@link LOG_META_MARKER} marker key/value.
+ */
+export const isLogMeta = (value: unknown): value is CallMetadata => {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    (value as Record<string, unknown>)[LOG_META_MARKER] === LOG_META_MARKER
+  );
+};