@dxos/log 0.8.4-main.b97322e → 0.8.4-main.bbf232bc24

package/package.json

@@ -1,47 +1,62 @@
 {
   "name": "@dxos/log",
-  "version": "0.8.4-main.b97322e",
+  "version": "0.8.4-main.bbf232bc24",
   "description": "Logger",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
   "sideEffects": true,
   "type": "module",
+  "imports": {
+    "#platform": {
+      "source": {
+        "browser": "./src/platform/browser/index.ts",
+        "default": "./src/platform/node/index.ts"
+      },
+      "types": "./dist/types/src/platform/node/index.d.ts",
+      "browser": "./dist/lib/browser/platform/browser/index.mjs",
+      "default": "./dist/lib/node-esm/platform/node/index.mjs"
+    },
+    "#console-processor": {
+      "source": {
+        "browser": "./src/processors/console-stub.ts",
+        "default": "./src/processors/console-processor.ts"
+      },
+      "types": "./dist/types/src/processors/console-processor.d.ts",
+      "browser": "./dist/lib/browser/processors/console-stub.mjs",
+      "default": "./dist/lib/node-esm/processors/console-processor.mjs"
+    }
+  },
   "exports": {
     ".": {
+      "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": {
         "require": "./dist/lib/node/index.cjs",
         "default": "./dist/lib/node-esm/index.mjs"
-      },
-      "types": "./dist/types/src/index.d.ts"
+      }
     }
   },
-  "browser": {
-    "./src/platform/node/index.ts": "./src/platform/browser/index.ts",
-    "./src/processors/console-processor.ts": "./src/processors/console-stub.ts"
-  },
   "types": "dist/types/src/index.d.ts",
-  "typesVersions": {
-    "*": {}
-  },
   "files": [
     "dist",
     "src"
   ],
   "dependencies": {
-    "chalk": "^4.1.0",
-    "js-yaml": "^4.1.0",
+    "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.b97322e",
-    "@dxos/util": "0.8.4-main.b97322e"
+    "@dxos/util": "0.8.4-main.bbf232bc24",
+    "@dxos/node-std": "0.8.4-main.bbf232bc24"
   },
   "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/config.ts

@@ -6,8 +6,8 @@ import { type LogProcessor } from './context';
 
 /**
  * Standard levels.
+ * NOTE: Keep aligned with LogLevel in @dxos/protocols.
  */
-// NOTE: Keep aligned with LogLevel in @dxos/protocols.
 // TODO(burdon): Update numbers?
 export enum LogLevel {
   TRACE = 5,
@@ -18,7 +18,8 @@ export enum LogLevel {
   ERROR = 14,
 }
 
-export const levels: { [index: string]: LogLevel } = {
+export const levels: Record<string, LogLevel> = {
+  '*': LogLevel.TRACE,
   trace: LogLevel.TRACE,
   debug: LogLevel.DEBUG,
   verbose: LogLevel.VERBOSE,

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 LogEntry {
+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 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;
+  }
 }
 
 /**
@@ -27,8 +156,33 @@ export interface LogEntry {
  */
 export type LogProcessor = (config: LogConfig, entry: LogEntry) => void;
 
-const matchFilter = (filter: LogFilter, level: LogLevel, path: string) => {
-  return level >= filter.level && (!filter.pattern || path.includes(filter.pattern));
+/**
+ * Returns:
+ * true if the log entry matches the filter,
+ * false if should be excluded, or
+ * undefined if it the filter doesn't match the level.
+ */
+const matchFilter = (filter: LogFilter, level: LogLevel, path?: string): boolean | undefined => {
+  // TODO(burdon): Support regexp.
+  if (filter.pattern?.startsWith('-')) {
+    // Exclude.
+    if (path?.includes(filter.pattern.slice(1))) {
+      if (level >= filter.level) {
+        return false;
+      }
+    }
+  } else {
+    // Include.
+    if (filter.pattern?.length) {
+      if (path?.includes(filter.pattern)) {
+        return level >= filter.level;
+      }
+    } else {
+      if (level >= filter.level) {
+        return true;
+      }
+    }
+  }
 };
 
 /**
@@ -36,12 +190,24 @@ const matchFilter = (filter: LogFilter, level: LogLevel, path: string) => {
  */
 export const shouldLog = (entry: LogEntry, filters?: LogFilter[]): boolean => {
   if (filters === undefined) {
-    return true;
-  } else {
-    return filters.some((filter) => matchFilter(filter, entry.level, entry.meta?.F ?? ''));
+    return false;
   }
+
+  const results = filters
+    .map((filter) => matchFilter(filter, entry.level, entry.meta?.F))
+    .filter((result): result is boolean => result !== undefined);
+
+  // Skip if any are explicitely false.
+  // console.log({ level: entry.level, path: entry.meta?.F }, filters, results, results.length);
+  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) {
@@ -69,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

@@ -5,7 +5,7 @@
 import chalk from 'chalk';
 import { inspect } from 'node:util';
 
-import type { LogMethods } from './log';
+import { type LogMethods } from './log';
 import { type CallMetadata } from './meta';
 
 let nextPromiseId = 0;
@@ -190,13 +190,13 @@ const logAsyncRejected = (
   );
 };
 
+const COLOR_FUNCTION = [220, 220, 170] as const;
+
 // https://github.com/dxos/dxos/issues/7286
 const greenCheck = typeof chalk.green === 'function' ? chalk.green('✔') : '✔';
 
 const formatTimeElapsed = (startTime: number) => chalk.gray(`${(performance.now() - startTime).toFixed(0)}ms`);
 
-const COLOR_FUNCTION = [220, 220, 170] as const;
-
 const formatFunction = (name: string) => chalk.bold(chalk.rgb(...COLOR_FUNCTION)(name));
 
 const formatPromise = (id: number) => chalk.blue(`Promise#${id}`);