@hexclave/shared 1.0.0

package/dist/esm/utils/proxies.js

@@ -0,0 +1,197 @@
+import { throwErr } from "./errors.js";
+import { nicify } from "./strings.js";
+
+//#region src/utils/proxies.tsx
+/**
+* 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.
+*/
+function throwingProxy(error) {
+	const doThrow = () => {
+		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
+	});
+}
+function logged(name, toLog, options = {}) {
+	return new Proxy(toLog, {
+		get(target, prop, receiver) {
+			const orig = Reflect.get(target, prop, receiver);
+			if (typeof orig === "function") return function(...args) {
+				const success = (v, isPromise) => 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: /* @__PURE__ */ new Error()
+				});
+				const error = (e, isPromise) => console.debug(`logged(...): Error in ${name}.${String(prop)}(${args.map((a) => nicify(a)).join(", ")})`, {
+					this: this,
+					args,
+					promise: isPromise ? result : false,
+					error: e,
+					trace: /* @__PURE__ */ new Error()
+				});
+				let result;
+				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, thisArg, args);
+		},
+		construct(target, args, newTarget) {
+			console.log(`Constructing ${name}(${JSON.stringify(args).slice(1, -1)})`);
+			return Reflect.construct(target, 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);
+		}
+	});
+}
+function createLazyProxy(factory) {
+	let cache = void 0;
+	let initialized = 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, thisArg, argumentsList);
+		},
+		construct(target, argumentsList, newTarget) {
+			const instance = initializeIfNeeded();
+			return Reflect.construct(instance, argumentsList, newTarget);
+		}
+	});
+}
+(void 0)?.test("createLazyProxy", ({ expect }) => {
+	let factoryCallCount = 0;
+	const createObject = () => {
+		factoryCallCount++;
+		return {
+			value: 42,
+			method: () => "hello"
+		};
+	};
+	const proxy = createLazyProxy(createObject);
+	expect(factoryCallCount).toBe(0);
+	expect(proxy.value).toBe(42);
+	expect(factoryCallCount).toBe(1);
+	expect(proxy.method()).toBe("hello");
+	expect(factoryCallCount).toBe(1);
+	proxy.value = 100;
+	expect(proxy.value).toBe(100);
+	expect(factoryCallCount).toBe(1);
+	let classFactoryCallCount = 0;
+	class TestClass {
+		constructor() {
+			classFactoryCallCount++;
+		}
+		getValue() {
+			return "class value";
+		}
+	}
+	const classFactory = () => new TestClass();
+	const classProxy = createLazyProxy(classFactory);
+	expect(classFactoryCallCount).toBe(0);
+	expect(classProxy.getValue()).toBe("class value");
+	expect(classFactoryCallCount).toBe(1);
+	expect(classProxy.getValue()).toBe("class value");
+	expect(classFactoryCallCount).toBe(1);
+});
+
+//#endregion
+export { createLazyProxy, logged, throwingProxy };
+//# sourceMappingURL=proxies.js.map

package/dist/esm/utils/proxies.js.map

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

package/dist/esm/utils/react.d.ts

@@ -0,0 +1,61 @@
+import React, { SetStateAction } from "react";
+
+//#region src/utils/react.d.ts
+declare function componentWrapper<C extends React.ComponentType<any> | keyof React.JSX.IntrinsicElements, ExtraProps extends {} = {}>(displayName: string, render: React.ForwardRefRenderFunction<RefFromComponent<C>, React.ComponentPropsWithRef<C> & ExtraProps>): React.FC<React.ComponentPropsWithRef<C> & ExtraProps & {
+  ref?: React.Ref<RefFromComponent<C>> | undefined;
+}>;
+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;
+declare function use<T>(promise: Promise<T>): T;
+declare function forwardRefIfNeeded<T, P = {}>(render: React.ForwardRefRenderFunction<T, P>): React.FC<P & {
+  ref?: React.Ref<T>;
+}>;
+declare function getNodeText(node: React.ReactNode): string;
+/**
+ * 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();`
+ */
+declare function suspend(): never;
+declare function mapRef<T, R>(ref: ReadonlyRef<T>, mapper: (value: T) => R): ReadonlyRef<R>;
+type ReadonlyRef<T> = {
+  readonly current: T;
+};
+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.
+ */
+declare function useRefState<T>(initialValue: T | (() => T)): RefState<T>;
+declare function mapRefState<T, R>(refState: RefState<T>, mapper: (value: T) => R, reverseMapper: (oldT: T, newR: R) => T): RefState<R>;
+declare function useQueryState(key: string, defaultValue?: string): readonly [string | null, (next: string | null) => void];
+declare function shouldRethrowRenderingError(error: unknown): boolean;
+declare class NoSuspenseBoundaryError extends Error {
+  digest: string;
+  reason: string;
+  __noSuspenseBoundarySentinel: string;
+  constructor(options: {
+    caller?: string;
+  });
+}
+/**
+ * Use this in a component or a hook to disable SSR. Should be wrapped in a Suspense boundary, or it will throw an error.
+ */
+declare function suspendIfSsr(caller?: string): void;
+//#endregion
+export { NoSuspenseBoundaryError, ReadonlyRef, RefState, componentWrapper, forwardRefIfNeeded, getNodeText, mapRef, mapRefState, shouldRethrowRenderingError, suspend, suspendIfSsr, use, useQueryState, useRefState };
+//# sourceMappingURL=react.d.ts.map

package/dist/esm/utils/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","names":[],"sources":["../../../src/utils/react.tsx"],"mappings":";;;iBAOgB,gBAAA,WACJ,KAAA,CAAM,aAAA,cAA2B,KAAA,CAAM,GAAA,CAAI,iBAAA,6BAAA,CAErD,WAAA,UAAqB,MAAA,EAAQ,KAAA,CAAM,wBAAA,CAAyB,gBAAA,CAAiB,CAAA,GAAI,KAAA,CAAM,qBAAA,CAAsB,CAAA,IAAK,UAAA,IAAW,KAAA,CAAA,EAAA,CAAA,KAAA,CAAA,qBAAA,CAAA,CAAA,IAAA,UAAA;;;KAK1H,gBAAA,WAA2B,KAAA,CAAM,aAAA,cAA2B,KAAA,CAAM,GAAA,CAAI,iBAAA,IAAqB,WAAA,CAAY,wBAAA,CAAyB,KAAA,CAAM,qBAAA,CAAsB,CAAA;AAAA,KAC5J,wBAAA,MAA8B,CAAA,SAAU,KAAA,CAAM,SAAA,YAAqB,CAAA;AAAA,iBAGxD,GAAA,GAAA,CAAO,OAAA,EAAS,OAAA,CAAQ,CAAA,IAAK,CAAA;AAAA,iBA4B7B,kBAAA,WAAA,CAA8B,MAAA,EAAQ,KAAA,CAAM,wBAAA,CAAyB,CAAA,EAAG,CAAA,IAAK,KAAA,CAAM,EAAA,CAAG,CAAA;EAAM,GAAA,GAAM,KAAA,CAAM,GAAA,CAAI,CAAA;AAAA;AAAA,iBAY5G,WAAA,CAAY,IAAA,EAAM,KAAA,CAAM,SAAA;;;;;;iBAkExB,OAAA,CAAA;AAAA,iBAKA,MAAA,MAAA,CAAa,GAAA,EAAK,WAAA,CAAY,CAAA,GAAI,MAAA,GAAS,KAAA,EAAO,CAAA,KAAM,CAAA,GAAI,WAAA,CAAY,CAAA;AAAA,KAa5E,WAAA;EAAA,SACD,OAAA,EAAS,CAAA;AAAA;AAAA,KAGR,QAAA,MAAc,WAAA,CAAY,CAAA;EACpC,GAAA,GAAM,OAAA,EAAS,cAAA,CAAe,CAAA;AAAA;;;;;;;;;;;;;;;;;iBAmBhB,WAAA,GAAA,CAAe,YAAA,EAAc,CAAA,UAAW,CAAA,IAAK,QAAA,CAAS,CAAA;AAAA,iBA0BtD,WAAA,MAAA,CAAkB,QAAA,EAAU,QAAA,CAAS,CAAA,GAAI,MAAA,GAAS,KAAA,EAAO,CAAA,KAAM,CAAA,EAAG,aAAA,GAAgB,IAAA,EAAM,CAAA,EAAG,IAAA,EAAM,CAAA,KAAM,CAAA,GAAI,QAAA,CAAS,CAAA;AAAA,iBAiBpH,aAAA,CAAc,GAAA,UAAa,YAAA,sCAAqB,IAAA;AAAA,iBA4BhD,2BAAA,CAA4B,KAAA;AAAA,cAI/B,uBAAA,SAAgC,KAAA;EAC3C,MAAA;EACA,MAAA;EACA,4BAAA;cAEY,OAAA;IAAW,MAAA;EAAA;AAAA;;AAzOxB;;iBA6Se,YAAA,CAAa,MAAA"}

package/dist/esm/utils/react.js

@@ -0,0 +1,229 @@
+import React from "react";
+import { isBrowserLike } from "./env.js";
+import { neverResolve, runAsynchronously } from "./promises.js";
+import { deindent } from "./strings.js";
+import { NO_SUSPENSE_BOUNDARY_ERROR_SENTINEL, ensureMonkeyPatch } from "./monkey-patch.js";
+
+//#region src/utils/react.tsx
+function componentWrapper(displayName, render) {
+	const Component = forwardRefIfNeeded(render);
+	Component.displayName = displayName;
+	return Component;
+}
+const react18PromiseCache = /* @__PURE__ */ new WeakMap();
+function use(promise) {
+	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;
+		else throw result.error;
+	} else {
+		react18PromiseCache.set(promise, {
+			"status": "pending",
+			progress: void 0
+		});
+		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;
+	}
+}
+function forwardRefIfNeeded(render) {
+	const version = React.version;
+	if (parseInt(version.split(".")[0]) < 19) return React.forwardRef(render);
+	else return ((props) => render(props, props.ref));
+}
+function getNodeText(node) {
+	if (["number", "string"].includes(typeof node)) return `${node}`;
+	if (!node) return "";
+	if (Array.isArray(node)) return node.map(getNodeText).join("");
+	if (typeof node === "object" && "props" in node) return getNodeText(node.props.children);
+	throw new Error(`Unknown node type: ${typeof node}`);
+}
+(void 0)?.test("getNodeText", ({ expect }) => {
+	expect(getNodeText("hello")).toBe("hello");
+	expect(getNodeText(42)).toBe("42");
+	expect(getNodeText(null)).toBe("");
+	expect(getNodeText(void 0)).toBe("");
+	expect(getNodeText([
+		"hello",
+		" ",
+		"world"
+	])).toBe("hello world");
+	expect(getNodeText([
+		1,
+		2,
+		3
+	])).toBe("123");
+	expect(getNodeText([
+		"hello",
+		42,
+		null
+	])).toBe("hello42");
+	expect(getNodeText({ props: { children: "child text" } })).toBe("child text");
+	expect(getNodeText({ props: { children: { props: { children: "nested text" } } } })).toBe("nested text");
+	expect(getNodeText([{ props: { children: "first" } }, { props: { children: "second" } }])).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();`
+*/
+function suspend() {
+	use(neverResolve());
+	throw new Error("Somehow a Promise that never resolves was resolved?");
+}
+function mapRef(ref, mapper) {
+	let last = null;
+	return { get current() {
+		const input = ref.current;
+		if (last === null || input !== last[0]) last = [input, mapper(input)];
+		return last[1];
+	} };
+}
+/**
+* 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.
+*/
+function useRefState(initialValue) {
+	const lazyInitRef = React.useRef(null);
+	if (lazyInitRef.current === null) lazyInitRef.current = { v: typeof initialValue === "function" ? initialValue() : initialValue };
+	const resolvedInitialValue = lazyInitRef.current.v;
+	const [, setState] = React.useState(() => resolvedInitialValue);
+	const ref = React.useRef(resolvedInitialValue);
+	const setValue = React.useCallback((updater) => {
+		const value = typeof updater === "function" ? updater(ref.current) : updater;
+		ref.current = value;
+		setState(value);
+	}, []);
+	return React.useMemo(() => ({
+		get current() {
+			return ref.current;
+		},
+		set: setValue
+	}), [setValue]);
+}
+function mapRefState(refState, mapper, reverseMapper) {
+	let last = null;
+	return {
+		get current() {
+			const input = refState.current;
+			if (last === null || input !== last[0]) last = [input, mapper(input)];
+			return last[1];
+		},
+		set(updater) {
+			const value = typeof updater === "function" ? updater(this.current) : updater;
+			refState.set(reverseMapper(refState.current, value));
+		}
+	};
+}
+function useQueryState(key, defaultValue) {
+	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) => {
+		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];
+}
+function shouldRethrowRenderingError(error) {
+	return !!error && typeof error === "object" && "digest" in error && error.digest === "BAILOUT_TO_CLIENT_SIDE_RENDERING";
+}
+var NoSuspenseBoundaryError = class extends Error {
+	constructor(options) {
+		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.__noSuspenseBoundarySentinel = NO_SUSPENSE_BOUNDARY_ERROR_SENTINEL;
+		this.name = "NoSuspenseBoundaryError";
+		this.reason = options.caller ?? "suspendIfSsr()";
+		this.digest = "BAILOUT_TO_CLIENT_SIDE_RENDERING";
+	}
+};
+(void 0)?.test("NoSuspenseBoundaryError", ({ expect }) => {
+	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");
+	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");
+	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.
+*/
+function suspendIfSsr(caller) {
+	if (!isBrowserLike()) throw new NoSuspenseBoundaryError({ caller });
+}
+
+//#endregion
+export { NoSuspenseBoundaryError, componentWrapper, forwardRefIfNeeded, getNodeText, mapRef, mapRefState, shouldRethrowRenderingError, suspend, suspendIfSsr, use, useQueryState, useRefState };
+//# sourceMappingURL=react.js.map

package/dist/esm/utils/react.js.map

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

package/dist/esm/utils/redirect-urls.d.ts

@@ -0,0 +1,30 @@
+//#region src/utils/redirect-urls.d.ts
+type TrustedDomainConfig = {
+  allowLocalhost?: boolean;
+  trustedDomains: readonly (string | null | undefined)[];
+};
+declare function getHostedHandlerTrustedDomain(options: {
+  projectId: string;
+  hostedHandlerDomainSuffix?: string;
+  hostedHandlerUrlTemplate?: string;
+  stackPortPrefix?: string;
+}): string;
+declare function getHostedHandlerUrlFromConfig(options: {
+  projectId: string;
+  hostedPath: string;
+  hostedHandlerDomainSuffix?: string;
+  hostedHandlerUrlTemplate?: string;
+  stackPortPrefix?: string;
+}): string;
+declare function getImplicitlyTrustedDomainsForProject(options: {
+  projectId: string;
+  hostedHandlerDomainSuffix?: string;
+  hostedHandlerUrlTemplate?: string;
+  stackPortPrefix?: string;
+}): string[];
+declare function isAcceptedNativeAppUrl(urlOrString: string): boolean;
+declare function validateRedirectUrl(urlOrString: string | URL, config: TrustedDomainConfig): boolean;
+declare function getTrustedParentDomain(currentDomain: string, trustedDomains: readonly (string | null | undefined)[]): string | null;
+//#endregion
+export { getHostedHandlerTrustedDomain, getHostedHandlerUrlFromConfig, getImplicitlyTrustedDomainsForProject, getTrustedParentDomain, isAcceptedNativeAppUrl, validateRedirectUrl };
+//# sourceMappingURL=redirect-urls.d.ts.map

package/dist/esm/utils/redirect-urls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redirect-urls.d.ts","names":[],"sources":["../../../src/utils/redirect-urls.tsx"],"mappings":";KAGK,mBAAA;EACH,cAAA;EACA,cAAA;AAAA;AAAA,iBAgCc,6BAAA,CAA8B,OAAA;EAC5C,SAAA;EACA,yBAAA;EACA,wBAAA;EACA,eAAA;AAAA;AAAA,iBAQc,6BAAA,CAA8B,OAAA;EAC5C,SAAA;EACA,UAAA;EACA,yBAAA;EACA,wBAAA;EACA,eAAA;AAAA;AAAA,iBA0Bc,qCAAA,CAAsC,OAAA;EACpD,SAAA;EACA,yBAAA;EACA,wBAAA;EACA,eAAA;AAAA;AAAA,iBA0Ec,sBAAA,CAAuB,WAAA;AAAA,iBAOvB,mBAAA,CACd,WAAA,WAAsB,GAAA,EACtB,MAAA,EAAQ,mBAAA;AAAA,iBAYM,sBAAA,CAAuB,aAAA,UAAuB,cAAA"}