Add framework-agnostic source types for reactive bindings

.changeset/open-cameras-sit.md

@@ -0,0 +1,17 @@
+---
+'@solana/subscribable': minor
+'@solana/kit': minor
+---
+
+Add framework-agnostic source duck-types for reactive bindings.
+
+`@solana/subscribable` now exports two new types:
+
+- `ReactiveStreamSource<T>` — anything with a `reactiveStore({ abortSignal })` method that returns a `ReactiveStreamStore<T>`. `PendingRpcSubscriptionsRequest<T>` satisfies this by design.
+- `ReactiveActionSource<T>` — anything with a zero-argument `reactiveStore()` method that returns a `ReactiveActionStore<[], T>`. `PendingRpcRequest<T>` satisfies this by design.
+
+These let reactive-framework bindings consume a single duck-type instead of naming concrete producer types — and let plugin authors expose their own pending-request objects to those bindings without modification.
+
+Both source types live in `@solana/subscribable` and are not re-exported from `@solana/kit`, matching the existing convention for their parent `ReactiveStreamStore` / `ReactiveActionStore` types — anyone consuming a source duck-type is already in the reactive-primitives layer and will already be importing the related store types from the same package.
+
+`@solana/kit` now publicly exports the previously-private `CreateReactiveStoreWithInitialValueAndSlotTrackingConfig` type so non-React consumers (e.g. plugins) can declare function return shapes based on it without taking a dependency on `@solana/react`.

packages/kit/src/create-reactive-store-with-initial-value-and-slot-tracking.ts

@@ -3,7 +3,18 @@ import type { PendingRpcSubscriptionsRequest } from '@solana/rpc-subscriptions';
 import type { SolanaRpcResponse } from '@solana/rpc-types';
 import type { ReactiveState, ReactiveStreamStore } from '@solana/subscribable';
 
-type CreateReactiveStoreWithInitialValueAndSlotTrackingConfig<TRpcValue, TSubscriptionValue, TItem> = Readonly<{
+/**
+ * Configuration for {@link createReactiveStoreWithInitialValueAndSlotTracking}. Pairs a one-shot
+ * RPC fetch with an ongoing subscription so the resulting store can hydrate from the initial
+ * response and keep up to date with notifications, slot-deduplicating the two streams.
+ *
+ * @typeParam TRpcValue - The value type returned by `rpcRequest` (inside the {@link SolanaRpcResponse} envelope).
+ * @typeParam TSubscriptionValue - The value type emitted by `rpcSubscriptionRequest` (inside the {@link SolanaRpcResponse} envelope).
+ * @typeParam TItem - The unified item type the store holds, produced by the two value mappers.
+ *
+ * @see {@link createReactiveStoreWithInitialValueAndSlotTracking}
+ */
+export type CreateReactiveStoreWithInitialValueAndSlotTrackingConfig<TRpcValue, TSubscriptionValue, TItem> = Readonly<{
     /**
      * Triggering this abort signal will cancel the pending RPC request and subscription, and
      * disconnect the store from further updates.

packages/rpc-spec/src/__typetests__/reactive-action-source-typetest.ts

@@ -0,0 +1,8 @@
+import type { ReactiveActionSource } from '@solana/subscribable';
+
+import { PendingRpcRequest } from '../rpc';
+
+// `PendingRpcRequest<T>` is structurally assignable to `ReactiveActionSource<T>` — the duck-type
+// reactive-framework bindings consume so they don't have to name a concrete producer type.
+null as unknown as PendingRpcRequest<number> satisfies ReactiveActionSource<number>;
+null as unknown as PendingRpcRequest<{ foo: string }> satisfies ReactiveActionSource<{ foo: string }>;

packages/rpc-subscriptions-spec/src/__typetests__/reactive-stream-source-typetest.ts

@@ -0,0 +1,11 @@
+import type { ReactiveStreamSource } from '@solana/subscribable';
+
+import { PendingRpcSubscriptionsRequest } from '../rpc-subscriptions-request';
+
+// `PendingRpcSubscriptionsRequest<T>` is structurally assignable to `ReactiveStreamSource<T>` —
+// the duck-type reactive-framework bindings consume so they don't have to name a concrete
+// producer type.
+null as unknown as PendingRpcSubscriptionsRequest<number> satisfies ReactiveStreamSource<number>;
+null as unknown as PendingRpcSubscriptionsRequest<{ foo: string }> satisfies ReactiveStreamSource<{
+    foo: string;
+}>;

packages/subscribable/src/reactive-action-store.ts

@@ -48,6 +48,28 @@ export type ReactiveActionStore<TArgs extends readonly unknown[], TResult> = {
     readonly subscribe: (listener: () => void) => () => void;
 };
 
+/**
+ * Duck-type for objects that build a {@link ReactiveActionStore} on demand via a zero-argument
+ * `reactiveStore()` method. Satisfied by `PendingRpcRequest<T>`. The `[]` argument tuple is
+ * intentional — the operation's arguments are already baked into the pending request, so each
+ * `dispatch()` re-fires the same call.
+ *
+ * @typeParam T - The value type resolved by the wrapped operation.
+ *
+ * @example
+ * ```ts
+ * function bind<T>(source: ReactiveActionSource<T>) {
+ *     return source.reactiveStore();
+ * }
+ * ```
+ *
+ * @see {@link ReactiveActionStore}
+ * @see {@link ReactiveStreamSource}
+ */
+export type ReactiveActionSource<T> = {
+    reactiveStore(): ReactiveActionStore<[], T>;
+};
+
 const IDLE_STATE: ReactiveActionState<never> = Object.freeze({
     data: undefined,
     error: undefined,

packages/subscribable/src/reactive-stream-store.ts

@@ -131,6 +131,28 @@ export type ReactiveStreamStore<T> = {
  */
 export type ReactiveStore<T> = ReactiveStreamStore<T>;
 
+/**
+ * Duck-type for objects that build a {@link ReactiveStreamStore} on demand via a
+ * `reactiveStore({ abortSignal })` method. Satisfied by `PendingRpcSubscriptionsRequest<T>`.
+ * Reactive-framework bindings (e.g. React's `useSubscription`) consume this duck-type so they
+ * don't have to name a concrete producer type.
+ *
+ * @typeParam T - The value type emitted by the resulting stream store.
+ *
+ * @example
+ * ```ts
+ * function bind<T>(source: ReactiveStreamSource<T>, abortSignal: AbortSignal) {
+ *     return source.reactiveStore({ abortSignal });
+ * }
+ * ```
+ *
+ * @see {@link ReactiveStreamStore}
+ * @see {@link ReactiveActionSource}
+ */
+export type ReactiveStreamSource<T> = {
+    reactiveStore(options: { abortSignal: AbortSignal }): ReactiveStreamStore<T>;
+};
+
 /**
  * Returns a {@link ReactiveStreamStore} given a data publisher.
  *