Document @solana/rpc-subscriptions-spec with TypeDoc

Author: steveluscher

packages/rpc-spec/src/rpc.ts

@@ -52,7 +52,7 @@ type PendingRpcRequestReturnTypeMapper<TMethodImplementation> =
         : never;
 
 /**
- * Creates a {@link Rpc} instance given an {@link RpcApi | RpcApi<TRpcMethods>} and a
+ * Creates a {@link Rpc} instance given a {@link RpcApi | RpcApi<TRpcMethods>} and a
  * {@link RpcTransport} capable of fulfilling them.
  */
 export function createRpc<TRpcMethods, TRpcTransport extends RpcTransport>(

packages/rpc-subscriptions-spec/README.md

@@ -17,7 +17,7 @@ This API is designed to be used as follows:
 
 ```ts
 const rpcSubscriptions =
-    // Step 1 - Create an `RpcSubscriptions` instance. This may be stateful.
+    // Step 1 - Create a `RpcSubscriptions` instance. This may be stateful.
     createSolanaRpcSubscriptions(mainnet('wss://api.mainnet-beta.solana.com'));
 const response = await rpcSubscriptions
     // Step 2 - Call supported methods on it to produce `PendingRpcSubscriptionsRequest` objects.
@@ -40,7 +40,7 @@ try {
 
 ### `RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>`
 
-A channel is a `DataPublisher` that you can subscribe to events of type `RpcSubscriptionChannelEvents<TInboundMessage>`. Additionally, you can use it to send messages of type `TOutboundMessage` back to the remote end by calling the `send(message)` method.
+A channel is a `DataPublisher` on which you can subscribe to events of type `RpcSubscriptionChannelEvents<TInboundMessage>`. Additionally, you can use this object to send messages of type `TOutboundMessage` back to the remote end by calling its `send(message)` method.
 
 ### `RpcSubscriptionsChannelCreator<TOutboundMessage, TInboundMessage>`
 

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

@@ -1,3 +1,32 @@
+/**
+ * This package contains types that describe the implementation of the JSON RPC Subscriptions API,
+ * as well as methods to create one. It can be used standalone, but it is also exported as part of
+ * Kit [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).
+ *
+ * @example
+ * ```ts
+ * const rpcSubscriptions =
+ *     // Step 1 - Create a `RpcSubscriptions` instance. This may be stateful.
+ *     createSolanaRpcSubscriptions(mainnet('wss://api.mainnet-beta.solana.com'));
+ * const response = await rpcSubscriptions
+ *     // Step 2 - Call supported methods on it to produce `PendingRpcSubscriptionsRequest` objects.
+ *     .slotNotifications({ commitment: 'confirmed' })
+ *     // Step 3 - Call the `subscribe()` method on those pending requests to trigger them.
+ *     .subscribe({ abortSignal: AbortSignal.timeout(10_000) });
+ * // Step 4 - Iterate over the result.
+ * try {
+ *     for await (const slotNotification of slotNotifications) {
+ *         console.log('Got a slot notification', slotNotification);
+ *     }
+ * } catch (e) {
+ *     console.error('The subscription closed unexpectedly', e);
+ * } finally {
+ *     console.log('We have stopped listening for notifications');
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
 export * from './rpc-subscriptions-request';
 export * from './rpc-subscriptions';
 export * from './rpc-subscriptions-api';

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

@@ -6,9 +6,23 @@ import { RpcSubscriptionsTransportDataEvents } from './rpc-subscriptions-transpo
 
 export type RpcSubscriptionsApiConfig<TApiMethods extends RpcSubscriptionsApiMethods> = Readonly<{
     planExecutor: RpcSubscriptionsPlanExecutor<ReturnType<TApiMethods[keyof TApiMethods]>>;
+    /**
+     * An optional function that transforms the {@link RpcRequest} before it is sent to the JSON RPC
+     * server.
+     *
+     * This is useful when the params supplied by the caller need to be transformed before
+     * forwarding the message to the server. Use cases for this include applying defaults,
+     * forwarding calls to renamed methods, and serializing complex values.
+     */
     requestTransformer?: RpcRequestTransformer;
 }>;
 
+/**
+ * A function that implements a protocol for subscribing and unsubscribing from notifications given
+ * a {@link RpcSubscriptionsChannel}, a {@link RpcRequest}, and an `AbortSignal`.
+ *
+ * @returns A {@link DataPublisher} that emits {@link RpcSubscriptionsTransportDataEvents}
+ */
 type RpcSubscriptionsPlanExecutor<TNotification> = (
     config: Readonly<{
         channel: RpcSubscriptionsChannel<unknown, unknown>;
@@ -17,6 +31,26 @@ type RpcSubscriptionsPlanExecutor<TNotification> = (
     }>,
 ) => Promise<DataPublisher<RpcSubscriptionsTransportDataEvents<TNotification>>>;
 
+/**
+ * This type allows an {@link RpcSubscriptionsApi} to describe how a particular subscription should
+ * be issued to the JSON RPC server.
+ *
+ * Given a function that was called on a {@link RpcSubscriptions}, this object exposes an `execute`
+ * function that dictates which subscription request will be sent, how the underlying transport will
+ * be used, and how the notifications will be transformed.
+ *
+ * This function accepts a {@link RpcSubscriptionsChannel} and an `AbortSignal` and asynchronously
+ * returns a {@link DataPublisher}. This gives us the opportunity to:
+ *
+ * - define the `payload` from the requested method name and parameters before passing it to the
+ *   channel.
+ * - call the underlying channel zero, one or multiple times depending on the use-case (e.g.
+ *   caching or coalescing multiple subscriptions).
+ * - transform the notification from the JSON RPC server, in case it does not match the
+ *   `TNotification` specified by the
+ *   {@link PendingRpcSubscriptionsRequest | PendingRpcSubscriptionsRequest<TNotification>} emitted
+ *   from the publisher returned.
+ */
 export type RpcSubscriptionsPlan<TNotification> = Readonly<{
     /**
      * This method may be called with a newly-opened channel or a pre-established channel.
@@ -35,6 +69,12 @@ export type RpcSubscriptionsPlan<TNotification> = Readonly<{
     request: RpcRequest;
 }>;
 
+/**
+ * For each of `TRpcSubscriptionsMethods`, this object exposes a method with the same name that maps
+ * between its input arguments and a
+ * {@link RpcSubscriptionsPlan | RpcSubscriptionsPlan<TNotification>} that implements the execution
+ * of a JSON RPC subscription for `TNotifications`.
+ */
 export type RpcSubscriptionsApi<TRpcSubscriptionMethods> = {
     [MethodName in keyof TRpcSubscriptionMethods]: RpcSubscriptionsReturnTypeMapper<
         TRpcSubscriptionMethods[MethodName]
@@ -51,6 +91,47 @@ export interface RpcSubscriptionsApiMethods {
     [methodName: string]: RpcSubscriptionsApiMethod;
 }
 
+/**
+ * Creates a JavaScript proxy that converts _any_ function call called on it to a
+ * {@link RpcSubscriptionsPlan} by creating an `execute` function that:
+ *
+ * - calls the supplied {@link RpcSubscriptionsApiConfig.planExecutor} with a JSON RPC v2 payload
+ *   object with the requested `methodName` and `params` properties, optionally transformed by
+ *   {@link RpcSubscriptionsApiConfig.requestTransformer}.
+ *
+ * @example
+ * ```ts
+ * // For example, given this `RpcSubscriptionsApi`:
+ * const rpcSubscriptionsApi = createJsonRpcSubscriptionsApi({
+ *     async planExecutor({ channel, request }) {
+ *         await channel.send(request);
+ *         return {
+ *             ...channel,
+ *             on(type, listener, options) {
+ *                 if (type !== 'message') {
+ *                     return channel.on(type, listener, options);
+ *                 }
+ *                 return channel.on(
+ *                     'message',
+ *                     function resultGettingListener(message) {
+ *                         listener(message.result);
+ *                     },
+ *                     options,
+ *                 );
+ *             }
+ *         }
+ *     },
+ *     requestTransformer: (...rawParams) => rawParams.reverse(),
+ * });
+ *
+ * // ...the following function call:
+ * rpcSubscriptionsApi.foo('bar', { baz: 'bat' });
+ *
+ * // ...will produce a `RpcSubscriptionsPlan` that:
+ * // -   Uses the following payload: { id: 1, jsonrpc: '2.0', method: 'foo', params: [{ baz: 'bat' }, 'bar'] }.
+ * // -   Emits the "result" property of each RPC Subscriptions message.
+ * ```
+ */
 export function createRpcSubscriptionsApi<TRpcSubscriptionsApiMethods extends RpcSubscriptionsApiMethods>(
     config: RpcSubscriptionsApiConfig<TRpcSubscriptionsApiMethods>,
 ): RpcSubscriptionsApi<TRpcSubscriptionsApiMethods> {

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

@@ -12,21 +12,51 @@ type RpcSubscriptionsChannelSolanaErrorCode =
     | typeof SOLANA_ERROR__RPC_SUBSCRIPTIONS__CHANNEL_FAILED_TO_CONNECT;
 
 export type RpcSubscriptionChannelEvents<TInboundMessage> = {
+    /**
+     * Fires when the channel closes unexpectedly.
+     * @eventProperty
+     */
     error: SolanaError<RpcSubscriptionsChannelSolanaErrorCode>;
+    /**
+     * Fires on every message received from the remote end.
+     * @eventProperty
+     */
     message: TInboundMessage;
 };
 
+/**
+ * A {@link DataPublisher} on which you can subscribe to events of type
+ * {@link RpcSubscriptionChannelEvents | RpcSubscriptionChannelEvents<TInboundMessage>}.
+ * Additionally, you can use this object to send messages of type `TOutboundMessage` back to the
+ * remote end by calling its {@link RpcSubscriptionsChannel.send | `send(message)`} method.
+ */
 export interface RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>
     extends DataPublisher<RpcSubscriptionChannelEvents<TInboundMessage>> {
     send(message: TOutboundMessage): Promise<void>;
 }
 
+/**
+ * A channel creator is a function that accepts an `AbortSignal`, returns a new
+ * {@link RpcSubscriptionsChannel}, and tears down the channel when the abort signal fires.
+ */
 export type RpcSubscriptionsChannelCreator<TOutboundMessage, TInboundMessage> = (
     config: Readonly<{
         abortSignal: AbortSignal;
     }>,
 ) => Promise<RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>>;
 
+/**
+ * Given a channel with inbound messages of type `T` and a function of type `T => U`, returns a new
+ * channel with inbound messages of type `U`.
+ *
+ * Note that this only affects messages of type `"message"` and thus, does not affect incoming error
+ * messages.
+ *
+ * @example Parsing incoming JSON messages
+ * ```ts
+ * const transformedChannel = transformChannelInboundMessages(channel, JSON.parse);
+ * ```
+ */
 export function transformChannelInboundMessages<TOutboundMessage, TNewInboundMessage, TInboundMessage>(
     channel: RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>,
     transform: (message: TInboundMessage) => TNewInboundMessage,
@@ -50,6 +80,15 @@ export function transformChannelInboundMessages<TOutboundMessage, TNewInboundMes
     });
 }
 
+/**
+ * Given a channel with outbound messages of type `T` and a function of type `U => T`, returns a new
+ * channel with outbound messages of type `U`.
+ *
+ * @example Stringifying JSON messages before sending them over the wire
+ * ```ts
+ * const transformedChannel = transformChannelOutboundMessages(channel, JSON.stringify);
+ * ```
+ */
 export function transformChannelOutboundMessages<TNewOutboundMessage, TOutboundMessage, TInboundMessage>(
     channel: RpcSubscriptionsChannel<TOutboundMessage, TInboundMessage>,
     transform: (message: TNewOutboundMessage) => TOutboundMessage,

packages/rpc-subscriptions-spec/src/rpc-subscriptions-pubsub-plan.ts

@@ -95,6 +95,18 @@ function getMemoizedDemultiplexedNotificationPublisherFromChannelAndResponseTran
     return publisher;
 }
 
+/**
+ * Given a channel, this function executes the particular subscription plan required by the Solana
+ * JSON RPC Subscriptions API.
+ *
+ * @param config
+ *
+ * 1. Calls the `subscribeRequest` on the remote RPC
+ * 2. Waits for a response containing the subscription id
+ * 3. Returns a {@link DataPublisher} that publishes notifications related to that subscriptions id,
+ *    filtering out all others
+ * 4. Calls the `unsubscribeMethodName` on the remote RPC when the abort signal is fired.
+ */
 export async function executeRpcPubSubSubscriptionPlan<TNotification>({
     channel,
     responseTransformer,

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

@@ -1,7 +1,17 @@
+/**
+ * Pending subscriptions are the result of calling a supported method on a {@link RpcSubscriptions}
+ * object. They encapsulate all of the information necessary to make the subscription without
+ * actually making it.
+ *
+ * Calling the {@link PendingRpcSubscriptionsRequest.subscribe | `subscribe(options)`} method on a
+ * {@link PendingRpcSubscriptionsRequest | PendingRpcSubscriptionsRequest<TNotification>} will
+ * trigger the subscription and return a promise for an async iterable that vends `TNotifications`.
+ */
 export type PendingRpcSubscriptionsRequest<TNotification> = {
     subscribe(options: RpcSubscribeOptions): Promise<AsyncIterable<TNotification>>;
 };
 
 export type RpcSubscribeOptions = Readonly<{
+    /** An `AbortSignal` to fire when you want to unsubscribe */
     abortSignal: AbortSignal;
 }>;

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

@@ -4,14 +4,27 @@ import { DataPublisher } from '@solana/subscribable';
 import { RpcSubscriptionsPlan } from './rpc-subscriptions-api';
 
 export type RpcSubscriptionsTransportDataEvents<TNotification> = {
+    /**
+     * Fires when there is an error with the subscription or the channel.
+     * @eventProperty
+     */
     error: SolanaError;
+    /**
+     * Fires on every notification received.
+     * @eventProperty
+     */
     notification: TNotification;
 };
 
 interface RpcSubscriptionsTransportConfig<TNotification> extends RpcSubscriptionsPlan<TNotification> {
+    /** An `AbortSignal` to fire when you want to unsubscribe */
     signal: AbortSignal;
 }
 
+/**
+ * A function that can act as a transport for a {@link RpcSubscriptions}. It need only return a
+ * promise for a {@link DataPublisher} given the supplied config.
+ */
 export interface RpcSubscriptionsTransport {
     <TNotification>(
         config: RpcSubscriptionsTransportConfig<TNotification>,

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

@@ -11,6 +11,13 @@ export type RpcSubscriptionsConfig<TRpcMethods> = Readonly<{
     transport: RpcSubscriptionsTransport;
 }>;
 
+/**
+ * An object that exposes all of the functions described by `TRpcSubscriptionsMethods`.
+ *
+ * Calling each method returns a
+ * {@link PendingRpcSubscriptionsRequest | PendingRpcSubscriptionsRequest<TNotification>} where
+ * `TNotification` is that method's notification type.
+ */
 export type RpcSubscriptions<TRpcSubscriptionsMethods> = {
     [TMethodName in keyof TRpcSubscriptionsMethods]: PendingRpcSubscriptionsRequestBuilder<
         OverloadImplementations<TRpcSubscriptionsMethods, TMethodName>
@@ -33,6 +40,11 @@ type PendingRpcSubscriptionsRequestReturnTypeMapper<TSubscriptionMethodImplement
           ) => PendingRpcSubscriptionsRequest<ReturnType<TSubscriptionMethodImplementation>>
         : never;
 
+/**
+ * Creates a {@link RpcSubscriptions} instance given a
+ * {@link RpcSubscriptionsApi | RpcSubscriptionsApi<TRpcSubscriptionsApiMethods>} and a
+ * {@link RpcSubscriptionsTransport} capable of fulfilling them.
+ */
 export function createSubscriptionRpc<TRpcSubscriptionsApiMethods>(
     rpcConfig: RpcSubscriptionsConfig<TRpcSubscriptionsApiMethods>,
 ): RpcSubscriptions<TRpcSubscriptionsApiMethods> {