@alchemy/common 0.0.0-alpha.0

package/src/logging/config.ts

@@ -0,0 +1,365 @@
+/**
+ * Log level constants for controlling diagnostics output.
+ * Lower numeric values indicate higher priority (more restrictive filtering).
+ *
+ * @example
+ * ```ts
+ * import { LogLevel, setGlobalLoggerConfig } from "@alchemy/common";
+ *
+ * setGlobalLoggerConfig({ level: LogLevel.DEBUG });
+ * ```
+ */
+export const LogLevel = {
+  /** Critical errors only */
+  ERROR: 0,
+  /** Warnings and errors */
+  WARN: 1,
+  /** Informational messages, warnings, and errors */
+  INFO: 2,
+  /** Debug messages and all above */
+  DEBUG: 3,
+  /** All messages including verbose details */
+  VERBOSE: 4,
+} as const;
+
+// eslint-disable-next-line @typescript-eslint/no-redeclare
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+
+/**
+ * Configuration for redacting sensitive data in log output.
+ */
+export type RedactConfig = {
+  /** Predicate function to test if a key should be redacted. Returns true if the key should be redacted. */
+  keys?: (key: string) => boolean;
+  /** Function to replace redacted values. Defaults to returning "[REDACTED]". */
+  replacer?: (value: unknown, key?: string) => unknown;
+};
+
+/**
+ * Configuration for the diagnostics logging system.
+ * All properties are optional and will use sensible defaults if not provided.
+ */
+export type DiagnosticsConfig = {
+  /** Minimum log level to emit. Defaults to INFO in development, ERROR in production. */
+  level?: LogLevel;
+  /** Configuration for redacting sensitive data in logs. */
+  redact?: RedactConfig;
+  /** Array of sink functions to receive log entries. Defaults to console sink. */
+  sinks?: Array<(entry: LogEntry) => void>;
+  /** Disable telemetry headers in requests. Defaults to false. */
+  disableTelemetryHeaders?: boolean;
+  /** Array of exact namespace strings to allow. If undefined or empty, all namespaces are enabled. Example: ["aa-infra", "wallet-apis"] */
+  enabledNamespaces?: string[];
+};
+
+/**
+ * Base context attached to all log entries from a logger instance.
+ */
+export type LoggerContextBase = {
+  /** Package name (e.g., "@alchemy/aa-infra") */
+  package: string;
+  /** Package version (e.g., "1.0.0") */
+  version: string;
+};
+
+/**
+ * A single log entry emitted by the diagnostics logger.
+ */
+export type LogEntry = {
+  /** Timestamp in milliseconds since epoch (Date.now()) */
+  ts: number;
+  /** Log level of this entry */
+  level: LogLevel;
+  /** Optional namespace for filtering/grouping (e.g., "aa-infra", "wallet-apis") */
+  namespace: string | undefined;
+  /** The log message */
+  message: string;
+  /** Optional structured data attached to this log entry */
+  data?: Record<string, unknown>;
+  /** Package context (name and version) */
+  context: LoggerContextBase;
+};
+
+let globalConfig: Required<DiagnosticsConfig> | undefined;
+
+function defaultConfig(): Required<DiagnosticsConfig> {
+  const env = (typeof process !== "undefined" && process.env) || {};
+
+  // Default level: INFO in dev, ERROR in prod
+  const isDev = env.NODE_ENV === "development";
+  const defaultLevel = isDev ? LogLevel.INFO : LogLevel.ERROR;
+
+  let level: LogLevel = defaultLevel;
+  const envLevel = env.ALCHEMY_LOG_LEVEL;
+  if (envLevel) {
+    const normalized = envLevel.toUpperCase() as keyof typeof LogLevel;
+    if (normalized in LogLevel) {
+      level = LogLevel[normalized];
+    } else {
+      console.warn(
+        `[alchemy/common] Invalid ALCHEMY_LOG_LEVEL value: "${envLevel}". Expected one of: ERROR, WARN, INFO, DEBUG, VERBOSE. Using default: ${isDev ? "INFO" : "ERROR"}`,
+      );
+    }
+  }
+
+  return {
+    level,
+    redact: {
+      keys: (key: string) =>
+        /^(authorization|apiKey|jwt|privateKey|secret|password)$/i.test(key),
+      replacer: () => "[REDACTED]",
+    },
+    sinks: [consoleSink],
+    disableTelemetryHeaders: false,
+    enabledNamespaces: [],
+  };
+}
+
+/**
+ * Gets the current global logger configuration.
+ * If not yet initialized, returns default configuration based on environment.
+ *
+ * @returns {Required<DiagnosticsConfig>} The current global configuration with all fields populated
+ * @example
+ * ```ts
+ * import { getGlobalLoggerConfig } from "@alchemy/common";
+ *
+ * const config = getGlobalLoggerConfig();
+ * console.log("Current log level:", config.level);
+ * ```
+ */
+export function getGlobalLoggerConfig(): Required<DiagnosticsConfig> {
+  globalConfig ??= defaultConfig();
+  return globalConfig;
+}
+
+/**
+ * Sets the global logger configuration.
+ * Partial configuration is supported - unspecified fields retain their current values.
+ *
+ * Configuration precedence (highest to lowest):
+ * 1. Explicit setGlobalLoggerConfig calls
+ * 2. ALCHEMY_LOG_LEVEL environment variable
+ * 3. Defaults (INFO in dev, ERROR in prod)
+ *
+ * @param {DiagnosticsConfig} cfg - Partial configuration to apply
+ * @example
+ * ```ts
+ * import { setGlobalLoggerConfig, LogLevel } from "@alchemy/common";
+ *
+ * // Set log level only
+ * setGlobalLoggerConfig({ level: LogLevel.DEBUG });
+ *
+ * // Add custom sink
+ * setGlobalLoggerConfig({
+ *   sinks: [(entry) => console.log(JSON.stringify(entry))]
+ * });
+ *
+ * // Filter to specific namespaces
+ * setGlobalLoggerConfig({
+ *   enabledNamespaces: ["aa-infra", "wallet-apis"]
+ * });
+ * ```
+ */
+export function setGlobalLoggerConfig(cfg: DiagnosticsConfig): void {
+  const current = getGlobalLoggerConfig();
+  globalConfig = {
+    level: cfg.level ?? current.level,
+    redact: cfg.redact ?? current.redact,
+    sinks: cfg.sinks ?? current.sinks,
+    disableTelemetryHeaders:
+      cfg.disableTelemetryHeaders ?? current.disableTelemetryHeaders,
+    enabledNamespaces:
+      "enabledNamespaces" in cfg
+        ? (cfg.enabledNamespaces ?? [])
+        : current.enabledNamespaces,
+  };
+}
+
+/**
+ * Checks if a given log level is enabled based on current global configuration.
+ * Used internally by logger to short-circuit disabled log statements.
+ *
+ * @param {LogLevel} level - The log level to check
+ * @returns {boolean} True if the level is enabled (will be logged), false otherwise
+ * @example
+ * ```ts
+ * import { isLevelEnabled, LogLevel } from "@alchemy/common";
+ *
+ * if (isLevelEnabled(LogLevel.DEBUG)) {
+ *   // Perform expensive debug computation
+ * }
+ * ```
+ */
+export function isLevelEnabled(level: LogLevel): boolean {
+  return level <= getGlobalLoggerConfig().level;
+}
+
+/**
+ * Checks if a given namespace is enabled based on current global configuration.
+ * Used internally by logger to short-circuit logs from disabled namespaces.
+ *
+ * @param {string | undefined} namespace - The namespace to check
+ * @returns {boolean} True if the namespace is enabled (will be logged), false otherwise
+ * @example
+ * ```ts
+ * import { isNamespaceEnabled } from "@alchemy/common";
+ *
+ * if (isNamespaceEnabled("aa-infra")) {
+ *   // This namespace is enabled
+ * }
+ * ```
+ */
+export function isNamespaceEnabled(namespace: string | undefined): boolean {
+  const { enabledNamespaces } = getGlobalLoggerConfig();
+
+  // If no filter is set or it's an empty array, all namespaces are enabled
+  if (!enabledNamespaces || enabledNamespaces.length === 0) {
+    return true;
+  }
+
+  // If namespace is undefined, disable it (only named namespaces can be filtered)
+  if (namespace === undefined) {
+    return false;
+  }
+
+  // Check if the namespace is in the enabled list
+  return enabledNamespaces.includes(namespace);
+}
+
+/**
+ * Redacts sensitive keys in an object based on global redaction configuration.
+ * Performs deep redaction by recursively processing nested objects and arrays.
+ * Default redaction includes: authorization, apiKey, jwt, privateKey, secret, password.
+ *
+ * @param {Record<string, unknown> | undefined} obj - The object to redact
+ * @returns {Record<string, unknown> | undefined} A new object with sensitive values redacted, or undefined if input was undefined
+ * @example
+ * ```ts
+ * import { redactObject } from "@alchemy/common";
+ *
+ * const data = {
+ *   apiKey: "secret123",
+ *   userId: "user-456",
+ *   nested: { secret: "hidden" }
+ * };
+ *
+ * const redacted = redactObject(data);
+ * // { apiKey: "[REDACTED]", userId: "user-456", nested: { secret: "[REDACTED]" } }
+ * ```
+ */
+export function redactObject(
+  obj: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+  if (!obj) return obj;
+  const { keys, replacer } = getGlobalLoggerConfig().redact;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (keys && keys(k)) {
+      out[k] = replacer ? replacer(v, k) : "[REDACTED]";
+    } else if (Array.isArray(v)) {
+      // Recursively redact array elements
+      out[k] = v.map((item) =>
+        item != null && typeof item === "object"
+          ? redactObject(item as Record<string, unknown>)
+          : item,
+      );
+    } else if (v != null && typeof v === "object") {
+      // Recursively redact nested objects
+      out[k] = redactObject(v as Record<string, unknown>);
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+/**
+ * Format timestamp as HH:MM:SS.mmm
+ *
+ * @param {number} ts - Timestamp in milliseconds since epoch
+ * @returns {string} Formatted timestamp string
+ */
+function formatTimestamp(ts: number): string {
+  const date = new Date(ts);
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  const seconds = String(date.getSeconds()).padStart(2, "0");
+  const milliseconds = String(date.getMilliseconds()).padStart(3, "0");
+  return `${hours}:${minutes}:${seconds}.${milliseconds}`;
+}
+
+/**
+ * Format data as a JSON object for console output.
+ * Filters out context fields (package, version) to avoid duplication.
+ * Handles BigInt values by converting them to strings.
+ *
+ * @param {Record<string, unknown> | undefined} data - The data object to format
+ * @returns {string} Formatted JSON string with leading space, or empty string if no data
+ */
+function formatData(data: Record<string, unknown> | undefined): string {
+  if (!data || Object.keys(data).length === 0) return "";
+
+  // Filter out context fields (package, version) and create clean object
+  const filtered = Object.entries(data)
+    .filter(([key]) => key !== "package" && key !== "version")
+    .reduce(
+      (acc, [key, value]) => {
+        acc[key] = value;
+        return acc;
+      },
+      {} as Record<string, unknown>,
+    );
+
+  if (Object.keys(filtered).length === 0) return "";
+
+  return (
+    " " +
+    JSON.stringify(filtered, (_key, value) =>
+      typeof value === "bigint" ? value.toString() : value,
+    )
+  );
+}
+
+/**
+ * Default console sink for diagnostics logging.
+ * Routes log entries to appropriate console methods based on log level.
+ *
+ * Format: [HH:MM:SS.mmm] [package@version] message {data}
+ *
+ * @param {LogEntry} entry - The log entry to output
+ * @example
+ * ```ts
+ * import { consoleSink, setGlobalLoggerConfig } from "@alchemy/common";
+ *
+ * // Console sink is used by default, but can be explicitly configured
+ * setGlobalLoggerConfig({
+ *   sinks: [consoleSink]
+ * });
+ * ```
+ */
+export function consoleSink(entry: LogEntry): void {
+  const { ts, level, message, data, context } = entry;
+  const timestamp = formatTimestamp(ts);
+  const prefix = `[${timestamp}] [${context.package}@${context.version}]`;
+  const dataStr = formatData(data);
+  const output = `${prefix} ${message}${dataStr}`;
+
+  switch (level) {
+    case LogLevel.ERROR:
+      console.error(output);
+      break;
+    case LogLevel.WARN:
+      console.warn(output);
+      break;
+    case LogLevel.INFO:
+      console.info(output);
+      break;
+    case LogLevel.DEBUG:
+      console.debug(output);
+      break;
+    case LogLevel.VERBOSE:
+      console.log(output);
+      break;
+  }
+}

package/src/logging/index.ts

@@ -0,0 +1,20 @@
+export { createLogger, LogLevel, consoleSink } from "./logger.js";
+export type { DiagnosticsLogger } from "./logger.js";
+export {
+  setGlobalLoggerConfig,
+  getGlobalLoggerConfig,
+  isLevelEnabled,
+  isNamespaceEnabled,
+  redactObject,
+} from "./config.js";
+export type {
+  LogEntry,
+  DiagnosticsConfig,
+  RedactConfig,
+  LoggerContextBase,
+} from "./config.js";
+
+// Testing utilities
+export { InMemorySink } from "./sinks.js";
+
+export type * from "./types.js";

package/src/logging/local.ts

@@ -0,0 +1,39 @@
+import type { EventsSchema, InnerLogger, LoggerContext } from "./types.js";
+import { isClientDevMode } from "./utils.js";
+
+/**
+ * Creates a local-only logger that outputs events to the console in development mode.
+ * This logger does not send data to external services and is safe for all environments.
+ *
+ * @template Schema - The events schema defining allowed events and their data structures
+ * @param {LoggerContext} context - Context information to attach to all events
+ * @returns {InnerLogger<Schema>} A logger instance that logs to console in dev mode
+ */
+export function createLocalLogger<Schema extends EventsSchema = []>(
+  context: LoggerContext,
+): InnerLogger<Schema> {
+  const isDev = isClientDevMode();
+
+  // Generate a simple anonymous ID for local logging
+  const anonId = `local-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+
+  return {
+    _internal: {
+      ready: Promise.resolve(),
+      anonId,
+    },
+    trackEvent: async ({ name, data }) => {
+      if (isDev) {
+        try {
+          console.log(`[${context.package}] Event: ${name}`, {
+            ...data,
+            ...context,
+            timestamp: new Date().toISOString(),
+          });
+        } catch {
+          // Silently ignore console logging errors
+        }
+      }
+    },
+  };
+}

package/src/logging/logger.ts

@@ -0,0 +1,194 @@
+import {
+  LogLevel,
+  consoleSink,
+  getGlobalLoggerConfig,
+  isLevelEnabled,
+  isNamespaceEnabled,
+  redactObject,
+  type LoggerContextBase,
+  type LogEntry,
+} from "./config.js";
+
+/**
+ * Lazy message supplier function for expensive log computations.
+ * Only evaluated when the log level is enabled.
+ *
+ * @returns {[string, Record<string, unknown>?]} Tuple of [message, optional data]
+ */
+type MessageSupplier = () => [string, Record<string, unknown>?];
+
+/**
+ * Diagnostics logger instance for developer-facing debugging output.
+ * Provides level-based logging (error, warn, info, debug, verbose) with structured data.
+ */
+export type DiagnosticsLogger = {
+  /** Log debug messages for development and troubleshooting */
+  debug: (
+    msg: string | MessageSupplier,
+    data?: Record<string, unknown>,
+  ) => void;
+  /** Log informational messages for key operations */
+  info: (msg: string | MessageSupplier, data?: Record<string, unknown>) => void;
+  /** Log warnings for recoverable issues */
+  warn: (msg: string | MessageSupplier, data?: Record<string, unknown>) => void;
+  /** Log errors for failures */
+  error: (
+    msg: string | MessageSupplier,
+    data?: Record<string, unknown>,
+  ) => void;
+  /** Log verbose details for very detailed tracing */
+  verbose: (
+    msg: string | MessageSupplier,
+    data?: Record<string, unknown>,
+  ) => void;
+  /** Create a child logger with additional context merged into all log entries */
+  withContext: (extra: Record<string, unknown>) => DiagnosticsLogger;
+  /**
+   * Wrap a function to measure and log its execution time at DEBUG level.
+   * Supports both synchronous and asynchronous functions.
+   *
+   * @template TArgs - Function argument types
+   * @template TRet - Function return type
+   * @param name - Name for profiling logs
+   * @param func - Function to profile
+   * @returns Wrapped function that logs execution time
+   */
+  profiled<TArgs extends any[], TRet>(
+    name: string,
+    func: (...args: TArgs) => TRet,
+  ): (...args: TArgs) => TRet;
+};
+
+/**
+ * Parameters for creating a diagnostics logger instance.
+ */
+export type CreateLoggerParams = LoggerContextBase & {
+  /** Optional namespace for filtering/grouping (e.g., "aa-infra", "wallet-apis") */
+  namespace?: string;
+  /** Optional base context merged into all log entries from this logger */
+  baseContext?: Record<string, unknown>;
+};
+
+/**
+ * Creates a diagnostics logger instance for a package.
+ * Loggers emit structured log entries to configured sinks (default: console).
+ *
+ * All log methods support:
+ * - String messages: `logger.info("message", { data })`
+ * - Lazy suppliers: `logger.debug(() => ["expensive", computeData()])` (only evaluated when level enabled)
+ *
+ * @param {CreateLoggerParams} params - Logger configuration
+ * @returns {DiagnosticsLogger} A logger instance
+ * @example
+ * ```ts
+ * import { createLogger } from "@alchemy/common";
+ *
+ * const logger = createLogger({
+ *   package: "@alchemy/aa-infra",
+ *   version: "1.0.0",
+ *   namespace: "aa-infra"
+ * });
+ *
+ * logger.info("processing request", { chainId: 1 });
+ * logger.debug("detailed state", { userOp: op });
+ *
+ * // Child logger with additional context
+ * const childLogger = logger.withContext({ requestId: "123" });
+ * childLogger.info("step complete"); // includes requestId in all logs
+ *
+ * // Profile a function
+ * const sendWithProfiling = logger.profiled("sendUserOp", sendUserOp);
+ * await sendWithProfiling(op); // logs execution time at DEBUG level
+ * ```
+ */
+export function createLogger(params: CreateLoggerParams): DiagnosticsLogger {
+  const { namespace, baseContext, ...ctx } = params;
+
+  function emit(
+    level: LogLevel,
+    msgOrFn: string | MessageSupplier,
+    data?: Record<string, unknown>,
+  ) {
+    if (!isLevelEnabled(level)) return;
+    if (!isNamespaceEnabled(namespace)) return;
+
+    let message: string;
+    let payload: Record<string, unknown> | undefined = data;
+
+    if (typeof msgOrFn === "function") {
+      const [m, d] = msgOrFn();
+      message = m;
+      payload = d ?? data;
+    } else {
+      message = msgOrFn;
+    }
+
+    const entry: LogEntry = {
+      ts: Date.now(),
+      level,
+      namespace,
+      message,
+      data: redactObject({ ...(baseContext || {}), ...(payload || {}) }),
+      context: ctx,
+    };
+
+    for (const sink of getGlobalLoggerConfig().sinks) {
+      try {
+        sink(entry);
+      } catch (e) {
+        // Silently continue if a sink throws - don't break other sinks
+      }
+    }
+  }
+
+  const logger: DiagnosticsLogger = {
+    debug: (m, d) => emit(LogLevel.DEBUG, m, d),
+    info: (m, d) => emit(LogLevel.INFO, m, d),
+    warn: (m, d) => emit(LogLevel.WARN, m, d),
+    error: (m, d) => emit(LogLevel.ERROR, m, d),
+    verbose: (m, d) => emit(LogLevel.VERBOSE, m, d),
+    withContext(extra) {
+      return createLogger({
+        ...params,
+        baseContext: { ...(baseContext || {}), ...extra },
+      });
+    },
+    profiled<TArgs extends any[], TRet>(
+      name: string,
+      func: (...args: TArgs) => TRet,
+    ) {
+      return function profiledWrapper(this: any, ...args: TArgs): TRet {
+        const start = Date.now();
+        const result = func.apply(this, args) as TRet;
+        const finish = (ok: boolean) => {
+          const dur = Date.now() - start;
+          const msg = ok ? `profiled ${name}` : `profiled ${name} (failed)`;
+          // Use DEBUG for timing
+          emit(LogLevel.DEBUG, msg, {
+            executionTimeMs: dur,
+            functionName: name,
+          });
+        };
+        const maybePromise = result as unknown as { then?: Function };
+        if (maybePromise && typeof maybePromise.then === "function") {
+          return (result as unknown as Promise<unknown>).then(
+            (r) => {
+              finish(true);
+              return r as TRet;
+            },
+            (e) => {
+              finish(false);
+              throw e;
+            },
+          ) as unknown as TRet;
+        }
+        finish(true);
+        return result as TRet;
+      };
+    },
+  };
+
+  return logger;
+}
+
+export { LogLevel, consoleSink };

package/src/logging/noop.ts

@@ -0,0 +1,13 @@
+import type { InnerLogger } from "./types.js";
+
+/**
+ * No-operation logger that discards all events.
+ * Used as a fallback when logger initialization fails or in disabled states.
+ */
+export const noopLogger: InnerLogger<any> = {
+  trackEvent: async () => {},
+  _internal: {
+    ready: Promise.resolve(),
+    anonId: "",
+  },
+};