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

package/src/environment.test.ts

@@ -0,0 +1,222 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { inferEnvironmentName } from './environment';
+
+const SUFFIX_PATTERN = /^[0-9a-z]{6}$/;
+
+const splitId = (id: string): { scope: string; name: string; suffix: string } => {
+  const firstColon = id.indexOf(':');
+  const lastColon = id.lastIndexOf(':');
+  return {
+    scope: id.slice(0, firstColon),
+    name: id.slice(firstColon + 1, lastColon),
+    suffix: id.slice(lastColon + 1),
+  };
+};
+
+class FakeStorage implements Storage {
+  #map = new Map<string, string>();
+  get length(): number {
+    return this.#map.size;
+  }
+  clear(): void {
+    this.#map.clear();
+  }
+  getItem(key: string): string | null {
+    return this.#map.get(key) ?? null;
+  }
+  key(index: number): string | null {
+    return Array.from(this.#map.keys())[index] ?? null;
+  }
+  removeItem(key: string): void {
+    this.#map.delete(key);
+  }
+  setItem(key: string, value: string): void {
+    this.#map.set(key, value);
+  }
+}
+
+class FakeSharedWorkerGlobalScope {}
+class FakeDedicatedWorkerGlobalScope {}
+class FakeServiceWorkerGlobalScope {}
+
+const makeWorkerScope = (Ctor: new () => object, ctorName: string, name?: string): Record<string, unknown> => {
+  const scope = Object.create(Ctor.prototype) as Record<string, unknown>;
+  scope[ctorName] = Ctor;
+  if (name !== undefined) {
+    scope.name = name;
+  }
+  return scope;
+};
+
+const makeWindowScope = (origin: string, sessionStorage?: FakeStorage): Record<string, unknown> => {
+  const scope: Record<string, unknown> = {
+    location: { origin },
+    sessionStorage,
+  };
+  scope.window = scope;
+  return scope;
+};
+
+describe('inferEnvironmentName', () => {
+  test('falls back to unknown:: when no recognized globals are present', ({ expect }) => {
+    const id = inferEnvironmentName({ scope: {} });
+    const { scope, name, suffix } = splitId(id);
+    expect(scope).toBe('unknown');
+    expect(name).toBe('');
+    expect(suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('shared worker: emits shared-worker:<name>:<suffix>', ({ expect }) => {
+    const scope = makeWorkerScope(FakeSharedWorkerGlobalScope, 'SharedWorkerGlobalScope', 'dxos-client-worker');
+    const id = inferEnvironmentName({ scope });
+    const parts = splitId(id);
+    expect(parts.scope).toBe('shared-worker');
+    expect(parts.name).toBe('dxos-client-worker');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('dedicated worker: emits dedicated-worker:<name>:<suffix>', ({ expect }) => {
+    const scope = makeWorkerScope(FakeDedicatedWorkerGlobalScope, 'DedicatedWorkerGlobalScope', 'dxos-client-worker');
+    const id = inferEnvironmentName({ scope });
+    const parts = splitId(id);
+    expect(parts.scope).toBe('dedicated-worker');
+    expect(parts.name).toBe('dxos-client-worker');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('service worker: emits service-worker::<suffix> (no name on global)', ({ expect }) => {
+    const scope = makeWorkerScope(FakeServiceWorkerGlobalScope, 'ServiceWorkerGlobalScope');
+    const id = inferEnvironmentName({ scope });
+    const parts = splitId(id);
+    expect(parts.scope).toBe('service-worker');
+    expect(parts.name).toBe('');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('anonymous worker: empty name segment', ({ expect }) => {
+    const scope = makeWorkerScope(FakeDedicatedWorkerGlobalScope, 'DedicatedWorkerGlobalScope');
+    const id = inferEnvironmentName({ scope });
+    const parts = splitId(id);
+    expect(parts.scope).toBe('dedicated-worker');
+    expect(parts.name).toBe('');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('window: emits tab:<origin>:<suffix>', ({ expect }) => {
+    const scope = makeWindowScope('https://composer.dxos.org', new FakeStorage());
+    const id = inferEnvironmentName({ scope });
+    const parts = splitId(id);
+    expect(parts.scope).toBe('tab');
+    expect(parts.name).toBe('https://composer.dxos.org');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('window: origin containing colons is preserved (split on first/last colon)', ({ expect }) => {
+    const scope = makeWindowScope('http://localhost:5173', new FakeStorage());
+    const id = inferEnvironmentName({ scope });
+    const parts = splitId(id);
+    expect(parts.scope).toBe('tab');
+    expect(parts.name).toBe('http://localhost:5173');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('window: suffix is stable across calls (sessionStorage backed)', ({ expect }) => {
+    const session = new FakeStorage();
+    const scope = makeWindowScope('http://localhost:5173', session);
+    const first = inferEnvironmentName({ scope });
+    const second = inferEnvironmentName({ scope });
+    expect(splitId(first).suffix).toBe(splitId(second).suffix);
+  });
+
+  test('window: different sessionStorage instances yield different suffixes (different tabs)', ({ expect }) => {
+    const scopeA = makeWindowScope('http://localhost:5173', new FakeStorage());
+    const scopeB = makeWindowScope('http://localhost:5173', new FakeStorage());
+    const idA = inferEnvironmentName({ scope: scopeA });
+    const idB = inferEnvironmentName({ scope: scopeB });
+    // Stronger than the typical "all suffixes differ" check since the chance of collision
+    // for a 6-char base-36 suffix is ~5e-10 per pair.
+    expect(splitId(idA).suffix).not.toBe(splitId(idB).suffix);
+  });
+
+  test('window: missing sessionStorage falls back to fresh random per call', ({ expect }) => {
+    const scope = makeWindowScope('https://example.com', undefined);
+    const first = inferEnvironmentName({ scope });
+    const second = inferEnvironmentName({ scope });
+    expect(splitId(first).suffix).toMatch(SUFFIX_PATTERN);
+    expect(splitId(second).suffix).toMatch(SUFFIX_PATTERN);
+    // Without storage we can't pin them; assert behavior, not equality.
+  });
+
+  test('worker suffixes vary across calls (no persistence)', ({ expect }) => {
+    const scope = makeWorkerScope(FakeDedicatedWorkerGlobalScope, 'DedicatedWorkerGlobalScope', 'w');
+    const ids = new Set<string>();
+    for (let index = 0; index < 16; index++) {
+      ids.add(splitId(inferEnvironmentName({ scope })).suffix);
+    }
+    expect(ids.size).toBeGreaterThan(1);
+  });
+
+  test('node: emits node:<pid>:<suffix>', ({ expect }) => {
+    const scope = { process: { pid: 12345, versions: { node: '24.1.0' } } };
+    const id = inferEnvironmentName({ scope });
+    const parts = splitId(id);
+    expect(parts.scope).toBe('node');
+    expect(parts.name).toBe('12345');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('node: missing pid yields empty name segment', ({ expect }) => {
+    const scope = { process: { versions: { node: '24.1.0' } } };
+    const parts = splitId(inferEnvironmentName({ scope }));
+    expect(parts.scope).toBe('node');
+    expect(parts.name).toBe('');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('node: process without versions.node is not detected as node', ({ expect }) => {
+    // e.g. a userland `process`-like object — should fall through to unknown.
+    const scope = { process: { pid: 1, versions: {} } };
+    const parts = splitId(inferEnvironmentName({ scope }));
+    expect(parts.scope).toBe('unknown');
+  });
+
+  test('cloudflare worker: emits cf-worker::<suffix>', ({ expect }) => {
+    const scope = { navigator: { userAgent: 'Cloudflare-Workers' } };
+    const id = inferEnvironmentName({ scope });
+    const parts = splitId(id);
+    expect(parts.scope).toBe('cf-worker');
+    expect(parts.name).toBe('');
+    expect(parts.suffix).toMatch(SUFFIX_PATTERN);
+  });
+
+  test('cloudflare worker: detected even when service-worker scope is also present', ({ expect }) => {
+    // CF workers in service-worker syntax expose ServiceWorkerGlobalScope; CF should win.
+    const scope = makeWorkerScope(FakeServiceWorkerGlobalScope, 'ServiceWorkerGlobalScope') as any;
+    scope.navigator = { userAgent: 'Cloudflare-Workers' };
+    const parts = splitId(inferEnvironmentName({ scope }));
+    expect(parts.scope).toBe('cf-worker');
+  });
+
+  test('cloudflare worker: detected even when process is also exposed (nodejs_compat)', ({ expect }) => {
+    // CF workers with the nodejs_compat flag expose a partial `process` polyfill;
+    // CF detection must still win over the node fallback.
+    const scope: Record<string, unknown> = {
+      navigator: { userAgent: 'Cloudflare-Workers' },
+      process: { pid: 1, versions: { node: '20.0.0' } },
+    };
+    const parts = splitId(inferEnvironmentName({ scope }));
+    expect(parts.scope).toBe('cf-worker');
+  });
+
+  test('safe to invoke with no arguments in the host runtime (does not throw)', ({ expect }) => {
+    expect(() => inferEnvironmentName()).not.toThrow();
+    const id = inferEnvironmentName();
+    // Format must always be 3 colon-separated segments with a valid suffix.
+    expect(splitId(id).suffix).toMatch(SUFFIX_PATTERN);
+  });
+});

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

@@ -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,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 * 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;
+  }
+};