| null | undefined` from a `DisplayReactor`; for a\nvariant error such as ICRC-1's `TransferError` it is `undefined`.\n\nFor an error value with a text `code` (the API shape), `message` is the value's\nown `message`: its text, or the text inside an `opt text`, which a `Reactor`\ndecodes as `[string]` and a `DisplayReactor` as the text itself, so both give\nOrbit's `\"Account not found\"`. Without one (an empty `opt`, say), `message` is\nthe value written as JSON. For any other error value it is\n`\"Canister Error: \"` followed by the value, written as JSON when it is an\nobject.\n\n`CanisterError.isApiError(value)` checks only that `value` has `code`,\n`message` and `details`. It narrows to `ApiError`, whose `message` and\n`details` are `unknown` unless you name them, as decoding decides their types:\n`ApiError<[] | [string], [] | [Array<[string, string]>]>` for Orbit's error\nthrough a `Reactor`.\n\n## Utilities\n\n### Token Amounts\n\nA ledger counts in base units (e8s, satoshis, wei): a `nat`, which a `Reactor`\nreturns as a `bigint` and a `DisplayReactor` as integer text. Converting through\n`Number` loses digits β `Math.floor(Number(\"0.29\") * 10 ** 8)` is `28999999`,\nso a transfer of 0.29 sends 0.28999999 β and a balance past 2^53 base units\n(9 Γ 10^7 ICP, or 0.009 of an 18-decimal token) prints wrong. `formatTokenAmount`\nand `parseTokenAmount` work on the digits, so they are exact for every amount:\n\n```typescript\nimport { formatTokenAmount, parseTokenAmount } from \"@ic-reactor/core\"\n\n// Base units β text. Takes a bigint, a DisplayReactor's text or a safe\n// integer, and decimals as a number, bigint or text.\nformatTokenAmount(150_000_000n, 8) // \"1.5\"\nformatTokenAmount(\"123456789\", 8, { maxFractionDigits: 2 }) // \"1.23\"\nformatTokenAmount(100_000_000n, 8, { minFractionDigits: 2 }) // \"1.00\"\nformatTokenAmount(123_456_789_000n, 8, { locale: \"de-DE\" }) // \"1.234,56789\"\n\n// Text a person typed β base units\nparseTokenAmount(\"0.29\", 8) // 29000000n\nparseTokenAmount(\"1.1\", 18) // 1100000000000000000n\nparseTokenAmount(\"0.123456789\", 8) // throws RangeError\n```\n\n`formatTokenAmount(value, decimals, options?)`:\n\n| Option | Default | Effect |\n| ------------------- | ------------------------ | ---------------------------------------------------------------------------------- |\n| `maxFractionDigits` | `decimals` | The most fraction digits to show; the rest are dropped as `roundingMode` says. |\n| `minFractionDigits` | `0` | Pad the fraction with zeros to at least this many digits. |\n| `trimTrailingZeros` | `true` | Drop zeros at the end of the fraction; `false` pads it to `maxFractionDigits`. |\n| `roundingMode` | `\"trunc\"` | `\"trunc\"` cuts, so a balance never shows more than is held; `\"halfExpand\"` rounds. |\n| `locale` | none | Separators, grouping and digits of a BCP 47 locale, through `Intl.NumberFormat`. |\n| `useGrouping` | `false`, or the locale's | Group thousands: `,` without a locale, the locale's own separator with one. |\n\nWithout a `locale` the text is plain (`-`, digits and `.`): the same on the\nserver and in every browser, and the form `parseTokenAmount` reads back. A\nnegative amount (an `int`) gets a leading `-` unless every digit shown is zero.\n\n`parseTokenAmount(text, decimals, { allowNegative? })` takes digits with at\nmost one `.`, trimming whitespace around them, and accepts `\"5.\"` and `\".5\"`.\nIt refuses the rest rather than guess:\n\n- a blank value, letters, grouping (`\"1,000\"`), an exponent (`\"1e-8\"`) or a\n sign other than `-`: `TypeError`;\n- more fraction digits than the token has, unless the extra ones are zeros:\n `RangeError`, since rounding would send something other than what was typed;\n- a negative amount, unless `allowNegative: true`: `RangeError`. A ledger's\n amounts are `nat`.\n\nIt returns a `bigint`, which a `Reactor` takes as it is. A `DisplayReactor`\ntakes a `nat` as text, so pass it `amount.toString()`.\n\n### Principal Text\n\n`isPrincipalText(value)` tells whether a value is the text of a principal β a\nuser, a canister, `aaaaa-aa` or the anonymous `2vxsx-fae` β so a form can check\na pasted recipient without a `try` around `Principal.fromText`:\n\n```typescript\nimport { isPrincipalText } from \"@ic-reactor/core\"\n\nconst to = input.trim()\nif (!isPrincipalText(to)) {\n setError(\"Enter a principal such as ryjl3-tyaaa-aaaaa-aaaba-cai\")\n} else {\n // DisplayReactor: pass `to`. Reactor: pass Principal.fromText(to).\n}\n```\n\nIt is `true` exactly when the text is the canonical text of a principal of at\nmost 29 bytes, the most the Internet Computer accepts: lowercase with its dashes\nand checksum, and no whitespace. The JSON form `{\"__principal__\":\"β¦\"}`, which\n`Principal.fromText` also reads, is refused. It returns a `boolean` rather than\nnarrowing, so a `string` it refuses stays a `string`.\n\n### JSON for Display\n\n`jsonToString(value)` writes a call's result as JSON indented by two spaces, for\na `` or a log line. `JSON.stringify` throws on a `bigint` and writes a\n`Principal` as `{\"__principal__\":\"β¦\"}` and a `Uint8Array` as an object keyed by\nindex, so `jsonToString` writes a raw `Reactor` value the way a `DisplayReactor`\nshows it: a `bigint` as its digits, a `Principal` as its text, a `Uint8Array`\nas lowercase hex, and any other typed array as an array of numbers. Other\nvalues are written as `JSON.stringify(value, null, 2)` writes them.\n\n```typescript\nimport { jsonToString } from \"@ic-reactor/core\"\n\njsonToString({ owner: principal, amount: 5n, memo: [new Uint8Array([1, 2])] })\n// { \"owner\": \"aaaaa-aa\", \"amount\": \"5\", \"memo\": [\"0102\"] }, indented\n```\n\nThe text is for reading: it does not record which strings were numbers,\nprincipals or bytes, so it does not parse back into the value.\n\n### Result Unwrapping\n\nA method returning `variant { Ok : T; Err : E }` does not hand you the raw\nvariant. The Reactor's default `transformResult` unwraps it, so `data` is `T`\nand an `Err` is thrown as a `CanisterError` carrying the `Err` payload β which\nmeans it reaches the query/mutation `error` channel rather than `data`. This\nhappens at the candid-decoded layer, after the call has already succeeded at the\ntransport level, so a canister-level `Err` stays distinguishable from a\n`CallError`.\n\nDeclare the service with the raw candid shape; the unwrapping applies on top of\nit, and `ReactorReturnOk` is the type the hooks actually give you. The thrown\n`CanisterError` carries the raw payload on `.err`.\n\nTo keep the raw variant instead, override `transformResult` on a Reactor\nsubclass β that is the only way, since `callMethod()` passes its decoded\nresponse through `transformResult` as well.\n\nThe same logic is exported as `extractOkResult`, which handles both uppercase\n(`Ok`/`Err`) and lowercase (`ok`/`err`) variants:\n\n```typescript\nimport { extractOkResult } from \"@ic-reactor/core\"\n\n// Candid: Result\n// Returns the Ok value or throws CanisterError with the Err value\nconst result = extractOkResult({ Ok: \"success\" }) // \"success\"\nconst result2 = extractOkResult({ ok: \"success\" }) // \"success\"\n```\n\n### Query Key Generation\n\n```typescript\nconst queryKey = reactor.generateQueryKey({\n functionName: \"get_user\",\n args: [\"user-123\"],\n})\n// [reactor.canisterId.toString(), \"get_user\", '[\"user-123\"]']\n\nconst scopedKey = reactor.generateQueryKey(\n {\n functionName: \"get_user\",\n args: [\"user-123\"],\n },\n {\n canisterId: otherCanisterId,\n effectiveCanisterId: managementCanisterId, // optional\n }\n)\n// [otherCanisterId, \"get_user\", { effectiveTarget: { canisterId: managementCanisterId } }, '[\"user-123\"]']\n```\n\nThe key shape is\n`[resolvedCanisterId, functionName, { transform }?, { agent }?, { effectiveTarget }?, argKey?, ...queryKey]`.\nThe `{ transform }` segment is present whenever the reactor's transform is not\n`\"candid\"`, so the keys above are a `Reactor`'s. A `DisplayReactor` key carries\n`{ transform: \"display\" }`: the first call above returns\n`[canisterId, \"get_user\", { transform: \"display\" }, '[\"user-123\"]']`, and a\n`Reactor` and a `DisplayReactor` over one canister never share a cache entry.\n`argKey` is a single string, not the individual arguments: the arguments\nserialized as JSON with `bigint` rendered as a decimal string and the keys of\nevery plain object sorted, so `{ b, a }` and `{ a, b }` give the same key. A\nbare `JSON.stringify(args)` does not match it once a record's fields are out of\nalphabetical order. A blob is written as a tag followed by its lowercase hex, so\na `Uint8Array`, a `number[]` and a `DisplayReactor`'s hex text holding the same\nbytes give the same key. A `DisplayReactor` writes each `opt` and variant in one\nform, whichever it was given in, so an `opt` given bare or as `[value]`, none\ngiven as `null`, `undefined` or `[]`, and a variant given with or without\n`_type` give the same key. A `vec record { text; T }` given to it as an object\nor a `Map` is written as its entries in order, since the order is part of what\nit sends. A record or variant given to it as a class instance is written as the\nplain object its codec sends, a field its class supplies through a getter\nincluded. Fields a record does not declare are left out and every value of `reserved` is written as\n`null`, since neither is sent, and a `DisplayReactor` writes a float or an\ninteger of 32 bits or fewer given as text as its number, and a `Principal` as\nits text. An argument the reactor refuses, such as `undefined` where Candid\n`null` is required or a bigint where a `DisplayReactor` takes text, is written\nbehind a tag of its own, so the call fails instead of being answered from the\ncache entry of an argument it takes. The\n`{ effectiveTarget }` segment is dropped when it names\nthe same canister the key is already rooted at, and any custom `queryKey` is\nappended element-wise. Build keys with `generateQueryKey` (or a query object's\n`getQueryKey()`) rather than by hand.\n\nIf you pass `callConfig` to `fetchQuery`, `getQueryOptions`, the bound query\nhooks (`useActorQuery`, `useActorSuspenseQuery` and the two infinite-query\nhooks) or `createInfiniteQuery` / `createSuspenseInfiniteQuery`, use the same\n`callConfig` when generating or looking up query keys. `createQuery`,\n`createSuspenseQuery` and their `...Factory` variants take no `callConfig`: a\nconfig that carries one fails with TS2353. The cache key is partitioned by the\nresolved target canister and, when present, `effectiveCanisterId` and\n`callConfig.agent`.\n\nA `callConfig.agent` that is not the `ClientManager`'s own agent adds an\n`{ agent: n }` segment after `{ transform }` and before `argKey`, where `n`\nnumbers that agent within the running process. The same query through that\nagent and through the manager's agent are two cache entries, since each is\nanswered for its own identity or network. Keys without an override are\nunchanged, `invalidateQueries({ functionName })` matches both entries, and\n`updateAgent()` sweeps both. Each process counts from a random start, so an\noverride entry in a dehydrated server cache, or in a cache persisted and\nrestored later, is not found by another process's agents.\n\nQuery keys name the canister, not the `ClientManager`. Two `ClientManager`s on\nthe same canister (two identities, or a local replica and mainnet) must each\nget their own `QueryClient`: sharing one, their reactors share cache entries,\nand one manager's `updateAgent()` sweeps the other's. `defineReactor` builds a\n`QueryClient` per manager by default.\n\n## TypeScript Types\n\n### Actor Types\n\n```typescript\nimport type {\n FunctionName, // Method names from actor service\n ActorMethodParameters, // Parameter types for a method\n ActorMethodReturnType, // Return type for a method\n ReactorArgs, // Args with optional transforms\n ReactorReturnOk, // Return type (Ok extracted from Result)\n ReactorReturnErr, // Error type (Err from Result)\n} from \"@ic-reactor/core\"\n```\n\n### Types From a Reactor\n\nThe same types, read off a reactor instance with `typeof`, so neither the\nservice type nor the transform has to be spelled out:\n\n```typescript\nimport type {\n ServiceOf, // The reactor's service type\n TransformOf, // \"candid\", \"display\", or a subclass's transform\n ReactorArgsOf, // ReactorArgs\n ReactorDataOf, // ReactorReturnOk\n ReactorErrorOf, // ReactorReturnErr\n} from \"@ic-reactor/core\"\nimport { DisplayReactor } from \"@ic-reactor/core\"\n\nconst ledger = new DisplayReactor({\n clientManager,\n idlFactory,\n name: \"ledger\",\n})\n\ntype Account = ReactorArgsOf[0] // { owner: string; ... }\ntype Balance = ReactorDataOf // string\ntype TransferError = ReactorErrorOf\n```\n\n### State Types\n\n```typescript\nimport type { AgentState } from \"@ic-reactor/core\"\n\nconst state: AgentState = clientManager.agentState\nstate.isInitialized // boolean\nstate.isInitializing // boolean\nstate.error // Error | undefined\nstate.network // string | undefined\nstate.isLocalhost // boolean\n```\n\n`AuthState` is exported by [`@ic-reactor/react`](../react), not by this package:\n\n```typescript\nimport type { AuthState } from \"@ic-reactor/react\"\n```\n\n## Advanced Usage\n\n### Multiple Canisters\n\n```typescript\nimport { ClientManager, DisplayReactor, Reactor } from \"@ic-reactor/core\"\n\nconst clientManager = new ClientManager({ queryClient })\n\n// All reactors share the same agent and identity\nconst backend = new Reactor({\n clientManager,\n idlFactory: backendIdl,\n name: \"backend\",\n canisterId: \"...\",\n})\nconst ledger = new DisplayReactor({\n clientManager,\n idlFactory: ledgerIdl,\n name: \"ledger\",\n canisterId: \"...\",\n})\nconst nft = new Reactor({\n clientManager,\n idlFactory: nftIdl,\n name: \"nft\",\n canisterId: \"...\",\n})\n\n// Sign in once (via @ic-reactor/react) β every reactor picks up the identity\nawait authentication.login()\n```\n\nFor several canisters of one interface, such as the ICRC ledgers of a\nmulti-token wallet, build one reactor and ask it for the others with\n`forCanister(canisterId)`. Each sibling is the same class on the same\n`ClientManager`, starts with the reactor's interface, polling options and (for\na `DisplayReactor`) validators, and keys its queries by its own canister. The\nsame id always gives the same sibling:\n\n```typescript\nimport { DisplayReactor } from \"@ic-reactor/core\"\n\nconst icp = new DisplayReactor({\n clientManager,\n idlFactory: ledgerIdl,\n name: \"ledger\",\n canisterId: \"ryjl3-tyaaa-aaaaa-aaaba-cai\",\n})\n\nconst ckbtc = icp.forCanister(\"mxzaz-hqaaa-aaaar-qaada-cai\")\nconst [icpSymbol, ckbtcSymbol] = await Promise.all([\n icp.fetchQuery({ functionName: \"icrc1_symbol\" }),\n ckbtc.fetchQuery({ functionName: \"icrc1_symbol\" }),\n])\n```\n\nPrefer it to `setCanisterId`, which retargets one shared reactor and every\nview built on it at once.\n\n### Custom Polling Options\n\n`pollingOptions` is the `PollingOptions` type from `@icp-sdk/core/agent`. The\nreactor hands the same object to every update call, so a `strategy` set here\npolls all of them. `createPollingStrategy` is built to be shared that way: it\nkeeps a separate attempt count, clock and timeout for each request.\n\n```typescript\nimport { Reactor, createPollingStrategy } from \"@ic-reactor/core\"\n\nconst backend = new Reactor<_SERVICE>({\n clientManager,\n idlFactory,\n name: \"backend\",\n canisterId: \"...\",\n pollingOptions: {\n // Give up on a request that is still pending after two minutes\n // (the default is five).\n strategy: createPollingStrategy({ timeoutMs: 120_000 }),\n },\n})\n```\n\nLeave `strategy` out and the agent builds a fresh `defaultStrategy()` for each\nrequest.\n\nDon't put `defaultStrategy()`, or any other strategy from\n`@icp-sdk/core/agent`, in the reactor's `pollingOptions`. Those are made for a\nsingle request: `defaultStrategy()` starts its five-minute timeout when it is\ncreated and keeps one backoff for everything it polls. Five minutes after the\nreactor is built, every update call still pending at its first poll fails with\n`Request timed out after 300000 msec`. To use one, create it for the call:\n\n```typescript\nimport { defaultStrategy } from \"@icp-sdk/core/agent\"\n\nconst result = await backend.callMethod({\n functionName: \"transfer\",\n args: [transferArgs],\n callConfig: { pollingOptions: { strategy: defaultStrategy() } },\n})\n```\n\n### Direct Agent Access\n\n```typescript\nimport { StatePaths } from \"@icp-sdk/core/agent\"\n\n// Get subnet ID\nconst subnetId = await backend.subnetId()\n\n// Read subnet state: the well-known paths are on StatePaths\nconst state = await backend.subnetState({ paths: [StatePaths.time] })\n\n// Access underlying agent\nconst agent = backend.agent\n```\n\n## Testing\n\n`@ic-reactor/core/testing` runs code that uses IC Reactor against a fake\nreplica, with no replica to start and no `Reactor` stub to cast.\n`installFakeReplica` replaces the global `fetch` and answers the agent with the\ncanisters you give it; `createTestCanister` builds one from handlers typed from\nyour service. `ClientManager`, `Reactor`, `DisplayReactor`, query keys and error\nunwrapping all run as in production.\n\n```typescript\nimport { afterEach, beforeEach, expect, it } from \"vitest\"\nimport { QueryClient } from \"@tanstack/query-core\"\nimport { ClientManager, Reactor } from \"@ic-reactor/core\"\nimport {\n createTestCanister,\n installFakeReplica,\n type FakeReplica,\n} from \"@ic-reactor/core/testing\"\nimport { idlFactory, type _SERVICE } from \"./declarations/backend\"\n\nconst BACKEND = \"bkyz2-fmaaa-aaaaa-qaaaq-cai\"\nlet replica: FakeReplica\n\nbeforeEach(() => {\n replica = installFakeReplica({\n canisters: {\n [BACKEND]: createTestCanister<_SERVICE>(idlFactory, {\n // Decoded arguments and the verified caller in, a Candid result out.\n greet: ([name], { caller }) => `Hello, ${name} (${caller.toText()})`,\n }),\n },\n })\n})\nafterEach(() => replica.restore())\n\nit(\"greets\", async () => {\n // Built after the fake is installed: an agent keeps the fetch it found.\n const backend = new Reactor<_SERVICE>({\n clientManager: new ClientManager({\n queryClient: new QueryClient(),\n agentOptions: { host: replica.host },\n }),\n name: \"backend\",\n canisterId: BACKEND,\n idlFactory,\n })\n\n await expect(\n backend.fetchQuery({ functionName: \"greet\", args: [\"Ada\"] })\n ).resolves.toBe(\"Hello, Ada (2vxsx-fae)\")\n})\n```\n\n- Return `{ Err: ... }` from a handler to get a `CanisterError`; throw to get\n the `CallError` of a canister trap.\n- Sign in with `clientManager.updateAgent(Ed25519KeyIdentity.generate())`; the\n fake checks request signatures and passes the caller to each handler.\n- `replica.requests` lists every request the fake received.\n- The fake answers the IC API on `replica.host` only, and fails (and logs\n once) an IC API request to any other origin without touching the network.\n With no `host` it answers where a `ClientManager` with no `host` calls: the\n page's origin in jsdom or happy-dom, `http://127.0.0.1:4943` in plain Node.\n Every other request goes to the `fetch` it replaced.\n\nThe main entry never imports this entry point. It signs with `@noble/curves`,\nan optional peer dependency that `@icp-sdk/core` already installs; add it as a\ndevDependency only under a strict package manager. See the\n[Testing guide](https://ic-reactor.b3pay.net/v3/guides/testing).\n\n## Documentation\n\nFor comprehensive guides and API reference, visit the [documentation site](https://ic-reactor.b3pay.net/v3).\n\n## License\n\nMIT Β© [Behrad Deylami](https://github.com/b3hr4d)\n","readmeFilename":"README.md"}