Add RpcSendable / RpcSubscribable duck-types and loosen reactive-store config

Add `RpcSendable<T>` to `@solana/rpc-spec` and `RpcSubscribable<T>` to `@solana/rpc-subscriptions-spec` — structural duck-types covering just `send({ abortSignal })` and `subscribe({ abortSignal })` respectively. Both are intentionally narrower than the concrete `PendingRpcRequest<T>` / `PendingRpcSubscriptionsRequest<T>`, which also expose `reactiveStore()`. Use them at consumer boundaries to accept request-like objects without forcing producers to implement the full store-bearing shape.

Loosens the `rpcRequest` and `rpcSubscriptionRequest` fields on `CreateReactiveStoreWithInitialValueAndSlotTrackingConfig` (exported) and the internal config for `createAsyncGeneratorWithInitialValueAndSlotTracking` to use the new types. Both primitives only ever call `.send()` and `.subscribe()` on their inputs, so the previous `Pending*Request` constraint was over-tight — existing callers passing concrete `rpc.getAccountInfo(addr)` / `rpcSubscriptions.accountNotifications(addr)` results still satisfy the loosened types structurally.

Motivation: plugin-authored wrappers (caching layers, request batchers, request dedup) and test mocks no longer need to stub out an unused `reactiveStore()` method just to satisfy the type. Parallels the existing `ReactiveStreamSource<T>` / `ReactiveActionSource<T>` duck-types in `@solana/subscribable` — same pattern, applied to the producer side of one-shot and subscription requests.

Author: mcintyre94

.changeset/empty-deserts-happen.md

@@ -0,0 +1,23 @@
+---
+'@solana/rpc-spec': minor
+'@solana/rpc-subscriptions-spec': minor
+'@solana/kit': minor
+---
+
+Add `RpcSendable<T>` and `RpcSubscribable<T>` structural duck-types alongside the concrete `PendingRpcRequest<T>` and `PendingRpcSubscriptionsRequest<T>`. Both new types are intentionally narrower — `RpcSendable<T>` covers just `send({ abortSignal })` and `RpcSubscribable<T>` covers just `subscribe({ abortSignal })` — so consumers (higher-level kit helpers, plugin-authored wrappers, test mocks) can accept request-like objects without taking on the full `{ reactiveStore, send }` / `{ reactiveStore, subscribe }` shape.
+
+```ts
+import type { RpcSendable, RpcSubscribable } from '@solana/kit';
+
+type RpcSendable<TResponse> = {
+    send(options?: RpcSendOptions): Promise<TResponse>;
+};
+
+type RpcSubscribable<TNotification> = {
+    subscribe(options: RpcSubscribeOptions): Promise<AsyncIterable<TNotification>>;
+};
+```
+
+`PendingRpcRequest<T>` still structurally satisfies `RpcSendable<T>`; `PendingRpcSubscriptionsRequest<T>` still satisfies `RpcSubscribable<T>`. No change at producer boundaries (`rpc.<method>(...)` / `rpcSubscriptions.<method>(...)` returns).
+
+Loosens the `rpcRequest` / `rpcSubscriptionRequest` fields on `CreateReactiveStoreWithInitialValueAndSlotTrackingConfig` (exported) and the internal config for `createAsyncGeneratorWithInitialValueAndSlotTracking` from `PendingRpcRequest<...>` / `PendingRpcSubscriptionsRequest<...>` to `RpcSendable<...>` / `RpcSubscribable<...>` — both primitives only ever call `.send()` and `.subscribe()` on those inputs, so they now accept any compatible duck-type. Existing callers passing concrete `Pending*Request` objects continue to work.

packages/kit/src/__tests__/create-async-generator-with-initial-value-and-slot-tracking-test.ts

@@ -1,22 +1,19 @@
-import type { PendingRpcRequest } from '@solana/rpc';
-import type { PendingRpcSubscriptionsRequest } from '@solana/rpc-subscriptions';
+import type { RpcSendable } from '@solana/rpc';
+import type { RpcSubscribable } from '@solana/rpc-subscriptions';
 import type { SolanaRpcResponse } from '@solana/rpc-types';
 
 import { createAsyncGeneratorWithInitialValueAndSlotTracking } from '../create-async-generator-with-initial-value-and-slot-tracking';
 
 type TestValue = { count: number };
 
 function createMockRpcRequest(): {
-    mockRequest: PendingRpcRequest<SolanaRpcResponse<TestValue>>;
+    mockRequest: RpcSendable<SolanaRpcResponse<TestValue>>;
     reject(error: unknown): void;
     resolve(response: SolanaRpcResponse<TestValue>): void;
 } {
     const { promise, resolve, reject } = Promise.withResolvers<SolanaRpcResponse<TestValue>>();
     return {
         mockRequest: {
-            reactiveStore: jest.fn().mockImplementation(() => {
-                throw new Error('not implemented');
-            }),
             send: jest.fn().mockReturnValue(promise),
         },
         reject,
@@ -27,7 +24,7 @@ function createMockRpcRequest(): {
 function createMockSubscriptionRequest(): {
     complete(): void;
     error(err: unknown): void;
-    mockRequest: PendingRpcSubscriptionsRequest<SolanaRpcResponse<TestValue>>;
+    mockRequest: RpcSubscribable<SolanaRpcResponse<TestValue>>;
     pushNotification(notification: SolanaRpcResponse<TestValue>): void;
 } {
     const notifications: SolanaRpcResponse<TestValue>[] = [];
@@ -93,9 +90,6 @@ function createMockSubscriptionRequest(): {
         complete,
         error,
         mockRequest: {
-            reactiveStore: jest.fn().mockImplementation(() => {
-                throw new Error('not implemented');
-            }),
             subscribe: jest.fn().mockResolvedValue(asyncIterable),
         },
         pushNotification,

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

@@ -1,22 +1,19 @@
-import type { PendingRpcRequest } from '@solana/rpc';
-import type { PendingRpcSubscriptionsRequest } from '@solana/rpc-subscriptions';
+import type { RpcSendable } from '@solana/rpc';
+import type { RpcSubscribable } from '@solana/rpc-subscriptions';
 import type { SolanaRpcResponse } from '@solana/rpc-types';
 
 import { createReactiveStoreWithInitialValueAndSlotTracking } from '../create-reactive-store-with-initial-value-and-slot-tracking';
 
 type TestValue = { count: number };
 
 function createMockRpcRequest(): {
-    mockRequest: PendingRpcRequest<SolanaRpcResponse<TestValue>>;
+    mockRequest: RpcSendable<SolanaRpcResponse<TestValue>>;
     reject(error: unknown): void;
     resolve(response: SolanaRpcResponse<TestValue>): void;
 } {
     const { promise, resolve, reject } = Promise.withResolvers<SolanaRpcResponse<TestValue>>();
     return {
         mockRequest: {
-            reactiveStore: jest.fn().mockImplementation(() => {
-                throw new Error('not implemented');
-            }),
             send: jest.fn().mockReturnValue(promise),
         },
         reject,
@@ -27,7 +24,7 @@ function createMockRpcRequest(): {
 function createMockSubscriptionRequest(): {
     complete(): void;
     error(err: unknown): void;
-    mockRequest: PendingRpcSubscriptionsRequest<SolanaRpcResponse<TestValue>>;
+    mockRequest: RpcSubscribable<SolanaRpcResponse<TestValue>>;
     pushNotification(notification: SolanaRpcResponse<TestValue>): void;
 } {
     const notifications: SolanaRpcResponse<TestValue>[] = [];
@@ -93,9 +90,6 @@ function createMockSubscriptionRequest(): {
         complete,
         error,
         mockRequest: {
-            reactiveStore: jest.fn().mockImplementation(() => {
-                throw new Error('not implemented');
-            }),
             subscribe: jest.fn().mockResolvedValue(asyncIterable),
         },
         pushNotification,
@@ -627,20 +621,14 @@ describe('createReactiveStoreWithInitialValueAndSlotTracking', () => {
                 error(err: unknown): void;
                 pushNotification(notification: SolanaRpcResponse<TestValue>): void;
             }[] = [];
-            const rpcRequest: PendingRpcRequest<SolanaRpcResponse<TestValue>> = {
-                reactiveStore: jest.fn().mockImplementation(() => {
-                    throw new Error('not implemented');
-                }),
+            const rpcRequest: RpcSendable<SolanaRpcResponse<TestValue>> = {
                 send: jest.fn().mockImplementation(() => {
                     const { promise, resolve, reject } = Promise.withResolvers<SolanaRpcResponse<TestValue>>();
                     rpcInstances.push({ reject, resolve });
                     return promise;
                 }),
             };
-            const rpcSubscriptionRequest: PendingRpcSubscriptionsRequest<SolanaRpcResponse<TestValue>> = {
-                reactiveStore: jest.fn().mockImplementation(() => {
-                    throw new Error('not implemented');
-                }),
+            const rpcSubscriptionRequest: RpcSubscribable<SolanaRpcResponse<TestValue>> = {
                 subscribe: jest.fn().mockImplementation(() => {
                     const instance = createMockSubscriptionRequest();
                     subscriptionInstances.push({

packages/kit/src/create-async-generator-with-initial-value-and-slot-tracking.ts

@@ -1,5 +1,5 @@
-import type { PendingRpcRequest } from '@solana/rpc';
-import type { PendingRpcSubscriptionsRequest } from '@solana/rpc-subscriptions';
+import type { RpcSendable } from '@solana/rpc';
+import type { RpcSubscribable } from '@solana/rpc-subscriptions';
 import type { SolanaRpcResponse } from '@solana/rpc-types';
 
 type CreateAsyncGeneratorWithInitialValueAndSlotTrackingConfig<TRpcValue, TSubscriptionValue, TItem> = Readonly<{
@@ -9,18 +9,18 @@ type CreateAsyncGeneratorWithInitialValueAndSlotTrackingConfig<TRpcValue, TSubsc
      */
     abortSignal: AbortSignal;
     /**
-     * A pending RPC request whose response will be yielded as the generator's first value
+     * A one-shot RPC request whose response will be yielded as the generator's first value
      * (unless a subscription notification with a newer slot arrives first).
      * The response must be a {@link SolanaRpcResponse} so that its slot can be compared with
      * subscription notifications.
      */
-    rpcRequest: PendingRpcRequest<SolanaRpcResponse<TRpcValue>>;
+    rpcRequest: RpcSendable<SolanaRpcResponse<TRpcValue>>;
     /**
-     * A pending RPC subscription request whose notifications will be yielded as they arrive.
+     * An RPC subscription request whose notifications will be yielded as they arrive.
      * Each notification must be a {@link SolanaRpcResponse} so that its slot can be compared
      * with the initial RPC response and other notifications.
      */
-    rpcSubscriptionRequest: PendingRpcSubscriptionsRequest<SolanaRpcResponse<TSubscriptionValue>>;
+    rpcSubscriptionRequest: RpcSubscribable<SolanaRpcResponse<TSubscriptionValue>>;
     /**
      * Maps the value from a subscription notification to the item type yielded by the generator.
      */

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

@@ -1,5 +1,5 @@
-import type { PendingRpcRequest } from '@solana/rpc';
-import type { PendingRpcSubscriptionsRequest } from '@solana/rpc-subscriptions';
+import type { RpcSendable } from '@solana/rpc';
+import type { RpcSubscribable } from '@solana/rpc-subscriptions';
 import type { SolanaRpcResponse } from '@solana/rpc-types';
 import type { ReactiveState, ReactiveStreamStore } from '@solana/subscribable';
 
@@ -16,17 +16,17 @@ import type { ReactiveState, ReactiveStreamStore } from '@solana/subscribable';
  */
 export type CreateReactiveStoreWithInitialValueAndSlotTrackingConfig<TRpcValue, TSubscriptionValue, TItem> = Readonly<{
     /**
-     * A pending RPC request whose response will be used to set the store's initial state.
+     * A one-shot RPC request whose response will be used to set the store's initial state.
      * The response must be a {@link SolanaRpcResponse} so that its slot can be compared with
      * subscription notifications.
      */
-    rpcRequest: PendingRpcRequest<SolanaRpcResponse<TRpcValue>>;
+    rpcRequest: RpcSendable<SolanaRpcResponse<TRpcValue>>;
     /**
-     * A pending RPC subscription request whose notifications will be used to keep the store
-     * up to date. Each notification must be a {@link SolanaRpcResponse} so that its slot can be
+     * An RPC subscription request whose notifications will be used to keep the store up to
+     * date. Each notification must be a {@link SolanaRpcResponse} so that its slot can be
      * compared with the initial RPC response and other notifications.
      */
-    rpcSubscriptionRequest: PendingRpcSubscriptionsRequest<SolanaRpcResponse<TSubscriptionValue>>;
+    rpcSubscriptionRequest: RpcSubscribable<SolanaRpcResponse<TSubscriptionValue>>;
     /**
      * Maps the value from a subscription notification to the item type stored in the reactive store.
      */

packages/rpc-spec/src/rpc.ts

@@ -67,6 +67,16 @@ export type RpcSendOptions = Readonly<{
     abortSignal?: AbortSignal;
 }>;
 
+/**
+ * Structural duck-type for anything fireable via `send({ abortSignal })`. Satisfied by
+ * {@link PendingRpcRequest | PendingRpcRequest<TResponse>}.
+ *
+ * @typeParam TResponse - The value `send()` resolves to.
+ */
+export type RpcSendable<TResponse> = {
+    send(options?: RpcSendOptions): Promise<TResponse>;
+};
+
 type PendingRpcRequestBuilder<TMethodImplementations> = UnionToIntersection<
     Flatten<{
         [P in keyof TMethodImplementations]: PendingRpcRequestReturnTypeMapper<TMethodImplementations[P]>;

packages/rpc-subscriptions-spec/src/rpc-subscriptions-request.ts

@@ -58,3 +58,13 @@ export type RpcSubscribeOptions = Readonly<{
     /** An `AbortSignal` to fire when you want to unsubscribe */
     abortSignal: AbortSignal;
 }>;
+
+/**
+ * Structural duck-type for anything subscribable via `subscribe({ abortSignal })`. Satisfied by
+ * {@link PendingRpcSubscriptionsRequest | PendingRpcSubscriptionsRequest<TNotification>}.
+ *
+ * @typeParam TNotification - The notification type yielded by the returned async iterable.
+ */
+export type RpcSubscribable<TNotification> = {
+    subscribe(options: RpcSubscribeOptions): Promise<AsyncIterable<TNotification>>;
+};