@mikeatlast/ponder 0.16.1-fork.1

package/src/utils/generators.ts

@@ -0,0 +1,157 @@
+import { promiseWithResolvers } from "@/utils/promiseWithResolvers.js";
+import { startClock } from "./timer.js";
+
+/**
+ * Merges multiple async generators into a single async generator.
+ *
+ * @param generators - The generators to merge.
+ * @returns A single async generator that yields results from all input generators.
+ */
+export async function* mergeAsyncGenerators<T>(
+  generators: AsyncGenerator<T>[],
+): AsyncGenerator<T> {
+  const promises = generators.map((gen) => gen.next());
+
+  while (promises.length > 0) {
+    const wrappedPromises = promises.map((promise, index) =>
+      promise.then((result) => ({ index, result })),
+    );
+
+    const { result, index } = await Promise.race(wrappedPromises);
+
+    if (result.done) {
+      generators.splice(index, 1);
+      promises.splice(index, 1);
+    } else {
+      const generator = generators[index]!;
+      const promise = generator.next();
+
+      promises.splice(index, 1);
+      generators.splice(index, 1);
+
+      generators.push(generator);
+      promises.push(promise);
+
+      yield result.value;
+    }
+  }
+}
+
+/**
+ * Buffers the results of an async generator.
+ *
+ * @param generator - The generator to buffer.
+ * @param size - The size of the buffer.
+ * @returns An async generator that yields results from the input generator.
+ */
+export async function* bufferAsyncGenerator<T>(
+  generator: AsyncGenerator<T>,
+  size: number,
+  bufferCallback?: (bufferSize: number) => void,
+): AsyncGenerator<T> {
+  const buffer: T[] = [];
+  let done = false;
+
+  let pwr1 = promiseWithResolvers<void>();
+  let pwr2 = promiseWithResolvers<void>();
+
+  (async () => {
+    for await (const result of generator) {
+      buffer.push(result);
+
+      bufferCallback?.(buffer.length);
+
+      pwr1.resolve();
+
+      if (buffer.length >= size) await pwr2.promise;
+      pwr2 = promiseWithResolvers<void>();
+    }
+    done = true;
+    pwr1.resolve();
+  })();
+
+  while (done === false || buffer.length > 0) {
+    if (buffer.length > 0) {
+      pwr2.resolve();
+
+      yield buffer.shift()!;
+    } else {
+      await pwr1.promise;
+      pwr1 = promiseWithResolvers<void>();
+    }
+  }
+}
+
+/**
+ * Drains an async generator into an array.
+ *
+ * @param asyncGenerator - The async generator to drain.
+ * @returns An array of results from the input generator.
+ */
+export async function drainAsyncGenerator<T>(
+  asyncGenerator: AsyncGenerator<T>,
+): Promise<T[]> {
+  const result: T[] = [];
+
+  for await (const events of asyncGenerator) {
+    result.push(events);
+  }
+
+  return result;
+}
+
+/**
+ * Records the total time taken to yield results from an async generator.
+ *
+ * @param asyncGenerator - The async generator to record.
+ * @param callback - A callback function that receives duration metrics.
+ * @returns An async generator that yields results from the input generator.
+ */
+export async function* recordAsyncGenerator<T>(
+  asyncGenerator: AsyncGenerator<T>,
+  callback: (params: { await: number; yield: number; total: number }) => void,
+): AsyncGenerator<T> {
+  let endClockTotal = startClock();
+  for await (const result of asyncGenerator) {
+    const endClockInner = startClock();
+    yield result;
+    callback({
+      await: endClockTotal() - endClockInner(),
+      yield: endClockInner(),
+      total: endClockTotal(),
+    });
+    endClockTotal = startClock();
+  }
+}
+
+/**
+ * Creates an async generator that yields values from a callback.
+ */
+export function createCallbackGenerator<T>(
+  bufferCallback?: (bufferSize: number) => void,
+): {
+  callback: (value: T) => void;
+  generator: AsyncGenerator<T, void, unknown>;
+} {
+  const buffer: T[] = [];
+  let pwr = promiseWithResolvers<void>();
+
+  const callback = (value: T) => {
+    buffer.push(value);
+    bufferCallback?.(buffer.length);
+    pwr.resolve();
+  };
+
+  async function* generator() {
+    while (true) {
+      if (buffer.length > 0) {
+        yield buffer.shift()!;
+      } else {
+        await pwr.promise;
+        pwr = promiseWithResolvers<void>();
+      }
+    }
+  }
+
+  return { callback, generator: generator() };
+}

package/src/utils/hash.ts

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+
+// Adapted from https://stackoverflow.com/questions/77336994/stronger-type-for-value-in-json-stringifyvalue-any
+type JSONSerializable =
+  | string
+  | number
+  | boolean
+  | null
+  | JSONObject
+  | JSONArray;
+type JSONObject = { [key: string]: JSONSerializable };
+type JSONArray = Array<JSONSerializable>;
+
+/**
+ * Generates a 10-character hexadecimal hash of a JSON-serializable value.
+ */
+export function hash(value: JSONSerializable): string {
+  return createHash("sha256")
+    .update(JSON.stringify(value))
+    .digest("hex")
+    .slice(0, 10);
+}

package/src/utils/interval.ts

@@ -0,0 +1,212 @@
+import { range } from "./range.js";
+
+export type Interval = [number, number];
+
+/**
+ * Return the total sum of a list of numeric intervals.
+ *
+ * @param intervals List of numeric intervals to find the sum of.
+ * @returns Sum of the intervals.
+ */
+export function intervalSum(intervals: Interval[]) {
+  let totalSum = 0;
+
+  for (const [start, end] of intervals) {
+    totalSum += end - start + 1;
+  }
+
+  return totalSum;
+}
+
+/**
+ * Return the union of a list of numeric intervals.
+ *
+ * @param intervals List of numeric intervals to find the union of.
+ * @returns Union of the intervals, represented as a list of intervals.
+ */
+export function intervalUnion(intervals_: Interval[]) {
+  if (intervals_.length === 0) return [];
+
+  // Create copies to avoid mutating the originals.
+  const intervals = intervals_.map((interval) => [...interval] as Interval);
+  // Sort intervals based on the left end.
+  intervals.sort((a, b) => a[0] - b[0]);
+
+  const result: Interval[] = [];
+  let currentInterval = intervals[0]!;
+
+  for (let i = 1; i < intervals.length; i++) {
+    const nextInterval = intervals[i]!;
+
+    if (currentInterval[1] >= nextInterval[0] - 1) {
+      // Merge overlapping intervals
+      currentInterval[1] = Math.max(currentInterval[1], nextInterval[1]);
+    } else {
+      // No overlap, add current interval to result
+      result.push(currentInterval);
+      currentInterval = nextInterval;
+    }
+  }
+
+  result.push(currentInterval); // Add the last interval
+  return result;
+}
+
+/**
+ * Return the intersection of two lists of numeric intervals.
+ *
+ * @param list1 First list of numeric intervals.
+ * @param list2 Second list of numeric intervals.
+ * @returns Intersection of the intervals, represented as a list of intervals.
+ */
+export function intervalIntersection(
+  list1: Interval[],
+  list2: Interval[],
+): Interval[] {
+  const result: Interval[] = [];
+  let i = 0;
+  let j = 0;
+
+  while (i < list1.length && j < list2.length) {
+    const [start1, end1] = list1[i]!;
+    const [start2, end2] = list2[j]!;
+
+    const intersectionStart = Math.max(start1, start2);
+    const intersectionEnd = Math.min(end1, end2);
+
+    if (intersectionStart <= intersectionEnd) {
+      result.push([intersectionStart, intersectionEnd]);
+    }
+
+    if (end1 < end2) {
+      i++;
+    } else {
+      j++;
+    }
+  }
+
+  // Merge potentially overlapping intervals before returning.
+  return intervalUnion(result);
+}
+
+/**
+ * Return the intersection of many lists of numeric intervals.
+ *
+ * @param list1 First list of numeric intervals.
+ * @param list2 Second list of numeric intervals.
+ * @returns Intersection of the intervals, represented as a list of intervals.
+ */
+export function intervalIntersectionMany(lists: Interval[][]): Interval[] {
+  if (lists.length === 0) return [];
+  if (lists.length === 1) return lists[0]!;
+
+  let result: Interval[] = lists[0]!;
+
+  for (let i = 1; i < lists.length; i++) {
+    result = intervalIntersection(result, lists[i]!);
+  }
+
+  return intervalUnion(result);
+}
+
+/**
+ * Return the difference between two lists of numeric intervals (initial - remove).
+ *
+ * @param initial Starting/base list of numeric intervals.
+ * @param remove List of numeric intervals to remove.
+ * @returns Difference of the intervals, represented as a list of intervals.
+ */
+export function intervalDifference(
+  initial: Interval[],
+  remove: Interval[],
+): Interval[] {
+  // Create copies to avoid mutating the originals.
+  const initial_ = initial.map((interval) => [...interval] as Interval);
+  const remove_ = remove.map((interval) => [...interval] as Interval);
+
+  const result: Interval[] = [];
+
+  let i = 0;
+  let j = 0;
+
+  while (i < initial.length && j < remove.length) {
+    const interval1 = initial_[i]!;
+    const interval2 = remove_[j]!;
+
+    if (interval1[1] < interval2[0]) {
+      // No overlap, add interval1 to the result
+      result.push(interval1);
+      i++;
+    } else if (interval2[1] < interval1[0]) {
+      // No overlap, move to the next interval in remove
+      j++;
+    } else {
+      // There is an overlap
+      if (interval1[0] < interval2[0]) {
+        // Add the left part of interval1
+        result.push([interval1[0], interval2[0] - 1]);
+      }
+      if (interval1[1] > interval2[1]) {
+        // Update interval1's start to exclude the overlap
+        interval1[0] = interval2[1] + 1;
+        j++;
+      } else {
+        // No more overlap, move to the next interval in initial
+        i++;
+      }
+    }
+  }
+
+  // Add any remaining intervals from initial
+  while (i < initial_.length) {
+    result.push(initial_[i]!);
+    i++;
+  }
+
+  return result;
+}
+
+/**
+ * Return an interval that encompasses all the intervals in the list.
+ *
+ * @param intervals List of numeric intervals to find the bounds of.
+ * @returns Bounds of the intervals.
+ */
+export function intervalBounds(intervals: Interval[]): Interval {
+  const start = Math.min(...intervals.map((interval) => interval[0]));
+  const end = Math.max(...intervals.map((interval) => interval[1]));
+
+  return [start, end];
+}
+
+export function sortIntervals(intervals: Interval[]) {
+  return intervals.sort((a, b) => (a[0] < b[0] ? -1 : 1));
+}
+
+export function getChunks({
+  interval,
+  maxChunkSize,
+}: {
+  interval: Interval;
+  maxChunkSize: number;
+}) {
+  const _chunks: Interval[] = [];
+
+  const [startBlock, endBlock] = interval;
+
+  let fromBlock = startBlock;
+  let toBlock = Math.min(fromBlock + maxChunkSize - 1, endBlock);
+
+  while (fromBlock <= endBlock) {
+    _chunks.push([fromBlock, toBlock]);
+
+    fromBlock = toBlock + 1;
+    toBlock = Math.min(fromBlock + maxChunkSize - 1, endBlock);
+  }
+
+  return _chunks;
+}
+
+export function intervalRange(interval: Interval) {
+  return range(interval[0], interval[1] + 1);
+}

package/src/utils/lowercase.ts

@@ -0,0 +1,6 @@
+/**
+ * Transforms the input string to lower case.
+ */
+export function toLowerCase<T extends string>(value: T) {
+  return value.toLowerCase() as Lowercase<T>;
+}

package/src/utils/mutex.ts

@@ -0,0 +1,33 @@
+import {
+  type PromiseWithResolvers,
+  promiseWithResolvers,
+} from "./promiseWithResolvers.js";
+
+export const createLock = (): {
+  lock: () => Promise<void>;
+  unlock: () => void;
+} => {
+  const queue: PromiseWithResolvers<void>[] = [];
+  let locked = false;
+
+  return {
+    lock: async () => {
+      if (locked === false) {
+        locked = true;
+        return;
+      }
+
+      const pwr = promiseWithResolvers<void>();
+      queue.push(pwr);
+      return pwr.promise;
+    },
+    unlock: () => {
+      if (queue.length > 0) {
+        const pwr = queue.shift()!;
+        pwr.resolve();
+      } else {
+        locked = false;
+      }
+    },
+  };
+};

package/src/utils/never.ts

@@ -0,0 +1,3 @@
+export const never = (_x: never) => {
+  throw "unreachable";
+};

package/src/utils/offset.ts

@@ -0,0 +1,133 @@
+import type { AbiParameter } from "abitype";
+import { InvalidAbiDecodingTypeError } from "viem";
+
+// Adapted from viem.
+// https://github.com/wagmi-dev/viem/blob/5c95fafceffe7f399b5b5ee32119e2d78a0c8acd/src/utils/abi/decodeEventLog.ts
+
+export function getBytesConsumedByParam(param: AbiParameter): number {
+  const arrayComponents = getArrayComponents(param.type);
+  if (arrayComponents) {
+    const [length, innerType] = arrayComponents;
+
+    // If the array is dynamic or has dynamic children, it uses the
+    // dynamic encoding scheme (32 byte header).
+    if (!length || hasDynamicChild(param)) {
+      return 32;
+    }
+
+    // If the length of the array is known in advance,
+    // and the length of each element in the array is known,
+    // the array data is encoded contiguously after the array.
+    const bytesConsumedByInnerType = getBytesConsumedByParam({
+      ...param,
+      type: innerType,
+    });
+    return length * bytesConsumedByInnerType;
+  }
+
+  if (param.type === "tuple") {
+    // If the tuple has dynamic children, it uses the dynamic encoding
+    // scheme (32 byte header).
+    if (hasDynamicChild(param)) {
+      return 32;
+    }
+
+    // Otherwise the tuple has static children, so we can just decode
+    // each component in sequence.
+    let consumed = 0;
+    for (const component of (param as any).components ?? []) {
+      consumed += getBytesConsumedByParam(component);
+    }
+    return consumed;
+  }
+
+  // Otherwise, it's a dynamic string or bytes (32 bytes),
+  // or a static number, address, or bool (32 bytes).
+  if (
+    param.type === "string" ||
+    param.type.startsWith("bytes") ||
+    param.type.startsWith("uint") ||
+    param.type.startsWith("int") ||
+    param.type === "address" ||
+    param.type === "bool"
+  ) {
+    return 32;
+  }
+
+  throw new InvalidAbiDecodingTypeError(param.type, {
+    docsPath: "/docs/contract/decodeAbiParameters",
+  });
+}
+
+export type TupleAbiParameter = AbiParameter & {
+  type: "tuple";
+  components: readonly AbiParameter[];
+};
+
+export function getNestedParamOffset(
+  param: TupleAbiParameter,
+  names: string[],
+): number {
+  let consumed = 0;
+  let isFound = false;
+  for (const component of param.components) {
+    if (component.name === names[0]) {
+      // the end of the branch
+      if (names.length === 1) {
+        isFound = true;
+        break;
+      }
+
+      // additional nesting
+      if (component.type === "tuple") {
+        const nestedConsumed = getNestedParamOffset(
+          component as TupleAbiParameter,
+          names.slice(1),
+        );
+        return consumed + nestedConsumed;
+      } else {
+        throw new Error(
+          `Factory event parameter '${param.name}.${names.join(".")}' is not valid for ${param.name} struct signature.`,
+        );
+      }
+    } else {
+      consumed += getBytesConsumedByParam(component);
+    }
+  }
+
+  if (!isFound) {
+    throw new Error(
+      `Factory event parameter '${param.name}.${names.join(".")}' not found in ${param.name} struct signature.`,
+    );
+  }
+
+  return consumed;
+}
+
+function hasDynamicChild(param: AbiParameter) {
+  const { type } = param;
+  if (type === "string") return true;
+  if (type === "bytes") return true;
+  if (type.endsWith("[]")) return true;
+
+  if (type === "tuple") return (param as any).components?.some(hasDynamicChild);
+
+  const arrayComponents = getArrayComponents(param.type);
+  if (
+    arrayComponents &&
+    hasDynamicChild({ ...param, type: arrayComponents[1] } as AbiParameter)
+  )
+    return true;
+
+  return false;
+}
+
+function getArrayComponents(
+  type: string,
+): [length: number | null, innerType: string] | undefined {
+  const matches = type.match(/^(.*)\[(\d+)?\]$/);
+  return matches
+    ? // Return `null` if the array is dynamic.
+      [matches[2] ? Number(matches[2]) : null, matches[1]!]
+    : undefined;
+}

package/src/utils/order.ts

@@ -0,0 +1,16 @@
+export const orderObject = (obj: any): any => {
+  if (Array.isArray(obj)) return obj.map((x) => orderObject(x));
+  if (typeof obj !== "object") return obj;
+
+  const newObj = {} as any;
+  for (const key of Object.keys(obj).sort()) {
+    const val = obj[key];
+    if (typeof val === "object") {
+      newObj[key] = orderObject(obj[key]);
+    } else {
+      newObj[key] = obj[key];
+    }
+  }
+
+  return newObj;
+};

package/src/utils/partition.ts

@@ -0,0 +1,53 @@
+/**
+ * Divides an array into two arrays, where the first array
+ * contains all elements that satisfy the predicate, and the
+ * second array contains all elements that do not satisfy the
+ * predicate.
+ *
+ * Note: It is assumed that the array monotonically goes from true to false.
+ *
+ * @param array - The array to partition.
+ * @param predicate - The predicate to partition the array by.
+ *
+ * @returns A tuple containing the left and right arrays.
+ *
+ * @example
+ * ```ts
+ * const [left, right] = partition([1, 2, 3, 4, 5], (n) => n <= 2);
+ * // left = [1, 2]
+ * // right = [3, 4, 5]
+ * ```
+ */
+export const partition = <T>(
+  array: T[],
+  predicate: (item: T) => boolean,
+): [T[], T[]] => {
+  if (array.length === 0) {
+    return [[], []];
+  }
+
+  if (predicate(array[0]!) === false) {
+    return [[], array];
+  }
+
+  if (predicate(array[array.length - 1]!)) {
+    return [array, []];
+  }
+
+  let low = 0;
+  let high = array.length;
+
+  while (low < high) {
+    const mid = Math.floor((low + high) / 2);
+    if (predicate(array[mid]!)) {
+      low = mid + 1;
+    } else {
+      high = mid;
+    }
+  }
+
+  const left = array.slice(0, low);
+  const right = array.slice(low);
+
+  return [left, right];
+};