@dxos/log 0.8.4-staging.ac66bdf99f → 0.9.0

package/src/log.ts

@@ -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;
 }
 

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/index.ts

@@ -6,4 +6,3 @@ export * from './browser-processor';
 export * from './common';
 export * from '#console-processor';
 export * from './debug-processor';
-export * from './file-processor';