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

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

@@ -4,7 +4,7 @@
 
 import { describe, test } from 'vitest';
 
-import { type LogConfig, type LogEntry, LogLevel } from './index';
+import { type LogConfig, LogEntry, type LogEntryInit, LogLevel } from './index';
 import { LogBuffer } from './log-buffer';
 
 const baseConfig: LogConfig = {
@@ -13,11 +13,12 @@ const baseConfig: LogConfig = {
   processors: [],
 };
 
-const createEntry = (overrides: Partial<LogEntry> = {}): LogEntry => ({
-  level: LogLevel.INFO,
-  message: 'test message',
-  ...overrides,
-});
+const createEntry = (overrides: Partial<LogEntryInit> = {}): LogEntry =>
+  new LogEntry({
+    level: LogLevel.INFO,
+    message: 'test message',
+    ...overrides,
+  });
 
 describe('LogBuffer', () => {
   test('pushes and serializes log entries', ({ expect }) => {
@@ -123,7 +124,9 @@ describe('LogBuffer', () => {
 
     const lines = buffer.serialize().split('\n');
     const record = JSON.parse(lines[0]);
-    expect(record.c).toBeUndefined();
+    // 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 }) => {

package/src/log-buffer.ts

@@ -2,36 +2,15 @@
 // Copyright 2025 DXOS.org
 //
 
-import { CircularBuffer, getDebugName } from '@dxos/util';
+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;
 
-/**
- * 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.
  */
@@ -51,39 +30,40 @@ export class LogBuffer {
       return;
     }
 
+    const { filename, line, context: scopeName } = entry.computedMeta;
+
     const record: LogRecord = {
-      t: new Date().toISOString(),
+      t: new Date(entry.timestamp).toISOString(),
       l: shortLevelName[entry.level] ?? '?',
       m: entry.message ?? '',
     };
 
-    if (entry.meta) {
-      record.f = getRelativeFilename(entry.meta.F);
-      record.n = entry.meta.L;
+    if (filename !== undefined) {
+      record.f = filename;
+    }
+    if (line !== undefined) {
+      record.n = line;
+    }
+    if (scopeName !== undefined) {
+      record.o = scopeName;
     }
 
-    if (entry.error) {
-      record.e = entry.error.stack ?? entry.error.message;
+    if (entry.computedError !== undefined) {
+      record.e = entry.computedError;
     }
 
-    if (entry.context != null) {
+    const computedContext = entry.computedContext;
+    if (Object.keys(computedContext).length > 0) {
       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;
+        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.
       }
     }
-    const scope = entry.meta?.S;
-    if (typeof scope === 'object' && scope !== null && Object.getPrototypeOf(scope) !== Object.prototype) {
-      record.o = getDebugName(scope);
-    }
 
     this._buffer.push(record);
   };
@@ -107,11 +87,3 @@ export class LogBuffer {
     return lines.join('\n');
   }
 }
-
-const getRelativeFilename = (filename: string): string => {
-  const match = filename.match(/.+\/(packages\/.+\/.+)/);
-  if (match) {
-    return match[1];
-  }
-  return filename;
-};

package/src/log.ts

@@ -3,7 +3,7 @@
 //
 
 import { type LogConfig, LogLevel, type LogOptions } from './config';
-import { type LogContext, type LogProcessor } from './context';
+import { type LogContext, LogEntry, type LogProcessor } from './context';
 import { createFunctionLogDecorator, createMethodLogDecorator } from './decorators';
 import { type CallMetadata } from './meta';
 import { createConfig } from './options';
@@ -29,15 +29,57 @@ export interface LogMethods {
   config: (options?: LogOptions) => Log;
   addProcessor: (processor: LogProcessor, addDefault?: boolean) => () => void;
 
+  /**
+   * Log at `trace` level.
+   *
+   * Generally not surfaced to the developer and not captured in a log file.
+   */
   trace: LogFunction;
+
+  /**
+   * Log at `debug` level.
+   * Generally not surfaced to the developer and captured in a log file.
+   */
   debug: LogFunction;
+
+  /**
+   * Log at `verbose` level.
+   * Generally not surfaced to the developer and not captured in a log file.
+   */
   verbose: LogFunction;
+
+  /**
+   * Log at `info` level.
+   * Generally surfaced to the developer and captured in a log file.
+   */
   info: LogFunction;
+
+  /**
+   * Log at `warn` level.
+   * Generally surfaced to the developer and captured in a log file.
+   */
   warn: LogFunction;
+
+  /**
+   * Log at `error` level.
+   * Generally surfaced to the developer and captured in a log file.
+   */
   error: LogFunction;
+
+  /**
+   * Log an error and its stack trace at an `error` level.
+   * Generally surfaced to the developer and captured in a log file.
+   */
   catch: (error: Error | any, context?: LogContext, meta?: CallMetadata) => void;
 
+  /**
+   * Decorator to log method parameters and return value at the `info` level.
+   */
   method: (arg0?: never, arg1?: never, meta?: CallMetadata) => MethodDecorator;
+
+  /**
+   * Wrapper to log function parameters and return value at the `info` level.
+   */
   function: <F extends (...args: any[]) => any>(
     name: string,
     fn: F,
@@ -46,7 +88,14 @@ export interface LogMethods {
     },
   ) => F;
 
+  /**
+   * Log a horizontal rule at the `info` level.
+   */
   break: () => void;
+
+  /**
+   * Log a stack trace at the `info` level.
+   */
   stack: (message?: string, context?: never, meta?: CallMetadata) => void;
 }
 
@@ -98,15 +147,8 @@ export const createLog = (): LogImp => {
     error?: Error,
   ) => {
     // TODO(burdon): Do the filter matching upstream (here) rather than in each processor?
-    log._config.processors.forEach((processor) =>
-      processor(log._config, {
-        level,
-        message,
-        context,
-        meta,
-        error,
-      }),
-    );
+    const entry = new LogEntry({ level, message, context, meta, error });
+    log._config.processors.forEach((processor) => processor(log._config, entry));
   };
 
   /**

package/src/meta.ts

@@ -3,11 +3,27 @@
 //
 
 /**
- * Metadata injected b y the log transform plugin.
+ * Marker key + value injected on every {@link CallMetadata} object by the log transform plugin.
+ * Used by {@link isLogMeta} to detect a log-meta argument at runtime (e.g. for variadic
+ * `param_index: 'last'` callees that don't have a fixed meta slot).
+ */
+export const LOG_META_MARKER = '~LogMeta';
+
+/**
+ * Metadata injected by the log transform plugin.
  *
  * Field names are intentionally short to reduce the size of the generated code.
  */
 export interface CallMetadata {
+  /**
+   * Marker tag — when present, equal to {@link LOG_META_MARKER} ({@link `'~LogMeta'`}).
+   * Injected by the log transform plugin on every emitted meta object so that {@link isLogMeta}
+   * can distinguish a meta argument from a regular user-supplied value at runtime.
+   * Optional because hand-written `CallMetadata` literals (decorators, RPC mappers, tests)
+   * don't need the marker — they are recognized by position in the call signature.
+   */
+  '~LogMeta'?: typeof LOG_META_MARKER;
+
   /**
    * File name.
    */
@@ -35,3 +51,15 @@ export interface CallMetadata {
    */
   A?: string[];
 }
+
+/**
+ * Type guard: `true` when `value` is a {@link CallMetadata} object emitted by the log transform plugin.
+ * Detection is based on the presence of the {@link LOG_META_MARKER} marker key/value.
+ */
+export const isLogMeta = (value: unknown): value is CallMetadata => {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    (value as Record<string, unknown>)[LOG_META_MARKER] === LOG_META_MARKER
+  );
+};

package/src/processors/browser-processor.ts

@@ -2,23 +2,11 @@
 // Copyright 2022 DXOS.org
 //
 
-import { getDebugName, safariCheck } from '@dxos/util';
+import { safariCheck } from '@dxos/util';
 
 import { LogLevel } from '../config';
 import { type LogProcessor, getContextFromEntry, shouldLog } from '../context';
 
-const getRelativeFilename = (filename: string) => {
-  // TODO(burdon): Hack uses "packages" as an anchor (pre-parse NX?)
-  // Including `packages/` part of the path so that excluded paths (e.g. from dist) are clickable in vscode.
-  const match = filename.match(/.+\/(packages\/.+\/.+)/);
-  if (match) {
-    const [, filePath] = match;
-    return filePath;
-  }
-
-  return filename;
-};
-
 type Config = {
   useTestProcessor: boolean;
   printFileLinks: boolean;
@@ -47,23 +35,26 @@ const APP_BROWSER_PROCESSOR: LogProcessor = (config, entry) => {
   // const LOG_BROWSER_CSS = ['color:gray; font-size:10px; padding-bottom: 4px', 'color:#B97852; font-size:14px;'];
   const LOG_BROWSER_CSS: string[] = [];
 
+  const { filename, line: lineNumber, context: scopeDebugName } = entry.computedMeta;
+
   let link = '';
-  if (entry.meta) {
-    const filename = getRelativeFilename(entry.meta.F);
+  if (filename !== undefined && lineNumber !== undefined) {
     const filepath = `${LOG_BROWSER_PREFIX.replace(/\/$/, '')}/${filename}`;
     // TODO(burdon): Line numbers not working for app link, even with colons.
     //  https://stackoverflow.com/a/54459820/2804332
-    link = `${filepath}#L${entry.meta.L}`;
+    link = `${filepath}#L${lineNumber}`;
   }
 
   let args = [];
 
-  if (entry.meta?.S) {
-    const scope = entry.meta?.S;
-    const scopeName = scope.name || getDebugName(scope);
-    const processPrefix = entry.meta.S?.hostSessionId ? '[worker] ' : '';
-    // TODO(dmaretskyi): Those can be made clickable with a custom formatter.
-    args.push(`%c${processPrefix}${scopeName}`, 'color:#C026D3;font-weight:bold');
+  const scope = entry.meta?.S;
+  if (scope) {
+    const scopeName = scope.name || scopeDebugName;
+    if (scopeName) {
+      const processPrefix = scope.hostSessionId ? '[worker] ' : '';
+      // TODO(dmaretskyi): Those can be made clickable with a custom formatter.
+      args.push(`%c${processPrefix}${scopeName}`, 'color:#C026D3;font-weight:bold');
+    }
   }
 
   if (entry.message) {
@@ -73,9 +64,9 @@ const APP_BROWSER_PROCESSOR: LogProcessor = (config, entry) => {
   const context = getContextFromEntry(entry);
   if (context) {
     if (Object.keys(context).length === 1 && 'error' in context) {
-      args.push(context.error);
+      args.push(unwrapEffectError(context.error));
     } else if (Object.keys(context).length === 1 && 'err' in context) {
-      args.push(context.err);
+      args.push(unwrapEffectError(context.err));
     } else {
       args.push(context);
     }
@@ -114,10 +105,8 @@ const TEST_BROWSER_PROCESSOR: LogProcessor = (config, entry) => {
     return;
   }
 
-  let path = '';
-  if (entry.meta) {
-    path = `${getRelativeFilename(entry.meta.F)}:${entry.meta.L}`;
-  }
+  const { filename, line: lineNumber } = entry.computedMeta;
+  const path = filename !== undefined && lineNumber !== undefined ? `${filename}:${lineNumber}` : '';
 
   let args = [];
 
@@ -148,3 +137,13 @@ const TEST_BROWSER_PROCESSOR: LogProcessor = (config, entry) => {
 };
 
 export const BROWSER_PROCESSOR: LogProcessor = CONFIG.useTestProcessor ? TEST_BROWSER_PROCESSOR : APP_BROWSER_PROCESSOR;
+
+// effect-specific
+const originalSymbol = Symbol.for('effect/OriginalAnnotation');
+
+const unwrapEffectError = (error: any) => {
+  if (typeof error === 'object' && error !== null && originalSymbol in error) {
+    return error[originalSymbol];
+  }
+  return error;
+};

package/src/processors/console-processor.ts

@@ -9,7 +9,6 @@ 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> = {
   [LogLevel.TRACE]: 'gray',
@@ -93,22 +92,17 @@ export const CONSOLE_PROCESSOR: LogProcessor = (config, entry) => {
     return;
   }
 
+  const { filename, line: lineNumber } = entry.computedMeta;
   const parts: FormatParts = {
     level,
     message,
     error,
-    path: undefined,
-    line: undefined,
-    scope: undefined,
+    path: filename,
+    line: lineNumber,
+    scope: meta?.S,
     context: undefined,
   };
 
-  if (meta) {
-    parts.path = getRelativeFilename(meta.F);
-    parts.line = meta.L;
-    parts.scope = meta.S;
-  }
-
   const context = getContextFromEntry(entry);
   if (context) {
     // Remove undefined fields.

package/src/processors/file-processor.ts

@@ -5,11 +5,8 @@
 import { appendFileSync, mkdirSync, openSync } from 'node:fs';
 import { dirname } from 'node:path';
 
-import { jsonlogify } from '@dxos/util';
-
 import { type LogFilter, LogLevel } from '../config';
-import { type LogProcessor, getContextFromEntry, shouldLog } from '../context';
-import { getRelativeFilename } from './common';
+import { type LogProcessor, shouldLog } from '../context';
 
 // Amount of time to retry writing after encountering EAGAIN before giving up.
 const EAGAIN_MAX_DURATION = 1000;
@@ -49,10 +46,12 @@ export const createFileProcessor = ({
     }
 
     const record = {
-      ...entry,
-      timestamp: Date.now(),
-      ...(entry.meta ? { meta: { file: getRelativeFilename(entry.meta.F), line: entry.meta.L } } : {}),
-      context: jsonlogify(getContextFromEntry(entry)),
+      level: entry.level,
+      message: entry.message,
+      timestamp: entry.timestamp,
+      meta: entry.computedMeta,
+      context: entry.computedContext,
+      error: entry.computedError,
     };
     let retryTS: number = 0;