@latticexyz/utils 2.0.0-alpha.1.21 → 2.0.0-alpha.1.211

package/src/pack.spec.ts

@@ -0,0 +1,37 @@
+import { pack, unpack } from "./pack";
+
+describe("pack", () => {
+  it("should pack multiple numbers into one 32 bit integer", () => {
+    const packed = pack([1, 2], [8, 24]);
+    expect(packed).toBe(parseInt("1000000000000000000000010", 2));
+  });
+
+  it("should be the inverse of unpack", () => {
+    const bits = [8, 24];
+    const numbers = [16777218, 2072396467, -1];
+
+    for (const nums of numbers) {
+      expect(pack(unpack(nums, bits), bits)).toEqual(nums);
+    }
+  });
+});
+
+describe("unpack", () => {
+  it("should unpack a packed 32 bit integer into multiple numbers", () => {
+    const unpacked = unpack(parseInt("1000000000000000000000010", 2), [8, 24]);
+    expect(unpacked).toEqual([1, 2]);
+  });
+
+  it("should be the inverse of pack", () => {
+    const bits = [8, 24];
+    const numbers = [
+      [1, 2],
+      [123, 8798899],
+      [2 ** 8 - 1, 2 ** 24 - 1],
+    ];
+
+    for (const nums of numbers) {
+      expect(unpack(pack(nums, bits), bits)).toEqual(nums);
+    }
+  });
+});

package/src/pack.ts

@@ -0,0 +1,61 @@
+function rightMask(input: number, keep: number): number {
+  return input & (2 ** keep - 1);
+}
+
+/**
+ * Packs two unsigned integers in one 32 bit unsigned integer
+ * @param numbers Unsigned integers to be packed in 32 bit integer
+ * @param bitsPerNumber Bits for each number
+ * @returns Packed 32 bit unsigned integer
+ */
+export function pack(numbers: number[], bitsPerNumber: number[]): number {
+  // Total number of bits must be 32
+  if (bitsPerNumber.reduce((acc, curr) => acc + curr, 0) > 32) {
+    throw new Error("JS pretends integers are 32 bit when bitshifts are involved");
+  }
+
+  // Array lengths must match
+  if (numbers.length !== bitsPerNumber.length) throw new Error("Arrays' lengths must match");
+
+  // Numbers must fit in number of bits and must be unsigned
+  for (let i = 0; i < numbers.length; i++) {
+    if (numbers[i] < 0) {
+      throw new Error("Underflow: can only pack unsigned integer");
+    }
+    if (numbers[i] > 2 ** bitsPerNumber[i] - 1) {
+      const error = `Overflow: ${numbers[i]} does not fit in ${bitsPerNumber[i]} bits`;
+      throw new Error(error);
+    }
+  }
+
+  // Pack number
+  let packed = 0;
+  for (let i = 0; i < numbers.length; i++) {
+    packed = (packed << bitsPerNumber[i]) | numbers[i];
+  }
+  return packed;
+}
+
+/**
+ * Unpacks a packed 32 bit unsigned integer into the original unsigned integers
+ * @param packed Packed 32 bit unsigned integer
+ * @param bitsPerNumber Bits for each unsigned integer
+ * @returns Array of unpacked unsignd integers
+ */
+export function unpack(packed: number, bitsPerNumber: number[]): number[] {
+  const numbers: number[] = [];
+  let shiftedPacked = packed;
+  for (let i = bitsPerNumber.length - 1; i >= 0; i--) {
+    numbers.unshift(rightMask(shiftedPacked, bitsPerNumber[i]));
+    shiftedPacked = shiftedPacked >>> bitsPerNumber[i];
+  }
+  return numbers;
+}
+
+export function packTuple(numbers: [number, number]): number {
+  return pack(numbers, [8, 24]);
+}
+
+export function unpackTuple(packed: number): [number, number] {
+  return unpack(packed, [8, 24]) as [number, number];
+}

package/src/promise.ts

@@ -0,0 +1,46 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { deferred } from "./deferred";
+import { sleep } from "./sleep";
+
+export const range = function* (total = 0, step = 1, from = 0) {
+  // eslint-disable-next-line no-empty
+  for (let i = 0; i < total; yield from + i++ * step) {}
+};
+
+export async function rejectAfter<T>(ms: number, msg: string): Promise<T> {
+  await sleep(ms);
+  throw new Error(msg);
+}
+
+export const timeoutAfter = async <T>(promise: Promise<T>, ms: number, timeoutMsg: string) => {
+  return Promise.race([promise, rejectAfter<T>(ms, timeoutMsg)]);
+};
+
+export const callWithRetry = <T>(
+  fn: (...args: any[]) => Promise<T>,
+  args: any[] = [],
+  maxRetries = 10,
+  retryInterval = 1000
+): Promise<T> => {
+  const [resolve, reject, promise] = deferred<T>();
+  const process = async () => {
+    let res: T;
+    for (let i = 0; i < maxRetries; i++) {
+      try {
+        res = await fn(...args);
+        resolve(res);
+        break;
+      } catch (e) {
+        if (i < maxRetries - 1) {
+          console.info("[CallWithRetry Failed] attempt number=" + i, fn);
+          console.error(e);
+          await sleep(Math.min(retryInterval * 2 ** i + Math.random() * 100, 15000));
+        } else {
+          reject(e as unknown as Error);
+        }
+      }
+    }
+  };
+  process();
+  return promise;
+};

package/src/proxy.spec.ts

@@ -0,0 +1,186 @@
+import { runInAction } from "mobx";
+import { computed, observable } from "mobx";
+import { deferred } from "./deferred";
+import { cacheUntilReady } from "./proxy";
+
+describe("cacheUntilReady", () => {
+  describe("property access", () => {
+    it("should immediately relay simple property access to the computed target if it is ready", () => {
+      const target = computed(() => ({ a: 1 }));
+      const proxy = cacheUntilReady(target);
+      expect(proxy.a).toBe(1);
+      expect(proxy.proxied).toBe(false);
+    });
+
+    it("should immediately relay simple property access to the observable target if it is ready", () => {
+      const target = observable.box({ a: 1 });
+      const proxy = cacheUntilReady(target);
+      expect(proxy.a).toBe(1);
+      expect(proxy.proxied).toBe(false);
+    });
+
+    it("should immediately relay deep property access to the computed target if it is ready", () => {
+      const target = computed(() => ({ a: { b: { c: 2 } } }));
+      const proxy = cacheUntilReady(target);
+      expect(proxy.a.b.c).toBe(2);
+      expect(proxy.proxied).toBe(false);
+    });
+
+    it("should immediately relay deep property access to the observable target if it is ready", () => {
+      const target = observable.box({ a: { b: 2 } });
+      const proxy = cacheUntilReady(target);
+      expect(proxy.a.b).toBe(2);
+      expect(proxy.proxied).toBe(false);
+    });
+
+    it("should return undefined for property access if the target is not ready", () => {
+      const target = observable.box<{ a: { b: number } } | undefined>(undefined);
+      const proxy = cacheUntilReady(target);
+      const result1 = proxy.a;
+      const result2 = proxy.a.b;
+
+      expect(JSON.stringify(result1)).toBe(JSON.stringify({ proxied: true }));
+      expect(JSON.stringify(result2)).toBe(JSON.stringify({ proxied: true }));
+      expect(proxy.proxied).toBe(true);
+    });
+  });
+
+  describe("function calls", () => {
+    it("should immediately relay top level function calls to the computed target it if it ready", () => {
+      const target = computed(() => ({
+        a: () => 1,
+      }));
+
+      const proxy = cacheUntilReady(target);
+
+      expect(proxy.a()).toBe(1);
+    });
+
+    it("should immediately relay top level function calls to the observable target it if it ready", () => {
+      const target = observable.box({
+        a: () => 1,
+      });
+
+      const proxy = cacheUntilReady(target);
+
+      expect(proxy.a()).toBe(1);
+    });
+
+    it("should immediately relay deep nested function calls to the computed target it if it ready", () => {
+      const target = computed(() => ({
+        a: { b: () => 1 },
+      }));
+
+      const proxy = cacheUntilReady(target);
+
+      expect(proxy.a.b()).toBe(1);
+    });
+
+    it("should immediately relay deep nested function calls to the observable target it if it ready", () => {
+      const target = observable.box({
+        a: { b: () => 1 },
+      });
+
+      const proxy = cacheUntilReady(target);
+
+      expect(proxy.a.b()).toBe(1);
+    });
+
+    it("should chache top level function calls to the target until it is ready", async () => {
+      const target = observable.box<{ a: (n: number) => number } | undefined>(undefined);
+
+      const proxy = cacheUntilReady(target);
+
+      // Target is not ready yet, but function is called already
+      const result1 = proxy.a(1);
+      const result2 = proxy.a(2);
+
+      // Now target is ready
+      runInAction(() => target.set({ a: (n) => n }));
+
+      // Cached function calls are applied,
+      expect(await result1).toEqual(1);
+      expect(await result2).toEqual(2);
+    });
+
+    it("should chache nested function calls to the target until it is ready", async () => {
+      const target = observable.box<{ a: { b: (n: number) => number } } | undefined>(undefined);
+
+      const proxy = cacheUntilReady(target);
+
+      // Target is not ready yet, but function is called already
+      const result1 = proxy.a.b(1);
+      const result2 = proxy.a.b(2);
+
+      const getResult3 = async () => proxy.a.b((await result1) + (await result2));
+      const result3 = getResult3();
+
+      // Now target is ready
+      runInAction(() => target.set({ a: { b: (n) => n + 1 } }));
+
+      // Cached function calls are applied,
+      expect(await result1).toEqual(2);
+      expect(await result2).toEqual(3);
+      expect(await result3).toEqual(6);
+    });
+
+    it("should chache nested function calls without parameters to the target until it is ready", async () => {
+      const target = observable.box<{ a: { b: () => number } } | undefined>(undefined);
+
+      const proxy = cacheUntilReady(target);
+
+      // Target is not ready yet, but function is called already
+      const result1 = proxy.a.b();
+      const result2 = proxy.proxied && proxy.a.b();
+
+      // Now target is ready
+      runInAction(() => target.set({ a: { b: () => 1 } }));
+
+      // Cached function calls are applied,
+      expect(await result1).toEqual(1);
+      expect(await result2).toEqual(1);
+    });
+
+    it("should chache nested function calls with variable parameters to the target until it is ready", async () => {
+      const target = observable.box<{ a: { b: (...args: number[]) => number } } | undefined>(undefined);
+
+      const proxy = cacheUntilReady(target);
+
+      // Target is not ready yet, but function is called already
+      const result1 = proxy.a.b();
+      const result2 = proxy.a.b(1);
+      const result3 = proxy.a.b(1, 2);
+      const result4 = proxy.a.b(1, 2, 3);
+
+      // Now target is ready
+      runInAction(() => target.set({ a: { b: (...args) => args.reduce((acc, curr) => acc + curr, 0) } }));
+
+      // Cached function calls are applied,
+      expect(await result1).toEqual(0);
+      expect(await result2).toEqual(1);
+      expect(await result3).toEqual(3);
+      expect(await result4).toEqual(6);
+    });
+
+    it("should return a non-nested proxy if the called target function returns a proxy", async () => {
+      const target = observable.box<{ a: { b: () => Promise<number> } } | undefined>(undefined);
+
+      const proxy = cacheUntilReady(target);
+
+      // Target is not ready yet, but function is called already
+      const result1 = proxy.a.b();
+      const result2 = proxy.a.b();
+
+      const [resolve, , promise] = deferred<number>();
+      // Now target is ready
+      runInAction(() => target.set({ a: { b: () => promise } }));
+
+      // Now resolve the promise returned by the target function
+      resolve(1);
+
+      // Cached function calls are applied,
+      expect(await result1).toEqual(1);
+      expect(await result2).toEqual(1);
+    });
+  });
+});

package/src/proxy.ts

@@ -0,0 +1,101 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { IComputedValue, IObservableValue, reaction } from "mobx";
+import DeepProxy from "proxy-deep";
+import { deferred } from "./deferred";
+import { isFunction, isObject } from "./guards";
+import { Cached } from "./types";
+
+function deepAccess(target: Record<string, unknown>, path: string[]): any {
+  if (path.length === 0) return target;
+  if (path.length === 1) return target[path[0]];
+  const [next, ...rest] = path;
+  const nextTarget = target[next];
+  if (!isObject(nextTarget)) throw new Error("Path does not exist on the target");
+  return deepAccess(nextTarget, rest);
+}
+
+/**
+ * Caches any function calls to the target until the target is ready.
+ * @param target T extends Cachable
+ * @returns Cached<T>
+ */
+export function cacheUntilReady<T extends Record<string, any>>(
+  target: IObservableValue<T | undefined> | IComputedValue<T | undefined>
+): Cached<T> {
+  // The call queue contains the path and arguments of calls to the
+  // proxiedTarget while the target was not available yet.
+  // It also contains resolve and reject methods to fulfil the promise
+  // returned when calling the proxiedTarget once the target becomes available.
+  const callQueue: {
+    path: string[];
+    args?: any[];
+    resolve: (result: any) => void;
+    reject: (e: Error) => void;
+  }[] = [];
+
+  // The proxiedTarget proxies all calls to the target.
+  // If a function is called on the proxiedTarget while the target is not
+  // available, a promise is returned and the call will be stored in the callQueue
+  // until the target becomes available and the promise is fulfilled.
+  const proxiedTarget = new DeepProxy(
+    {},
+    {
+      get(_t, prop) {
+        const targetReady = target.get();
+        if (targetReady) {
+          // If the target is ready, relay all calls directly to the target
+          // (Except for the "proxied" key, which indicates whether the object is currently proxied)
+          if (prop === "proxied") return false;
+          return Reflect.get(targetReady, prop);
+        } else {
+          // Note: if the target is not available, accessing a property returns another proxy,
+          // not a Promise. It is possible to check whether a value is currently proxied using the proxied key.
+          if (prop === "proxied") return true;
+          if (prop === "name") return "ProxiedTarget";
+          if (prop === "toJSON") return () => ({ proxied: true });
+          return this.nest(() => void 0);
+        }
+      },
+      apply(_, thisArg, args) {
+        const targetReady = target.get();
+        if (targetReady) {
+          // If the target is ready, relay all calls directly to the target
+          const targetFunc = deepAccess(targetReady, this.path);
+          if (!isFunction(targetFunc)) throw new Error("Target is not callable");
+          return Reflect.apply(targetFunc, thisArg, args);
+        } else {
+          // Otherwise store the call and relay it to the target later once it's ready.
+          // The return value of this call is a promise, that gets resolved once the target is ready.
+          const [resolve, reject, promise] = deferred();
+          callQueue.push({ path: this.path, args, resolve, reject });
+          return promise;
+        }
+      },
+    }
+  );
+
+  reaction(
+    () => target.get(),
+    (targetReady) => {
+      if (!targetReady) return;
+      // Move all entries from callQueue to queuedCalls
+      const queuedCalls = callQueue.splice(0);
+      for (const { path, args, resolve, reject } of queuedCalls) {
+        const target = deepAccess(targetReady, path);
+        if (args && isFunction(target)) {
+          (async () => {
+            try {
+              resolve(await target(...args));
+            } catch (e: any) {
+              reject(e);
+            }
+          })();
+        } else {
+          resolve(target);
+        }
+      }
+    }
+  );
+
+  return proxiedTarget as Cached<T>;
+}

package/{dist/random.d.ts → src/random.ts}

@@ -4,9 +4,14 @@
  * @param from Lower bound (included). Default 0.
  * @returns A random integer between from and to.
  */
-export declare function random(to: number, from?: number): number;
+export function random(to: number, from = 0): number {
+  return Math.floor(Math.random() * (to - from + 1)) + from;
+}
+
 /**
  * @param array Array to pick a random element from.
  * @returns Random element from the given array.
  */
-export declare function pickRandom<T>(array: [T, ...T[]]): T;
+export function pickRandom<T>(array: [T, ...T[]]): T {
+  return array[random(array.length - 1)];
+}

package/src/rx.spec.ts

@@ -0,0 +1,45 @@
+import { Subject } from "rxjs";
+import { awaitStreamValue, streamToComputed } from "./rx";
+import { sleep } from "./sleep";
+
+describe("streamToComputed", () => {
+  it("should return a computed value that corresponds to the last stream value", () => {
+    const stream = new Subject<number>();
+    const comp = streamToComputed(stream);
+    expect(comp.get()).toBeUndefined();
+
+    stream.next(1);
+    expect(comp.get()).toBe(1);
+
+    stream.next(2);
+    expect(comp.get()).toBe(2);
+
+    stream.next(3);
+    stream.next(4);
+    expect(comp.get()).toBe(4);
+  });
+});
+
+describe("awaitStreamValue", () => {
+  it("should return a promise that resolves once the requested stream value is emitted", async () => {
+    const stream = new Subject<number>();
+    const promise = awaitStreamValue(stream, (v) => v === 1);
+
+    let isFulfilled = false;
+    (async () => {
+      await promise;
+      isFulfilled = true;
+    })();
+
+    await sleep(100);
+    expect(isFulfilled).toBe(false);
+
+    stream.next(2);
+    await sleep(100);
+    expect(isFulfilled).toBe(false);
+
+    stream.next(1);
+    await sleep(100);
+    expect(isFulfilled).toBe(true);
+  });
+});

package/src/rx.ts

@@ -0,0 +1,124 @@
+import {
+  concatMap,
+  delay,
+  filter,
+  first,
+  mergeMap,
+  Observable,
+  of,
+  OperatorFunction,
+  pipe,
+  ReplaySubject,
+  scan,
+  Timestamp,
+  timestamp,
+} from "rxjs";
+import { computed, IComputedValue, IObservableValue, observable, reaction, runInAction, toJS } from "mobx";
+import { deferred } from "./deferred";
+import { awaitValue } from "./mobx";
+
+export function filterNullish<T>(): OperatorFunction<T, NonNullable<T>> {
+  return pipe<Observable<T>, Observable<NonNullable<T>>>(
+    filter<T>((x: T) => x != null) as OperatorFunction<T, NonNullable<T>>
+  );
+}
+
+export function awaitPromise<T extends Promise<unknown>>(): OperatorFunction<T, Awaited<T>> {
+  return pipe(concatMap((x: T) => x)) as OperatorFunction<T, Awaited<T>>;
+}
+
+/**
+ * RxJS operator to stretch out an event stream by a given delay per event
+ * @param spacingDelayMs Delay between each event in ms
+ * @returns stream of events with at least spacingDelayMs spaceing between event
+ */
+export function stretch<T>(spacingDelayMs: number) {
+  return pipe(
+    timestamp<T>(),
+    scan((acc: (Timestamp<T> & { delay: number }) | null, curr: Timestamp<T>) => {
+      // calculate delay needed to offset next emission
+      let delay = 0;
+      if (acc !== null) {
+        const timeDelta = curr.timestamp - acc.timestamp;
+        delay = timeDelta > spacingDelayMs ? 0 : spacingDelayMs - timeDelta;
+      }
+
+      return {
+        timestamp: curr.timestamp,
+        delay: delay,
+        value: curr.value,
+      };
+    }, null),
+    filterNullish(),
+    mergeMap((i) => of(i.value).pipe(delay(i.delay)), 1)
+  );
+}
+
+export function observableToComputed<T>(obs: IObservableValue<T>): IComputedValue<T> {
+  return computed(() => obs.get());
+}
+
+export function computedToStream<T>(comp: IComputedValue<T> | IObservableValue<T>): Observable<T> {
+  const stream = new ReplaySubject<T>(1);
+  reaction(
+    () => comp.get(),
+    (value) => {
+      if (value != null) stream.next(value);
+    },
+    { fireImmediately: true }
+  );
+  return stream;
+}
+
+export function observableToStream<T>(obs: T): Observable<T> {
+  const stream = new ReplaySubject<T>(1);
+  reaction(
+    () => toJS(obs),
+    (value) => {
+      if (value != null) stream.next(value);
+    },
+    { fireImmediately: true }
+  );
+  return stream;
+}
+
+export function streamToComputed<T>(stream$: Observable<T>): IComputedValue<T | undefined> {
+  const value = observable.box<T | undefined>();
+  stream$.subscribe((val) => runInAction(() => value.set(val)));
+  return computed(() => value.get());
+}
+
+export async function streamToDefinedComputed<T>(stream$: Observable<T>): Promise<IComputedValue<T>> {
+  const value = observable.box<T>();
+  stream$.subscribe((val) => runInAction(() => value.set(val)));
+  const computedValue = computed(() => value.get());
+  await awaitValue(computedValue);
+  return computedValue as IComputedValue<T>;
+}
+
+/**
+ *
+ * @param stream$ RxJS observable to check for the given value
+ * @param predicate Predicate to check
+ * @returns A promise that resolves with the requested value once the predicate is true
+ */
+export async function awaitStreamValue<T>(
+  stream$: Observable<T>,
+  predicate: (value: T) => boolean = (value) => value != null
+): Promise<T> {
+  const [resolve, , promise] = deferred<T>();
+  stream$.pipe(first(predicate)).subscribe(resolve);
+  return promise;
+}
+
+/**
+ * Turns a stream into an updating object for easy access outside of rxjs
+ * @param stream$ Stream to turn into a wrapped value
+ * @returns Object with `current` key corresponding to last stream value
+ */
+export async function streamToWrappedValue<T>(stream$: Observable<T>): Promise<{ current: T }> {
+  const value: { current?: T } = {};
+  stream$.subscribe((v) => (value.current = v));
+  value.current = await awaitStreamValue(stream$);
+  return value as { current: T };
+}

package/src/sleep.ts

@@ -0,0 +1,3 @@
+export function sleep<T>(timeout: number, returns?: T): Promise<T> {
+  return new Promise<T>((resolve) => setTimeout(() => resolve(returns as T), timeout));
+}

package/src/types.ts

@@ -0,0 +1,48 @@
+import { enableLogger } from "./console";
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type Func<A extends any[], R> = (...args: A) => R;
+export type AsyncFunc<A extends any[], R> = R extends Promise<unknown> ? (...args: A) => R : (...args: A) => Promise<R>;
+
+export type CachedValue<V, Proxied extends boolean> = Proxied extends true
+  ? V extends Func<infer A, infer B>
+    ? AsyncFunc<A, B>
+    : V extends Record<string, any>
+    ? Cached<V> & { proxied: true }
+    : { proxied: true }
+  : V extends Func<infer A, infer B>
+  ? Func<A, B>
+  : V extends Record<string, any>
+  ? V
+  : V & { proxied: false };
+
+export type Cached<C> =
+  | ({ proxied: false } & { [key in keyof C]: CachedValue<C[key], false> })
+  | ({ proxied: true } & { [key in keyof C]: CachedValue<C[key], true> });
+
+/**
+ * @deprecated Use Awaited<T> instead
+ */
+export type PromiseValue<T> = Awaited<T>;
+
+export type ValueOf<T extends object> = T[keyof T];
+
+export type Area = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export type Coord = {
+  x: number;
+  y: number;
+};
+
+export type VoxelCoord = {
+  x: number;
+  y: number;
+  z: number;
+};
+
+export type Logger = ReturnType<typeof enableLogger>;