@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/react/tests/strict-mode.test.tsx

@@ -0,0 +1,288 @@
+/**
+ * The provider owns its client's life. React's development double-mount
+ * (`StrictMode` mounts, unmounts and mounts again at once) must not kill a
+ * client that is in use, and a real unmount must dispose it exactly once.
+ */
+import type { Client } from "@ic-reactor/core"
+import { act, render } from "@testing-library/react"
+import * as React from "react"
+import {
+  StrictMode,
+  useEffect,
+  type ComponentType,
+  type ReactNode,
+} from "react"
+import { describe, expect, it, vi } from "vitest"
+import { ReactorProvider, useAuth, useClient } from "../src/index.js"
+import {
+  clientOf,
+  clientWithAuth,
+  macrotask,
+  type TestAuth,
+  testAuth,
+  trackedFactory,
+} from "./helpers.js"
+
+/** Node's `gc()`, present when the worker runs with `--expose-gc`. */
+const collectGarbage = (globalThis as { gc?: () => void }).gc
+
+/** `React.Activity` exists from React 19.2; the peer range starts at 18. */
+const Activity = (
+  React as unknown as {
+    Activity?: ComponentType<{
+      mode: "visible" | "hidden"
+      children: ReactNode
+    }>
+  }
+).Activity
+
+function setup() {
+  // An auth for each client, as `() => new AuthClient()` makes one: a client
+  // disposes the auth it built, and a disposed auth tells nobody anything.
+  const auths: TestAuth[] = []
+  const tracked = trackedFactory(() =>
+    clientWithAuth(() => {
+      const auth = testAuth({ identity: 3, signedIn: false })
+      auths.push(auth)
+      return auth
+    })
+  )
+  /** The auth of the client most recently put to use. */
+  const currentAuth = () => auths[auths.length - 1] as TestAuth
+  const live: { client?: Client } = {}
+  /** Every client a render of the tree has used. */
+  const seen = new Set<Client>()
+  function Probe() {
+    // The provider's client, which useClient() returns a view of.
+    live.client = clientOf(useClient())
+    seen.add(live.client)
+    const { status } = useAuth()
+    return <p data-testid="status">{status}</p>
+  }
+  return { currentAuth, live, seen, Probe, ...tracked }
+}
+
+describe("a provider's client across mounts", () => {
+  it("survives React's development double-mount and keeps working", async () => {
+    const { currentAuth, live, seen, Probe, factory, made, trackOf } = setup()
+
+    const view = render(
+      <StrictMode>
+        <ReactorProvider client={factory}>
+          <Probe />
+        </ReactorProvider>
+      </StrictMode>
+    )
+    await act(macrotask)
+
+    // React's development render builds two clients and keeps one. The
+    // registry disposes the one React threw away when a collection finds it
+    // unreachable, which can happen at any point of this test, so the
+    // assertions are about the client in use. Where the runtime exposes
+    // `gc()`, run that collection now, so that they are checked after it.
+    const used = trackOf(live.client as Client)
+    const dropped = made.filter((entry) => entry !== used)
+    for (
+      let round = 0;
+      collectGarbage !== undefined &&
+      round < 20 &&
+      dropped.some((entry) => entry.dispose.mock.calls.length === 0);
+      round++
+    ) {
+      collectGarbage()
+      await macrotask()
+    }
+
+    // The client in use was not disposed, and the tree has used no other: no
+    // client was built to replace a disposed one.
+    expect(used.dispose).not.toHaveBeenCalled()
+    expect([...seen]).toEqual([used.client])
+    expect(factory.mock.calls.length).toBeLessThanOrEqual(2)
+    // The client still hears its auth: the subscription survived.
+    expect(view.getByTestId("status").textContent).toBe("anonymous")
+    await act(async () => {
+      await currentAuth().signIn()
+    })
+    expect(view.getByTestId("status").textContent).toBe("signed-in")
+    expect([...seen]).toEqual([used.client])
+    expect(used.dispose).not.toHaveBeenCalled()
+  })
+
+  it("disposes the client exactly once when the provider unmounts", async () => {
+    const { live, Probe, factory, trackOf } = setup()
+    const view = render(
+      <StrictMode>
+        <ReactorProvider client={factory}>
+          <Probe />
+        </ReactorProvider>
+      </StrictMode>
+    )
+    await act(macrotask)
+    const used = trackOf(live.client as Client)
+    expect(used.dispose).not.toHaveBeenCalled()
+
+    view.unmount()
+    await act(macrotask)
+    await act(macrotask)
+
+    expect(used.dispose).toHaveBeenCalledTimes(1)
+  })
+
+  it("disposes the client exactly once when it unmounts outside StrictMode too", async () => {
+    const { live, Probe, factory, trackOf, made } = setup()
+    const view = render(
+      <ReactorProvider client={factory}>
+        <Probe />
+      </ReactorProvider>
+    )
+    await act(macrotask)
+    const used = trackOf(live.client as Client)
+    // Without StrictMode, a mounted provider has built exactly one client.
+    expect(made).toHaveLength(1)
+    expect(used.dispose).not.toHaveBeenCalled()
+
+    view.unmount()
+    // The disposal is for the next macrotask, not this one.
+    expect(used.dispose).not.toHaveBeenCalled()
+    await act(macrotask)
+
+    expect(used.dispose).toHaveBeenCalledTimes(1)
+    // The real client was disposed, not only the call counted.
+    await expect(used.client.signIn()).rejects.toThrow(/disposed/)
+  })
+
+  it("keeps the client and the factory it was given when the parent renders again", async () => {
+    const { live, Probe, factory, made } = setup()
+    const first = render(
+      <ReactorProvider client={factory}>
+        <Probe />
+      </ReactorProvider>
+    )
+    const mounted = live.client
+
+    // A new function on every render, as an inline factory is.
+    first.rerender(
+      <ReactorProvider client={() => factory()}>
+        <Probe />
+      </ReactorProvider>
+    )
+    first.rerender(
+      <ReactorProvider client={() => factory()}>
+        <Probe />
+      </ReactorProvider>
+    )
+    await act(macrotask)
+
+    expect(live.client).toBe(mounted)
+    expect(factory).toHaveBeenCalledTimes(1)
+    expect(made).toHaveLength(1)
+  })
+
+  it.skipIf(Activity === undefined)(
+    "replaces a client that was disposed while its subtree was hidden",
+    async () => {
+      const Hideable = Activity as NonNullable<typeof Activity>
+      const { currentAuth, live, Probe, factory, made, trackOf } = setup()
+      const tree = (mode: "visible" | "hidden") => (
+        <Hideable mode={mode}>
+          <ReactorProvider client={factory}>
+            <Probe />
+          </ReactorProvider>
+        </Hideable>
+      )
+      const view = render(tree("visible"))
+      await act(macrotask)
+      const hidden = live.client as Client
+      hidden.queryClient.setQueryData(["cached"], "before hiding")
+
+      view.rerender(tree("hidden"))
+      await act(macrotask)
+      expect(trackOf(hidden).dispose).toHaveBeenCalledTimes(1)
+
+      view.rerender(tree("visible"))
+      await act(macrotask)
+
+      // The subtree runs on a live client again, not on the disposed one.
+      const shown = live.client as Client
+      expect(shown).not.toBe(hidden)
+      expect(made).toHaveLength(2)
+      // Hiding a provider drops its cache, as the provider's docs say.
+      expect(shown.queryClient.getQueryData(["cached"])).toBeUndefined()
+      expect(trackOf(shown).dispose).not.toHaveBeenCalled()
+      await act(async () => {
+        await currentAuth().signIn()
+      })
+      expect(view.getByTestId("status").textContent).toBe("signed-in")
+    }
+  )
+
+  it.skipIf(Activity === undefined)(
+    "builds one replacement, not two, when StrictMode shows a hidden subtree again",
+    async () => {
+      const Hideable = Activity as NonNullable<typeof Activity>
+      const { live, Probe, factory, made, trackOf } = setup()
+      const tree = (mode: "visible" | "hidden") => (
+        <StrictMode>
+          <Hideable mode={mode}>
+            <ReactorProvider client={factory}>
+              <Probe />
+            </ReactorProvider>
+          </Hideable>
+        </StrictMode>
+      )
+      const view = render(tree("visible"))
+      await act(macrotask)
+      const hidden = live.client as Client
+      const builtBefore = made.length
+
+      view.rerender(tree("hidden"))
+      await act(macrotask)
+      expect(trackOf(hidden).dispose).toHaveBeenCalledTimes(1)
+      view.rerender(tree("visible"))
+      await act(macrotask)
+
+      // StrictMode runs the effects of a revealed subtree twice before the
+      // replacement is committed; the factory still runs once for it, so no
+      // client is built only to be dropped.
+      expect(made.length - builtBefore).toBe(1)
+      const shown = live.client as Client
+      expect(shown).not.toBe(hidden)
+      expect(shown).toBe(made[made.length - 1]?.client)
+      expect(trackOf(shown).dispose).not.toHaveBeenCalled()
+      // The client that was hidden was disposed once, not again on the reveal.
+      expect(trackOf(hidden).dispose).toHaveBeenCalledTimes(1)
+    }
+  )
+})
+
+describe("a sign-in an effect starts", () => {
+  it("is one sign-in of the auth under StrictMode, which runs the effect twice", async () => {
+    const real = testAuth({ identity: 3, signedIn: false })
+    const signIn = vi.fn((_options?: unknown) => real.signIn())
+    const auth = { ...real, signIn }
+    // A sign-in route that calls signIn() straight from its effect, as the
+    // auth guide says an app with no server render can.
+    function SignInPage() {
+      const { status, signIn } = useAuth()
+      useEffect(() => {
+        if (status === "signed-in") return
+        signIn({ returnTo: "/account" }).catch(() => {})
+      }, [status, signIn])
+      return <p data-testid="status">{status}</p>
+    }
+
+    const view = render(
+      <StrictMode>
+        <ReactorProvider client={() => clientWithAuth(() => auth)}>
+          <SignInPage />
+        </ReactorProvider>
+      </StrictMode>
+    )
+    await act(macrotask)
+
+    expect(view.getByTestId("status").textContent).toBe("signed-in")
+    expect(signIn).toHaveBeenCalledTimes(1)
+    expect(signIn).toHaveBeenCalledWith({ returnTo: "/account" })
+    view.unmount()
+  })
+})

package/packages/react/tests/suspense.test-d.tsx

@@ -0,0 +1,357 @@
+/**
+ * Type tests for the options of `client.queryOptions()` as TanStack Query's
+ * React hooks take them, compiled by `pnpm typecheck` and never run.
+ * `useSuspenseQuery` and `useSuspenseQueries` take no `skipToken` for
+ * `queryFn`, so options built from variables that cannot be `skipToken` must
+ * carry none, and need no cast. Options built from variables that may be
+ * `skipToken` keep it, and the suspense hooks refuse them, here and as a trap
+ * of `packages/core/tests/traps.test-d.ts` that `pnpm verify:traps` proves.
+ */
+import type { Principal, WithMode } from "@meantjs/schema"
+import type { Canister, Client, ReactorError } from "@ic-reactor/core"
+import {
+  QueryClient,
+  skipToken,
+  useQueries,
+  useQuery,
+  useSuspenseQueries,
+  useSuspenseQuery,
+  type SkipToken,
+} from "@tanstack/react-query"
+import { expectTypeOf } from "vitest"
+
+type Account = { owner: Principal; subaccount: Uint8Array | null }
+type Query = WithMode<"query">
+/**
+ * What a generated module's `Actor` type looks like, cut down: each method is
+ * its call signature marked with its mode, as `meant gen` 0.5.1 writes it.
+ */
+type Ledger = {
+  icrc1_fee: (() => Promise<bigint>) & Query
+  icrc1_balance_of: ((account: Account) => Promise<bigint>) & Query
+  icrc1_name: (() => Promise<string>) & Query
+  outcome: ((
+    n: bigint
+  ) => Promise<{ tag: "Ok"; value: bigint } | { tag: "Err"; value: string }>) &
+    Query
+  pair: ((left: bigint, right: string) => Promise<string>) & Query
+  /** A Candid `reserved` argument, which a generated module types `unknown`. */
+  anything: ((value: unknown) => Promise<bigint>) & Query
+  /** `record {}`, as `meant gen` writes it. */
+  empty: ((value: Record<string, never>) => Promise<bigint>) & Query
+  /** A record of opts alone, an opt and `null`, as the generator writes them. */
+  options: ((value: { limit: bigint | null }) => Promise<bigint>) & Query
+  maybeNat: ((value: bigint | null) => Promise<bigint>) & Query
+  nothing: ((value: null) => Promise<bigint>) & Query
+  /** `record {}` written `{}`, as other generators write it. */
+  braces: ((value: {}) => Promise<bigint>) & Query
+}
+
+declare const client: Client
+declare const ledger: Canister<Ledger>
+declare const account: Account
+declare const maybeAccount: Account | SkipToken
+declare const queryClient: QueryClient
+
+export function SuspenseReads() {
+  // A method without arguments, called without variables.
+  const fee = useSuspenseQuery(client.queryOptions(ledger, "icrc1_fee"))
+  expectTypeOf(fee.data).toEqualTypeOf<bigint>()
+  expectTypeOf(fee.error).toEqualTypeOf<ReactorError | null>()
+
+  // ... or with `undefined` in their place.
+  const name = useSuspenseQuery(
+    client.queryOptions(ledger, "icrc1_name", undefined)
+  )
+  expectTypeOf(name.data).toEqualTypeOf<string>()
+
+  // Variables whose type does not include SkipToken.
+  const balance = useSuspenseQuery(
+    client.queryOptions(ledger, "icrc1_balance_of", account)
+  )
+  expectTypeOf(balance.data).toEqualTypeOf<bigint>()
+
+  // Two arguments, as the tuple.
+  const pair = useSuspenseQuery(client.queryOptions(ledger, "pair", [1n, "x"]))
+  expectTypeOf(pair.data).toEqualTypeOf<string>()
+
+  // A result read keeps its typed error.
+  const outcome = useSuspenseQuery(client.queryOptions(ledger, "outcome", 1n))
+  expectTypeOf(outcome.data).toEqualTypeOf<bigint>()
+  expectTypeOf(outcome.error).toEqualTypeOf<ReactorError<string> | null>()
+
+  // Several reads at once.
+  const [many, total] = useSuspenseQueries({
+    queries: [
+      client.queryOptions(ledger, "icrc1_fee"),
+      client.queryOptions(ledger, "icrc1_balance_of", account),
+    ],
+  })
+  expectTypeOf(many.data).toEqualTypeOf<bigint>()
+  expectTypeOf(total.data).toEqualTypeOf<bigint>()
+
+  // Spread, with options of the app's added.
+  const spread = useSuspenseQuery({
+    ...client.queryOptions(ledger, "icrc1_balance_of", account),
+    staleTime: 5_000,
+  })
+  expectTypeOf(spread.data).toEqualTypeOf<bigint>()
+
+  // Variables that may be skipped: a suspense read cannot wait for them.
+  // The two lines below each refusal say it is for SkipToken: without them a
+  // refusal for another reason (a retry the hook does not take) would pass.
+  const maybe = client.queryOptions(ledger, "icrc1_balance_of", maybeAccount)
+  // @ts-expect-error a suspense read cannot be skipped; read it with useQuery
+  const skipped = useSuspenseQuery(maybe)
+  expectTypeOf<
+    Extract<typeof maybe.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  useQuery(maybe)
+  const none = client.queryOptions(ledger, "icrc1_fee", skipToken)
+  // @ts-expect-error skipToken is for useQuery
+  const skippedMany = useSuspenseQueries({ queries: [none] })
+  expectTypeOf<
+    Extract<typeof none.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  useQueries({ queries: [none] })
+
+  // A reserved argument is `unknown`, which may hold skipToken whatever its
+  // value: such a read keeps SkipToken, and a suspense read of it needs a cast.
+  const reserved = client.queryOptions(ledger, "anything", 1n)
+  // @ts-expect-error a reserved argument may be skipToken
+  const reservedRead = useSuspenseQuery(reserved)
+  expectTypeOf<
+    Extract<typeof reserved.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  // The cast the Reads guide gives for it.
+  const reservedCast = useSuspenseQuery(
+    reserved as typeof reserved & {
+      queryFn: Exclude<typeof reserved.queryFn, SkipToken>
+    }
+  )
+  expectTypeOf(reservedCast.data).toEqualTypeOf<bigint>()
+
+  // Variables of a type `skipToken` is not assignable to: an empty record as
+  // the generator writes it, a record of opts alone, an opt and `null`. A value
+  // reads under suspense, and skipToken is refused.
+  const empty = useSuspenseQuery(client.queryOptions(ledger, "empty", {}))
+  expectTypeOf(empty.data).toEqualTypeOf<bigint>()
+  const emptySkipped = client.queryOptions(ledger, "empty", skipToken)
+  // @ts-expect-error skipToken is for useQuery
+  const emptySkippedRead = useSuspenseQuery(emptySkipped)
+  expectTypeOf<
+    Extract<typeof emptySkipped.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  useQuery(emptySkipped)
+  const [opts, opt, nothing] = useSuspenseQueries({
+    queries: [
+      client.queryOptions(ledger, "options", { limit: null }),
+      client.queryOptions(ledger, "maybeNat", null),
+      client.queryOptions(ledger, "nothing", null),
+    ],
+  })
+  expectTypeOf(opts.data).toEqualTypeOf<bigint>()
+  expectTypeOf(opt.data).toEqualTypeOf<bigint>()
+  expectTypeOf(nothing.data).toEqualTypeOf<bigint>()
+  // Each with skipToken is refused on its own, so one that wrongly read
+  // under suspense could not hide behind the others.
+  const optsSkipped = client.queryOptions(ledger, "options", skipToken)
+  // @ts-expect-error skipToken is for useQuery
+  const optsSkippedRead = useSuspenseQuery(optsSkipped)
+  expectTypeOf<
+    Extract<typeof optsSkipped.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  const optSkipped = client.queryOptions(ledger, "maybeNat", skipToken)
+  // @ts-expect-error skipToken is for useQuery
+  const optSkippedRead = useSuspenseQuery(optSkipped)
+  expectTypeOf<
+    Extract<typeof optSkipped.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  const nothingSkipped = client.queryOptions(ledger, "nothing", skipToken)
+  // @ts-expect-error skipToken is for useQuery
+  const nothingSkippedRead = useSuspenseQuery(nothingSkipped)
+  expectTypeOf<
+    Extract<typeof nothingSkipped.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  useQueries({ queries: [optsSkipped, optSkipped, nothingSkipped] })
+
+  // `{}` is a type skipToken is assignable to, like a reserved argument's
+  // `unknown`: it cannot tell a value from skipToken, so every read of it
+  // keeps SkipToken, with skipToken or with a value.
+  const bracesSkipped = client.queryOptions(ledger, "braces", skipToken)
+  // @ts-expect-error `{}` may be skipToken
+  const bracesSkippedRead = useSuspenseQuery(bracesSkipped)
+  expectTypeOf<
+    Extract<typeof bracesSkipped.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  useQuery(bracesSkipped)
+  const bracesValue = client.queryOptions(ledger, "braces", {})
+  // @ts-expect-error `{}` may be skipToken
+  const bracesRead = useSuspenseQuery(bracesValue)
+  expectTypeOf<
+    Extract<typeof bracesValue.queryFn, SkipToken>
+  >().toEqualTypeOf<SkipToken>()
+  useQuery(bracesValue)
+
+  return [
+    fee,
+    name,
+    balance,
+    pair,
+    outcome,
+    many,
+    total,
+    spread,
+    skipped,
+    skippedMany,
+    reservedRead,
+    reservedCast,
+    empty,
+    emptySkippedRead,
+    opts,
+    opt,
+    nothing,
+    optsSkippedRead,
+    optSkippedRead,
+    nothingSkippedRead,
+    bracesSkippedRead,
+    bracesRead,
+  ].length
+}
+
+export function Reads() {
+  // useQuery takes both: the read that may be skipped and the one that
+  // cannot, with the same data and error.
+  const skipped = useQuery(
+    client.queryOptions(ledger, "icrc1_balance_of", maybeAccount)
+  )
+  expectTypeOf(skipped.data).toEqualTypeOf<bigint | undefined>()
+  expectTypeOf(skipped.error).toEqualTypeOf<ReactorError | null>()
+  const read = useQuery(
+    client.queryOptions(ledger, "icrc1_balance_of", account)
+  )
+  expectTypeOf(read.data).toEqualTypeOf<bigint | undefined>()
+  expectTypeOf(read.error).toEqualTypeOf<ReactorError | null>()
+  const none = useQuery(client.queryOptions(ledger, "icrc1_fee", skipToken))
+  expectTypeOf(none.data).toEqualTypeOf<bigint | undefined>()
+  expectTypeOf(none.error).toEqualTypeOf<ReactorError | null>()
+  // useQueries types each query's error from its throwOnError alone, so the
+  // options' retry must take any error.
+  const [fee, balance] = useQueries({
+    queries: [
+      client.queryOptions(ledger, "icrc1_fee"),
+      client.queryOptions(ledger, "icrc1_balance_of", maybeAccount),
+    ],
+  })
+  expectTypeOf(fee.data).toEqualTypeOf<bigint | undefined>()
+  expectTypeOf(balance.data).toEqualTypeOf<bigint | undefined>()
+  return [skipped, read, none, fee, balance].length
+}
+
+// The options built from variables that cannot be skipped carry no SkipToken;
+// the ones built from variables that may be keep it, as before.
+export const certain = client.queryOptions(ledger, "icrc1_balance_of", account)
+expectTypeOf<Extract<typeof certain.queryFn, SkipToken>>().toBeNever()
+export const maybe = client.queryOptions(
+  ledger,
+  "icrc1_balance_of",
+  maybeAccount
+)
+expectTypeOf<
+  Extract<typeof maybe.queryFn, SkipToken>
+>().toEqualTypeOf<SkipToken>()
+export const skipped = client.queryOptions(ledger, "icrc1_fee", skipToken)
+expectTypeOf<
+  Extract<typeof skipped.queryFn, SkipToken>
+>().toEqualTypeOf<SkipToken>()
+
+// The key is tagged either way, so getQueryData and fetchQuery are typed.
+expectTypeOf(
+  queryClient.getQueryData(
+    client.queryOptions(ledger, "icrc1_balance_of", account).queryKey
+  )
+).toEqualTypeOf<bigint | undefined>()
+expectTypeOf(
+  queryClient.getQueryData(
+    client.queryOptions(ledger, "icrc1_balance_of", maybeAccount).queryKey
+  )
+).toEqualTypeOf<bigint | undefined>()
+expectTypeOf(
+  queryClient.fetchQuery(client.queryOptions(ledger, "icrc1_fee"))
+).toEqualTypeOf<Promise<bigint>>()
+
+// A wrapper of `client.queryOptions` written against the published 4.0.0-beta.1
+// types stops compiling where it takes the function's type whole: the
+// function has two signatures now, and one function cannot satisfy both, nor
+// can `Parameters` (the last signature's) be spread back into the call. The
+// forms below are the break the CHANGELOG lists.
+// @ts-expect-error a function typed Client["queryOptions"] must satisfy both signatures
+export const typedWrapper: Client["queryOptions"] = (c, m, ...rest) =>
+  // @ts-expect-error neither signature takes the rest of both
+  client.queryOptions(c, m, ...rest)
+export const spreadWrapper = (...args: Parameters<Client["queryOptions"]>) =>
+  // @ts-expect-error Parameters of an overloaded function is the last signature's, and its rest is not a tuple here
+  client.queryOptions(...args)
+
+// What a wrapper still does: the result type, and the options spread with the
+// app's own.
+export type QueryOptionsResult = ReturnType<Client["queryOptions"]>
+expectTypeOf<QueryOptionsResult["queryKey"]>().not.toBeNever()
+export const withStaleTime = {
+  ...client.queryOptions(ledger, "icrc1_balance_of", account),
+  staleTime: 1,
+}
+expectTypeOf<Extract<typeof withStaleTime.queryFn, SkipToken>>().toBeNever()
+
+// A `retry` written into the options' type takes an error typed `unknown`
+// too, as `useQueries` and `useSuspenseQueries` call it, so one whose error
+// parameter is annotated `ReactorError<E>` stops compiling: the third break
+// the CHANGELOG lists. One annotated `unknown`, or left to the context,
+// compiles.
+const outcome = client.queryOptions(ledger, "outcome", 1n)
+export const annotatedRetry: typeof outcome = {
+  ...outcome,
+  // @ts-expect-error the options' retry must also take an error typed unknown
+  retry: (_n: number, error: ReactorError<string>) => error.kind === "rejected",
+}
+export const unknownRetry: typeof outcome = {
+  ...outcome,
+  retry: (_n: number, error: unknown) => error !== null,
+}
+export const contextualRetry: typeof outcome = {
+  ...outcome,
+  retry: (n, error) => n < 3 && error !== null,
+}
+// The options of a read that cannot be skipped and of one that can are two
+// types now, so a variable inferred from the first no longer holds the
+// second: the fourth break the CHANGELOG lists. Built in one expression, the
+// two make a union that useQuery takes; a variable typed `V | SkipToken`
+// gives the wide options either way.
+export function OneVariableTwoReads(ready: boolean) {
+  let reassigned = client.queryOptions(ledger, "outcome", 1n)
+  const first = reassigned
+  // @ts-expect-error options that cannot be skipped do not hold options that can
+  reassigned = client.queryOptions(ledger, "outcome", skipToken)
+  expectTypeOf<Extract<typeof reassigned.queryFn, SkipToken>>().toBeNever()
+  const either = ready
+    ? client.queryOptions(ledger, "outcome", 1n)
+    : client.queryOptions(ledger, "outcome", skipToken)
+  const read = useQuery(either)
+  expectTypeOf(read.data).toEqualTypeOf<bigint | undefined>()
+  expectTypeOf(read.error).toEqualTypeOf<ReactorError<string> | null>()
+  const n: bigint | SkipToken = ready ? 1n : skipToken
+  let wide = client.queryOptions(ledger, "outcome", n)
+  const firstWide = wide
+  wide = client.queryOptions(ledger, "outcome", skipToken)
+  return [first, reassigned, read, firstWide, wide]
+}
+
+export function RetryOfTheApp() {
+  // A `retry` passed to the hook replaces the options' own, and keeps its
+  // annotation.
+  return useQuery({
+    ...outcome,
+    retry: (_n: number, error: ReactorError<string>) =>
+      error.kind === "rejected",
+  })
+}