@effectstream/utils 0.100.0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@effectstream/utils",
+  "version": "0.100.0",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/mod.ts",
+    "./node-env": "./src/config.ts",
+    "./runtime": "./src/runtime.ts",
+    "./runtime-spawn": "./src/runtime-spawn.ts"
+  },
+  "dependencies": {
+    "@coderspirit/nominal": "^4.1.1",
+    "@foxglove/crc": "^1.0.1",
+    "@sinclair/typebox": "0.34.41",
+    "@subsquid/ss58-codec": "^1.2.3",
+    "abitype": "1.1.0",
+    "bech32": "^2.0.0",
+    "bs58": "^6.0.0",
+    "bs58check": "^4.0.0",
+    "buffer": "^6.0.3",
+    "dotenv": "^16.4.7",
+    "effection": "^3.5.0",
+    "hi-base32": "^0.5.1",
+    "js-base64": "^3.7.7",
+    "js-sha512": "^0.9.0",
+    "viem": "2.37.3"
+  }
+}

package/src/binary-search.test.ts

@@ -0,0 +1,38 @@
+import { test, expect } from "bun:test";
+import { binarySearch } from "./binary-search.ts";
+
+test("binarySearch - finds exact match", () => {
+  const arr = [1, 3, 5, 7, 9];
+  const result = binarySearch(arr, 5, (val) => val);
+  expect(result).toEqual(2);
+});
+
+test("binarySearch - finds closest value >= target", () => {
+  const arr = [1, 3, 5, 7, 9];
+  const result = binarySearch(arr, 6, (val) => val);
+  expect(result).toEqual(3);
+});
+
+test("binarySearch - returns 0 if target is smaller than all elements", () => {
+  const arr = [1, 3, 5, 7, 9];
+  const result = binarySearch(arr, 0, (val) => val);
+  expect(result).toEqual(0);
+});
+
+test("binarySearch - returns undefined if target is larger than all elements", () => {
+  const arr = [1, 3, 5, 7, 9];
+  const result = binarySearch(arr, 10, (val) => val);
+  expect(result).toEqual(undefined);
+});
+
+test("binarySearch - returns undefined for empty array", () => {
+  const arr: number[] = [];
+  const result = binarySearch(arr, 5, (val) => val);
+  expect(result).toEqual(undefined);
+});
+
+test("binarySearch - works with custom projection function", () => {
+  const arr = [{ id: 10 }, { id: 20 }, { id: 30 }];
+  const result = binarySearch(arr, 20, (val) => val.id);
+  expect(result).toEqual(1);
+});

package/src/binary-search.ts

@@ -0,0 +1,45 @@
+/**
+ * Find the left-most entry index in an array satisfying the condition
+ *
+ * ex: binarySearch([6,7,7,8], 7, val => val) return `1`
+ */
+export function binarySearch<T>(
+  arr: T[],
+  target: number,
+  toNum: (val: T) => number,
+): number | undefined {
+  let low = 0;
+  let high = arr.length - 1;
+  let result: number | undefined = undefined; // This will hold the index of the smallest value >= target, if it exists
+
+  if (arr.length === 0) {
+    return undefined;
+  }
+
+  // if the target is smaller than all entries, just return right away
+  if (target - toNum(arr[0]) <= 0) {
+    return 0;
+  }
+  // if the target is bigger than all entries, just return right away
+  if (target - toNum(arr[arr.length - 1]) > 0) {
+    return undefined;
+  }
+
+  // first: find the largest index where the value is smaller than the target
+  while (low < high) {
+    const mid = low + Math.floor((high - low) / 2);
+
+    const val = target - toNum(arr[mid]);
+    if (val <= 0) {
+      high = mid;
+    } else {
+      result = mid;
+      low = mid + 1;
+    }
+  }
+  // sanity check: should never happen
+  if (result == null) {
+    return undefined;
+  }
+  return result + 1;
+}

package/src/captcha.ts

@@ -0,0 +1,21 @@
+// <reference lib="dom" />
+// error[banned-triple-slash-directives]: triple slash directives that modify globals are not allowed
+
+/**
+ * This method will dynamically add:
+ * <script src="https://www.google.com/recaptcha/api.js?render=YOUR_SITE_KEY"></script>
+ *
+ * You can manually add this script to your HTML,
+ * this method is just a helper to do it programmatically.
+ */
+export async function injectReCaptchaToHTML(document: any, reCAPTCHA_site_key: string): Promise<void> {
+  const url =
+    `https://www.google.com/recaptcha/api.js?render=${reCAPTCHA_site_key}`;
+  return await new Promise((resolve, reject) => {
+    const el = document.createElement("script");
+    el.src = url;
+    el.addEventListener("load", () => resolve());
+    el.addEventListener("error", () => reject());
+    document.body.append(el);
+  });
+}

package/src/concurrency/condVar.ts

@@ -0,0 +1,52 @@
+import type { Operation, Resolve, Scope, Task } from "effection";
+import { action, useScope } from "effection";
+
+export type CondVar<T> = {
+  wait: () => Operation<T>;
+  wake: (val: T) => void;
+};
+
+/**
+ * Allows blocking execution until a specific wake is called
+ *
+ * @example
+ * ```javascript
+ * const { wait, wake } = conditionVariable<void>();
+ * yield* spawn(function*() {
+ *     console.log('start wait');
+ *     yield* wait();
+ *     console.log('done wait');
+ * });
+ *
+ * yield* sleep(1000);
+ * wait(); // allows the spawn to continue executing
+ * ```
+ *
+ * See [Condition variables](https://en.wikipedia.org/wiki/Monitor_%28synchronization%29#Condition_variables) for more information
+ */
+export function conditionVariable<T>(): CondVar<T> {
+  let continuations: {
+    resolve: Resolve<T>;
+    scope: Scope;
+  }[] = [];
+
+  const wait = function* () {
+    const scope = yield* useScope();
+    return yield* action<T>(function* (resolve, _reject) {
+      continuations.push({ resolve, scope });
+    });
+  };
+
+  const wake = (val: T): void => {
+    const oldVal = continuations;
+    continuations = [];
+    for (const continuation of oldVal) {
+      // note: we explicitly do not await here
+      void continuation.scope.run(function* () {
+        continuation.resolve(val);
+      });
+    }
+  };
+
+  return { wait, wake };
+}

package/src/concurrency/latch.test.ts

@@ -0,0 +1,51 @@
+import { test, expect } from "bun:test";
+import { countdownLatch } from "./latch.ts";
+import { run, sleep, spawn } from "effection";
+
+test("countdownLatch - waits for countdown", async () => {
+  await run(function* () {
+    const { wait, countDown } = countdownLatch(2);
+    let done = false;
+
+    yield* spawn(function* () {
+      yield* wait();
+      done = true;
+    });
+
+    yield* sleep(10);
+    expect(done).toEqual(false);
+    countDown();
+
+    yield* sleep(10);
+    expect(done).toEqual(false);
+    countDown();
+
+    yield* sleep(10);
+    expect(done).toEqual(true);
+  });
+});
+
+test("countdownLatch - respects timeout", async () => {
+    await expect(async () => {
+        await run(function* () {
+            const { wait } = countdownLatch(1);
+            yield* wait(10); // 10ms timeout
+        });
+    }).toThrow("timeout");
+});
+
+test("countdownLatch - no-op if already zero", async () => {
+    await run(function* () {
+        const { wait, countDown } = countdownLatch(1);
+        countDown();
+        countDown(); // Should not error
+
+        let done = false;
+        yield* spawn(function* () {
+            yield* wait();
+            done = true;
+        });
+        yield* sleep(10);
+        expect(done).toEqual(true);
+    });
+});

package/src/concurrency/latch.ts

@@ -0,0 +1,61 @@
+import type { Operation } from "effection";
+import { action, race, sleep, spawn } from "effection";
+import { conditionVariable } from "./condVar.ts";
+
+/**
+ * Allow blocking execution until counted down N times
+ *
+ * @example
+ * ```javascript
+ * const { wait, countDown } = countdownLatch(2);
+ * yield* spawn(function* () {
+ *   yield* wait();
+ *   console.log("done");
+ * });
+ *
+ * yield* sleep(1000);
+ * countDown();
+ * yield* sleep(1000);
+ * countDown();
+ * ```
+ *
+ * See [Barrier](https://en.wikipedia.org/wiki/Barrier_%28computer_science%29) for more information
+ */
+export function countdownLatch<T>(
+  count: number,
+): {
+  wait: (timeout?: number) => Operation<void>;
+  countDown: () => void;
+} {
+  const vars = new Array(count).fill(null).map(() => conditionVariable<void>());
+  let currIndex = 0;
+
+  const wait = (timeout?: number) =>
+    action<void>(function* (resolve, reject) {
+      // note: start at `currIndex` and not 0
+      //       this is to support waiting on latches that have already started
+      const waitAll = yield* spawn(function* () {
+        for (let i = currIndex; i < count; i++) {
+          yield* vars[i].wait();
+        }
+        resolve();
+      });
+      if (timeout == null) return yield* waitAll;
+
+      const rejectOnTimeout = yield* spawn(function* (): Operation<void> {
+        yield* sleep(timeout);
+        reject(new Error("timeout"));
+      });
+      yield* race([waitAll, rejectOnTimeout]);
+    });
+  const countDown = (): void => {
+    if (currIndex >= count) {
+      return;
+    }
+    const oldValue = currIndex;
+    currIndex++;
+    vars[oldValue].wake();
+  };
+
+  return { wait, countDown };
+}

package/src/concurrency/mod.ts

@@ -0,0 +1,4 @@
+export * from "./condVar.ts";
+export * from "./latch.ts";
+export * from "./retry.ts";
+export * from "./utils.ts";

package/src/concurrency/retry.test.ts

@@ -0,0 +1,59 @@
+import { test, expect } from "bun:test";
+import { retry, tryYield } from "./retry.ts";
+import { run } from "effection";
+
+test("retry - succeeds immediately", async () => {
+  await run(function* () {
+    const result = yield* retry(
+      function* () { return "success"; },
+      (res) => res === "success"
+    );
+    expect(result).toEqual("success");
+  });
+});
+
+test("retry - retries until success", async () => {
+  await run(function* () {
+    let attempts = 0;
+    const result = yield* retry(
+      function* () {
+        attempts++;
+        return attempts < 3 ? "fail" : "success";
+      },
+      (res) => res === "success"
+    );
+    expect(result).toEqual("success");
+    expect(attempts).toEqual(3);
+  });
+});
+
+test("retry - fails after max attempts", async () => {
+  await expect(async () => {
+    await run(function* () {
+      yield* retry(
+        function* () { return "fail"; },
+        (res) => res === "success",
+        undefined,
+        2
+      );
+    });
+  }).toThrow("Max attempts reached");
+});
+
+test("tryYield - success case", async () => {
+    await run(function* () {
+        const op = function* () { return 42; };
+        const result = yield* tryYield(op());
+        expect(result.data).toEqual(42);
+        expect(result.error).toEqual(null);
+    });
+});
+
+test("tryYield - failure case", async () => {
+    await run(function* () {
+        const op = function* () { throw new Error("fail"); };
+        const result = yield* tryYield(op());
+        expect(result.data).toEqual(null);
+        expect(result.error?.message).toEqual("fail");
+    });
+});

package/src/concurrency/retry.ts

@@ -0,0 +1,67 @@
+import type { Operation } from "effection";
+
+export function* retry<Success, Failure = Success>(
+  fn: () => Operation<Success | Failure>,
+  isSuccess: (result: Success | Failure) => boolean,
+  onRetry?: (failResult: Failure) => Operation<void>,
+  maxAttempts?: number,
+): Operation<Success> {
+  return yield* retryInternal<Success, Failure>(
+    fn,
+    isSuccess,
+    0,
+    onRetry,
+    maxAttempts,
+  );
+}
+function* retryInternal<Success, Failure = Success>(
+  fn: () => Operation<Success | Failure>,
+  isSuccess: (result: Success | Failure) => boolean,
+  currAttempt: number,
+  onRetry?: (failResult: Failure) => Operation<void>,
+  maxAttempts?: number,
+): Operation<Success> {
+  const result = yield* fn();
+
+  if (isSuccess(result)) {
+    return result as Success;
+  }
+  if (onRetry != null) {
+    yield* onRetry(result as Failure);
+  }
+  if (maxAttempts == null || currAttempt !== maxAttempts) {
+    return yield* retryInternal<Success, Failure>(
+      fn,
+      isSuccess,
+      currAttempt + 1,
+      onRetry,
+      maxAttempts,
+    );
+  }
+  throw new Error("Max attempts reached");
+}
+
+// Types for the result object with discriminated union
+type Success<T> = {
+  data: T;
+  error: null;
+};
+
+type Failure<E> = {
+  data: null;
+  error: E;
+};
+
+type Result<T, E = Error> = Success<T> | Failure<E>;
+
+// Main wrapper function
+export function* tryYield<T, E = Error>(
+  promise: Operation<T>,
+): Operation<Result<T, E>> {
+  try {
+    const data = yield* promise;
+    return { data, error: null };
+  } catch (error) {
+    return { data: null, error: error as E };
+  }
+}

package/src/concurrency/utils.ts

@@ -0,0 +1,33 @@
+import type { Operation } from "effection";
+
+/**
+ * Equivalent of Promise.then
+ */
+export function* then<A, B>(
+  operation: Operation<A>,
+  fn: (value: A) => Operation<B>,
+): Operation<B> {
+  return yield* fn(yield* operation);
+}
+
+/**
+ * TODO: this is a better `then` since it's much easier to chain
+ * @example
+export function then<A, B>(
+  fn: (value: A) => Operation<B>,
+): (operation: Operation<A>) => Operation<B> {
+  return function* (operation) {
+    return yield* fn(yield* operation);
+  };
+}
+  * but the problem is that it relies on a `pipe` function
+  * that is only available in effection v4
+  * end-goal: api looks like this
+  * @example
+pipe(
+  operation,
+  then(lift((val) => val * 2)),
+  then(lift((val) => String(val)),
+  then(lift((val) => val.toUpperCase())),
+)
+*/