@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/packages/core/tests/traps.test-d.ts

@@ -0,0 +1,476 @@
+/**
+ * Trap types: the mistakes the types of `@ic-reactor/core` are written to make
+ * a compile error, each proven to bite.
+ *
+ * A `@ts-expect-error` is only worth something while the line below it really
+ * is an error. If a refactor widens a type until the line compiles, TypeScript
+ * reports the directive as unused (TS2578), but only to whoever runs `tsc`
+ * over this file, and a trap that stopped trapping looks the same as a trap
+ * that still does in a green build. `scripts/verify-traps.mjs`
+ * (`pnpm verify:traps`, a CI gate) closes that gap: for every trap below it
+ * applies a fault that removes exactly that trap to a copy of this package,
+ * runs `tsc` on the copy, and requires TS2578 on exactly the trap's line and
+ * nothing else. A trap with no fault fixture, or a fixture whose fault leaves
+ * the trap standing, fails CI.
+ *
+ * ## Adding a trap
+ *
+ * 1. Write the line that must not compile, with a tag on the line above the
+ *    directive, the id first and the directive straight after it, on a line
+ *    of its own:
+ *
+ *        // trap: <id>
+ *        // @ts-expect-error <what the line gets wrong, and what to do instead>
+ *        theLineThatMustNotCompile()
+ *
+ *    The id is lowercase words joined by `-`. Several lines may share one id
+ *    when one fault removes them all. A `@ts-expect-error` with no tag, a tag
+ *    with no directive under it, and any `@ts-ignore` or `@ts-nocheck` in this
+ *    file fail the script.
+ *
+ * 2. Write `scripts/traps/<id>.json`, the fault that makes the line compile:
+ *
+ *        {
+ *          "file": "src/units.ts",
+ *          "search": "export function formatUnits(\n  value: bigint,",
+ *          "replace": "export function formatUnits(\n  value: bigint | number,"
+ *        }
+ *
+ *    `file` is relative to this package, and `search` must occur exactly once
+ *    in it. For several edits write `{ "edits": [ { "file", "search",
+ *    "replace" }, ... ] }`; for more than text replacement, write
+ *    `scripts/traps/<id>.mjs` exporting a default function that takes
+ *    `{ dir, applyEdits }`, where `dir` is the copy of this package and
+ *    `applyEdits(edits)` applies a list of the same edits.
+ *
+ *    The fault is the *natural* regression: widening the type, dropping the
+ *    check, exporting the internal. It must change nothing else: no other
+ *    diagnostic may appear, so repair what the fault breaks in the same
+ *    fixture.
+ *
+ * 3. Run `pnpm verify:traps`, then check by hand that the fault is one a
+ *    refactor could really commit.
+ *
+ * A trap about another package belongs in a `traps.test-d.ts` of its own,
+ * registered in `SUITES` of `scripts/verify-traps.mjs`.
+ *
+ * Checked by `pnpm typecheck` (this file is in the typecheck project), not run
+ * by vitest.
+ */
+import type { Principal } from "@meantjs/schema"
+import { Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import {
+  MutationObserver,
+  QueryObserver,
+  keepPreviousData,
+  skipToken,
+  type OmitKeyof,
+  type QueryKey,
+  type QueryObserverOptions,
+  type SkipToken,
+} from "@tanstack/query-core"
+import {
+  createClient,
+  formatUnits,
+  isReactorError,
+  parseUnits,
+} from "../src/index.js"
+import type { Canister, Network, ReactorError } from "../src/index.js"
+import { createTestClient, type TestHandlers } from "../src/testing/index.js"
+import { createTestAuth } from "../src/testing/test-auth.js"
+import * as icrc1 from "./fixtures/icrc1.js"
+import * as shapes from "./fixtures/shapes.js"
+import * as skippable from "./fixtures/skippable.js"
+
+// What a generated module's `Err` arm looks like for ICRC-1 `icrc1_transfer`.
+type TransferError =
+  | { BadFee: { expected_fee: bigint } }
+  | { InsufficientFunds: { balance: bigint } }
+
+// `icrc1_decimals : () -> (nat8) query` and a balance that is still loading.
+declare const decimals: number
+declare const balance: bigint
+declare const loading: bigint | undefined
+
+// ---------------------------------------------------------------------------
+// Units: a `Number` is the lossy input they exist to replace
+// ---------------------------------------------------------------------------
+
+// trap: format-units-refuses-number
+// @ts-expect-error a Number amount cannot hold every balance; pass the bigint a ledger returned
+formatUnits(1.5, 8)
+
+// trap: format-units-refuses-missing-value
+// @ts-expect-error the amount may still be loading; show a placeholder instead of formatting undefined
+formatUnits(loading, 8)
+
+// trap: parse-units-refuses-number
+// @ts-expect-error read the text a person typed, not a Number: Number math turns 0.29 into 28999999
+parseUnits(1.5, decimals)
+
+// trap: parse-units-unknown-option
+// @ts-expect-error v3 called it allowNegative; the option is `signed`
+parseUnits("-1", 8, { allowNegative: true })
+
+// trap: format-units-unknown-option
+// @ts-expect-error v3 had rounding modes; this cuts and never rounds
+formatUnits(balance, 8, { roundingMode: "halfExpand" })
+
+// ---------------------------------------------------------------------------
+// Networks: one of the names, or an object with a host
+// ---------------------------------------------------------------------------
+
+// trap: network-refuses-unknown-name
+// @ts-expect-error a network is "ic", "local", "env" or an object; "mainnet" would be a typo that falls through
+export const unknownName: Network = "mainnet"
+
+// ---------------------------------------------------------------------------
+// Errors: `err` is typed only where the canister returned one
+// ---------------------------------------------------------------------------
+
+export const readNeverErr = (error: ReactorError) => {
+  if (error.kind === "canister_err") {
+    // trap: never-err-has-no-type
+    // @ts-expect-error a method without an Err arm has no typed `err`; it is undefined for every kind
+    return error.err.BadFee
+  }
+  return undefined
+}
+
+export const readErrOffTheArm = (error: ReactorError<TransferError>) => {
+  if (error.kind !== "canister_err") {
+    // trap: err-only-on-canister-err
+    // @ts-expect-error `err` is undefined for every kind but canister_err; check the kind first
+    return "BadFee" in error.err
+  }
+  return undefined
+}
+
+// ---------------------------------------------------------------------------
+// The entry: the classifier and the resolver are the client's, not an app's
+// ---------------------------------------------------------------------------
+
+// trap: internals-not-exported
+// @ts-expect-error classifyError is internal; an app reads `mayHaveExecuted` off the error it is given
+import { classifyError } from "../src/index.js"
+// trap: internals-not-exported
+// @ts-expect-error resolveNetwork is internal; an app passes a Network to createClient
+import { resolveNetwork } from "../src/index.js"
+
+export const internals = { classifyError, resolveNetwork }
+
+// ---------------------------------------------------------------------------
+// The client: who calls is written down exactly once
+// ---------------------------------------------------------------------------
+
+const someone = Ed25519KeyIdentity.generate()
+
+// trap: client-says-who-calls
+// @ts-expect-error neither identity nor auth: who calls is not written down; pass identity: "anonymous" for a read-only client
+createClient({ network: "ic" })
+
+// trap: client-says-who-calls-once
+// @ts-expect-error identity and auth together: who calls is written twice; identity fixes the caller, auth signs users in
+createClient({ network: "ic", identity: someone, auth: () => createTestAuth() })
+
+// ---------------------------------------------------------------------------
+// Canisters: methods, variables and principals come from the generated Actor
+// ---------------------------------------------------------------------------
+
+const client = createClient({ network: "ic", identity: "anonymous" })
+const ledger = client.canister<icrc1.Actor>(icrc1.actor, {
+  id: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+})
+const shapesCanister = client.canister<shapes.Actor>(shapes.actor, {
+  id: "rrkah-fqaaa-aaaaa-aaaaq-cai",
+})
+declare const owner: Principal
+const account: icrc1.Account = { owner, subaccount: null }
+declare const transferArg: icrc1.TransferArg
+
+// trap: canister-method-unknown
+// @ts-expect-error icrc1_balance is not a method of the ICRC-1 ledger; it is icrc1_balance_of
+void ledger.icrc1_balance(account)
+
+// trap: options-method-unknown
+// @ts-expect-error a typo in the method name: the builders take the generated Actor's method names only
+client.queryOptions(ledger, "icrc1_balance", account)
+
+// trap: options-vars-wrong-type
+// @ts-expect-error icrc1_balance_of takes an Account, not its owner: { owner, subaccount: null }
+client.queryOptions(ledger, "icrc1_balance_of", owner)
+
+// trap: principal-is-not-plain-text
+// @ts-expect-error a principal is checked text: principal("aaaaa-aa") from @meantjs/schema, not a string literal
+void ledger.icrc1_balance_of({ owner: "aaaaa-aa", subaccount: null })
+
+// trap: vars-of-two-arguments-are-the-tuple
+// @ts-expect-error pair takes two arguments: pass them as the tuple [left, right]
+client.queryOptions(shapesCanister, "pair", 1n)
+
+// ---------------------------------------------------------------------------
+// The typed guard: `err` is the Err arm of the method it names, not another's
+// ---------------------------------------------------------------------------
+
+// An ICRC-2 ledger: icrc2_approve has an Err arm of its own, which has no
+// BadBurn; that is icrc1_transfer's.
+type ApproveError =
+  | { tag: "AllowanceChanged"; value: { current_allowance: bigint } }
+  | { tag: "Expired"; value: { ledger_time: bigint } }
+  | { tag: "InsufficientFunds"; value: { balance: bigint } }
+declare const icrc2Ledger: Canister<
+  icrc1.Actor & {
+    icrc2_approve: (
+      arg: unknown
+    ) => Promise<
+      { tag: "Ok"; value: bigint } | { tag: "Err"; value: ApproveError }
+    >
+  }
+>
+
+export const readAnotherMethodsErr = (error: unknown) => {
+  if (
+    isReactorError(error, icrc2Ledger, "icrc2_approve") &&
+    error.kind === "canister_err"
+  ) {
+    // trap: guard-err-is-the-methods
+    // @ts-expect-error an approve cannot fail with BadBurn, a transfer's Err: the guard types `err` by the method named, so name the one that was called
+    return error.err.tag === "BadBurn"
+  }
+  return undefined
+}
+
+// A false three-argument guard means only "not this call's error". The error
+// can still be of any kind, even once the one-argument guard has narrowed it.
+export const readAnotherCallsKind = (error: unknown) => {
+  if (!isReactorError(error)) throw error
+  if (isReactorError(error, ledger, "icrc1_transfer")) return undefined
+  // trap: guard-false-keeps-every-kind
+  // @ts-expect-error another call's error can be of any kind, not only canister_err: check kind before reading err
+  const kind: "canister_err" = error.kind
+  return kind
+}
+
+// ---------------------------------------------------------------------------
+// Re-sending: only a write the app says the canister deduplicates
+// ---------------------------------------------------------------------------
+
+export const resendWithoutAKey = (error: unknown) =>
+  // trap: resend-states-its-dedupe-key
+  // @ts-expect-error re-sending is safe only for a write the canister deduplicates: state what it deduplicates on with { dedupedBy }
+  client.resendOf(error, ledger, "icrc1_transfer")
+
+export const resendByAFieldItLacks = (error: unknown) =>
+  client.resendOf(error, ledger, "icrc1_transfer", {
+    // trap: resend-key-reads-the-methods-arg
+    // @ts-expect-error dedupedBy reads the method's own argument, and a TransferArg has no nonce: name the field the canister deduplicates on
+    dedupedBy: (arg) => arg.nonce,
+  })
+
+// A method named by data, given as `any` (#874): its variables are the value
+// of a one-argument method, as at run time, not a list.
+export const writeOfANamedMethod = (named: string) =>
+  new MutationObserver(client.queryClient, {
+    ...client.mutationOptions<icrc1.Actor, any>(ledger, named),
+    // trap: any-method-vars-not-a-list
+    // @ts-expect-error under <A, any> the variables are the value of a one-argument method, not a list: vars[0] is not its argument
+    onSuccess: (_data, vars) => vars[0],
+  })
+
+// What `useSuspenseQuery` of `@tanstack/react-query` takes, written over
+// query-core: the options of a `QueryObserver`, without the ones a suspense
+// read has no use for, and a `queryFn` that is never `skipToken`, since a
+// suspense read cannot wait for its variables.
+type SuspenseQueryOptions<T, E, K extends QueryKey> = OmitKeyof<
+  QueryObserverOptions<T, E, T, T, K>,
+  "queryFn" | "enabled" | "throwOnError" | "placeholderData"
+> & {
+  queryFn?: Exclude<QueryObserverOptions<T, E, T, T, K>["queryFn"], SkipToken>
+}
+declare function useSuspenseQuery<T, E, K extends QueryKey>(
+  options: SuspenseQueryOptions<T, E, K>
+): { data: T }
+declare const ready: boolean
+
+// Variables that cannot be skipped give options a suspense read takes as they
+// are. The read with variables is a tuple: under the fault of
+// options-vars-wrong-type a single argument is `unknown`, which may hold
+// `skipToken`, and its read would be refused too.
+useSuspenseQuery(client.queryOptions(ledger, "icrc1_fee"))
+useSuspenseQuery(client.queryOptions(shapesCanister, "pair", [1n, "x"]))
+
+// Variables that may be skipped give options it refuses. The traps read a
+// method without arguments: under the fault of options-vars-wrong-type, which
+// widens every argument to `unknown`, the variables of a method with
+// arguments can no longer be told from `skipToken`, and one fault must remove
+// one trap. packages/react/tests/suspense.test-d.tsx refuses an `Account |
+// SkipToken` under the real `useSuspenseQuery`.
+
+const gated = client.queryOptions(
+  ledger,
+  "icrc1_fee",
+  ready ? undefined : skipToken
+)
+// trap: suspense-refuses-skippable-read
+// @ts-expect-error a suspense read cannot be skipped: render it once it can run, or read it with useQuery
+useSuspenseQuery(gated)
+// trap: suspense-refuses-skippable-read
+// @ts-expect-error skipToken is for useQuery; a suspense read always runs
+useSuspenseQuery(client.queryOptions(ledger, "icrc1_fee", skipToken))
+
+// Variables of a type `skipToken` is assignable to may always be skipped, and
+// the options keep SkipToken: a Candid `reserved` argument, which the
+// generator writes `unknown`, and an empty record written `{}` by hand
+// (`meant gen` writes `record {}` as `Record<string, never>`, which
+// a symbol is not). tests/skip.test-d.ts pins what the generator writes.
+const skippableIds = { id: "rrkah-fqaaa-aaaaa-aaaaq-cai" }
+const gen = client.canister<skippable.Actor>(skippable.actor, skippableIds)
+declare const braces: Canister<{ braces: (r: {}) => Promise<bigint> }>
+// trap: suspense-refuses-vars-skip-fits
+// @ts-expect-error a reserved argument may be skipToken, so a suspense read refuses it; read it with useQuery
+useSuspenseQuery(client.queryOptions(gen, "anything", skipToken))
+// trap: suspense-refuses-vars-skip-fits
+// @ts-expect-error skipToken is assignable to `{}`, so a suspense read refuses it; read it with useQuery
+useSuspenseQuery(client.queryOptions(braces, "braces", skipToken))
+
+// An argument `skipToken` is not assignable to, such as an empty record as the
+// generator writes it, still takes `skipToken` in its place, and the options
+// keep SkipToken.
+// trap: suspense-refuses-argument-skip
+// @ts-expect-error skipToken is for useQuery; a suspense read always runs
+useSuspenseQuery(client.queryOptions(gen, "empty_record", skipToken))
+
+// ---------------------------------------------------------------------------
+// Reads: a query refetches, so an update or a oneway is not a read
+// ---------------------------------------------------------------------------
+//
+// The generated Actor says each method's mode (`$.WithMode<"update">`), and
+// `queryOptions` reads it: every refetch of a read built from an update would
+// run the update again, and a oneway has no reply to cache.
+
+// trap: query-options-refuses-update
+// @ts-expect-error icrc1_transfer is an update: every refetch would transfer again; use client.mutationOptions(ledger, "icrc1_transfer")
+client.queryOptions(ledger, "icrc1_transfer", transferArg)
+// trap: query-options-refuses-update
+// @ts-expect-error an update is not a read while its variables load either; use client.mutationOptions for a write
+client.queryOptions(shapesCanister, "bump", skipToken)
+
+// trap: query-options-refuses-oneway
+// @ts-expect-error fire is a oneway method: it has no reply to cache; call it directly, or through client.mutationOptions
+client.queryOptions(shapesCanister, "fire", "x")
+// trap: query-options-refuses-oneway
+// @ts-expect-error { update: "idempotent" } opts in an update, not a oneway, which has no reply to cache whatever the options say
+client.queryOptions(shapesCanister, "fire", "x", { update: "idempotent" })
+
+// Each of these compiles. A query and a composite query are reads (a
+// composite query of a certified canister is refused at run time: no type
+// says a canister is certified).
+export const queryRead = client.queryOptions(shapesCanister, "one", 1n)
+export const compositeRead = client.queryOptions(
+  shapesCanister,
+  "composite",
+  1n
+)
+// An update that answers the same however often it runs is read with the
+// opt-in, its variables first, even `undefined` for a method without
+// arguments. Its options are a suspense read's like any other, and may wait
+// for their variables like any other.
+useSuspenseQuery(
+  client.queryOptions(shapesCanister, "three", undefined, {
+    update: "idempotent",
+  })
+)
+export const idempotentRead = client.queryOptions(
+  shapesCanister,
+  "address",
+  "seed",
+  { update: "idempotent" }
+)
+export const idempotentWhileLoading = client.queryOptions(
+  shapesCanister,
+  "address",
+  ready ? "seed" : skipToken,
+  { update: "idempotent" }
+)
+// An Actor written by hand says no mode: each of its methods may be read, and
+// the client refuses an update or a oneway at run time instead
+// (tests/traps/update-as-query.test.ts reads the ledger through one).
+type HandWrittenLedger = {
+  icrc1_fee: () => Promise<bigint>
+  icrc1_transfer: (arg: icrc1.TransferArg) => Promise<icrc1.TransferResult>
+}
+const handWritten = client.canister<HandWrittenLedger>(icrc1.actor, {
+  id: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+})
+export const handWrittenFee = client.queryOptions(handWritten, "icrc1_fee")
+export const handWrittenTransfer = client.queryOptions(
+  handWritten,
+  "icrc1_transfer",
+  transferArg
+)
+
+// ---------------------------------------------------------------------------
+// The test client: handlers answer in the generated Actor's domain values
+// ---------------------------------------------------------------------------
+
+type LedgerHandlers = TestHandlers<icrc1.Actor>
+
+// trap: test-handler-nat-is-bigint
+// @ts-expect-error icrc1_fee replies a nat, which is a bigint: 10_000 is a number, write 10_000n
+export const feeAsNumber: LedgerHandlers = { icrc1_fee: () => 10_000 }
+
+// trap: test-handler-method-unknown
+// @ts-expect-error icrc1_balance is not a method of the ICRC-1 ledger; it is icrc1_balance_of
+export const balanceTypo: LedgerHandlers = { icrc1_balance: () => 1n }
+
+// trap: test-handler-takes-the-domain-value
+// @ts-expect-error icrc1_balance_of takes an Account, not text: ({ owner }) => ...
+export const ofText: LedgerHandlers = { icrc1_balance_of: (_o: string) => 1n }
+
+// A refusal aimed at a method: an option it does not have would be ignored,
+// and the refusal would land on whatever request came next.
+const { refuseNext } = createTestClient()
+refuseNext(429, { method: "icrc1_transfer", times: 3 })
+// trap: refuse-next-unknown-option
+// @ts-expect-error refuseNext() has no option `methd`; it is `method`
+refuseNext(429, { methd: "icrc1_transfer" })
+
+// ---------------------------------------------------------------------------
+// Known holes (D36): these COMPILE on purpose
+// ---------------------------------------------------------------------------
+//
+// D36 records what the types do not stop, and decides against an ESLint plugin
+// to stop it: each is a mistake the eval scores, a runtime refusal where there
+// is one, and a line in the guide's "Do not" list. They are written here as
+// code that compiles, with no directive and no trap tag, so that nobody adds a
+// `@ts-expect-error` for one, and so that the day a type does start refusing
+// one shows up as a failing build here: a decision, not a surprise.
+
+// D36: spreading `retry: 3` into the options of a write. A mutation is never
+// retried (an update re-sent after an unknown outcome can run twice), but the
+// options are plain TanStack options, so nothing refuses the spread.
+export const retriedWrite = new MutationObserver(client.queryClient, {
+  ...client.mutationOptions(ledger, "icrc1_transfer"),
+  retry: 3,
+})
+
+// D36: `placeholderData: keepPreviousData` on a read. The previous key's data
+// is shown for the new key, which for a caller-scoped key can be another
+// principal's balance. It is a TanStack option; the type cannot tell.
+export const previousBalance = new QueryObserver(client.queryClient, {
+  ...client.queryOptions(ledger, "icrc1_balance_of", account),
+  placeholderData: keepPreviousData,
+})
+
+// D36: an array-literal key. Typed by hand it is a `QueryKey` like any other,
+// so it compiles, and then matches nothing the client builds: keys start with
+// "ic-reactor" and hold the caller. `client.queryKey(...)` is the only builder.
+void client.queryClient.invalidateQueries({ queryKey: ["balance", owner] })
+
+// D36: a hand-built query function calling an update. To TanStack any
+// function is a query function: this runs the transfer again on every
+// refetch, as whoever is signed in at that moment, not the key's caller.
+export const transferAsRead = new QueryObserver(client.queryClient, {
+  queryKey: ["transfer", owner],
+  queryFn: () => ledger.icrc1_transfer(transferArg),
+})

package/packages/core/tests/units.test-d.ts

@@ -0,0 +1,118 @@
+/**
+ * The types of `parseUnits` and `formatUnits`.
+ *
+ * Both are strict about what they take: `parseUnits` reads text only, since a
+ * `Number` amount is the lossy input it replaces, and `formatUnits` shows a
+ * `bigint` only, which is what a ledger's `nat` is in a generated module.
+ * Neither takes an option it does not implement, so a v3 name such as
+ * `allowNegative` or `locale` is a compile error and not silently ignored.
+ *
+ * Checked by `pnpm typecheck` (tests are in the typecheck project), not by
+ * vitest.
+ */
+import { describe, it, expectTypeOf } from "vitest"
+import { formatUnits, parseUnits } from "../src/index.js"
+
+// `icrc1_balance_of : (Account) -> (nat) query` and
+// `icrc1_decimals : () -> (nat8) query`, as a generated module returns them.
+declare const balance: bigint
+declare const decimals: number
+declare const loading: bigint | undefined
+declare const input: string
+
+describe("parseUnits", () => {
+  it("returns a bigint", () => {
+    expectTypeOf(parseUnits("1.5", 8)).toEqualTypeOf<bigint>()
+    expectTypeOf(parseUnits(input, decimals)).toEqualTypeOf<bigint>()
+    expectTypeOf(parseUnits("-1", 8, { signed: true })).toEqualTypeOf<bigint>()
+  })
+
+  it("takes text only", () => {
+    // @ts-expect-error a Number amount is the lossy input this replaces
+    parseUnits(1.5, 8)
+    // @ts-expect-error nor is a bigint
+    parseUnits(balance, 8)
+    // @ts-expect-error nor an amount that may still be missing
+    parseUnits(undefined, 8)
+  })
+
+  it("takes decimals as a number, and requires it", () => {
+    // @ts-expect-error decimals are required
+    parseUnits("1.5")
+    // @ts-expect-error a bigint decimals is converted with Number() first
+    parseUnits("1.5", 8n)
+    // @ts-expect-error digit text is not decimals
+    parseUnits("1.5", "8")
+  })
+
+  it("types its options", () => {
+    expectTypeOf(parseUnits)
+      .parameter(2)
+      .toEqualTypeOf<{ signed?: boolean } | undefined>()
+
+    parseUnits("1.5", 8, {})
+    parseUnits("1.5", 8, { signed: false })
+    // @ts-expect-error signed is a boolean
+    parseUnits("-1", 8, { signed: "true" })
+    // @ts-expect-error v3 called it allowNegative
+    parseUnits("-1", 8, { allowNegative: true })
+    // @ts-expect-error not an option
+    parseUnits("1.5", 8, { decimals: 2 })
+  })
+})
+
+describe("formatUnits", () => {
+  it("returns a string", () => {
+    expectTypeOf(formatUnits(balance, 8)).toEqualTypeOf<string>()
+    expectTypeOf(formatUnits(150_000_000n, decimals)).toEqualTypeOf<string>()
+    expectTypeOf(
+      formatUnits(balance, 8, { maxFractionDigits: 2, minFractionDigits: 2 })
+    ).toEqualTypeOf<string>()
+  })
+
+  it("takes a bigint only", () => {
+    // @ts-expect-error a Number amount cannot hold every balance
+    formatUnits(1.5, 8)
+    // @ts-expect-error not even a whole one
+    formatUnits(150_000_000, 8)
+    // @ts-expect-error integer text is not an amount; read it with BigInt
+    formatUnits("150000000", 8)
+    // @ts-expect-error the amount may be undefined while it loads
+    formatUnits(loading, 8)
+    // @ts-expect-error null is not an amount
+    formatUnits(null, 8)
+  })
+
+  it("takes decimals as a number, and requires it", () => {
+    // @ts-expect-error decimals are required
+    formatUnits(balance)
+    // @ts-expect-error a bigint decimals is converted with Number() first
+    formatUnits(balance, 8n)
+    // @ts-expect-error digit text is not decimals
+    formatUnits(balance, "8")
+  })
+
+  it("types its options", () => {
+    expectTypeOf(formatUnits)
+      .parameter(2)
+      .toEqualTypeOf<
+        { maxFractionDigits?: number; minFractionDigits?: number } | undefined
+      >()
+
+    formatUnits(balance, 8, {})
+    formatUnits(balance, 8, { maxFractionDigits: 2 })
+    formatUnits(balance, 8, { minFractionDigits: 2 })
+    // @ts-expect-error the digit counts are numbers
+    formatUnits(balance, 8, { maxFractionDigits: "2" })
+    // @ts-expect-error v3 had rounding modes; this cuts and never rounds
+    formatUnits(balance, 8, { roundingMode: "halfExpand" })
+    // @ts-expect-error v3 had a locale; format the plain text with Intl
+    formatUnits(balance, 8, { locale: "de-DE" })
+    // @ts-expect-error v3 had grouping; format the plain text with Intl
+    formatUnits(balance, 8, { useGrouping: true })
+    // @ts-expect-error v3 had trimTrailingZeros; minFractionDigits pads
+    formatUnits(balance, 8, { trimTrailingZeros: false })
+    // @ts-expect-error not an option
+    formatUnits(balance, 8, { decimals: 2 })
+  })
+})