@dxos/log 0.8.4-main.fd6878d → 0.8.4-main.fffef41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/log",
-  "version": "0.8.4-main.fd6878d",
+  "version": "0.8.4-main.fffef41",
   "description": "Logger",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -35,8 +35,8 @@
     "js-yaml": "^4.1.0",
     "lodash.defaultsdeep": "^4.6.1",
     "lodash.omit": "^4.5.0",
-    "@dxos/node-std": "0.8.4-main.fd6878d",
-    "@dxos/util": "0.8.4-main.fd6878d"
+    "@dxos/node-std": "0.8.4-main.fffef41",
+    "@dxos/util": "0.8.4-main.fffef41"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.5",

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

@@ -27,8 +27,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,10 +61,16 @@ 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);
 };
 
 export const getContextFromEntry = (entry: LogEntry): Record<string, any> | undefined => {

package/src/decorators.ts

@@ -6,7 +6,7 @@ import { inspect } from 'node:util';
 
 import chalk from 'chalk';
 
-import type { LogMethods } from './log';
+import { type LogMethods } from './log';
 import { type CallMetadata } from './meta';
 
 let nextPromiseId = 0;
@@ -191,13 +191,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}`);

package/src/log.test.ts

@@ -4,10 +4,11 @@
 
 import path from 'node:path';
 
-import { describe, test } from 'vitest';
+import { beforeEach, describe, test } from 'vitest';
 
 import { LogLevel } from './config';
-import { log } from './log';
+import { shouldLog } from './context';
+import { type Log, createLog } from './log';
 
 class LogError extends Error {
   constructor(
@@ -25,13 +26,52 @@ class LogError extends Error {
   }
 }
 
-log.config({
-  filter: LogLevel.DEBUG,
-});
+describe('log', () => {
+  let log!: Log;
 
-/* eslint-disable prefer-arrow-functions/prefer-arrow-functions */
+  beforeEach(() => {
+    log = createLog();
+    log.config({
+      filter: LogLevel.DEBUG,
+    });
+  });
+
+  test('filters', ({ expect }) => {
+    const tests = [
+      { expected: 0, filter: 'ERROR' },
+      { expected: 2, filter: 'INFO' },
+      { expected: 1, filter: 'foo:INFO' },
+      { expected: 4, filter: 'DEBUG' },
+      { expected: 2, filter: 'DEBUG,-foo:*' },
+      { expected: 1, filter: 'INFO,-foo:*' },
+      { expected: 3, filter: 'DEBUG,-foo:INFO' },
+      { expected: 3, filter: 'foo:DEBUG,bar:INFO' },
+    ];
+
+    for (const test of tests) {
+      let count = 0;
+      const log = createLog();
+      const remove = log.addProcessor((config, entry) => {
+        if (shouldLog(entry, config.filters)) {
+          count++;
+        }
+      });
+      log.config({
+        filter: test.filter,
+      });
+
+      console.group(`Filter: "${test.filter}"`);
+      log.debug('line 1', {}, { F: 'foo.ts', L: 1, S: undefined });
+      log.info('line 2', {}, { F: 'foo.ts', L: 2, S: undefined });
+      log.debug('line 3', {}, { F: 'bar.ts', L: 3, S: undefined });
+      log.info('line 4', {}, { F: 'bar.ts', L: 4, S: undefined });
+      console.groupEnd();
+
+      expect(count, `Filter: "${test.filter}"`).toBe(test.expected);
+      remove();
+    }
+  });
 
-describe('log', () => {
   test('throws an error', () => {
     try {
       throw new LogError('Test failed', { value: 1 });
@@ -56,16 +96,6 @@ describe('log', () => {
     }
   });
 
-  test('config', () => {
-    log.config({
-      filter: LogLevel.INFO,
-    });
-
-    log.debug('Debug level log message');
-    log.info('Info level log message');
-    log.warn('Warn level log message');
-  });
-
   test('config file', () => {
     log.config({
       file: path.join('packages/common/log/test-config.yml'),
@@ -91,7 +121,7 @@ describe('log', () => {
     });
   });
 
-  test('error', function () {
+  test('error', () => {
     const myError = new Error('Test error', { cause: new Error('Cause') });
     log.catch(myError);
   });

package/src/log.ts

@@ -6,7 +6,14 @@ import { type LogConfig, LogLevel, type LogOptions } from './config';
 import { type LogContext, type LogProcessor } from './context';
 import { createFunctionLogDecorator, createMethodLogDecorator } from './decorators';
 import { type CallMetadata } from './meta';
-import { DEFAULT_PROCESSORS, getConfig } from './options';
+import { createConfig } from './options';
+
+/**
+ * Accessible from browser console.
+ */
+declare global {
+  const DX_LOG: Log;
+}
 
 /**
  * Logging function.
@@ -17,6 +24,9 @@ type LogFunction = (message: string, context?: LogContext, meta?: CallMetadata)
  * Logging methods.
  */
 export interface LogMethods {
+  config: (options: LogOptions) => Log;
+  addProcessor: (processor: LogProcessor, addDefault?: boolean) => () => void;
+
   trace: LogFunction;
   debug: LogFunction;
   verbose: LogFunction;
@@ -24,70 +34,56 @@ export interface LogMethods {
   warn: LogFunction;
   error: LogFunction;
   catch: (error: Error | any, context?: LogContext, meta?: CallMetadata) => void;
-  break: () => void;
-  stack: (message?: string, context?: never, meta?: CallMetadata) => void;
+
   method: (arg0?: never, arg1?: never, meta?: CallMetadata) => MethodDecorator;
-  func: <F extends (...args: any[]) => any>(
+  function: <F extends (...args: any[]) => any>(
     name: string,
     fn: F,
-    opts?: { transformOutput?: (result: ReturnType<F>) => Promise<any> | any },
+    opts?: {
+      transformOutput?: (result: ReturnType<F>) => Promise<any> | any;
+    },
   ) => F;
+
+  break: () => void;
+  stack: (message?: string, context?: never, meta?: CallMetadata) => void;
 }
 
 /**
  * Properties accessible on the logging function.
+ * @internal
  */
-interface Log extends LogMethods, LogFunction {
-  config: (options: LogOptions) => void;
-  addProcessor: (processor: LogProcessor) => void;
-  runtimeConfig: LogConfig;
+export interface Log extends LogFunction, LogMethods {
+  readonly runtimeConfig: LogConfig;
 }
 
+/**
+ * @internal
+ */
 interface LogImp extends Log {
+  _id: string;
   _config: LogConfig;
 }
 
-const createLog = (): LogImp => {
-  const log: LogImp = ((...params) => processLog(LogLevel.DEBUG, ...params)) as LogImp;
-
-  log._config = getConfig();
-  Object.defineProperty(log, 'runtimeConfig', { get: () => log._config });
-
-  log.addProcessor = (processor: LogProcessor) => {
-    if (DEFAULT_PROCESSORS.filter((p) => p === processor).length === 0) {
-      DEFAULT_PROCESSORS.push(processor);
-    }
-    if (log._config.processors.filter((p) => p === processor).length === 0) {
-      log._config.processors.push(processor);
-    }
-  };
-
-  // Set config.
-  log.config = (options: LogOptions) => {
-    log._config = getConfig(options);
-  };
-
-  // TODO(burdon): API to set context and separate error object.
-  //  E.g., log.warn('failed', { key: 123 }, err);
-
-  log.trace = (...params) => processLog(LogLevel.TRACE, ...params);
-  log.debug = (...params) => processLog(LogLevel.DEBUG, ...params);
-  log.verbose = (...params) => processLog(LogLevel.VERBOSE, ...params);
-  log.info = (...params) => processLog(LogLevel.INFO, ...params);
-  log.warn = (...params) => processLog(LogLevel.WARN, ...params);
-  log.error = (...params) => processLog(LogLevel.ERROR, ...params);
+let logCount = 0;
 
-  // Catch only shows error message, not stacktrace.
-  log.catch = (error: Error | any, context, meta) => processLog(LogLevel.ERROR, undefined, context, meta, error);
-
-  // Show break.
-  log.break = () => log.info('——————————————————————————————————————————————————');
+/**
+ * Create a logging function with properties.
+ * @internal
+ */
+export const createLog = (): LogImp => {
+  // Default function.
+  const log: LogImp = ((...params) => processLog(LogLevel.DEBUG, ...params)) as LogImp;
 
-  log.stack = (message, context, meta) =>
-    processLog(LogLevel.INFO, `${message ?? 'Stack Dump'}\n${getFormattedStackTrace()}`, context, meta);
+  // Add private properties.
+  Object.assign<LogImp, Partial<LogImp>>(log, {
+    _id: `log-${++logCount}`,
+    _config: createConfig(),
+  });
 
-  log.method = createMethodLogDecorator(log);
-  log.func = createFunctionLogDecorator(log);
+  // TODO(burdon): Document.
+  Object.defineProperty(log, 'runtimeConfig', {
+    get: () => log._config,
+  });
 
   /**
    * Process the current log call.
@@ -99,16 +95,72 @@ const createLog = (): LogImp => {
     meta?: CallMetadata,
     error?: Error,
   ) => {
-    log._config.processors.forEach((processor) => processor(log._config, { level, message, context, meta, 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,
+      }),
+    );
   };
 
+  /**
+   * API.
+   */
+  Object.assign<Log, LogMethods>(log, {
+    /**
+     * Update config.
+     * NOTE: Preserves any processors that were already added to this logger instance
+     * unless an explicit processor option is provided.
+     */
+    config: ({ processor, ...options }) => {
+      const config = createConfig(options);
+      // TODO(burdon): This could be buggy since the behavior is not reentrant.
+      const processors = processor ? config.processors : log._config.processors;
+      log._config = { ...config, processors };
+      return log;
+    },
+
+    /**
+     * Adds a processor to the logger.
+     */
+    addProcessor: (processor) => {
+      if (log._config.processors.filter((p) => p === processor).length === 0) {
+        log._config.processors.push(processor);
+      }
+
+      return () => {
+        log._config.processors = log._config.processors.filter((p) => p !== processor);
+      };
+    },
+
+    trace: (...params) => processLog(LogLevel.TRACE, ...params),
+    debug: (...params) => processLog(LogLevel.DEBUG, ...params),
+    verbose: (...params) => processLog(LogLevel.VERBOSE, ...params),
+    info: (...params) => processLog(LogLevel.INFO, ...params),
+    warn: (...params) => processLog(LogLevel.WARN, ...params),
+    error: (...params) => processLog(LogLevel.ERROR, ...params),
+    catch: (error, context, meta) => processLog(LogLevel.ERROR, undefined, context, meta, error),
+
+    method: createMethodLogDecorator(log),
+    function: createFunctionLogDecorator(log),
+
+    break: () => log.info('-'.repeat(80)),
+    stack: (message, context, meta) => {
+      return processLog(LogLevel.INFO, `${message ?? 'Stack Dump'}\n${getFormattedStackTrace()}`, context, meta);
+    },
+  });
+
   return log;
 };
 
 /**
  * Global logging function.
  */
-export const log: Log = ((globalThis as any).dx_log ??= createLog());
+export const log: Log = ((globalThis as any).DX_LOG ??= createLog());
 
 const start = Date.now();
 let last = start;
@@ -128,12 +180,4 @@ export const debug = (label?: any, args?: any) => {
   last = Date.now();
 };
 
-/**
- * Accessible from browser console.
- */
-declare global {
-  // eslint-disable-next-line camelcase
-  const dx_log: Log;
-}
-
 const getFormattedStackTrace = () => new Error().stack!.split('\n').slice(3).join('\n');

package/src/options.ts

@@ -12,32 +12,46 @@ import { BROWSER_PROCESSOR, CONSOLE_PROCESSOR, DEBUG_PROCESSOR } from './process
 /**
  * Processor variants.
  */
-export const processors: { [index: string]: LogProcessor } = {
+export const processors: Record<string, LogProcessor> = {
   [LogProcessorType.CONSOLE]: CONSOLE_PROCESSOR,
   [LogProcessorType.BROWSER]: BROWSER_PROCESSOR,
   [LogProcessorType.DEBUG]: DEBUG_PROCESSOR,
 };
 
-const IS_BROWSER = typeof window !== 'undefined' || typeof navigator !== 'undefined';
+const browser = typeof window !== 'undefined' || typeof navigator !== 'undefined';
 
-export const DEFAULT_PROCESSORS = [IS_BROWSER ? BROWSER_PROCESSOR : CONSOLE_PROCESSOR];
+export const DEFAULT_PROCESSORS = [browser ? BROWSER_PROCESSOR : CONSOLE_PROCESSOR];
 
+const parseLogLevel = (level: string, defValue = LogLevel.WARN) => levels[level.toLowerCase()] ?? defValue;
+
+/**
+ * @internal
+ */
 export const parseFilter = (filter: string | string[] | LogLevel): LogFilter[] => {
   if (typeof filter === 'number') {
     return [{ level: filter }];
   }
 
-  const parseLogLevel = (level: string, defValue = LogLevel.WARN) => levels[level.toLowerCase()] ?? defValue;
-
   const lines = typeof filter === 'string' ? filter.split(/,\s*/) : filter;
   return lines.map((filter) => {
     const [pattern, level] = filter.split(':');
-    return level ? { level: parseLogLevel(level), pattern } : { level: parseLogLevel(pattern) };
+    return level
+      ? {
+          level: parseLogLevel(level),
+          pattern,
+        }
+      : {
+          level: parseLogLevel(pattern),
+        };
   });
 };
 
-export const getConfig = (options?: LogOptions): LogConfig => {
-  const nodeOptions: LogOptions | undefined =
+/**
+ * @internal
+ */
+export const createConfig = (options?: LogOptions): LogConfig => {
+  // Node only.
+  const envOptions: LogOptions | undefined =
     'process' in globalThis
       ? {
           file: process!.env.LOG_CONFIG,
@@ -46,12 +60,12 @@ export const getConfig = (options?: LogOptions): LogConfig => {
         }
       : undefined;
 
-  const mergedOptions: LogOptions = defaultsDeep({}, loadOptions(nodeOptions?.file), nodeOptions, options);
+  const mergedOptions: LogOptions = defaultsDeep({}, loadOptions(envOptions?.file), envOptions, options);
   return {
     options: mergedOptions,
     filters: parseFilter(mergedOptions.filter ?? LogLevel.INFO),
     captureFilters: parseFilter(mergedOptions.captureFilter ?? LogLevel.WARN),
-    processors: mergedOptions.processor ? [processors[mergedOptions.processor]] : DEFAULT_PROCESSORS,
+    processors: mergedOptions.processor ? [processors[mergedOptions.processor]] : [...DEFAULT_PROCESSORS],
     prefix: mergedOptions.prefix,
   };
 };

package/src/processors/browser-processor.ts

@@ -74,6 +74,8 @@ const APP_BROWSER_PROCESSOR: LogProcessor = (config, entry) => {
   if (context) {
     if (Object.keys(context).length === 1 && 'error' in context) {
       args.push(context.error);
+    } else if (Object.keys(context).length === 1 && 'err' in context) {
+      args.push(context.err);
     } else {
       args.push(context);
     }

package/src/processors/file-processor.ts

@@ -14,6 +14,7 @@ import { getRelativeFilename } from './common';
 
 // Amount of time to retry writing after encountering EAGAIN before giving up.
 const EAGAIN_MAX_DURATION = 1000;
+
 /**
  * Create a file processor.
  * @param path - Path to log file to create or append to, or existing open file descriptor e.g. stdout.
@@ -38,6 +39,7 @@ export const createFileProcessor = ({
     if (!shouldLog(entry, filters)) {
       return;
     }
+
     if (typeof pathOrFd === 'number') {
       fd = pathOrFd;
     } else {