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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/log",
-  "version": "0.8.4-main.fbb7a13",
+  "version": "0.8.4-main.fcc0d83b33",
   "description": "Logger",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -43,9 +43,6 @@
     }
   },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
@@ -54,14 +51,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/util": "0.8.4-main.fcc0d83b33",
+    "@dxos/node-std": "0.8.4-main.fcc0d83b33"
   },
   "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/context.ts

@@ -2,8 +2,11 @@
 // Copyright 2022 DXOS.org
 //
 
+import { getDebugName } from '@dxos/util';
+
 import { type LogConfig, type LogFilter, type LogLevel } from './config';
 import { type CallMetadata } from './meta';
+import { getRelativeFilename } from './processors/common';
 import { gatherLogInfoFromScope } from './scope';
 
 /**
@@ -12,14 +15,140 @@ import { gatherLogInfoFromScope } from './scope';
 export type LogContext = Record<string, any> | Error | any;
 
 /**
- * Record for current log line.
+ * Normalized call-site metadata suitable for display and serialization.
+ */
+export interface ComputedLogMeta {
+  /** Relative filename (normalized via {@link getRelativeFilename}). */
+  filename?: string;
+
+  /** Line number within the file. */
+  line?: number;
+
+  /** Debug name of the enclosing scope (class instance), e.g. `MyClass#3`. */
+  context?: string;
+}
+
+/**
+ * Fields required to construct a {@link LogEntry}.
  */
-export interface LogEntry {
+export interface LogEntryInit {
   level: LogLevel;
   message?: string;
   context?: LogContext;
   meta?: CallMetadata;
   error?: Error;
+  /** Overrides the default timestamp ({@link Date.now}). */
+  timestamp?: number;
+}
+
+/**
+ * Record for a single log line processed by the logging pipeline.
+ *
+ * Raw fields (`level`, `message`, `context`, `meta`, `error`) are preserved so processors
+ * can access unmodified inputs. Derived, lazily computed getters
+ * ({@link computedContext}, {@link computedError}, {@link computedMeta}) centralize
+ * the formatting logic shared across processors that write to serialized stores.
+ */
+export class LogEntry {
+  /** Severity of this entry. */
+  readonly level: LogLevel;
+
+  /** Human-readable log message, if any. */
+  readonly message?: string;
+
+  /**
+   * Raw context value passed at the call site. May be a record, an Error, a function
+   * returning either, or any other value. Processors that need the flattened /
+   * JSON-safe view should prefer {@link computedContext}.
+   */
+  readonly context?: LogContext;
+
+  /** Raw call-site metadata injected by the log transform plugin. */
+  readonly meta?: CallMetadata;
+
+  /** Error passed to `log.catch()` / `log.error(err)`, if any. */
+  readonly error?: Error;
+
+  /** Unix timestamp in milliseconds of when the entry was created. */
+  readonly timestamp: number;
+
+  #computedContext: Record<string, unknown> | undefined;
+  #computedContextComputed = false;
+  #computedError: string | undefined;
+  #computedErrorComputed = false;
+  #computedMeta: ComputedLogMeta | undefined;
+  #resolvedContext: unknown;
+  #resolvedContextComputed = false;
+
+  constructor(init: LogEntryInit) {
+    this.level = init.level;
+    this.message = init.message;
+    this.context = init.context;
+    this.meta = init.meta;
+    this.error = init.error;
+    this.timestamp = init.timestamp ?? Date.now();
+  }
+
+  /**
+   * Resolve a function-valued {@link context} once and cache, so getters that
+   * independently consult the raw context don't trigger duplicate evaluation.
+   */
+  #resolveContext(): unknown {
+    if (!this.#resolvedContextComputed) {
+      this.#resolvedContext = typeof this.context === 'function' ? this.context() : this.context;
+      this.#resolvedContextComputed = true;
+    }
+    return this.#resolvedContext;
+  }
+
+  /**
+   * Flattened, JSON-safe context intended for serialized stores.
+   *
+   * - Single-level key-value map.
+   * - Primitives (`boolean`, `number`, `string`, `null`, `undefined`) pass through.
+   * - Non-primitive values are stringified one level deep via `JSON.stringify` (no recursion).
+   * - The reserved `error` / `err` keys are stripped — use {@link computedError} instead.
+   * - Properties from `@logInfo`-decorated members of the scope (`meta.S`) are inlined.
+   *
+   * Lazily computed and memoized on first access.
+   */
+  get computedContext(): Record<string, unknown> {
+    if (!this.#computedContextComputed) {
+      this.#computedContext = computeContext(this, this.#resolveContext());
+      this.#computedContextComputed = true;
+    }
+    return this.#computedContext ?? {};
+  }
+
+  /**
+   * Stringified error for this entry, sourced (in priority order) from:
+   *   1. {@link error} (e.g. `log.catch(err)`),
+   *   2. {@link context} when the context itself is an {@link Error},
+   *   3. `context.error` or `context.err`.
+   *
+   * Formatted as `.stack` when available, falling back to `.message` or `String(err)`.
+   *
+   * Lazily computed and memoized on first access.
+   */
+  get computedError(): string | undefined {
+    if (!this.#computedErrorComputed) {
+      this.#computedError = computeError(this, this.#resolveContext());
+      this.#computedErrorComputed = true;
+    }
+    return this.#computedError;
+  }
+
+  /**
+   * Normalized call-site metadata suitable for display / serialization.
+   *
+   * Lazily computed and memoized on first access.
+   */
+  get computedMeta(): ComputedLogMeta {
+    if (this.#computedMeta === undefined) {
+      this.#computedMeta = computeMeta(this);
+    }
+    return this.#computedMeta;
+  }
 }
 
 /**
@@ -73,6 +202,12 @@ export const shouldLog = (entry: LogEntry, filters?: LogFilter[]): boolean => {
   return results.length > 0 && !results.some((results) => results === false);
 };
 
+/**
+ * Merges scope info, entry context, and error into a single record — preserving nested
+ * objects and Error instances so rich consumers (console inspect, devtools) can format them.
+ *
+ * Prefer {@link LogEntry.computedContext} for serialized / JSON outputs.
+ */
 export const getContextFromEntry = (entry: LogEntry): Record<string, any> | undefined => {
   let context;
   if (entry.meta) {
@@ -100,3 +235,108 @@ export const getContextFromEntry = (entry: LogEntry): Record<string, any> | unde
 
   return context && Object.keys(context).length > 0 ? context : undefined;
 };
+
+const RESERVED_ERROR_KEYS = new Set(['error', 'err']);
+
+const stringifyOneLevel = (value: unknown): unknown => {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  const type = typeof value;
+  if (type === 'boolean' || type === 'number' || type === 'string') {
+    return value;
+  }
+  if (type === 'bigint') {
+    return (value as bigint).toString();
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+};
+
+const computeContext = (entry: LogEntry, rawContext: unknown): Record<string, unknown> => {
+  const result: Record<string, unknown> = {};
+
+  const mergeInto = (source: unknown): void => {
+    if (!source || typeof source !== 'object') {
+      return;
+    }
+    for (const [key, value] of Object.entries(source)) {
+      if (RESERVED_ERROR_KEYS.has(key)) {
+        continue;
+      }
+      result[key] = stringifyOneLevel(value);
+    }
+  };
+
+  if (entry.meta?.S !== undefined && entry.meta.S !== null) {
+    mergeInto(gatherLogInfoFromScope(entry.meta.S));
+  }
+
+  if (rawContext instanceof Error) {
+    // Structured debug info attached to thrown errors lives on `.context`.
+    mergeInto((rawContext as any).context);
+  } else {
+    mergeInto(rawContext);
+  }
+
+  if (entry.error) {
+    mergeInto((entry.error as any).context);
+  }
+
+  return result;
+};
+
+const stringifyError = (err: unknown): string | undefined => {
+  if (err === null || err === undefined) {
+    return undefined;
+  }
+  if (err instanceof Error) {
+    return err.stack ?? err.message;
+  }
+  return String(err);
+};
+
+const computeError = (entry: LogEntry, rawContext: unknown): string | undefined => {
+  if (entry.error !== undefined) {
+    return stringifyError(entry.error);
+  }
+
+  if (rawContext instanceof Error) {
+    return stringifyError(rawContext);
+  }
+  if (rawContext && typeof rawContext === 'object') {
+    const ctxErr = (rawContext as any).error ?? (rawContext as any).err;
+    if (ctxErr !== undefined && ctxErr !== null) {
+      return stringifyError(ctxErr);
+    }
+  }
+
+  return undefined;
+};
+
+const computeMeta = (entry: LogEntry): ComputedLogMeta => {
+  if (!entry.meta) {
+    return {};
+  }
+
+  const scope = entry.meta.S;
+  // Skip globalThis and plain object scopes (module-level logs); only report class instances.
+  let scopeContext: string | undefined;
+  if (
+    typeof scope === 'object' &&
+    scope !== null &&
+    scope !== globalThis &&
+    Object.getPrototypeOf(scope) !== Object.prototype
+  ) {
+    scopeContext = getDebugName(scope);
+  }
+
+  return {
+    filename: getRelativeFilename(entry.meta.F),
+    line: entry.meta.L,
+    context: scopeContext,
+  };
+};

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