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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/log",
-  "version": "0.8.4-main.fbb7a13",
+  "version": "0.8.4-main.fcfe5033a5",
   "description": "Logger",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -54,14 +54,12 @@
     "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.fbb7a13",
-    "@dxos/util": "0.8.4-main.fbb7a13"
+    "@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/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

@@ -2,9 +2,8 @@
 // Copyright 2023 DXOS.org
 //
 
-import { inspect } from 'node:util';
-
 import chalk from 'chalk';
+import { inspect } from 'node:util';
 
 import { type LogMethods } from './log';
 import { type CallMetadata } from './meta';

package/src/experimental/classes.test.ts

@@ -5,7 +5,6 @@
 import { describe, test } from 'vitest';
 
 import { log } from '../log';
-
 import { debugInfo, ownershipClass } from './ownership';
 
 describe('classes', 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 };
 
@@ -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,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,7 +3,6 @@
 //
 
 import path from 'node:path';
-
 import { beforeEach, describe, test } from 'vitest';
 
 import { LogLevel } from './config';

package/src/log.ts

@@ -10,6 +10,8 @@ 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;
@@ -24,7 +26,7 @@ type LogFunction = (message: string, context?: LogContext, meta?: CallMetadata)
  * Logging methods.
  */
 export interface LogMethods {
-  config: (options: LogOptions) => Log;
+  config: (options?: LogOptions) => Log;
   addProcessor: (processor: LogProcessor, addDefault?: boolean) => () => void;
 
   trace: LogFunction;
@@ -116,7 +118,7 @@ export const createLog = (): LogImp => {
      * NOTE: Preserves any processors that were already added to this logger instance
      * unless an explicit processor option is provided.
      */
-    config: ({ processor, ...options }) => {
+    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;

package/src/platform/node/index.ts

@@ -2,9 +2,8 @@
 // Copyright 2022 DXOS.org
 //
 
-import fs from 'node:fs';
-
 import yaml from 'js-yaml';
+import fs from 'node:fs';
 
 import { type LogOptions } from '../../config';
 

package/src/processors/console-processor.ts

@@ -2,15 +2,13 @@
 // Copyright 2022 DXOS.org
 //
 
-import { inspect } from 'node:util';
-
 import chalk from 'chalk';
+import { inspect } from 'node:util';
 
 import { getPrototypeSpecificInstanceId, pickBy } from '@dxos/util';
 
 import { type LogConfig, LogLevel, shortLevelName } from '../config';
 import { type LogProcessor, getContextFromEntry, shouldLog } from '../context';
-
 import { getRelativeFilename } from './common';
 
 const LEVEL_COLORS: Record<LogLevel, typeof chalk.ForegroundColor> = {

package/src/processors/file-processor.ts

@@ -9,7 +9,6 @@ import { jsonlogify } from '@dxos/util';
 
 import { type LogFilter, LogLevel } from '../config';
 import { type LogProcessor, getContextFromEntry, shouldLog } from '../context';
-
 import { getRelativeFilename } from './common';
 
 // Amount of time to retry writing after encountering EAGAIN before giving up.