@stackframe/stack-shared 2.8.20 → 2.8.22

package/dist/utils/react.d.mts

@@ -1,5 +1,10 @@
-import React, { MutableRefObject } from 'react';
+import React, { SetStateAction } from 'react';
 
+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 forwardRefIfNeeded<T, P = {}>(render: React.ForwardRefRenderFunction<T, P>): React.FC<P & {
     ref?: React.Ref<T>;
 }>;
@@ -10,11 +15,31 @@ declare function getNodeText(node: React.ReactNode): string;
  * 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;
-type InstantStateRef<T> = Readonly<MutableRefObject<T>>;
+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.
+ * 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 useInstantState<T>(initialValue: T): [InstantStateRef<T>, (value: T) => void];
+declare function useRefState<T>(initialValue: T): RefState<T>;
+declare function mapRefState<T, R>(refState: RefState<T>, mapper: (value: T) => R, reverseMapper: (oldT: T, newR: R) => T): RefState<R>;
 declare class NoSuspenseBoundaryError extends Error {
     digest: string;
     reason: string;
@@ -27,4 +52,4 @@ declare class NoSuspenseBoundaryError extends Error {
  */
 declare function suspendIfSsr(caller?: string): void;
 
-export { type InstantStateRef, NoSuspenseBoundaryError, forwardRefIfNeeded, getNodeText, suspend, suspendIfSsr, useInstantState };
+export { NoSuspenseBoundaryError, type ReadonlyRef, type RefState, componentWrapper, forwardRefIfNeeded, getNodeText, mapRef, mapRefState, suspend, suspendIfSsr, useRefState };

package/dist/utils/react.d.ts

@@ -1,5 +1,10 @@
-import React, { MutableRefObject } from 'react';
+import React, { SetStateAction } from 'react';
 
+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 forwardRefIfNeeded<T, P = {}>(render: React.ForwardRefRenderFunction<T, P>): React.FC<P & {
     ref?: React.Ref<T>;
 }>;
@@ -10,11 +15,31 @@ declare function getNodeText(node: React.ReactNode): string;
  * 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;
-type InstantStateRef<T> = Readonly<MutableRefObject<T>>;
+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.
+ * 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 useInstantState<T>(initialValue: T): [InstantStateRef<T>, (value: T) => void];
+declare function useRefState<T>(initialValue: T): RefState<T>;
+declare function mapRefState<T, R>(refState: RefState<T>, mapper: (value: T) => R, reverseMapper: (oldT: T, newR: R) => T): RefState<R>;
 declare class NoSuspenseBoundaryError extends Error {
     digest: string;
     reason: string;
@@ -27,4 +52,4 @@ declare class NoSuspenseBoundaryError extends Error {
  */
 declare function suspendIfSsr(caller?: string): void;
 
-export { type InstantStateRef, NoSuspenseBoundaryError, forwardRefIfNeeded, getNodeText, suspend, suspendIfSsr, useInstantState };
+export { NoSuspenseBoundaryError, type ReadonlyRef, type RefState, componentWrapper, forwardRefIfNeeded, getNodeText, mapRef, mapRefState, suspend, suspendIfSsr, useRefState };

package/dist/utils/react.js

@@ -31,17 +31,25 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var react_exports = {};
 __export(react_exports, {
   NoSuspenseBoundaryError: () => NoSuspenseBoundaryError,
+  componentWrapper: () => componentWrapper,
   forwardRefIfNeeded: () => forwardRefIfNeeded,
   getNodeText: () => getNodeText,
+  mapRef: () => mapRef,
+  mapRefState: () => mapRefState,
   suspend: () => suspend,
   suspendIfSsr: () => suspendIfSsr,
-  useInstantState: () => useInstantState
+  useRefState: () => useRefState
 });
 module.exports = __toCommonJS(react_exports);
 var import_react = __toESM(require("react"));
 var import_env = require("./env.js");
 var import_promises = require("./promises.js");
 var import_strings = require("./strings.js");
+function componentWrapper(displayName, render) {
+  const Component = forwardRefIfNeeded(render);
+  Component.displayName = displayName;
+  return Component;
+}
 function forwardRefIfNeeded(render) {
   const version = import_react.default.version;
   const major = parseInt(version.split(".")[0]);
@@ -70,14 +78,47 @@ function suspend() {
   import_react.default.use((0, import_promises.neverResolve)());
   throw new Error("Somehow a Promise that never resolves was resolved?");
 }
-function useInstantState(initialValue) {
+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];
+    }
+  };
+}
+function useRefState(initialValue) {
   const [, setState] = import_react.default.useState(initialValue);
   const ref = import_react.default.useRef(initialValue);
-  const setValue = import_react.default.useCallback((value) => {
+  const setValue = import_react.default.useCallback((updater) => {
+    const value = typeof updater === "function" ? updater(ref.current) : updater;
     setState(value);
     ref.current = value;
   }, []);
-  return [ref, setValue];
+  const res = import_react.default.useMemo(() => ({
+    current: ref.current,
+    set: setValue
+  }), [ref.current, setValue]);
+  return res;
+}
+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));
+    }
+  };
 }
 var NoSuspenseBoundaryError = class extends Error {
   constructor(options) {
@@ -119,10 +160,13 @@ function suspendIfSsr(caller) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   NoSuspenseBoundaryError,
+  componentWrapper,
   forwardRefIfNeeded,
   getNodeText,
+  mapRef,
+  mapRefState,
   suspend,
   suspendIfSsr,
-  useInstantState
+  useRefState
 });
 //# sourceMappingURL=react.js.map

package/dist/utils/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/react.tsx"],"sourcesContent":["import React, { MutableRefObject } from \"react\";\nimport { isBrowserLike } from \"./env\";\nimport { neverResolve } from \"./promises\";\nimport { deindent } from \"./strings\";\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}\nundefined?.test(\"forwardRefIfNeeded\", ({ expect }) => {\n  // Mock React.version and React.forwardRef\n  const originalVersion = React.version;\n  const originalForwardRef = React.forwardRef;\n\n  try {\n    // Test with React version < 19\n    Object.defineProperty(React, 'version', { value: '18.2.0', writable: true });\n\n    // Create a render function\n    const renderFn = (props: any, ref: any) => null;\n\n    // Call forwardRefIfNeeded\n    const result = forwardRefIfNeeded(renderFn);\n\n    // Verify the function returns something\n    expect(result).toBeDefined();\n\n    // Test with React version >= 19\n    Object.defineProperty(React, 'version', { value: '19.0.0', writable: true });\n\n    // Call forwardRefIfNeeded again with React 19\n    const result19 = forwardRefIfNeeded(renderFn);\n\n    // Verify the function returns something\n    expect(result19).toBeDefined();\n  } finally {\n    // Restore original values\n    Object.defineProperty(React, 'version', { value: originalVersion });\n    React.forwardRef = originalForwardRef;\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}\nundefined?.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  React.use(neverResolve());\n  throw new Error(\"Somehow a Promise that never resolves was resolved?\");\n}\n\nexport type InstantStateRef<T> = Readonly<MutableRefObject<T>>;\n\n/**\n * Like useState, but its value is immediately available.\n */\nexport function useInstantState<T>(initialValue: T): [InstantStateRef<T>, (value: T) => void] {\n  const [, setState] = React.useState(initialValue);\n  const ref = React.useRef(initialValue);\n  const setValue = React.useCallback((value: T) => {\n    setState(value);\n    ref.current = value;\n  }, []);\n  return [ref, setValue];\n}\n\nexport class NoSuspenseBoundaryError extends Error {\n  digest: string;\n  reason: string;\n\n  constructor(options: { caller?: string }) {\n    super(deindent`\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      The fix depends on which of the 3 scenarios caused it:\n      \n      1. 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. 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      3. 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      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}\nundefined?.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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAwC;AACxC,iBAA8B;AAC9B,sBAA6B;AAC7B,qBAAyB;AAElB,SAAS,mBAA8B,QAAoF;AAGhI,QAAM,UAAU,aAAAA,QAAM;AACtB,QAAM,QAAQ,SAAS,QAAQ,MAAM,GAAG,EAAE,CAAC,CAAC;AAC5C,MAAI,QAAQ,IAAI;AACd,WAAO,aAAAA,QAAM,WAAiB,MAAa;AAAA,EAC7C,OAAO;AACL,WAAQ,CAAC,UAAa,OAAO,OAAQ,MAAc,GAAG;AAAA,EACxD;AACF;AAkCO,SAAS,YAAY,MAA+B;AACzD,MAAI,CAAC,UAAU,QAAQ,EAAE,SAAS,OAAO,IAAI,GAAG;AAC9C,WAAO,GAAG,IAAI;AAAA,EAChB;AACA,MAAI,CAAC,MAAM;AACT,WAAO;AAAA,EACT;AACA,MAAI,MAAM,QAAQ,IAAI,GAAG;AACvB,WAAO,KAAK,IAAI,WAAW,EAAE,KAAK,EAAE;AAAA,EACtC;AACA,MAAI,OAAO,SAAS,YAAY,WAAW,MAAM;AAC/C,WAAO,YAAY,KAAK,MAAM,QAAQ;AAAA,EACxC;AACA,QAAM,IAAI,MAAM,sBAAsB,OAAO,IAAI,EAAE;AACrD;AAoDO,SAAS,UAAiB;AAC/B,eAAAA,QAAM,QAAI,8BAAa,CAAC;AACxB,QAAM,IAAI,MAAM,qDAAqD;AACvE;AAOO,SAAS,gBAAmB,cAA2D;AAC5F,QAAM,CAAC,EAAE,QAAQ,IAAI,aAAAA,QAAM,SAAS,YAAY;AAChD,QAAM,MAAM,aAAAA,QAAM,OAAO,YAAY;AACrC,QAAM,WAAW,aAAAA,QAAM,YAAY,CAAC,UAAa;AAC/C,aAAS,KAAK;AACd,QAAI,UAAU;AAAA,EAChB,GAAG,CAAC,CAAC;AACL,SAAO,CAAC,KAAK,QAAQ;AACvB;AAEO,IAAM,0BAAN,cAAsC,MAAM;AAAA,EAIjD,YAAY,SAA8B;AACxC,UAAM;AAAA,QACF,QAAQ,UAAU,gBAAgB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kHASwE,QAAQ,UAAU,gBAAgB;AAAA;AAAA;AAAA,6GAGvC,QAAQ,UAAU,gBAAgB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,KAW1I;AAED,SAAK,OAAO;AACZ,SAAK,SAAS,QAAQ,UAAU;AAIhC,SAAK,SAAS;AAAA,EAChB;AACF;AA0BO,SAAS,aAAa,QAAiB;AAC5C,MAAI,KAAC,0BAAc,GAAG;AACpB,UAAM,IAAI,wBAAwB,EAAE,OAAO,CAAC;AAAA,EAC9C;AACF;","names":["React"]}
+{"version":3,"sources":["../../src/utils/react.tsx"],"sourcesContent":["import React, { SetStateAction } from \"react\";\nimport { isBrowserLike } from \"./env\";\nimport { neverResolve } from \"./promises\";\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\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}\nundefined?.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  React.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): RefState<T> {\n  const [, setState] = React.useState(initialValue);\n  const ref = React.useRef(initialValue);\n  const setValue = React.useCallback((updater: SetStateAction<T>) => {\n    const value: T = typeof updater === \"function\" ? (updater as any)(ref.current) : updater;\n    setState(value);\n    ref.current = value;\n  }, []);\n  const res = React.useMemo(() => ({\n    current: ref.current,\n    set: setValue,\n  }), [ref.current, 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 class NoSuspenseBoundaryError extends Error {\n  digest: string;\n  reason: string;\n\n  constructor(options: { caller?: string }) {\n    super(deindent`\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      The fix depends on which of the 3 scenarios caused it:\n      \n      1. 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. 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      3. 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      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}\nundefined?.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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","names":["React"]}

package/dist/utils/types.d.mts

@@ -1,5 +1,6 @@
 type IsAny<T> = 0 extends (1 & T) ? true : false;
-type isNullish<T> = T extends null | undefined ? true : false;
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsNullish<T> = T extends null | undefined ? true : false;
 type NullishCoalesce<T, U> = T extends null | undefined ? U : T;
 type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
 /**
@@ -20,4 +21,4 @@ type PrettifyType<T> = T extends object ? {
     [K in keyof T]: T[K];
 } & {} : T;
 
-export type { IfAndOnlyIf, IsAny, NullishCoalesce, PrettifyType, UnionToIntersection, isNullish };
+export type { IfAndOnlyIf, IsAny, IsNever, IsNullish, NullishCoalesce, PrettifyType, UnionToIntersection };

package/dist/utils/types.d.ts

@@ -1,5 +1,6 @@
 type IsAny<T> = 0 extends (1 & T) ? true : false;
-type isNullish<T> = T extends null | undefined ? true : false;
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsNullish<T> = T extends null | undefined ? true : false;
 type NullishCoalesce<T, U> = T extends null | undefined ? U : T;
 type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
 /**
@@ -20,4 +21,4 @@ type PrettifyType<T> = T extends object ? {
     [K in keyof T]: T[K];
 } & {} : T;
 
-export type { IfAndOnlyIf, IsAny, NullishCoalesce, PrettifyType, UnionToIntersection, isNullish };
+export type { IfAndOnlyIf, IsAny, IsNever, IsNullish, NullishCoalesce, PrettifyType, UnionToIntersection };

package/dist/utils/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/types.tsx"],"sourcesContent":["export type IsAny<T> = 0 extends (1 & T) ? true : false;\nexport type isNullish<T> = T extends null | undefined ? true : false;\n\nexport type NullishCoalesce<T, U> = T extends null | undefined ? U : T;\n\n// distributive conditional type magic. See: https://stackoverflow.com/a/50375286\nexport type UnionToIntersection<U> =\n  (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never\n\n\n/**\n * A variation of TypeScript's conditionals with slightly different semantics. It is the perfect type for cases where:\n *\n * - If all possible values are contained in `Extends`, then it will be mapped to `Then`.\n * - If all possible values are not contained in `Extends`, then it will be mapped to `Otherwise`.\n * - If some possible values are contained in `Extends` and some are not, then it will be mapped to `Then | Otherwise`.\n *\n * This is different from TypeScript's built-in conditional types (`Value extends Extends ? Then : Otherwise`), which\n * returns `Otherwise` for the third case (causing unsoundness in many real-world cases).\n */\nexport type IfAndOnlyIf<Value, Extends, Then, Otherwise> =\n  | (Value extends Extends ? never : Otherwise)\n  | (Value & Extends extends never ? never : Then);\n\n\n/**\n * Can be used to prettify a type in the IDE; for example, some complicated intersected types can be flattened into a single type.\n */\nexport type PrettifyType<T> = T extends object ? { [K in keyof T]: T[K] } & {} : T;\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../../src/utils/types.tsx"],"sourcesContent":["export type IsAny<T> = 0 extends (1 & T) ? true : false;\nexport type IsNever<T> = [T] extends [never] ? true : false;\nexport type IsNullish<T> = T extends null | undefined ? true : false;\n\nexport type NullishCoalesce<T, U> = T extends null | undefined ? U : T;\n\n// distributive conditional type magic. See: https://stackoverflow.com/a/50375286\nexport type UnionToIntersection<U> =\n  (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never\n\n\n/**\n * A variation of TypeScript's conditionals with slightly different semantics. It is the perfect type for cases where:\n *\n * - If all possible values are contained in `Extends`, then it will be mapped to `Then`.\n * - If all possible values are not contained in `Extends`, then it will be mapped to `Otherwise`.\n * - If some possible values are contained in `Extends` and some are not, then it will be mapped to `Then | Otherwise`.\n *\n * This is different from TypeScript's built-in conditional types (`Value extends Extends ? Then : Otherwise`), which\n * returns `Otherwise` for the third case (causing unsoundness in many real-world cases).\n */\nexport type IfAndOnlyIf<Value, Extends, Then, Otherwise> =\n  | (Value extends Extends ? never : Otherwise)\n  | (Value & Extends extends never ? never : Then);\n\n\n/**\n * Can be used to prettify a type in the IDE; for example, some complicated intersected types can be flattened into a single type.\n */\nexport type PrettifyType<T> = T extends object ? { [K in keyof T]: T[K] } & {} : T;\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackframe/stack-shared",
-  "version": "2.8.20",
+  "version": "2.8.22",
   "files": [
     "README.md",
     "dist",