@hexclave/shared 1.0.3 → 1.0.5

package/src/utils/maps.tsx

@@ -0,0 +1,407 @@
+import { Result } from "./results";
+
+export class WeakRefIfAvailable<T extends object> {
+  private readonly _ref: { deref: () => T | undefined };
+
+  constructor(value: T) {
+    if (typeof WeakRef === "undefined") {
+      this._ref = { deref: () => value };
+    } else {
+      this._ref = new WeakRef<T>(value);
+    }
+  }
+
+  deref(): T | undefined {
+    return this._ref.deref();
+  }
+}
+import.meta.vitest?.test("WeakRefIfAvailable", ({ expect }) => {
+  // Test with an object
+  const obj = { id: 1, name: "test" };
+  const weakRef = new WeakRefIfAvailable(obj);
+
+  // Test deref returns the original object
+  expect(weakRef.deref()).toBe(obj);
+
+  // Test with a different object
+  const obj2 = { id: 2, name: "test2" };
+  const weakRef2 = new WeakRefIfAvailable(obj2);
+  expect(weakRef2.deref()).toBe(obj2);
+  expect(weakRef2.deref()).not.toBe(obj);
+
+  // We can't easily test garbage collection in this environment,
+  // but we can verify the basic functionality works
+});
+
+
+/**
+ * A WeakMap-like object that can be iterated over.
+ *
+ * Note that it relies on WeakRef, and always falls back to the regular Map behavior (ie. no GC) in browsers that don't support it.
+ */
+export class IterableWeakMap<K extends object, V> {
+  private readonly _weakMap: WeakMap<K & WeakKey, { value: V, keyRef: WeakRefIfAvailable<K & WeakKey> }>;
+  private readonly _keyRefs: Set<WeakRefIfAvailable<K & WeakKey>>;
+
+  constructor(entries?: readonly (readonly [K, V])[] | null) {
+    const mappedEntries = entries?.map((e) => [e[0], { value: e[1], keyRef: new WeakRefIfAvailable(e[0]) }] as const);
+    this._weakMap = new WeakMap(mappedEntries ?? []);
+    this._keyRefs = new Set(mappedEntries?.map((e) => e[1].keyRef) ?? []);
+  }
+
+  get(key: K): V | undefined {
+    return this._weakMap.get(key)?.value;
+  }
+
+  set(key: K, value: V): this {
+    const existing = this._weakMap.get(key);
+    const updated = { value, keyRef: existing?.keyRef ?? new WeakRefIfAvailable(key) };
+    this._weakMap.set(key, updated);
+    this._keyRefs.add(updated.keyRef);
+    return this;
+  }
+
+  delete(key: K): boolean {
+    const res = this._weakMap.get(key);
+    if (res) {
+      this._weakMap.delete(key);
+      this._keyRefs.delete(res.keyRef);
+      return true;
+    }
+    return false;
+  }
+
+  has(key: K): boolean {
+    return this._weakMap.has(key) && this._keyRefs.has(this._weakMap.get(key)!.keyRef);
+  }
+
+  *[Symbol.iterator](): IterableIterator<[K, V]> {
+    for (const keyRef of this._keyRefs) {
+      const key = keyRef.deref();
+      const existing = key ? this._weakMap.get(key) : undefined;
+      if (!key) {
+        // This can happen if the key was GCed. Remove it so the next iteration is faster.
+        this._keyRefs.delete(keyRef);
+      } else if (existing) {
+        yield [key, existing.value];
+      }
+    }
+  }
+
+  [Symbol.toStringTag] = "IterableWeakMap";
+}
+import.meta.vitest?.test("IterableWeakMap", ({ expect }) => {
+  // Test basic functionality
+  const map = new IterableWeakMap<{ id: number }, string>();
+
+  // Create object keys
+  const obj1 = { id: 1 };
+  const obj2 = { id: 2 };
+
+  // Test set and get
+  map.set(obj1, "value1");
+  expect(map.get(obj1)).toBe("value1");
+
+  // Test has
+  expect(map.has(obj1)).toBe(true);
+  expect(map.has(obj2)).toBe(false);
+  expect(map.has({ id: 1 })).toBe(false); // Different object with same content
+
+  // Test with multiple keys
+  map.set(obj2, "value2");
+  expect(map.get(obj2)).toBe("value2");
+  expect(map.get(obj1)).toBe("value1"); // Original still exists
+
+  // Test delete
+  expect(map.delete(obj1)).toBe(true);
+  expect(map.has(obj1)).toBe(false);
+  expect(map.get(obj1)).toBeUndefined();
+  expect(map.has(obj2)).toBe(true); // Other key still exists
+
+  // Test delete non-existent key
+  expect(map.delete({ id: 3 })).toBe(false);
+
+  // Test iteration
+  const iterMap = new IterableWeakMap<{ id: number }, number>();
+  const iterObj1 = { id: 1 };
+  const iterObj2 = { id: 2 };
+  const iterObj3 = { id: 3 };
+
+  iterMap.set(iterObj1, 1);
+  iterMap.set(iterObj2, 2);
+  iterMap.set(iterObj3, 3);
+
+  const entries = Array.from(iterMap);
+  expect(entries.length).toBe(3);
+
+  // Find entries by their values since we can't directly compare objects in the array
+  const values = entries.map(entry => entry[1]);
+  expect(values).toContain(1);
+  expect(values).toContain(2);
+  expect(values).toContain(3);
+
+  // Test constructor with entries
+  const initialEntries: [{ id: number }, string][] = [
+    [{ id: 4 }, "initial1"],
+    [{ id: 5 }, "initial2"]
+  ];
+  const mapWithEntries = new IterableWeakMap(initialEntries);
+
+  // We can't directly access the initial entries since they're different object references
+  // But we can verify the map has the correct number of entries
+  const entriesFromConstructor = Array.from(mapWithEntries);
+  expect(entriesFromConstructor.length).toBe(2);
+});
+
+/**
+ * A map that is a IterableWeakMap for object keys and a regular Map for primitive keys. Also provides iteration over both
+ * object and primitive keys.
+ *
+ * Note that, just like IterableWeakMap, older browsers without support for WeakRef will use a regular Map for object keys.
+ */
+export class MaybeWeakMap<K, V> {
+  private readonly _primitiveMap: Map<K, V>;
+  private readonly _weakMap: IterableWeakMap<K & WeakKey, V>;
+
+  constructor(entries?: readonly (readonly [K, V])[] | null) {
+    const entriesArray = [...entries ?? []];
+    this._primitiveMap = new Map(entriesArray.filter((e) => !this._isAllowedInWeakMap(e[0])));
+    this._weakMap = new IterableWeakMap(entriesArray.filter((e): e is [K & WeakKey, V] => this._isAllowedInWeakMap(e[0])));
+  }
+
+  private _isAllowedInWeakMap(key: K): key is K & WeakKey {
+    return (typeof key === "object" && key !== null) || (typeof key === "symbol" && Symbol.keyFor(key) === undefined);
+  }
+
+  get(key: K): V | undefined {
+    if (this._isAllowedInWeakMap(key)) {
+      return this._weakMap.get(key);
+    } else {
+      return this._primitiveMap.get(key);
+    }
+  }
+
+  set(key: K, value: V): this {
+    if (this._isAllowedInWeakMap(key)) {
+      this._weakMap.set(key, value);
+    } else {
+      this._primitiveMap.set(key, value);
+    }
+    return this;
+  }
+
+  delete(key: K): boolean {
+    if (this._isAllowedInWeakMap(key)) {
+      return this._weakMap.delete(key);
+    } else {
+      return this._primitiveMap.delete(key);
+    }
+  }
+
+  has(key: K): boolean {
+    if (this._isAllowedInWeakMap(key)) {
+      return this._weakMap.has(key);
+    } else {
+      return this._primitiveMap.has(key);
+    }
+  }
+
+  *[Symbol.iterator](): IterableIterator<[K, V]> {
+    yield* this._primitiveMap;
+    yield* this._weakMap;
+  }
+
+  [Symbol.toStringTag] = "MaybeWeakMap";
+}
+import.meta.vitest?.test("MaybeWeakMap", ({ expect }) => {
+  // Test with primitive keys
+  const map = new MaybeWeakMap<string | object, number>();
+
+  // Test with string keys
+  map.set("key1", 1);
+  map.set("key2", 2);
+  expect(map.get("key1")).toBe(1);
+  expect(map.get("key2")).toBe(2);
+  expect(map.has("key1")).toBe(true);
+  expect(map.has("nonexistent")).toBe(false);
+
+  // Test with object keys
+  const obj1 = { id: 1 };
+  const obj2 = { id: 2 };
+  map.set(obj1, 3);
+  map.set(obj2, 4);
+  expect(map.get(obj1)).toBe(3);
+  expect(map.get(obj2)).toBe(4);
+  expect(map.has(obj1)).toBe(true);
+
+  // Test delete with primitive key
+  expect(map.delete("key1")).toBe(true);
+  expect(map.has("key1")).toBe(false);
+  expect(map.delete("nonexistent")).toBe(false);
+
+  // Test delete with object key
+  expect(map.delete(obj1)).toBe(true);
+  expect(map.has(obj1)).toBe(false);
+
+  // Test iteration
+  const entries = Array.from(map);
+  expect(entries.length).toBe(2);
+  expect(entries).toContainEqual(["key2", 2]);
+  expect(entries).toContainEqual([obj2, 4]);
+
+  // Test constructor with entries
+  const initialEntries: [string | object, number][] = [
+    ["initial1", 10],
+    [{ id: 3 }, 20]
+  ];
+  const mapWithEntries = new MaybeWeakMap(initialEntries);
+  expect(mapWithEntries.get("initial1")).toBe(10);
+  expect(mapWithEntries.get(initialEntries[1][0])).toBe(20);
+});
+
+
+type DependenciesMapInner<V> = (
+  & { map: MaybeWeakMap<unknown, DependenciesMapInner<V>> }
+  & (
+    | { hasValue: true, value: V }
+    | { hasValue: false, value: undefined }
+  )
+);
+
+/**
+ * A map that stores values indexed by an array of keys. If the keys are objects and the environment supports WeakRefs,
+ * they are stored in a WeakMap.
+ */
+export class DependenciesMap<K extends any[], V> {
+  private _inner: DependenciesMapInner<V> = { map: new MaybeWeakMap(), hasValue: false, value: undefined };
+
+  private _valueToResult(inner: DependenciesMapInner<V>): Result<V, void> {
+    if (inner.hasValue) {
+      return Result.ok(inner.value);
+    } else {
+      return Result.error(undefined);
+    }
+  }
+
+
+  private _unwrapFromInner(dependencies: any[], inner: DependenciesMapInner<V>): Result<V, void> {
+    if ((dependencies.length === 0)) {
+      return this._valueToResult(inner);
+    } else {
+      const [key, ...rest] = dependencies;
+      const newInner = inner.map.get(key);
+      if (!newInner) {
+        return Result.error(undefined);
+      }
+      return this._unwrapFromInner(rest, newInner);
+    }
+  }
+
+  private _setInInner(dependencies: any[], value: Result<V, void>, inner: DependenciesMapInner<V>): Result<V, void> {
+    if (dependencies.length === 0) {
+      const res = this._valueToResult(inner);
+      if (value.status === "ok") {
+        inner.hasValue = true;
+        inner.value = value.data;
+      } else {
+        inner.hasValue = false;
+        inner.value = undefined;
+      }
+      return res;
+    } else {
+      const [key, ...rest] = dependencies;
+      let newInner = inner.map.get(key);
+      if (!newInner) {
+        inner.map.set(key, newInner = { map: new MaybeWeakMap(), hasValue: false, value: undefined });
+      }
+      return this._setInInner(rest, value, newInner);
+    }
+  }
+
+  private *_iterateInner(dependencies: any[], inner: DependenciesMapInner<V>): IterableIterator<[K, V]> {
+    if (inner.hasValue) {
+      yield [dependencies as K, inner.value];
+    }
+    for (const [key, value] of inner.map) {
+      yield* this._iterateInner([...dependencies, key], value);
+    }
+  }
+
+  get(dependencies: K): V | undefined {
+    return Result.or(this._unwrapFromInner(dependencies, this._inner), undefined);
+  }
+
+  set(dependencies: K, value: V): this {
+    this._setInInner(dependencies, Result.ok(value), this._inner);
+    return this;
+  }
+
+  delete(dependencies: K): boolean {
+    return this._setInInner(dependencies, Result.error(undefined), this._inner).status === "ok";
+  }
+
+  has(dependencies: K): boolean {
+    return this._unwrapFromInner(dependencies, this._inner).status === "ok";
+  }
+
+  clear(): void {
+    this._inner = { map: new MaybeWeakMap(), hasValue: false, value: undefined };
+  }
+
+  *[Symbol.iterator](): IterableIterator<[K, V]> {
+    yield* this._iterateInner([], this._inner);
+  }
+
+  [Symbol.toStringTag] = "DependenciesMap";
+}
+import.meta.vitest?.test("DependenciesMap", ({ expect }) => {
+  // Test basic functionality
+  const map = new DependenciesMap<[string, number], string>();
+
+  // Test set and get
+  map.set(["key", 1], "value1");
+  expect(map.get(["key", 1])).toBe("value1");
+
+  // Test has
+  expect(map.has(["key", 1])).toBe(true);
+  expect(map.has(["key", 2])).toBe(false);
+
+  // Test with different dependencies
+  map.set(["key", 2], "value2");
+  expect(map.get(["key", 2])).toBe("value2");
+  expect(map.get(["key", 1])).toBe("value1"); // Original still exists
+
+  // Test delete
+  expect(map.delete(["key", 1])).toBe(true);
+  expect(map.has(["key", 1])).toBe(false);
+  expect(map.get(["key", 1])).toBeUndefined();
+  expect(map.has(["key", 2])).toBe(true); // Other key still exists
+
+  // Test delete non-existent key
+  expect(map.delete(["nonexistent", 1])).toBe(false);
+
+  // Test clear
+  map.clear();
+  expect(map.has(["key", 2])).toBe(false);
+
+  // Test with object keys
+  const objMap = new DependenciesMap<[object, number], string>();
+  const obj1 = { id: 1 };
+  const obj2 = { id: 2 };
+  objMap.set([obj1, 1], "object1");
+  objMap.set([obj2, 2], "object2");
+  expect(objMap.get([obj1, 1])).toBe("object1");
+  expect(objMap.get([obj2, 2])).toBe("object2");
+
+  // Test iteration
+  const iterMap = new DependenciesMap<[string], number>();
+  iterMap.set(["a"], 1);
+  iterMap.set(["b"], 2);
+  iterMap.set(["c"], 3);
+
+  const entries = Array.from(iterMap);
+  expect(entries.length).toBe(3);
+  expect(entries).toContainEqual([["a"], 1]);
+  expect(entries).toContainEqual([["b"], 2]);
+  expect(entries).toContainEqual([["c"], 3]);
+});

package/src/utils/math.tsx

@@ -0,0 +1,18 @@
+/**
+ * Similar to the modulo operator, but always returns a positive number (even when the input is negative).
+ */
+export function remainder(n: number, d: number): number {
+  return ((n % d) + Math.abs(d)) % d;
+}
+import.meta.vitest?.test("remainder", ({ expect }) => {
+  expect(remainder(10, 3)).toBe(1);
+  expect(remainder(10, 5)).toBe(0);
+  expect(remainder(10, 7)).toBe(3);
+  // Test with negative numbers
+  expect(remainder(-10, 3)).toBe(2);
+  expect(remainder(-5, 2)).toBe(1);
+  expect(remainder(-7, 4)).toBe(1);
+  // Test with decimal numbers
+  expect(remainder(10.5, 3)).toBeCloseTo(1.5);
+  expect(remainder(-10.5, 3)).toBeCloseTo(1.5);
+});

package/src/utils/monkey-patch.tsx

@@ -0,0 +1,29 @@
+import { createGlobal } from "./globals";
+
+export const NO_SUSPENSE_BOUNDARY_ERROR_SENTINEL = "__stack-no-suspense-boundary-error__";
+
+export function isNoSuspenseBoundaryError(value: unknown): boolean {
+  return (
+    typeof value === "object"
+    && value !== null
+    && (value as Record<string, unknown>).__noSuspenseBoundarySentinel === NO_SUSPENSE_BOUNDARY_ERROR_SENTINEL
+  );
+}
+
+export function ensureMonkeyPatch() {
+  createGlobal("__console-error-monkey-patch__", () => {
+    const originalConsoleError = console.error;
+    console.error = function (...args: unknown[]) {
+      // React's default error handlers will log all errors to the console, even those that we intentionally use to suppress SSR.
+      // Next.js among others override the default error handler and will not log SSR errors to the console.
+      // However, vanilla React and other frameworks like TanStack Start use the default error handler.
+      // Hence, we suppress the error here if it is a NoSuspenseBoundaryError.
+      // It's very cursed, but it's really our best option. Talk to @konsti if you want to know more.
+      if (args.length === 1 && isNoSuspenseBoundaryError(args[0])) {
+        return;
+      }
+      return originalConsoleError.apply(this, args);
+    };
+    return true;
+  });
+}

package/src/utils/node-http.tsx

@@ -0,0 +1,47 @@
+import { IncomingMessage, ServerResponse } from "http";
+import { getRelativePart } from "./urls";
+
+class ServerResponseWithBodyChunks extends ServerResponse {
+  bodyChunks: Uint8Array[] = [];
+
+  // note: we actually override this, even though it's private in the parent
+  _send(data: string, encoding: BufferEncoding, callback?: (() => void) | null, byteLength?: number) {
+    if (typeof encoding === "function") {
+      callback = encoding;
+      encoding = "utf-8";
+    }
+    const encodedBuffer = new Uint8Array(Buffer.from(data, encoding));
+    this.bodyChunks.push(encodedBuffer);
+    callback?.();
+  }
+}
+
+export async function createNodeHttpServerDuplex(options: {
+  method: string,
+  originalUrl?: URL,
+  url: URL,
+  headers: Headers,
+  body: Uint8Array,
+}): Promise<[IncomingMessage, ServerResponseWithBodyChunks]> {
+  // See https://github.com/nodejs/node/blob/main/lib/_http_incoming.js
+  // and https://github.com/nodejs/node/blob/main/lib/_http_common.js (particularly the `parserXyz` functions)
+
+  const incomingMessage = new IncomingMessage({
+    encrypted: options.originalUrl?.protocol === "https:",  // trick frameworks into believing this is an HTTPS request
+  } as any);
+  incomingMessage.httpVersionMajor = 1;
+  incomingMessage.httpVersionMinor = 1;
+  incomingMessage.httpVersion = '1.1';
+  incomingMessage.method = options.method;
+  incomingMessage.url = getRelativePart(options.url);
+  (incomingMessage as any).originalUrl = options.originalUrl && getRelativePart(options.originalUrl);  // originalUrl is an extension used by some servers; for example, oidc-provider reads it to construct the paths for the .well-known/openid-configuration
+  const rawHeaders = [...options.headers.entries()].flat();
+  (incomingMessage as any)._addHeaderLines(rawHeaders, rawHeaders.length);
+  incomingMessage.push(Buffer.from(options.body));
+  incomingMessage.complete = true;
+  incomingMessage.push(null);  // to emit end event, see: https://github.com/nodejs/node/blob/4cf6fabce20eb3050c5b543d249e931ea3d3cad5/lib/_http_common.js#L150
+
+  const serverResponse = new ServerResponseWithBodyChunks(incomingMessage);
+
+  return [incomingMessage, serverResponse];
+}

package/src/utils/numbers.tsx

@@ -0,0 +1,82 @@
+const magnitudes = [
+  [1_000, "k"],
+  [1_000, "M"],
+  [1_000, "bn"],
+  [1_000, "bln"],
+  [1_000, "trln"],
+] as const;
+
+export function prettyPrintWithMagnitudes(num: number): string {
+  if (typeof num !== "number") throw new Error("Expected a number");
+  if (Number.isNaN(num)) return "NaN";
+  if (num < 0) return "-" + prettyPrintWithMagnitudes(-num);
+  if (!Number.isFinite(num)) return "∞";
+
+  let current = toFixedMax(num, 1);
+  let lastSuffix = "";
+  for (const [difference, suffix] of magnitudes) {
+    if (+current >= difference) {
+      current = toFixedMax(+current / difference, 1);
+      lastSuffix = suffix;
+    } else {
+      break;
+    }
+  }
+  return current + lastSuffix;
+}
+import.meta.vitest?.test("prettyPrintWithMagnitudes", ({ expect }) => {
+  // Test different magnitudes
+  expect(prettyPrintWithMagnitudes(999)).toBe("999");
+  expect(prettyPrintWithMagnitudes(1000)).toBe("1k");
+  expect(prettyPrintWithMagnitudes(1500)).toBe("1.5k");
+  expect(prettyPrintWithMagnitudes(999499)).toBe("999.5k");
+  expect(prettyPrintWithMagnitudes(999500)).toBe("999.5k");
+  expect(prettyPrintWithMagnitudes(999949)).toBe("999.9k");
+  expect(prettyPrintWithMagnitudes(999950)).toBe("1M");
+  expect(prettyPrintWithMagnitudes(1000000)).toBe("1M");
+  expect(prettyPrintWithMagnitudes(1500000)).toBe("1.5M");
+  expect(prettyPrintWithMagnitudes(1000000000)).toBe("1bn");
+  expect(prettyPrintWithMagnitudes(1500000000)).toBe("1.5bn");
+  expect(prettyPrintWithMagnitudes(1000000000000)).toBe("1bln");
+  expect(prettyPrintWithMagnitudes(1500000000000)).toBe("1.5bln");
+  expect(prettyPrintWithMagnitudes(1000000000000000)).toBe("1trln");
+  expect(prettyPrintWithMagnitudes(1500000000000000)).toBe("1.5trln");
+  // Test small numbers
+  expect(prettyPrintWithMagnitudes(100)).toBe("100");
+  expect(prettyPrintWithMagnitudes(0)).toBe("0");
+  expect(prettyPrintWithMagnitudes(0.5)).toBe("0.5");
+  // Test negative numbers
+  expect(prettyPrintWithMagnitudes(-1000)).toBe("-1k");
+  expect(prettyPrintWithMagnitudes(-1500000)).toBe("-1.5M");
+  // Test special cases
+  expect(prettyPrintWithMagnitudes(NaN)).toBe("NaN");
+  expect(prettyPrintWithMagnitudes(Infinity)).toBe("∞");
+  expect(prettyPrintWithMagnitudes(-Infinity)).toBe("-∞");
+});
+
+export function toFixedMax(num: number, maxDecimals: number): string {
+  return num.toFixed(maxDecimals).replace(/\.?0+$/, "");
+}
+import.meta.vitest?.test("toFixedMax", ({ expect }) => {
+  expect(toFixedMax(1, 2)).toBe("1");
+  expect(toFixedMax(1.2, 2)).toBe("1.2");
+  expect(toFixedMax(1.23, 2)).toBe("1.23");
+  expect(toFixedMax(1.234, 2)).toBe("1.23");
+  expect(toFixedMax(1.0, 2)).toBe("1");
+  expect(toFixedMax(1.20, 2)).toBe("1.2");
+  expect(toFixedMax(0, 2)).toBe("0");
+});
+
+export function numberCompare(a: number, b: number): number {
+  return Math.sign(a - b);
+}
+import.meta.vitest?.test("numberCompare", ({ expect }) => {
+  expect(numberCompare(1, 2)).toBe(-1);
+  expect(numberCompare(2, 1)).toBe(1);
+  expect(numberCompare(1, 1)).toBe(0);
+  expect(numberCompare(0, 0)).toBe(0);
+  expect(numberCompare(-1, -2)).toBe(1);
+  expect(numberCompare(-2, -1)).toBe(-1);
+  expect(numberCompare(-1, 1)).toBe(-1);
+  expect(numberCompare(1, -1)).toBe(1);
+});

package/src/utils/oauth.tsx

@@ -0,0 +1,9 @@
+export const standardProviders = ["google", "github", "microsoft", "spotify", "facebook", "discord", "gitlab", "bitbucket", "linkedin", "apple", "x", "twitch"] as const;
+// No more shared providers should be added except for special cases
+export const sharedProviders = ["google", "github", "microsoft", "spotify"] as const;
+export const allProviders = standardProviders;
+export const publishableClientKeyNotNecessarySentinel = "__stack_public_client__";
+
+export type ProviderType = typeof allProviders[number];
+export type StandardProviderType = typeof standardProviders[number];
+export type SharedProviderType = typeof sharedProviders[number];