@hexclave/shared 1.0.3 → 1.0.5

package/src/utils/proxies.tsx

@@ -0,0 +1,212 @@
+import { throwErr } from "./errors";
+import { nicify } from "./strings";
+
+/**
+ * Creates a proxy that throws an error when any property is accessed, function is called,
+ * or any other operation is performed on it.
+ *
+ * Useful for placeholder values that should never actually be used at runtime.
+ */
+export function throwingProxy<T = any>(error: string | Error): T {
+  const doThrow = (): never => {
+    if (typeof error === "string") {
+      throwErr(error);
+    } else {
+      throwErr(error);
+    }
+  };
+
+  return new Proxy(() => {}, {
+    get: doThrow,
+    set: doThrow,
+    has: doThrow,
+    deleteProperty: doThrow,
+    ownKeys: doThrow,
+    getOwnPropertyDescriptor: doThrow,
+    defineProperty: doThrow,
+    getPrototypeOf: doThrow,
+    setPrototypeOf: doThrow,
+    isExtensible: doThrow,
+    preventExtensions: doThrow,
+    apply: doThrow,
+    construct: doThrow,
+  }) as T;
+}
+
+export function logged<T extends object>(name: string, toLog: T, options: {} = {}): T {
+  const proxy = new Proxy(toLog, {
+    get(target, prop, receiver) {
+      const orig = Reflect.get(target, prop, receiver);
+      if (typeof orig === "function") {
+        return function (this: any, ...args: any[]) {
+          const success = (v: any, isPromise: boolean) => console.debug(`logged(...): Called ${name}.${String(prop)}(${args.map(a => nicify(a)).join(", ")}) => ${isPromise ? "Promise<" : ""}${nicify(result)}${isPromise ? ">" : ""}`, { this: this, args, promise: isPromise ? result : false, result: v, trace: new Error() });
+          const error = (e: any, isPromise: boolean) => console.debug(`logged(...): Error in ${name}.${String(prop)}(${args.map(a => nicify(a)).join(", ")})`, { this: this, args, promise: isPromise ? result : false, error: e, trace: new Error() });
+
+          let result: unknown;
+          try {
+            result = orig.apply(this, args);
+          } catch (e) {
+            error(e, false);
+            throw e;
+          }
+          if (result instanceof Promise) {
+            result.then((v) => success(v, true)).catch((e) => error(e, true));
+          } else {
+            success(result, false);
+          }
+          return result;
+        };
+      }
+      return orig;
+    },
+    set(target, prop, value) {
+      console.log(`Setting ${name}.${String(prop)} to ${value}`);
+      return Reflect.set(target, prop, value);
+    },
+    apply(target, thisArg, args) {
+      console.log(`Calling ${name}(${JSON.stringify(args).slice(1, -1)})`);
+      return Reflect.apply(target as any, thisArg, args);
+    },
+    construct(target, args, newTarget) {
+      console.log(`Constructing ${name}(${JSON.stringify(args).slice(1, -1)})`);
+      return Reflect.construct(target as any, args, newTarget);
+    },
+    defineProperty(target, prop, descriptor) {
+      console.log(`Defining ${name}.${String(prop)} as ${JSON.stringify(descriptor)}`);
+      return Reflect.defineProperty(target, prop, descriptor);
+    },
+    deleteProperty(target, prop) {
+      console.log(`Deleting ${name}.${String(prop)}`);
+      return Reflect.deleteProperty(target, prop);
+    },
+    setPrototypeOf(target, prototype) {
+      console.log(`Setting prototype of ${name} to ${prototype}`);
+      return Reflect.setPrototypeOf(target, prototype);
+    },
+    preventExtensions(target) {
+      console.log(`Preventing extensions of ${name}`);
+      return Reflect.preventExtensions(target);
+    },
+  });
+  return proxy;
+}
+
+export function createLazyProxy<FactoryResult>(factory: () => FactoryResult): FactoryResult {
+  let cache: FactoryResult | undefined = undefined;
+  let initialized: boolean = false;
+
+  function initializeIfNeeded() {
+    if (!initialized) {
+      cache = factory();
+      initialized = true;
+    }
+    return cache!;
+  }
+
+  return new Proxy({}, {
+    get(target, prop, receiver) {
+      const instance = initializeIfNeeded();
+      return Reflect.get(instance, prop, receiver);
+    },
+    set(target, prop, value, receiver) {
+      const instance = initializeIfNeeded();
+      return Reflect.set(instance, prop, value, receiver);
+    },
+    has(target, prop) {
+      const instance = initializeIfNeeded();
+      return Reflect.has(instance, prop);
+    },
+    deleteProperty(target, prop) {
+      const instance = initializeIfNeeded();
+      return Reflect.deleteProperty(instance, prop);
+    },
+    ownKeys(target) {
+      const instance = initializeIfNeeded();
+      return Reflect.ownKeys(instance);
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      const instance = initializeIfNeeded();
+      return Reflect.getOwnPropertyDescriptor(instance, prop);
+    },
+    defineProperty(target, prop, descriptor) {
+      const instance = initializeIfNeeded();
+      return Reflect.defineProperty(instance, prop, descriptor);
+    },
+    getPrototypeOf(target) {
+      const instance = initializeIfNeeded();
+      return Reflect.getPrototypeOf(instance);
+    },
+    setPrototypeOf(target, proto) {
+      const instance = initializeIfNeeded();
+      return Reflect.setPrototypeOf(instance, proto);
+    },
+    isExtensible(target) {
+      const instance = initializeIfNeeded();
+      return Reflect.isExtensible(instance);
+    },
+    preventExtensions(target) {
+      const instance = initializeIfNeeded();
+      return Reflect.preventExtensions(instance);
+    },
+    apply(target, thisArg, argumentsList) {
+      const instance = initializeIfNeeded();
+      return Reflect.apply(instance as any, thisArg, argumentsList);
+    },
+    construct(target, argumentsList, newTarget) {
+      const instance = initializeIfNeeded();
+      return Reflect.construct(instance as any, argumentsList, newTarget);
+    }
+  }) as FactoryResult;
+}
+import.meta.vitest?.test("createLazyProxy", ({ expect }) => {
+  // Test with a simple object factory
+  let factoryCallCount = 0;
+  const createObject = () => {
+    factoryCallCount++;
+    return { value: 42, method: () => "hello" };
+  };
+
+  const proxy = createLazyProxy(createObject);
+
+  // Factory should not be called until property is accessed
+  expect(factoryCallCount).toBe(0);
+
+  // Accessing a property should initialize the object
+  expect(proxy.value).toBe(42);
+  expect(factoryCallCount).toBe(1);
+
+  // Accessing another property should not call factory again
+  expect(proxy.method()).toBe("hello");
+  expect(factoryCallCount).toBe(1);
+
+  // Test with property setting
+  proxy.value = 100;
+  expect(proxy.value).toBe(100);
+  expect(factoryCallCount).toBe(1);
+
+  // Test with a class factory
+  let classFactoryCallCount = 0;
+  class TestClass {
+    constructor() {
+      classFactoryCallCount++;
+    }
+
+    getValue() {
+      return "class value";
+    }
+  }
+
+  const classFactory = () => new TestClass();
+  const classProxy = createLazyProxy(classFactory);
+
+  // Factory should not be called until method is accessed
+  expect(classFactoryCallCount).toBe(0);
+
+  // Accessing a method should initialize the object
+  expect(classProxy.getValue()).toBe("class value");
+  expect(classFactoryCallCount).toBe(1);
+
+  // Accessing the method again should not call factory again
+  expect(classProxy.getValue()).toBe("class value");
+  expect(classFactoryCallCount).toBe(1);
+});

package/src/utils/react.tsx

@@ -0,0 +1,308 @@
+import React, { SetStateAction } from "react";
+import { isBrowserLike } from "./env";
+import { neverResolve, runAsynchronously } from "./promises";
+import { AsyncResult } from "./results";
+import { ensureMonkeyPatch, NO_SUSPENSE_BOUNDARY_ERROR_SENTINEL } from "./monkey-patch";
+import { deindent } from "./strings";
+
+export function componentWrapper<
+  C extends React.ComponentType<any> | keyof React.JSX.IntrinsicElements,
+  ExtraProps extends {} = {}
+>(displayName: string, render: React.ForwardRefRenderFunction<RefFromComponent<C>, React.ComponentPropsWithRef<C> & ExtraProps>) {
+  const Component = forwardRefIfNeeded(render);
+  Component.displayName = displayName;
+  return Component;
+}
+type RefFromComponent<C extends React.ComponentType<any> | keyof React.JSX.IntrinsicElements> = NonNullable<RefFromComponentDistCond<React.ComponentPropsWithRef<C>["ref"]>>;
+type RefFromComponentDistCond<A> = A extends React.RefObject<infer T> ? T : never;  // distributive conditional type; see https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
+
+const react18PromiseCache = new WeakMap<Promise<unknown>, AsyncResult<unknown, unknown>>();
+export function use<T>(promise: Promise<T>): T {
+  if ("use" in React) {
+    return React.use(promise);
+  } else {
+    if (react18PromiseCache.has(promise)) {
+      const result = react18PromiseCache.get(promise)!;
+      if (result.status === "pending") {
+        throw promise;
+      } else if (result.status === "ok") {
+        return result.data as T;
+      } else {
+        throw result.error;
+      }
+    } else {
+      react18PromiseCache.set(promise, { "status": "pending", progress: undefined });
+      runAsynchronously(async () => {
+        try {
+          const res = await promise;
+          react18PromiseCache.set(promise, { "status": "ok", data: res });
+        } catch (e) {
+          react18PromiseCache.set(promise, { "status": "error", error: e });
+        }
+      });
+      throw promise;
+    }
+  }
+}
+
+export function forwardRefIfNeeded<T, P = {}>(render: React.ForwardRefRenderFunction<T, P>): React.FC<P & { ref?: React.Ref<T> }> {
+  // TODO: when we drop support for react 18, remove this
+
+  const version = React.version;
+  const major = parseInt(version.split(".")[0]);
+  if (major < 19) {
+    return React.forwardRef<T, P>(render as any) as any;
+  } else {
+    return ((props: P) => render(props, (props as any).ref)) as any;
+  }
+}
+
+export function getNodeText(node: React.ReactNode): string {
+  if (["number", "string"].includes(typeof node)) {
+    return `${node}`;
+  }
+  if (!node) {
+    return "";
+  }
+  if (Array.isArray(node)) {
+    return node.map(getNodeText).join("");
+  }
+  if (React.isValidElement<{ children?: React.ReactNode }>(node)) {
+    return getNodeText(node.props.children);
+  }
+  throw new Error(`Unknown node type: ${typeof node}`);
+}
+import.meta.vitest?.test("getNodeText", ({ expect }) => {
+  // Test with string
+  expect(getNodeText("hello")).toBe("hello");
+
+  // Test with number
+  expect(getNodeText(42)).toBe("42");
+
+  // Test with null/undefined
+  expect(getNodeText(null)).toBe("");
+  expect(getNodeText(undefined)).toBe("");
+
+  // Test with array
+  expect(getNodeText(["hello", " ", "world"])).toBe("hello world");
+  expect(getNodeText([1, 2, 3])).toBe("123");
+
+  // Test with mixed array
+  expect(getNodeText(["hello", 42, null])).toBe("hello42");
+
+  // Test with React element
+  const mockElement = React.createElement("span", null, "child text");
+  expect(getNodeText(mockElement)).toBe("child text");
+
+  // Test with nested React elements
+  const nestedElement = React.createElement("div", null, React.createElement("span", null, "nested text"));
+  expect(getNodeText(nestedElement)).toBe("nested text");
+
+  // Test with array of React elements
+  const arrayOfElements = [
+    React.createElement("span", null, "first"),
+    React.createElement("span", null, "second"),
+  ];
+  expect(getNodeText(arrayOfElements)).toBe("firstsecond");
+});
+
+/**
+ * Suspends the currently rendered component indefinitely. Will not unsuspend unless the component rerenders.
+ *
+ * You can use this to translate older query- or AsyncResult-based code to new the Suspense system, for example: `if (query.isLoading) suspend();`
+ */
+export function suspend(): never {
+  use(neverResolve());
+  throw new Error("Somehow a Promise that never resolves was resolved?");
+}
+
+export function mapRef<T, R>(ref: ReadonlyRef<T>, mapper: (value: T) => R): ReadonlyRef<R> {
+  let last: [T, R] | null = null;
+  return {
+    get current() {
+      const input = ref.current;
+      if (last === null || input !== last[0]) {
+        last = [input, mapper(input)];
+      }
+      return last[1];
+    },
+  };
+}
+
+export type ReadonlyRef<T> = {
+  readonly current: T,
+};
+
+export type RefState<T> = ReadonlyRef<T> & {
+  set: (updater: SetStateAction<T>) => void,
+};
+
+/**
+ * Like useState, but its value is immediately available on refState.current after being set.
+ *
+ * Like useRef, but setting the value will cause a rerender.
+ *
+ * Note that useRefState returns a new object every time a rerender happens due to a value change, which is intentional
+ * as it allows you to specify it in a dependency array like this:
+ *
+ * ```tsx
+ * useEffect(() => {
+ *   // do something with refState.current
+ * }, [refState]);  // instead of refState.current
+ * ```
+ *
+ * If you don't want this, you can wrap the result in a useMemo call.
+ */
+export function useRefState<T>(initialValue: T | (() => T)): RefState<T> {
+  // Support lazy initialization like React.useState does: if initialValue is a function,
+  // call it once to get the actual initial value (React.useRef does NOT do this automatically).
+  const lazyInitRef = React.useRef<{ v: T } | null>(null);
+  if (lazyInitRef.current === null) {
+    lazyInitRef.current = {
+      v: typeof initialValue === "function" ? (initialValue as () => T)() : initialValue,
+    };
+  }
+  const resolvedInitialValue = lazyInitRef.current.v;
+  const [, setState] = React.useState<T>(() => resolvedInitialValue);
+  const ref = React.useRef(resolvedInitialValue);
+  const setValue = React.useCallback((updater: SetStateAction<T>) => {
+    const value: T = typeof updater === "function" ? (updater as any)(ref.current) : updater;
+    ref.current = value;
+    setState(value);
+  }, []);
+  const res = React.useMemo(() => ({
+    get current() {
+      return ref.current;
+    },
+    set: setValue,
+  }), [setValue]);
+  return res;
+}
+
+export function mapRefState<T, R>(refState: RefState<T>, mapper: (value: T) => R, reverseMapper: (oldT: T, newR: R) => T): RefState<R> {
+  let last: [T, R] | null = null;
+  return {
+    get current() {
+      const input = refState.current;
+      if (last === null || input !== last[0]) {
+        last = [input, mapper(input)];
+      }
+      return last[1];
+    },
+    set(updater: SetStateAction<R>) {
+      const value: R = typeof updater === "function" ? (updater as any)(this.current) : updater;
+      refState.set(reverseMapper(refState.current, value));
+    },
+  };
+}
+
+export function useQueryState(key: string, defaultValue?: string) {
+  const getValue = () => new URLSearchParams(window.location.search).get(key) ?? defaultValue ?? null;
+
+  const [value, setValue] = React.useState(getValue);
+
+  React.useEffect(() => {
+    const onPopState = () => setValue(getValue());
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, []);
+
+  const update = (next: string | null) => {
+    const params = new URLSearchParams(window.location.search);
+    if (next !== null) {
+      params.set(key, next);
+    } else {
+      params.delete(key);
+    }
+    const newUrl = params.toString()
+      ? `${window.location.pathname}?${params.toString()}`
+      : window.location.pathname;
+    window.history.pushState(null, "", newUrl);
+    setValue(next);
+  };
+
+  return [value, update] as const;
+}
+
+export function shouldRethrowRenderingError(error: unknown): boolean {
+  return !!error && typeof error === "object" && "digest" in error && error.digest === "BAILOUT_TO_CLIENT_SIDE_RENDERING";
+}
+
+export class NoSuspenseBoundaryError extends Error {
+  digest: string;
+  reason: string;
+  __noSuspenseBoundarySentinel = NO_SUSPENSE_BOUNDARY_ERROR_SENTINEL;
+
+  constructor(options: { caller?: string }) {
+    ensureMonkeyPatch();
+
+    super(deindent`
+      Suspense boundary not found! Read the error message below carefully (or paste it into your AI agent).
+
+      ${options.caller ?? "This code path"} attempted to display a loading indicator, but didn't find a Suspense boundary above it. Please read the error message below carefully.
+      
+      There are several potential causes:
+      
+      1. [Next.js] You are missing a loading.tsx file in your app directory. Fix it by adding a loading.tsx file in your app directory.
+
+      2. [React] You are missing a <Suspense> boundary in your component. Fix it by wrapping your component (or the entire app) in a <Suspense> component.
+
+      3. [Next.js] The component is rendered in the root (outermost) layout.tsx or template.tsx file. Next.js does not wrap those files in a Suspense boundary, even if there is a loading.tsx file in the same folder. To fix it, wrap your layout inside a route group like this:
+
+        - app
+        - - layout.tsx  // contains <html> and <body>, alongside providers and other components that don't need ${options.caller ?? "this code path"}
+        - - loading.tsx  // required for suspense
+        - - (main)
+        - - - layout.tsx  // contains the main layout of your app, like a sidebar or a header, and can use ${options.caller ?? "this code path"}
+        - - - route.tsx  // your actual main page
+        - - - the rest of your app
+
+        For more information on this approach, see Next's documentation on route groups: https://nextjs.org/docs/app/building-your-application/routing/route-groups
+      
+      4. You caught this error with try-catch or a custom error boundary. Fix this by rethrowing the error or not catching it in the first place.
+
+      5. Your version of Hexclave is too old. Upgrade to the latest version to see if that fixes the issue.
+
+      See: https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout
+
+      More information on SSR and Suspense boundaries: https://react.dev/reference/react/Suspense#providing-a-fallback-for-server-errors-and-client-only-content
+    `);
+
+    this.name = "NoSuspenseBoundaryError";
+    this.reason = options.caller ?? "suspendIfSsr()";
+
+    // set the digest so nextjs doesn't log the error
+    // https://github.com/vercel/next.js/blob/d01d6d9c35a8c2725b3d74c1402ab76d4779a6cf/packages/next/src/shared/lib/lazy-dynamic/bailout-to-csr.ts#L14
+    this.digest = "BAILOUT_TO_CLIENT_SIDE_RENDERING";
+  }
+}
+import.meta.vitest?.test("NoSuspenseBoundaryError", ({ expect }) => {
+  // Test with default options
+  const defaultError = new NoSuspenseBoundaryError({});
+  expect(defaultError.name).toBe("NoSuspenseBoundaryError");
+  expect(defaultError.reason).toBe("suspendIfSsr()");
+  expect(defaultError.digest).toBe("BAILOUT_TO_CLIENT_SIDE_RENDERING");
+  expect(defaultError.message).toContain("This code path attempted to display a loading indicator");
+
+  // Test with custom caller
+  const customError = new NoSuspenseBoundaryError({ caller: "CustomComponent" });
+  expect(customError.name).toBe("NoSuspenseBoundaryError");
+  expect(customError.reason).toBe("CustomComponent");
+  expect(customError.digest).toBe("BAILOUT_TO_CLIENT_SIDE_RENDERING");
+  expect(customError.message).toContain("CustomComponent attempted to display a loading indicator");
+
+  // Verify error message contains all the necessary information
+  expect(customError.message).toContain("loading.tsx");
+  expect(customError.message).toContain("route groups");
+  expect(customError.message).toContain("https://nextjs.org/docs/messages/missing-suspense-with-csr-bailout");
+});
+
+
+/**
+ * Use this in a component or a hook to disable SSR. Should be wrapped in a Suspense boundary, or it will throw an error.
+ */
+export function suspendIfSsr(caller?: string) {
+  if (!isBrowserLike()) {
+    throw new NoSuspenseBoundaryError({ caller });
+  }
+}