Add useSubscription for rendering based on a subscription#1702
Open
mcintyre94 wants to merge 1 commit into
Open
Add useSubscription for rendering based on a subscription#1702mcintyre94 wants to merge 1 commit into
useSubscription for rendering based on a subscription#1702mcintyre94 wants to merge 1 commit into
Conversation
🦋 Changeset detectedLatest commit: 25f6fbb The changes in this PR will be included in the next version bump. This PR includes changesets to release 47 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
This was referenced May 26, 2026
Member
Author
BundleMonFiles updated (25)
Unchanged files (122)
Total files change +8.28KB +1.57% Final result: ✅ View report in BundleMon website ➡️ |
Contributor
|
Documentation Preview: https://kit-docs-86cap6a31-anza-tech.vercel.app |
Member
Author
trevor-cortex
left a comment
trevor-cortex
left a comment
There was a problem hiding this comment.
Adds a useSubscription hook that is a near-perfect mirror of useRequest for ReactiveStreamSources, plus a disabledStreamStore companion for the null-source case. Composition is clean: useSubscription owns lifecycle (memo store, effect connect+reset, ref-synced getAbortSignal, stable reconnect), useSubscriptionResult does the useSyncExternalStore bridge and the SolanaRpcResponse unwrap via splitSolanaRpcResponse. The pattern matches useRequest / useRequestResult so closely that someone who already understands one can read the other immediately — which is exactly the right outcome here.
Things to watch out for:
index.tsexport ordering is broken.useSubscriptionis inserted betweenuseSignAndSendTransactionanduseSignIn, which puts it out of alphabetical order with theuseSign*cluster. Should sit afteruseSignTransactioninstead. Trivial fix; flagging inline.- SSR snapshot getter passed to
useSyncExternalStore.useSubscriptionResultpassesstore.getUnifiedStateas both the client and server snapshot getter — that's what makes the SSR test pass without React warning about a missing server snapshot, and it's only correct becauseIDLE_STATE/IDLE_STREAM_STATEare frozen singletons with stable identity. Worth noting thatuseRequestResultdoesn't currently pass a server snapshot at all, so there's a small inconsistency between the two bridges — not a blocker for this PR, but probably worth a follow-up to bringuseRequestResultin line (or document why it doesn't need it). slotafterloaded→error. The docblock forSubscriptionResult.slotlists when it'sundefined(loading / disabled / server / error-only). After a successfulloadedthat transitions toerror, the stale envelope is preserved instate.dataandsplitSolanaRpcResponsewill keep returning the staleslot. That's the right SWR behaviour, and the docs aren't wrong, but the "when only an error has arrived" qualifier is doing more work than it looks — readers may assumeerroralways nukesslot. Optional: a short note thatslotfollowsdata(stale onerrorafter a priorloaded).
Notes for subsequent reviewers:
- The fake subscription helper in
useSubscription-test.browser.tsxrelies on the store binding both thedataanderrorchannels via.on()on everyconnect()— it counts to 2 before resolvingpublisherReady. IfcreateReactiveStoreFromDataPublisherFactory's binding order or channel count ever changes, that handshake silently deadlocks. Worth a peek if you're touching the underlying store. - The
useEffect([store])cleanup ordering matters under StrictMode and source identity changes: cleanup runsstore.reset()on the previous store closure, then the new store'sconnect()fires. The fake's listener-array reset insidecreateDataPublisheris what makes the "aborts the prior connection's listeners when the source identity changes" test pass cleanly — confirmed by reading through; just calling out where the invariant lives in case it's not obvious. - The
disabledStreamStoretests are thorough (frozen state, no-opconnect/reset/retry/withSignal, no-notifysubscribe). Coverage of the disabled path is solid. - Typetest covers the unwrap on both envelope and raw shapes, the null-source case, the presence-based
reconnectAPI, and asserts the status union doesn't leak the action-store'success'vocabulary. Good signal-to-noise.
Comment on lines
+36
to
+31
| reconnect: (options?: { abortSignal?: AbortSignal | undefined }) => void, | ||
| disabled: boolean, | ||
| ): SubscriptionResult<UnwrapRpcResponse<T>> { | ||
| const state = useSyncExternalStore(store.subscribe, store.getUnifiedState, store.getUnifiedState); |
There was a problem hiding this comment.
Worth noting that this passes store.getUnifiedState as the server snapshot (3rd arg) — useRequestResult doesn't. The reason this is correct here is that idle state is a frozen singleton with stable identity, so the server and client snapshots match on first paint and useSyncExternalStore doesn't warn. Probably worth a follow-up to bring useRequestResult in line (its current 2-arg form likely triggers a React SSR warning in dev). Not a blocker for this PR.
Member
Author
There was a problem hiding this comment.
Updated useAction and useRequest to use the same pattern in their PRs
mcintyre94
force-pushed
the
react/use-subscription
branch
from
cc6b909 to
72a4b00
Compare
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
8dcf3dd to
3aa3b8a
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
from
72a4b00 to
af665ca
Compare
This was referenced May 27, 2026
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
3aa3b8a to
ac893f1
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
3 times, most recently
from
624e92f to
9ea41a8
Compare
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
ac893f1 to
2606839
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
2 times, most recently
from
67b86de to
b384ab6
Compare
This was referenced May 28, 2026
lorisleiva
reviewed
May 29, 2026
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
2606839 to
bb281ff
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
from
b384ab6 to
91c17e6
Compare
This was referenced May 30, 2026
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
bb281ff to
611f542
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
from
91c17e6 to
086ac26
Compare
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
611f542 to
9fefb8f
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
2 times, most recently
from
973fcc8 to
2d3ae0e
Compare
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
9fefb8f to
02d93ac
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
from
2d3ae0e to
8bd304c
Compare
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
2 times, most recently
from
5b68fd4 to
b9d4e6b
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
from
8bd304c to
3b21574
Compare
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
b9d4e6b to
4db12b0
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
from
3b21574 to
613df77
Compare
mcintyre94
added
the
do-not-close
`useSubscription(source)` opens a stream-store subscription on mount, re-opens whenever the source identity changes, and tears it down on unmount. The source is any `ReactiveStreamSource<T>` — `PendingRpcSubscriptionsRequest` is the canonical implementation. Pass `null` to disable.
The hook mirrors `useRequest`'s structure exactly: construct the lazy store via `useMemo`, fire `store.connect()` in a `useEffect`, tear down via `store.reset()` in cleanup. Same StrictMode-safe lifecycle pattern (mount → cleanup aborts → mount re-fires), same vocabulary, same per-call signal API.
The hook returns `{ data, error, reconnect, slot, status }`. Status is one of `loading | loaded | error | disabled`. After a notification arrives, an error-channel publish transitions to `error` while preserving the stale `data`; `reconnect()` returns to `loading` (preserving stale `data` and `error` for stale-while-revalidate) before settling on `loaded` or a fresh `error`. The bridge maps the store's `idle` state to `loading` when enabled (matching the about-to-commit-effect render) and to `disabled` when the source is null.
Notifications shaped as `SolanaRpcResponse<U>` (account/program/signature) are unwrapped via `isSolanaRpcResponse` from `@solana/rpc-types`: `data` is the inner value `U` and `slot` is lifted from `context.slot`. Raw notifications (slot/logs/root) pass through with `slot: undefined`. The `UnwrapRpcResponse<T>` conditional type (also from `@solana/rpc-types`) tracks the runtime unwrap at the type level.
Optional `getAbortSignal: () => AbortSignal` is invoked on every connection (initial subscribe + every `reconnect()`). The returned signal is composed with the store's per-connection controller via `AbortSignal.any` through `withSignal(signal).connect()`. The natural use is per-connection timeouts (`() => AbortSignal.timeout(30_000)`), which reset on reconnect. Factory is ref-synced — inline closures are fine. `reconnect()` accepts an optional `{ abortSignal }` override for one specific attempt; presence-based semantics distinguish "use factory" (omit the key), "explicit signal" (`{ abortSignal: signal }`), and "no signal" (`{ abortSignal: undefined }`).
SSR-safe: on the server the connect effect doesn't run, so the store stays `idle` and the hook reports `status: 'loading'`. The first client render hydrates from the same paint and commits the connect.
Adds `disabledStreamStore<T>()` to `staticStores.ts` — the stream-store analogue of `disabledActionStore` for the null-source case. Pinned by new tests alongside the existing `disabledActionStore` invariants.
Exports `SubscriptionResult<T>` and `UseSubscriptionOptions` for plugin hooks to build on.
mcintyre94
force-pushed
the
rpc-types/unwrap-rpc-response
branch
from
4db12b0 to
570cb6c
Compare
mcintyre94
force-pushed
the
react/use-subscription
branch
from
613df77 to
25f6fbb
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary of Changes
This PR adds the
useSubscriptionhook:This is a subscription analog to
useRequest. It uses thereactiveStreamStorestate machine, and immediately initialises the subscription on mount.The expected input is a
ReactiveStreamSource, the current implementation in Kit is a pending RPC subscriptions object. But eg. plugins could also publish their ownReactiveStreamSourceof the shapereactiveStore(): ReactiveStreamStoreand that would also work with this.As with
useRequestthe hook takes an optionalgetAbortSignalwhich creates an abort signal per connect (initial and calls toreconnect). The call toreconnectcan optionally override this per call.