@alchemy/common 0.0.0-alpha.0

package/src/logging/sinks.ts

@@ -0,0 +1,115 @@
+import type { LogEntry } from "./config.js";
+
+/**
+ * In-memory sink for testing purposes.
+ * Captures all log entries in an array that can be inspected in tests.
+ *
+ * **Note:** This is primarily intended for testing SDK integrations.
+ * Most applications should use the default console sink.
+ *
+ * @example
+ * ```ts
+ * import { InMemorySink, setGlobalLoggerConfig, createLogger } from "@alchemy/common";
+ *
+ * // In tests
+ * const sink = new InMemorySink();
+ *
+ * setGlobalLoggerConfig({
+ *   sinks: [sink.sink]
+ * });
+ *
+ * const logger = createLogger({
+ *   package: "@alchemy/aa-infra",
+ *   version: "1.0.0",
+ *   namespace: "aa-infra"
+ * });
+ *
+ * logger.info("test message");
+ *
+ * // Inspect captured logs
+ * expect(sink.count).toBe(1);
+ * expect(sink.latest()?.message).toBe("test message");
+ * ```
+ */
+export class InMemorySink {
+  /**
+   * Array of captured log entries
+   */
+  public entries: LogEntry[] = [];
+
+  /**
+   * Creates a new InMemorySink instance.
+   * Binds the sink method to the instance for use as a callback.
+   */
+  constructor() {
+    this.sink = this.sink.bind(this);
+  }
+
+  /**
+   * The sink function to pass to setGlobalLoggerConfig.
+   * Captures log entries into the internal array.
+   *
+   * @param {LogEntry} entry - The log entry to capture
+   * @returns {void}
+   */
+  sink(entry: LogEntry): void {
+    this.entries.push(entry);
+  }
+
+  /**
+   * Clear all captured entries
+   *
+   * @returns {void}
+   */
+  clear(): void {
+    this.entries = [];
+  }
+
+  /**
+   * Get entries filtered by log level
+   *
+   * @param {number} level - The log level to filter by (LogLevel.ERROR, LogLevel.INFO, etc.)
+   * @returns {LogEntry[]} Array of log entries matching the specified level
+   */
+  getByLevel(level: number): LogEntry[] {
+    return this.entries.filter((e) => e.level === level);
+  }
+
+  /**
+   * Get entries filtered by namespace
+   *
+   * @param {string} namespace - The namespace to filter by (e.g., "aa-infra", "wallet-apis")
+   * @returns {LogEntry[]} Array of log entries matching the specified namespace
+   */
+  getByNamespace(namespace: string): LogEntry[] {
+    return this.entries.filter((e) => e.namespace === namespace);
+  }
+
+  /**
+   * Get entries filtered by message substring
+   *
+   * @param {string} substring - The substring to search for in log messages
+   * @returns {LogEntry[]} Array of log entries containing the substring in their message
+   */
+  getByMessage(substring: string): LogEntry[] {
+    return this.entries.filter((e) => e.message.includes(substring));
+  }
+
+  /**
+   * Get the most recent log entry
+   *
+   * @returns {LogEntry | undefined} The latest log entry, or undefined if no entries have been captured
+   */
+  latest(): LogEntry | undefined {
+    return this.entries[this.entries.length - 1];
+  }
+
+  /**
+   * Get the number of captured entries
+   *
+   * @returns {number} The total count of captured log entries
+   */
+  get count(): number {
+    return this.entries.length;
+  }
+}

package/src/logging/types.ts

@@ -0,0 +1,111 @@
+/**
+ * Schema definition for event logging.
+ * An array of event definitions with their names and optional data structures.
+ */
+export type EventsSchema = readonly {
+  EventName: string;
+  EventData?: Record<string, any>;
+}[];
+
+type Prettify<T> = {
+  [K in keyof T]: T[K];
+} & {};
+
+/**
+ * Type-safe parameters for tracking events based on the provided schema.
+ * Ensures event names and data structures match the schema definition.
+ * When no schema is provided, allows any event with optional data.
+ *
+ * @template Schema - The events schema to validate against
+ */
+export type TrackEventParameters<Schema extends EventsSchema> =
+  Schema extends readonly []
+    ? { name: string; data?: any }
+    : {
+        [K in keyof Schema]: Prettify<
+          { name: Schema[K]["EventName"] } & ([undefined] extends [
+            Schema[K]["EventData"],
+          ]
+            ? { data?: undefined }
+            : { data: Schema[K]["EventData"] })
+        >;
+      }[number];
+
+/**
+ * Main event logger interface for type-safe event tracking and performance profiling.
+ *
+ * @template Schema - The events schema defining allowed events and their data structures
+ */
+export interface EventLogger<Schema extends EventsSchema = []> {
+  /**
+   * Tracks an event with type-safe validation against the schema.
+   *
+   * @param params - Event parameters including name and optional data
+   * @returns Promise that resolves when the event is tracked
+   */
+  trackEvent(
+    params: TrackEventParameters<
+      Schema extends readonly [] ? [] : [...Schema, PerformanceEvent]
+    >,
+  ): Promise<void>;
+
+  /**
+   * Wraps a function to automatically track its execution time as a performance event.
+   *
+   * @template TArgs - Function argument types
+   * @template TRet - Function return type
+   * @param name - Name identifier for the profiled function
+   * @param func - Function to wrap with performance tracking
+   * @returns Wrapped function that tracks execution time
+   */
+  profiled<TArgs extends any[], TRet>(
+    name: string,
+    func: (...args: TArgs) => TRet,
+  ): (...args: TArgs) => TRet;
+
+  /** Internal properties for logger state and configuration */
+  _internal: {
+    /** Promise that resolves when logger is ready for use */
+    ready: Promise<unknown>;
+    /** Anonymous identifier for this logger instance */
+    anonId: string;
+  };
+}
+
+/**
+ * Internal logger interface without the profiled method.
+ * Used internally by different logger implementations.
+ *
+ * @template Schema - The events schema defining allowed events and their data structures
+ */
+export type InnerLogger<Schema extends EventsSchema> = Omit<
+  EventLogger<Schema>,
+  "profiled"
+>;
+
+/**
+ * Context information attached to all logged events.
+ * Provides metadata about the package and version generating events.
+ */
+export type LoggerContext = {
+  /** Name of the package generating events */
+  package: string;
+  /** Version of the package generating events */
+  version: string;
+  /** Additional context properties as key-value pairs */
+  [key: string]: string;
+};
+
+/**
+ * Built-in performance event schema for tracking function execution times.
+ * Automatically included in all event schemas for profiled function tracking.
+ */
+export type PerformanceEvent = {
+  EventName: "performance";
+  EventData: {
+    /** Execution time in milliseconds */
+    executionTimeMs: number;
+    /** Name of the function being profiled */
+    functionName: string;
+  };
+};

package/src/logging/utils.ts

@@ -0,0 +1,31 @@
+// just in case we're in a setting that doesn't have these types defined
+declare const __DEV__: boolean | undefined;
+declare const window: Window | undefined;
+
+/**
+ * Detects if the current environment is in development mode.
+ * Checks multiple common development environment indicators.
+ *
+ * @returns {boolean} True if running in development mode
+ */
+export function isClientDevMode() {
+  if (typeof __DEV__ !== "undefined" && __DEV__) {
+    return true;
+  }
+
+  if (
+    typeof process !== "undefined" &&
+    process.env.NODE_ENV === "development"
+  ) {
+    return true;
+  }
+
+  if (
+    typeof window !== "undefined" &&
+    window.location?.hostname?.includes("localhost")
+  ) {
+    return true;
+  }
+
+  return false;
+}

package/src/rest/restClient.ts

@@ -0,0 +1,64 @@
+import { FetchError } from "../errors/FetchError.js";
+import { ServerError } from "../errors/ServerError.js";
+import { withAlchemyHeaders } from "../utils/headers.js";
+import type { RestRequestFn, RestRequestSchema } from "./types.js";
+
+const ALCHEMY_API_URL = "https://api.g.alchemy.com";
+
+/**
+ * Parameters for creating an AlchemyRestClient instance.
+ */
+export type AlchemyRestClientParams = {
+  /** API key for Alchemy authentication */
+  apiKey?: string;
+  /** JWT token for Alchemy authentication */
+  jwt?: string;
+  /** Custom URL (optional - defaults to Alchemy's chain-agnostic URL, but can be used to override it) */
+  url?: string;
+  /** Custom headers to be sent with requests */
+  headers?: HeadersInit;
+};
+
+/**
+ * A client for making requests to Alchemy's non-JSON-RPC endpoints.
+ */
+export class AlchemyRestClient<Schema extends RestRequestSchema> {
+  private readonly url: string;
+  private readonly headers: Headers;
+
+  /**
+   * Creates a new instance of AlchemyRestClient.
+   *
+   * @param {AlchemyRestClientParams} params - The parameters for configuring the client, including API key, JWT, custom URL, and headers.
+   */
+  constructor({ apiKey, jwt, url, headers }: AlchemyRestClientParams) {
+    this.url = url ?? ALCHEMY_API_URL;
+    this.headers = new Headers(withAlchemyHeaders({ headers, apiKey, jwt }));
+  }
+
+  /**
+   * Makes an HTTP request to an Alchemy non-JSON-RPC endpoint.
+   *
+   * @param {RestRequestFn<Schema>} params - The parameters for the request
+   * @returns {Promise<unknown>} The response from the request
+   */
+  public request: RestRequestFn<Schema> = async (params) => {
+    const response = await fetch(`${this.url}/${params.route}`, {
+      method: params.method,
+      body: params.body ? JSON.stringify(params.body) : undefined,
+      headers: this.headers,
+    }).catch((error) => {
+      throw new FetchError(params.route, params.method, error);
+    });
+
+    if (!response.ok) {
+      throw new ServerError(
+        await response.text(),
+        response.status,
+        new Error(response.statusText),
+      );
+    }
+
+    return response.json();
+  };
+}

package/src/rest/types.ts

@@ -0,0 +1,42 @@
+import type { Prettify } from "viem";
+
+export type RestRequestSchema = readonly {
+  Route: string;
+  Method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "OPTIONS" | "HEAD";
+  Body?: unknown | undefined;
+  Response: unknown;
+}[];
+
+export type RestRequestParams<
+  Schema extends RestRequestSchema | undefined = undefined,
+> = Schema extends RestRequestSchema
+  ? {
+      [K in keyof Schema]: Prettify<
+        {
+          route: Schema[K] extends Schema[number] ? Schema[K]["Route"] : never;
+          method: Schema[K] extends Schema[number]
+            ? Schema[K]["Method"]
+            : never;
+        } & (Schema[K] extends Schema[number]
+          ? Schema[K]["Body"] extends undefined
+            ? { body?: undefined }
+            : { body: Schema[K]["Body"] }
+          : never)
+      >;
+    }[number]
+  : {
+      route: string;
+      method: RestRequestSchema[number]["Method"];
+      body?: unknown | undefined;
+    };
+
+export type RestRequestFn<
+  Schema extends RestRequestSchema | undefined = undefined,
+> = <
+  _parameters extends RestRequestParams<Schema> = RestRequestParams<Schema>,
+  _returnType = Schema extends RestRequestSchema
+    ? Extract<Schema[number], { Route: _parameters["route"] }>["Response"]
+    : unknown,
+>(
+  params: _parameters,
+) => Promise<_returnType>;

package/src/tracing/traceHeader.ts

@@ -0,0 +1,154 @@
+function generateRandomHexString(numBytes: number) {
+  const hexPairs = new Array(numBytes).fill(0).map(() =>
+    Math.floor(Math.random() * 16)
+      .toString(16)
+      .padStart(2, "0"),
+  );
+  return hexPairs.join("");
+}
+
+/**
+ * These are the headers that are used in the trace headers, could be found in the spec
+ *
+ * @see https://www.w3.org/TR/trace-context/#design-overview
+ */
+
+export const TRACE_HEADER_NAME = "traceparent";
+/**
+ * These are the headers that are used in the trace headers, could be found in the spec
+ *
+ * @see https://www.w3.org/TR/trace-context/#design-overview
+ */
+export const TRACE_HEADER_STATE = "tracestate";
+
+const clientTraceId = generateRandomHexString(16);
+/**
+ * Some tools that are useful when dealing with the values
+ * of the trace header. Follows the W3C trace context standard.
+ *
+ * @see https://www.w3.org/TR/trace-context/
+ */
+export class TraceHeader {
+  readonly traceId: string;
+  readonly parentId: string;
+  readonly traceFlags: string;
+  readonly traceState: Record<string, string>;
+
+  /**
+   * Initializes a new instance with the provided trace identifiers and state information.
+   *
+   * @param {string} traceId The unique identifier for the trace
+   * @param {string} parentId The identifier of the parent trace
+   * @param {string} traceFlags Flags containing trace-related options
+   * @param {TraceHeader["traceState"]} traceState The trace state information for additional trace context
+   */
+  constructor(
+    traceId: string,
+    parentId: string,
+    traceFlags: string,
+    traceState: TraceHeader["traceState"],
+  ) {
+    this.traceId = traceId;
+    this.parentId = parentId;
+    this.traceFlags = traceFlags;
+    this.traceState = traceState;
+  }
+
+  /**
+   * Creating a default trace id that is a random setup for both trace id and parent id
+   *
+   * @example ```ts
+   * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+   * ```
+   *
+   * @returns {TraceHeader} A default trace header
+   */
+  static default() {
+    return new TraceHeader(
+      clientTraceId,
+      generateRandomHexString(8),
+      "00", //Means no flag have been set, and no sampled state https://www.w3.org/TR/trace-context/#trace-flags
+      {},
+    );
+  }
+  /**
+   * Should be able to consume a trace header from the headers of an http request
+   *
+   * @example ```ts
+   * const traceHeader = TraceHeader.fromTraceHeader(headers);
+   * ```
+   *
+   * @param {Record<string,string>} headers The headers from the http request
+   * @returns {TraceHeader | undefined} The trace header object, or nothing if not found
+   */
+  static fromTraceHeader(
+    headers: Record<string, string>,
+  ): TraceHeader | undefined {
+    if (!headers[TRACE_HEADER_NAME]) {
+      return undefined;
+    }
+    const [version, traceId, parentId, traceFlags] =
+      headers[TRACE_HEADER_NAME]?.split("-");
+
+    const traceState =
+      headers[TRACE_HEADER_STATE]?.split(",").reduce(
+        (acc, curr) => {
+          const [key, value] = curr.split("=");
+          acc[key] = value;
+          return acc;
+        },
+        {} as Record<string, string>,
+      ) || {};
+    if (version !== "00") {
+      console.debug(
+        new Error(
+          `Invalid version for traceheader: ${headers[TRACE_HEADER_NAME]}`,
+        ),
+      );
+      return undefined;
+    }
+    return new TraceHeader(traceId, parentId, traceFlags, traceState);
+  }
+
+  /**
+   * Should be able to convert the trace header to the format that is used in the headers of an http request
+   *
+   * @example ```ts
+   * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+   * const headers = traceHeader.toTraceHeader();
+   * ```
+   *
+   * @returns {{traceparent: string, tracestate: string}} The trace header in the format of a record, used in our http client
+   */
+  toTraceHeader() {
+    return {
+      [TRACE_HEADER_NAME]: `00-${this.traceId}-${this.parentId}-${this.traceFlags}`,
+      [TRACE_HEADER_STATE]: Object.entries(this.traceState)
+        .map(([key, value]) => `${key}=${value}`)
+        .join(","),
+    } as const;
+  }
+
+  /**
+   * Should be able to create a new trace header with a new event in the trace state,
+   *  as the key of the eventName as breadcrumbs appending onto previous breadcrumbs with the - infix if exists. And the
+   * trace parent gets updated as according to the docs
+   *
+   * @example ```ts
+   * const traceHeader = TraceHeader.fromTraceHeader(headers) || TraceHeader.default();
+   * const newTraceHeader = traceHeader.withEvent("newEvent");
+   * ```
+   *
+   * @param {string} eventName The key of the new event
+   * @returns {TraceHeader} The new trace header
+   */
+  withEvent(eventName: string): TraceHeader {
+    const breadcrumbs = this.traceState.breadcrumbs
+      ? `${this.traceState.breadcrumbs}-${eventName}`
+      : eventName;
+    return new TraceHeader(this.traceId, this.parentId, this.traceFlags, {
+      ...this.traceState,
+      breadcrumbs,
+    });
+  }
+}

package/src/tracing/updateHeaders.ts

@@ -0,0 +1,66 @@
+import {
+  TRACE_HEADER_NAME,
+  TRACE_HEADER_STATE,
+  TraceHeader,
+} from "./traceHeader.js";
+
+/**
+ * The header that is used to track the trace id.
+ * We use a client specific one to not mess with the span tracing of the servers.
+ *
+ * @see headersUpdate
+ */
+const TRACKER_HEADER = "X-Alchemy-Client-Trace-Id";
+
+/**
+ * The header that is used to track the breadcrumb.
+ *
+ * @see headersUpdate
+ */
+const TRACKER_BREADCRUMB = "X-Alchemy-Client-Breadcrumb";
+
+/**
+ * Remove the tracking headers. This is used in our split transport to ensure that we remove the headers that
+ * are not used by the other systems.
+ *
+ * @param {unknown} x The headers to remove the tracking headers from
+ */
+export function mutateRemoveTrackingHeaders(x?: unknown) {
+  if (!x) return;
+  if (Array.isArray(x)) return;
+  if (typeof x !== "object") return;
+  TRACKER_HEADER in x && delete x[TRACKER_HEADER];
+  TRACKER_BREADCRUMB in x && delete x[TRACKER_BREADCRUMB];
+  TRACE_HEADER_NAME in x && delete x[TRACE_HEADER_NAME];
+  TRACE_HEADER_STATE in x && delete x[TRACE_HEADER_STATE];
+}
+
+function addCrumb(previous: string | undefined, crumb: string): string {
+  if (!previous) return crumb;
+  return `${previous} > ${crumb}`;
+}
+/**
+ * Update the headers with the trace header and breadcrumb.
+ *
+ * These trace headers are used in the imply ingestion pipeline to trace the request.
+ * And the breadcrumb is used to get finer grain details in the trace.
+ *
+ * Then there are the trace headers that are part of the W3C trace context standard.
+ *
+ * @param {string} crumb The crumb to add to the breadcrumb
+ * @returns {Function} A function that updates the headers
+ */
+export function headersUpdate(crumb: string) {
+  const headerUpdate_ = (x: Record<string, string>) => {
+    const traceHeader = (
+      TraceHeader.fromTraceHeader(x) || TraceHeader.default()
+    ).withEvent(crumb);
+    return {
+      [TRACKER_HEADER]: traceHeader.parentId,
+      ...x,
+      [TRACKER_BREADCRUMB]: addCrumb(x[TRACKER_BREADCRUMB], crumb),
+      ...traceHeader.toTraceHeader(),
+    };
+  };
+  return headerUpdate_;
+}