@alchemy/common 0.0.0-alpha.0

package/dist/esm/logging/config.js

@@ -0,0 +1,279 @@
+/**
+ * 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,
+};
+let globalConfig;
+function defaultConfig() {
+    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 = defaultLevel;
+    const envLevel = env.ALCHEMY_LOG_LEVEL;
+    if (envLevel) {
+        const normalized = envLevel.toUpperCase();
+        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) => /^(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() {
+    globalConfig ?? (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) {
+    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) {
+    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) {
+    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) {
+    if (!obj)
+        return obj;
+    const { keys, replacer } = getGlobalLoggerConfig().redact;
+    const out = {};
+    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)
+                : item);
+        }
+        else if (v != null && typeof v === "object") {
+            // Recursively redact nested objects
+            out[k] = redactObject(v);
+        }
+        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) {
+    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) {
+    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;
+    }, {});
+    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) {
+    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;
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/esm/logging/config.js.map

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

package/dist/esm/logging/index.d.ts

@@ -0,0 +1,6 @@
+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";
+export { InMemorySink } from "./sinks.js";
+export type * from "./types.js";

package/dist/esm/logging/index.js

@@ -0,0 +1,5 @@
+export { createLogger, LogLevel, consoleSink } from "./logger.js";
+export { setGlobalLoggerConfig, getGlobalLoggerConfig, isLevelEnabled, isNamespaceEnabled, redactObject, } from "./config.js";
+// Testing utilities
+export { InMemorySink } from "./sinks.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/logging/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/logging/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAElE,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,cAAc,EACd,kBAAkB,EAClB,YAAY,GACb,MAAM,aAAa,CAAC;AAQrB,oBAAoB;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC","sourcesContent":["export { createLogger, LogLevel, consoleSink } from \"./logger.js\";\nexport type { DiagnosticsLogger } from \"./logger.js\";\nexport {\n  setGlobalLoggerConfig,\n  getGlobalLoggerConfig,\n  isLevelEnabled,\n  isNamespaceEnabled,\n  redactObject,\n} from \"./config.js\";\nexport type {\n  LogEntry,\n  DiagnosticsConfig,\n  RedactConfig,\n  LoggerContextBase,\n} from \"./config.js\";\n\n// Testing utilities\nexport { InMemorySink } from \"./sinks.js\";\n\nexport type * from \"./types.js\";\n"]}

package/dist/esm/logging/local.d.ts

@@ -0,0 +1,10 @@
+import type { EventsSchema, InnerLogger, LoggerContext } from "./types.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 declare function createLocalLogger<Schema extends EventsSchema = []>(context: LoggerContext): InnerLogger<Schema>;

package/dist/esm/logging/local.js

@@ -0,0 +1,35 @@
+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(context) {
+    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
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=local.js.map

package/dist/esm/logging/local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.js","sourceRoot":"","sources":["../../../src/logging/local.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAsB;IAEtB,MAAM,KAAK,GAAG,eAAe,EAAE,CAAC;IAEhC,mDAAmD;IACnD,MAAM,MAAM,GAAG,SAAS,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IAEnF,OAAO;QACL,SAAS,EAAE;YACT,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;YACxB,MAAM;SACP;QACD,UAAU,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;YACnC,IAAI,KAAK,EAAE,CAAC;gBACV,IAAI,CAAC;oBACH,OAAO,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,OAAO,YAAY,IAAI,EAAE,EAAE;wBACjD,GAAG,IAAI;wBACP,GAAG,OAAO;wBACV,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;qBACpC,CAAC,CAAC;gBACL,CAAC;gBAAC,MAAM,CAAC;oBACP,yCAAyC;gBAC3C,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC","sourcesContent":["import type { EventsSchema, InnerLogger, LoggerContext } from \"./types.js\";\nimport { isClientDevMode } from \"./utils.js\";\n\n/**\n * Creates a local-only logger that outputs events to the console in development mode.\n * This logger does not send data to external services and is safe for all environments.\n *\n * @template Schema - The events schema defining allowed events and their data structures\n * @param {LoggerContext} context - Context information to attach to all events\n * @returns {InnerLogger<Schema>} A logger instance that logs to console in dev mode\n */\nexport function createLocalLogger<Schema extends EventsSchema = []>(\n  context: LoggerContext,\n): InnerLogger<Schema> {\n  const isDev = isClientDevMode();\n\n  // Generate a simple anonymous ID for local logging\n  const anonId = `local-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;\n\n  return {\n    _internal: {\n      ready: Promise.resolve(),\n      anonId,\n    },\n    trackEvent: async ({ name, data }) => {\n      if (isDev) {\n        try {\n          console.log(`[${context.package}] Event: ${name}`, {\n            ...data,\n            ...context,\n            timestamp: new Date().toISOString(),\n          });\n        } catch {\n          // Silently ignore console logging errors\n        }\n      }\n    },\n  };\n}\n"]}

package/dist/esm/logging/logger.d.ts

@@ -0,0 +1,80 @@
+import { LogLevel, consoleSink, type LoggerContextBase } 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 declare function createLogger(params: CreateLoggerParams): DiagnosticsLogger;
+export { LogLevel, consoleSink };

package/dist/esm/logging/logger.js

@@ -0,0 +1,111 @@
+import { LogLevel, consoleSink, getGlobalLoggerConfig, isLevelEnabled, isNamespaceEnabled, redactObject, } from "./config.js";
+/**
+ * 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) {
+    const { namespace, baseContext, ...ctx } = params;
+    function emit(level, msgOrFn, data) {
+        if (!isLevelEnabled(level))
+            return;
+        if (!isNamespaceEnabled(namespace))
+            return;
+        let message;
+        let payload = data;
+        if (typeof msgOrFn === "function") {
+            const [m, d] = msgOrFn();
+            message = m;
+            payload = d ?? data;
+        }
+        else {
+            message = msgOrFn;
+        }
+        const entry = {
+            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 = {
+        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(name, func) {
+            return function profiledWrapper(...args) {
+                const start = Date.now();
+                const result = func.apply(this, args);
+                const finish = (ok) => {
+                    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;
+                if (maybePromise && typeof maybePromise.then === "function") {
+                    return result.then((r) => {
+                        finish(true);
+                        return r;
+                    }, (e) => {
+                        finish(false);
+                        throw e;
+                    });
+                }
+                finish(true);
+                return result;
+            };
+        },
+    };
+    return logger;
+}
+export { LogLevel, consoleSink };
+//# sourceMappingURL=logger.js.map

package/dist/esm/logging/logger.js.map

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

package/dist/esm/logging/noop.d.ts

@@ -0,0 +1,6 @@
+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 declare const noopLogger: InnerLogger<any>;

package/dist/esm/logging/noop.js

@@ -0,0 +1,12 @@
+/**
+ * No-operation logger that discards all events.
+ * Used as a fallback when logger initialization fails or in disabled states.
+ */
+export const noopLogger = {
+    trackEvent: async () => { },
+    _internal: {
+        ready: Promise.resolve(),
+        anonId: "",
+    },
+};
+//# sourceMappingURL=noop.js.map

package/dist/esm/logging/noop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.js","sourceRoot":"","sources":["../../../src/logging/noop.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAqB;IAC1C,UAAU,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;IAC1B,SAAS,EAAE;QACT,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE;QACxB,MAAM,EAAE,EAAE;KACX;CACF,CAAC","sourcesContent":["import type { InnerLogger } from \"./types.js\";\n\n/**\n * No-operation logger that discards all events.\n * Used as a fallback when logger initialization fails or in disabled states.\n */\nexport const noopLogger: InnerLogger<any> = {\n  trackEvent: async () => {},\n  _internal: {\n    ready: Promise.resolve(),\n    anonId: \"\",\n  },\n};\n"]}