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

package/src/environment.ts

@@ -0,0 +1,129 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+/**
+ * Per-tab session-storage key used to stabilize the random suffix for the main thread.
+ * `sessionStorage` is per-tab and survives reloads of the same tab.
+ */
+const TAB_SUFFIX_STORAGE_KEY = '@dxos/log:env-suffix';
+
+const SUFFIX_LENGTH = 6;
+
+/**
+ * Generate a 6-character lowercase-alphanumeric suffix.
+ * Cryptographically random when `crypto` is available; falls back to `Math.random`.
+ */
+const randomSuffix = (): string => {
+  const cryptoRef = (globalThis as any).crypto as Crypto | undefined;
+  if (cryptoRef?.getRandomValues) {
+    const bytes = new Uint8Array(SUFFIX_LENGTH);
+    cryptoRef.getRandomValues(bytes);
+    // Each byte mod 36 maps to one base-36 char; mild modulo bias is acceptable for IDs.
+    let suffix = '';
+    for (const byte of bytes) {
+      suffix += (byte % 36).toString(36);
+    }
+    return suffix;
+  }
+  return Math.random()
+    .toString(36)
+    .slice(2, 2 + SUFFIX_LENGTH)
+    .padEnd(SUFFIX_LENGTH, '0');
+};
+
+/**
+ * Look up (or create) a stable per-tab suffix in `sessionStorage`.
+ * Same browser tab keeps the same suffix across reloads; different tabs get
+ * different suffixes; private/blocked storage falls back to a fresh random.
+ */
+const getOrCreateTabSuffix = (session: Storage | undefined): string => {
+  if (!session) {
+    return randomSuffix();
+  }
+  try {
+    const existing = session.getItem(TAB_SUFFIX_STORAGE_KEY);
+    if (existing && existing.length > 0) {
+      return existing;
+    }
+    const suffix = randomSuffix();
+    session.setItem(TAB_SUFFIX_STORAGE_KEY, suffix);
+    return suffix;
+  } catch {
+    return randomSuffix();
+  }
+};
+
+const isInstanceOf = (scope: unknown, ctorName: string): boolean => {
+  const ctor = (scope as any)?.[ctorName];
+  return typeof ctor === 'function' && scope instanceof ctor;
+};
+
+/**
+ * Cloudflare Workers set `navigator.userAgent` to this exact string, regardless of
+ * whether the worker is using modules or service-worker syntax. This is the most
+ * stable signal and is checked before browser worker scopes because CF workers in
+ * service-worker syntax also expose a `ServiceWorkerGlobalScope`.
+ */
+const CF_WORKER_USER_AGENT = 'Cloudflare-Workers';
+
+/**
+ * Options for {@link inferEnvironmentName}.
+ * Tests pass a custom `scope` to simulate worker / window globals.
+ */
+export type InferEnvironmentNameOptions = {
+  scope?: unknown;
+};
+
+/**
+ * Infer a writer/environment identifier from the current execution context.
+ *
+ * Safe to invoke in any JS runtime — never throws. Falls back to `unknown::<suffix>`
+ * when the runtime can't be classified.
+ *
+ * Format is always three colon-separated segments: `<scope>:<name>:<suffix>`.
+ * - `scope` — `tab | dedicated-worker | shared-worker | service-worker | cf-worker | node | unknown`.
+ * - `name` — `location.origin` for tabs, `self.name` for browser workers, `process.pid`
+ *   for node, empty for cf-workers / service workers / anonymous workers.
+ *   Note that `name` may itself contain `:` (e.g. `http://localhost:5173`); when parsing,
+ *   take the first segment as scope and the last as suffix, and treat everything in
+ *   between as the name.
+ * - `suffix` — 6-char random; stable per-tab via `sessionStorage`, fresh per worker / process instance.
+ */
+export const inferEnvironmentName = (options: InferEnvironmentNameOptions = {}): string => {
+  const scope: any = options.scope ?? globalThis;
+
+  // Cloudflare Workers — checked first because in service-worker syntax mode CF
+  // workers also report as `ServiceWorkerGlobalScope`.
+  if (scope.navigator?.userAgent === CF_WORKER_USER_AGENT) {
+    return `cf-worker::${randomSuffix()}`;
+  }
+
+  if (isInstanceOf(scope, 'SharedWorkerGlobalScope')) {
+    return `shared-worker:${scope.name ?? ''}:${randomSuffix()}`;
+  }
+
+  if (isInstanceOf(scope, 'ServiceWorkerGlobalScope')) {
+    return `service-worker::${randomSuffix()}`;
+  }
+
+  if (isInstanceOf(scope, 'DedicatedWorkerGlobalScope')) {
+    return `dedicated-worker:${scope.name ?? ''}:${randomSuffix()}`;
+  }
+
+  if (scope.window !== undefined && scope.window === scope) {
+    const origin = scope.location?.origin ?? '';
+    return `tab:${origin}:${getOrCreateTabSuffix(scope.sessionStorage)}`;
+  }
+
+  // Node.js — `process.versions.node` is the canonical signal.
+  // Avoid touching the real `process` global directly so tests passing `scope: {}`
+  // can opt out of node detection.
+  const proc = scope.process;
+  if (proc && typeof proc === 'object' && proc.versions?.node) {
+    const pid = typeof proc.pid === 'number' ? String(proc.pid) : '';
+    return `node:${pid}:${randomSuffix()}`;
+  }
+
+  return `unknown::${randomSuffix()}`;
+};

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,18 +2,21 @@
 // Copyright 2022 DXOS.org
 //
 
-import omit from 'lodash.omit';
-
-import { pick } from '@dxos/util';
+import { omit, pick } from '@dxos/util';
 
 export { omit, pick };
 
 export * from './config';
 export * from './context';
+export * from './environment';
+export * from './jsonl';
 export * from './log';
 export { parseFilter } from './options';
 export * from './processors';
 export * from './scope';
-export type * from './meta';
+export type { CallMetadata } from './meta';
+export { LOG_META_MARKER, isLogMeta } from './meta';
+export { dbg } from './dbg';
+export * from './log-buffer';
 
 export { getCurrentOwnershipScope } from './experimental/ownership';

package/src/jsonl.test.ts

@@ -0,0 +1,121 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { LogEntry, type LogEntryInit, LogLevel } from './index';
+import { serializeToJsonl } from './jsonl';
+
+const createEntry = (overrides: Partial<LogEntryInit> = {}): LogEntry =>
+  new LogEntry({
+    level: LogLevel.INFO,
+    message: 'test message',
+    ...overrides,
+  });
+
+const parseLine = (line: string | undefined) => {
+  if (line === undefined) {
+    throw new Error('expected line, got undefined');
+  }
+  return JSON.parse(line) as Record<string, unknown>;
+};
+
+describe('serializeToJsonl', () => {
+  test('returns undefined for TRACE level entries', ({ expect }) => {
+    expect(serializeToJsonl(createEntry({ level: LogLevel.TRACE }))).toBeUndefined();
+  });
+
+  test('emits compact record with t/l/m fields', ({ expect }) => {
+    const record = parseLine(serializeToJsonl(createEntry({ message: 'hello' })));
+    expect(record.t).toBeTypeOf('string');
+    expect(record.l).toBe('I');
+    expect(record.m).toBe('hello');
+  });
+
+  test('uses level letters D V I W E', ({ expect }) => {
+    const levels: Array<[LogLevel, string]> = [
+      [LogLevel.DEBUG, 'D'],
+      [LogLevel.VERBOSE, 'V'],
+      [LogLevel.INFO, 'I'],
+      [LogLevel.WARN, 'W'],
+      [LogLevel.ERROR, 'E'],
+    ];
+    for (const [level, letter] of levels) {
+      const record = parseLine(serializeToJsonl(createEntry({ level, message: '' })));
+      expect(record.l).toBe(letter);
+    }
+  });
+
+  test('omits optional fields when not present', ({ expect }) => {
+    const record = parseLine(serializeToJsonl(createEntry({ message: 'plain' })));
+    expect(record.f).toBeUndefined();
+    expect(record.n).toBeUndefined();
+    expect(record.o).toBeUndefined();
+    expect(record.e).toBeUndefined();
+    expect(record.c).toBeUndefined();
+    expect(record.i).toBeUndefined();
+  });
+
+  test('captures filename and line metadata', ({ expect }) => {
+    const record = parseLine(
+      serializeToJsonl(
+        createEntry({
+          meta: { F: '/home/user/project/packages/sdk/test.ts', L: 42, S: undefined },
+        }),
+      ),
+    );
+    expect(record.f).toBe('packages/sdk/test.ts');
+    expect(record.n).toBe(42);
+  });
+
+  test('captures error stack via computedError', ({ expect }) => {
+    const error = new Error('boom');
+    const record = parseLine(serializeToJsonl(createEntry({ error })));
+    expect(record.e).toContain('boom');
+  });
+
+  test('captures context as flat JSON string', ({ expect }) => {
+    const record = parseLine(serializeToJsonl(createEntry({ context: { count: 3, name: 'x' } })));
+    expect(record.c).toBeTypeOf('string');
+    const ctx = JSON.parse(record.c as string);
+    expect(ctx.count).toBe(3);
+    expect(ctx.name).toBe('x');
+  });
+
+  test('flattens nested objects in context (one level)', ({ expect }) => {
+    const record = parseLine(serializeToJsonl(createEntry({ context: { nested: { a: 1, b: 2 } } })));
+    const ctx = JSON.parse(record.c as string);
+    // computedContext converts nested objects to JSON strings via stringifyOneLevel.
+    expect(typeof ctx.nested).toBe('string');
+    expect(ctx.nested).toBe('{"a":1,"b":2}');
+  });
+
+  test('does not truncate long context (idb-store style)', ({ expect }) => {
+    const longValue = 'x'.repeat(2_000);
+    const record = parseLine(serializeToJsonl(createEntry({ context: { data: longValue } })));
+    const ctx = JSON.parse(record.c as string);
+    expect(ctx.data).toBe(longValue);
+  });
+
+  test('embeds env identifier in `i` field', ({ expect }) => {
+    const record = parseLine(
+      serializeToJsonl(createEntry({ message: 'm' }), { env: 'tab:http://localhost:5173:abc123' }),
+    );
+    expect(record.i).toBe('tab:http://localhost:5173:abc123');
+  });
+
+  test('omits `i` when env is not provided', ({ expect }) => {
+    const record = parseLine(serializeToJsonl(createEntry({ message: 'm' })));
+    expect(record.i).toBeUndefined();
+  });
+
+  test('output is valid single-line JSON (no embedded newlines)', ({ expect }) => {
+    const line = serializeToJsonl(createEntry({ message: 'multi\nline\nmessage' }));
+    expect(line).toBeDefined();
+    expect(line!.indexOf('\n')).toBe(-1);
+    // The newlines inside the message are escaped by JSON.stringify.
+    const record = JSON.parse(line!);
+    expect(record.m).toBe('multi\nline\nmessage');
+  });
+});

package/src/jsonl.ts

@@ -0,0 +1,104 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { LogLevel, shortLevelName } from './config';
+import { type LogEntry } from './context';
+
+/**
+ * Compact JSONL log record with short property names for small serialized size.
+ *
+ * Field names are intentionally one character to keep on-disk / on-wire size minimal —
+ * a single record can be emitted thousands of times per session.
+ */
+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/scope from which the log was emitted. */
+  o?: string;
+  /** Error stack. */
+  e?: string;
+  /** Context JSON (already a string of pre-stringified flat key/values). */
+  c?: string;
+  /** Environment identifier (see {@link inferEnvironmentName}). */
+  i?: string;
+};
+
+/**
+ * Options for {@link serializeToJsonl}.
+ */
+export type SerializeToJsonlOptions = {
+  /**
+   * Environment identifier embedded in the record's `i` field.
+   * Use {@link inferEnvironmentName} for a default that disambiguates tabs and workers.
+   */
+  env?: string;
+};
+
+/**
+ * Serialize a {@link LogEntry} to a single compact JSON line (no trailing newline).
+ *
+ * Returns `undefined` for entries at TRACE level — callers can use this to skip them.
+ *
+ * The output is compatible with newline-delimited JSON (NDJSON / JSONL): join multiple
+ * results with `\n` for a stream / file representation.
+ *
+ * Context is taken from {@link LogEntry.computedContext}, which has already flattened
+ * nested objects to strings (see `stringifyOneLevel` in `context.ts`), so the resulting
+ * `c` field is a JSON string of a flat `Record<string, primitive>` map. The function
+ * does **not** truncate context — callers that care about line size should set their own
+ * cap before calling, or trim post-hoc.
+ */
+export const serializeToJsonl = (entry: LogEntry, opts: SerializeToJsonlOptions = {}): string | undefined => {
+  if (entry.level <= LogLevel.TRACE) {
+    return undefined;
+  }
+
+  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;
+  }
+  if (opts.env !== undefined) {
+    record.i = opts.env;
+  }
+
+  const computedContext = entry.computedContext;
+  if (Object.keys(computedContext).length > 0) {
+    try {
+      record.c = JSON.stringify(computedContext);
+    } catch {
+      // Skip context that throws during serialization. `computedContext` is already flattened
+      // via `stringifyOneLevel`, so this is best-effort belt-and-suspenders.
+    }
+  }
+
+  try {
+    return JSON.stringify(record);
+  } catch {
+    return undefined;
+  }
+};

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