@dxos/log 0.8.4-main.c4373fc → 0.8.4-main.c85a9c8dae

package/package.json

@@ -1,13 +1,37 @@
 {
   "name": "@dxos/log",
-  "version": "0.8.4-main.c4373fc",
+  "version": "0.8.4-main.c85a9c8dae",
   "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",
@@ -18,10 +42,6 @@
       }
     }
   },
-  "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.c4373fc",
-    "@dxos/util": "0.8.4-main.c4373fc"
+    "@dxos/node-std": "0.8.4-main.c85a9c8dae",
+    "@dxos/util": "0.8.4-main.c85a9c8dae"
   },
   "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

@@ -19,6 +19,7 @@ export enum LogLevel {
 }
 
 export const levels: Record<string, LogLevel> = {
+  '*': LogLevel.TRACE,
   trace: LogLevel.TRACE,
   debug: LogLevel.DEBUG,
   verbose: LogLevel.VERBOSE,

package/src/context.ts

@@ -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 => {

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

@@ -6,7 +6,7 @@ import { inspect } from 'node:util';
 
 import chalk from 'chalk';
 
-import type { LogMethods } from './log';
+import { type LogMethods } from './log';
 import { type CallMetadata } from './meta';
 
 let nextPromiseId = 0;
@@ -191,13 +191,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/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 };
 
@@ -15,5 +13,7 @@ export { parseFilter } from './options';
 export * from './processors';
 export * from './scope';
 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,156 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { LogBuffer } from './log-buffer';
+
+import { type LogConfig, type LogEntry, LogLevel } from './index';
+
+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,108 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { CircularBuffer } 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;
+  /** 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`. */
+  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.
+      }
+    }
+
+    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

@@ -4,10 +4,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(
@@ -25,13 +26,52 @@ class LogError extends Error {
   }
 }
 
-log.config({
-  filter: LogLevel.DEBUG,
-});
+describe('log', () => {
+  let log!: Log;
 
-/* eslint-disable prefer-arrow-functions/prefer-arrow-functions */
+  beforeEach(() => {
+    log = createLog();
+    log.config({
+      filter: LogLevel.DEBUG,
+    });
+  });
+
+  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', () => {
   test('throws an error', () => {
     try {
       throw new LogError('Test failed', { value: 1 });
@@ -56,16 +96,6 @@ describe('log', () => {
     }
   });
 
-  test('config', () => {
-    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', () => {
     log.config({
       file: path.join('packages/common/log/test-config.yml'),
@@ -91,7 +121,7 @@ describe('log', () => {
     });
   });
 
-  test('error', function () {
+  test('error', () => {
     const myError = new Error('Test error', { cause: new Error('Cause') });
     log.catch(myError);
   });