@dxos/log 0.8.4-main.f9ba587 → 0.8.4-main.fcfe5033a5

package/package.json

@@ -1,27 +1,47 @@
 {
   "name": "@dxos/log",
-  "version": "0.8.4-main.f9ba587",
+  "version": "0.8.4-main.fcfe5033a5",
   "description": "Logger",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
+  "imports": {
+    "#platform": {
+      "source": {
+        "browser": "./src/platform/browser/index.ts",
+        "default": "./src/platform/node/index.ts"
+      },
+      "types": "./dist/types/src/platform/node/index.d.ts",
+      "browser": "./dist/lib/browser/platform/browser/index.mjs",
+      "default": "./dist/lib/node-esm/platform/node/index.mjs"
+    },
+    "#console-processor": {
+      "source": {
+        "browser": "./src/processors/console-stub.ts",
+        "default": "./src/processors/console-processor.ts"
+      },
+      "types": "./dist/types/src/processors/console-processor.d.ts",
+      "browser": "./dist/lib/browser/processors/console-stub.mjs",
+      "default": "./dist/lib/node-esm/processors/console-processor.mjs"
+    }
+  },
   "exports": {
     ".": {
+      "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": {
         "require": "./dist/lib/node/index.cjs",
         "default": "./dist/lib/node-esm/index.mjs"
-      },
-      "types": "./dist/types/src/index.d.ts"
+      }
     }
   },
-  "browser": {
-    "./src/platform/node/index.ts": "./src/platform/browser/index.ts",
-    "./src/processors/console-processor.ts": "./src/processors/console-stub.ts"
-  },
   "types": "dist/types/src/index.d.ts",
   "typesVersions": {
     "*": {}
@@ -31,17 +51,15 @@
     "src"
   ],
   "dependencies": {
-    "chalk": "^4.1.0",
-    "js-yaml": "^4.1.0",
+    "chalk": "^4.1.2",
+    "js-yaml": "4.1.1",
     "lodash.defaultsdeep": "^4.6.1",
-    "lodash.omit": "^4.5.0",
-    "@dxos/node-std": "0.8.4-main.f9ba587",
-    "@dxos/util": "0.8.4-main.f9ba587"
+    "@dxos/node-std": "0.8.4-main.fcfe5033a5",
+    "@dxos/util": "0.8.4-main.fcfe5033a5"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.5",
-    "@types/lodash.defaultsdeep": "^4.6.6",
-    "@types/lodash.omit": "^4.5.7"
+    "@types/lodash.defaultsdeep": "^4.6.6"
   },
   "publishConfig": {
     "access": "public"

package/src/config.ts

@@ -6,8 +6,8 @@ import { type LogProcessor } from './context';
 
 /**
  * Standard levels.
+ * NOTE: Keep aligned with LogLevel in @dxos/protocols.
  */
-// NOTE: Keep aligned with LogLevel in @dxos/protocols.
 // TODO(burdon): Update numbers?
 export enum LogLevel {
   TRACE = 5,
@@ -18,7 +18,8 @@ export enum LogLevel {
   ERROR = 14,
 }
 
-export const levels: { [index: string]: LogLevel } = {
+export const levels: Record<string, LogLevel> = {
+  '*': LogLevel.TRACE,
   trace: LogLevel.TRACE,
   debug: LogLevel.DEBUG,
   verbose: LogLevel.VERBOSE,

package/src/context.ts

@@ -16,7 +16,7 @@ export type LogContext = Record<string, any> | Error | any;
  */
 export interface LogEntry {
   level: LogLevel;
-  message: string;
+  message?: string;
   context?: LogContext;
   meta?: CallMetadata;
   error?: Error;
@@ -27,8 +27,33 @@ export interface LogEntry {
  */
 export type LogProcessor = (config: LogConfig, entry: LogEntry) => void;
 
-const matchFilter = (filter: LogFilter, level: LogLevel, path: string) => {
-  return level >= filter.level && (!filter.pattern || path.includes(filter.pattern));
+/**
+ * Returns:
+ * true if the log entry matches the filter,
+ * false if should be excluded, or
+ * undefined if it the filter doesn't match the level.
+ */
+const matchFilter = (filter: LogFilter, level: LogLevel, path?: string): boolean | undefined => {
+  // TODO(burdon): Support regexp.
+  if (filter.pattern?.startsWith('-')) {
+    // Exclude.
+    if (path?.includes(filter.pattern.slice(1))) {
+      if (level >= filter.level) {
+        return false;
+      }
+    }
+  } else {
+    // Include.
+    if (filter.pattern?.length) {
+      if (path?.includes(filter.pattern)) {
+        return level >= filter.level;
+      }
+    } else {
+      if (level >= filter.level) {
+        return true;
+      }
+    }
+  }
 };
 
 /**
@@ -36,10 +61,16 @@ const matchFilter = (filter: LogFilter, level: LogLevel, path: string) => {
  */
 export const shouldLog = (entry: LogEntry, filters?: LogFilter[]): boolean => {
   if (filters === undefined) {
-    return true;
-  } else {
-    return filters.some((filter) => matchFilter(filter, entry.level, entry.meta?.F ?? ''));
+    return false;
   }
+
+  const results = filters
+    .map((filter) => matchFilter(filter, entry.level, entry.meta?.F))
+    .filter((result): result is boolean => result !== undefined);
+
+  // Skip if any are explicitely false.
+  // console.log({ level: entry.level, path: entry.meta?.F }, filters, results, results.length);
+  return results.length > 0 && !results.some((results) => results === false);
 };
 
 export const getContextFromEntry = (entry: LogEntry): Record<string, any> | undefined => {
@@ -64,8 +95,7 @@ export const getContextFromEntry = (entry: LogEntry): Record<string, any> | unde
   }
 
   if (entry.error) {
-    const errorContext = (entry.error as any).context;
-    context = Object.assign(context ?? {}, { error: entry.error, ...errorContext });
+    context = Object.assign(context ?? {}, { error: entry.error });
   }
 
   return context && Object.keys(context).length > 0 ? context : undefined;

package/src/dbg.ts

@@ -0,0 +1,34 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type CallMetadata } from './meta';
+/**
+ * Debug-log value to console.
+ * Log's the expression being evaluated.
+ *
+ * If only one argument is provided, it will also be returned.
+ *
+ * @example
+ * ```ts
+ * dbg(foo, bar);
+ * // foo = 1
+ * // bar = 2
+ *
+ * bar = dbg(foo * 2);
+ * // foo * 2 = 2
+ * ```
+ *
+ * NOTE: The second argument is injected by the log transform plugin.
+ */
+export const dbg: {
+  <T>(value: T, _meta?: CallMetadata): T;
+} = <T>(arg: T, meta?: CallMetadata): T => {
+  if (meta?.A) {
+    console.log(`${meta.A[0]} =`, arg);
+  } else {
+    console.log(arg);
+  }
+
+  return arg;
+};

package/src/decorators.ts

@@ -5,7 +5,7 @@
 import chalk from 'chalk';
 import { inspect } from 'node:util';
 
-import type { LogMethods } from './log';
+import { type LogMethods } from './log';
 import { type CallMetadata } from './meta';
 
 let nextPromiseId = 0;
@@ -190,13 +190,13 @@ const logAsyncRejected = (
   );
 };
 
+const COLOR_FUNCTION = [220, 220, 170] as const;
+
 // https://github.com/dxos/dxos/issues/7286
 const greenCheck = typeof chalk.green === 'function' ? chalk.green('✔') : '✔';
 
 const formatTimeElapsed = (startTime: number) => chalk.gray(`${(performance.now() - startTime).toFixed(0)}ms`);
 
-const COLOR_FUNCTION = [220, 220, 170] as const;
-
 const formatFunction = (name: string) => chalk.bold(chalk.rgb(...COLOR_FUNCTION)(name));
 
 const formatPromise = (id: number) => chalk.blue(`Promise#${id}`);

package/src/experimental/classes.test.ts

@@ -4,8 +4,8 @@
 
 import { describe, test } from 'vitest';
 
-import { debugInfo, ownershipClass } from './ownership';
 import { log } from '../log';
+import { debugInfo, ownershipClass } from './ownership';
 
 describe('classes', function () {
   test('field instance', function () {

package/src/index.ts

@@ -2,9 +2,7 @@
 // Copyright 2022 DXOS.org
 //
 
-import omit from 'lodash.omit';
-
-import { pick } from '@dxos/util';
+import { omit, pick } from '@dxos/util';
 
 export { omit, pick };
 
@@ -14,6 +12,8 @@ export * from './log';
 export { parseFilter } from './options';
 export * from './processors';
 export * from './scope';
-export * from './meta';
+export type * from './meta';
+export { dbg } from './dbg';
+export * from './log-buffer';
 
 export { getCurrentOwnershipScope } from './experimental/ownership';

package/src/log-buffer.test.ts

@@ -0,0 +1,155 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { type LogConfig, type LogEntry, LogLevel } from './index';
+import { LogBuffer } from './log-buffer';
+
+const baseConfig: LogConfig = {
+  options: {},
+  filters: [{ level: LogLevel.DEBUG }],
+  processors: [],
+};
+
+const createEntry = (overrides: Partial<LogEntry> = {}): 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]);
+    expect(record.c).toBeUndefined();
+  });
+
+  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,117 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { CircularBuffer, getDebugName } from '@dxos/util';
+
+import { type LogConfig, LogLevel, shortLevelName } from './config';
+import { type LogEntry, type LogProcessor } from './context';
+
+const DEFAULT_BUFFER_SIZE = 2_000;
+const MAX_CONTEXT_LENGTH = 500;
+
+/**
+ * Compact log record with short property names for small serialized size.
+ */
+export type LogRecord = {
+  /** ISO timestamp. */
+  t: string;
+  /** Level letter (D, V, I, W, E). */
+  l: string;
+  /** Message. */
+  m: string;
+  /** File path. */
+  f?: string;
+  /** Line number. */
+  n?: number;
+  /* Object from which the log was emitted. */
+  o?: string;
+  /** Error stack. */
+  e?: string;
+  /** Context JSON. */
+  c?: string;
+};
+
+/**
+ * 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 record: LogRecord = {
+      t: new Date().toISOString(),
+      l: shortLevelName[entry.level] ?? '?',
+      m: entry.message ?? '',
+    };
+
+    if (entry.meta) {
+      record.f = getRelativeFilename(entry.meta.F);
+      record.n = entry.meta.L;
+    }
+
+    if (entry.error) {
+      record.e = entry.error.stack ?? entry.error.message;
+    }
+
+    if (entry.context != null) {
+      try {
+        const ctx = typeof entry.context === 'function' ? entry.context() : entry.context;
+        if (ctx != null && !(ctx instanceof Error)) {
+          let json = JSON.stringify(ctx);
+          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.
+      }
+    }
+    const scope = entry.meta?.S;
+    if (typeof scope === 'object' && scope !== null && Object.getPrototypeOf(scope) !== Object.prototype) {
+      record.o = getDebugName(scope);
+    }
+
+    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');
+  }
+}
+
+const getRelativeFilename = (filename: string): string => {
+  const match = filename.match(/.+\/(packages\/.+\/.+)/);
+  if (match) {
+    return match[1];
+  }
+  return filename;
+};

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);
+  });
 });