Document @solana/rpc-transformers with TypeDoc

Author: steveluscher

Diff for: packages/rpc-transformers/README.md

@@ -11,6 +11,8 @@
 
 # @solana/rpc-transformers
 
+This package contains helpers for transforming Solana JSON RPC and RPC Subscriptions requests, responses, and notifications in various ways appropriate for use in a JavaScript application.
+
 ## Request Transformers
 
 ### `getDefaultRequestTransformerForSolanaRpc(config)`
@@ -28,14 +30,14 @@ const requestTransformer = getDefaultRequestTransformerForSolanaRpc({
 });
 ```
 
-### `getDefaultCommitmentTransformer(config)`
+### `getDefaultCommitmentRequestTransformer(config)`
 
 Creates a transformer that adds the provided default commitment to the configuration object of the request when applicable.
 
 ```ts
-import { getDefaultCommitmentTransformer, OPTIONS_OBJECT_POSITION_BY_METHOD } from '@solana/rpc-transformers';
+import { getDefaultCommitmentRequestTransformer, OPTIONS_OBJECT_POSITION_BY_METHOD } from '@solana/rpc-transformers';
 
-const requestTransformer = getDefaultCommitmentTransformer({
+const requestTransformer = getDefaultCommitmentRequestTransformer({
     defaultCommitment: 'confirmed',
     optionsObjectPositionByMethod: OPTIONS_OBJECT_POSITION_BY_METHOD,
 });

Diff for: packages/rpc-transformers/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * This package contains helpers for transforming Solana JSON RPC and RPC Subscriptions requests,
+ * responses, and notifications in various ways appropriate for use in a JavaScript application.
+ *
+ * @packageDocumentation
+ */
 export * from './request-transformer';
 export * from './request-transformer-bigint-downcast';
 export * from './request-transformer-default-commitment';

Diff for: packages/rpc-transformers/src/request-transformer-bigint-downcast.ts

@@ -1,6 +1,17 @@
 import { downcastNodeToNumberIfBigint } from './request-transformer-bigint-downcast-internal';
 import { getTreeWalkerRequestTransformer } from './tree-traversal';
 
+/**
+ * Creates a transformer that downcasts all `BigInt` values to `Number`.
+ *
+ * @example
+ * ```ts
+ * import { getBigIntDowncastRequestTransformer } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getBigIntDowncastRequestTransformer();
+ * ```
+ *
+ */
 export function getBigIntDowncastRequestTransformer() {
     return getTreeWalkerRequestTransformer([downcastNodeToNumberIfBigint], { keyPath: [] });
 }

Diff for: packages/rpc-transformers/src/request-transformer-default-commitment.ts

@@ -3,6 +3,20 @@ import type { Commitment } from '@solana/rpc-types';
 
 import { applyDefaultCommitment } from './request-transformer-default-commitment-internal';
 
+/**
+ * Creates a transformer that adds the provided default commitment to the configuration object of the request when applicable.
+ *
+ * @param config
+ *
+ * @example
+ * ```ts
+ * import { getDefaultCommitmentRequestTransformer, OPTIONS_OBJECT_POSITION_BY_METHOD } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getDefaultCommitmentRequestTransformer({
+ *     defaultCommitment: 'confirmed',
+ *     optionsObjectPositionByMethod: OPTIONS_OBJECT_POSITION_BY_METHOD,
+ * });
+ */
 export function getDefaultCommitmentRequestTransformer({
     defaultCommitment,
     optionsObjectPositionByMethod,

Diff for: packages/rpc-transformers/src/request-transformer-integer-overflow.ts

@@ -5,6 +5,19 @@ import { getTreeWalkerRequestTransformer, KeyPath } from './tree-traversal';
 
 export type IntegerOverflowHandler = (request: RpcRequest, keyPath: KeyPath, value: bigint) => void;
 
+/**
+ * Creates a transformer that traverses the request parameters and executes the provided handler
+ * when an integer overflow is detected.
+ *
+ * @example
+ * ```ts
+ * import { getIntegerOverflowRequestTransformer } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getIntegerOverflowRequestTransformer((request, keyPath, value) => {
+ *     throw new Error(`Integer overflow at ${keyPath.join('.')}: ${value}`);
+ * });
+ * ```
+ */
 export function getIntegerOverflowRequestTransformer(onIntegerOverflow: IntegerOverflowHandler) {
     return <TParams>(request: RpcRequest<TParams>): RpcRequest => {
         const transformer = getTreeWalkerRequestTransformer(

Diff for: packages/rpc-transformers/src/request-transformer.ts

@@ -8,10 +8,41 @@ import { getIntegerOverflowRequestTransformer, IntegerOverflowHandler } from './
 import { OPTIONS_OBJECT_POSITION_BY_METHOD } from './request-transformer-options-object-position-config';
 
 export type RequestTransformerConfig = Readonly<{
+    /**
+     * An optional {@link Commitment} value to use as the default when none is supplied by the
+     * caller.
+     */
     defaultCommitment?: Commitment;
+    /**
+     * An optional function that will be called whenever a `bigint` input exceeds that which can be
+     * expressed using JavaScript numbers.
+     *
+     * This is used in the default {@link SolanaRpcSubscriptionsApi} to throw an exception rather
+     * than to allow truncated values to propagate through a program.
+     */
     onIntegerOverflow?: IntegerOverflowHandler;
 }>;
 
+/**
+ * Returns the default request transformer for the Solana RPC API.
+ *
+ * Under the hood, this function composes multiple
+ * {@link RpcRequestTransformer | RpcRequestTransformers} together such as the
+ * {@link getDefaultCommitmentTransformer}, the {@link getIntegerOverflowRequestTransformer} and the
+ * {@link getBigIntDowncastRequestTransformer}.
+ *
+ * @example
+ * ```ts
+ * import { getDefaultRequestTransformerForSolanaRpc } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getDefaultRequestTransformerForSolanaRpc({
+ *     defaultCommitment: 'confirmed',
+ *     onIntegerOverflow: (request, keyPath, value) => {
+ *         throw new Error(`Integer overflow at ${keyPath.join('.')}: ${value}`);
+ *     },
+ * });
+ * ```
+ */
 export function getDefaultRequestTransformerForSolanaRpc(config?: RequestTransformerConfig): RpcRequestTransformer {
     const handleIntegerOverflow = config?.onIntegerOverflow;
     return (request: RpcRequest): RpcRequest => {

Diff for: packages/rpc-transformers/src/response-transformer-bigint-upcast.ts

@@ -1,6 +1,25 @@
 import { getBigIntUpcastVisitor } from './response-transformer-bigint-upcast-internal';
 import { getTreeWalkerResponseTransformer, KeyPath } from './tree-traversal';
 
+/**
+ * Returns a transformer that upcasts all `Number` values to `BigInts` unless they match within the
+ * provided {@link KeyPath | KeyPaths}. In other words, the provided {@link KeyPath | KeyPaths} will
+ * remain as `Number` values, any other numeric value will be upcasted to a `BigInt`.
+ *
+ * Note that you can use {@link KEYPATH_WILDCARD} to match any key within a {@link KeyPath}.
+ *
+ * @example
+ * ```ts
+ * import { getBigIntUpcastResponseTransformer } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getBigIntUpcastResponseTransformer([
+ *     ['index'],
+ *     ['instructions', KEYPATH_WILDCARD, 'accounts', KEYPATH_WILDCARD],
+ *     ['instructions', KEYPATH_WILDCARD, 'programIdIndex'],
+ *     ['instructions', KEYPATH_WILDCARD, 'stackHeight'],
+ * ]);
+ * ```
+ */
 export function getBigIntUpcastResponseTransformer(allowedNumericKeyPaths: readonly KeyPath[]) {
     return getTreeWalkerResponseTransformer([getBigIntUpcastVisitor(allowedNumericKeyPaths)], { keyPath: [] });
 }

Diff for: packages/rpc-transformers/src/response-transformer-result.ts

@@ -2,6 +2,18 @@ import { RpcResponseTransformer } from '@solana/rpc-spec-types';
 
 type JsonRpcResponse = { result: unknown };
 
+/**
+ * Returns a transformer that extracts the `result` field from the body of the RPC response.
+ *
+ * For instance, we go from `{ jsonrpc: '2.0', result: 'foo', id: 1 }` to `'foo'`.
+ *
+ * @example
+ * ```ts
+ * import { getResultResponseTransformer } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getResultResponseTransformer();
+ * ```
+ */
 export function getResultResponseTransformer(): RpcResponseTransformer {
     return json => (json as JsonRpcResponse).result;
 }

Diff for: packages/rpc-transformers/src/response-transformer-throw-solana-error.ts

@@ -3,6 +3,17 @@ import { RpcResponseTransformer } from '@solana/rpc-spec-types';
 
 type JsonRpcResponse = { error: Parameters<typeof getSolanaErrorFromJsonRpcError>[0] } | { result: unknown };
 
+/**
+ * Returns a transformer that throws a {@link SolanaError} with the appropriate RPC error code if
+ * the body of the RPC response contains an error.
+ *
+ * @example
+ * ```ts
+ * import { getThrowSolanaErrorResponseTransformer } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getThrowSolanaErrorResponseTransformer();
+ * ```
+ */
 export function getThrowSolanaErrorResponseTransformer(): RpcResponseTransformer {
     return json => {
         const jsonRpcResponse = json as JsonRpcResponse;

Diff for: packages/rpc-transformers/src/response-transformer.ts

@@ -7,9 +7,31 @@ import { getResultResponseTransformer } from './response-transformer-result';
 import { getThrowSolanaErrorResponseTransformer } from './response-transformer-throw-solana-error';
 
 export type ResponseTransformerConfig<TApi> = Readonly<{
+    /**
+     * An optional map from the name of an API method to an array of {@link KeyPath | KeyPaths}
+     * pointing to values in the response that should materialize in the application as `Number`
+     * instead of `BigInt`.
+     */
     allowedNumericKeyPaths?: AllowedNumericKeypaths<TApi>;
 }>;
 
+/**
+ * Returns the default response transformer for the Solana RPC API.
+ *
+ * Under the hood, this function composes multiple
+ * {@link RpcResponseTransformer | RpcResponseTransformers} together such as the
+ * {@link getThrowSolanaErrorResponseTransformer}, the {@link getResultResponseTransformer} and the
+ * {@link getBigIntUpcastResponseTransformer}.
+ *
+ * @example
+ * ```ts
+ * import { getDefaultResponseTransformerForSolanaRpc } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getDefaultResponseTransformerForSolanaRpc({
+ *     allowedNumericKeyPaths: getAllowedNumericKeypaths(),
+ * });
+ * ```
+ */
 export function getDefaultResponseTransformerForSolanaRpc<TApi>(
     config?: ResponseTransformerConfig<TApi>,
 ): RpcResponseTransformer {
@@ -26,6 +48,20 @@ export function getDefaultResponseTransformerForSolanaRpc<TApi>(
     };
 }
 
+/**
+ * Returns the default response transformer for the Solana RPC Subscriptions API.
+ *
+ * Under the hood, this function composes the {@link getBigIntUpcastResponseTransformer}.
+ *
+ * @example
+ * ```ts
+ * import { getDefaultResponseTransformerForSolanaRpcSubscriptions } from '@solana/rpc-transformers';
+ *
+ * const responseTransformer = getDefaultResponseTransformerForSolanaRpcSubscriptions({
+ *     allowedNumericKeyPaths: getAllowedNumericKeypaths(),
+ * });
+ * ```
+ */
 export function getDefaultResponseTransformerForSolanaRpcSubscriptions<TApi>(
     config?: ResponseTransformerConfig<TApi>,
 ): RpcResponseTransformer {

Diff for: packages/rpc-transformers/src/tree-traversal.ts

@@ -39,6 +39,25 @@ function getTreeWalker(visitors: NodeVisitor[]) {
     };
 }
 
+/**
+ * Creates a transformer that traverses the request parameters and executes the provided visitors at
+ * each node. A custom initial state can be provided but must at least provide `{ keyPath: [] }`.
+ *
+ * @example
+ * ```ts
+ * import { getTreeWalkerRequestTransformer } from '@solana/rpc-transformers';
+ *
+ * const requestTransformer = getTreeWalkerRequestTransformer(
+ *     [
+ *         // Replaces foo.bar with "baz".
+ *         (node, state) => (state.keyPath === ['foo', 'bar'] ? 'baz' : node),
+ *         // Increments all numbers by 1.
+ *         node => (typeof node === number ? node + 1 : node),
+ *     ],
+ *     { keyPath: [] },
+ * );
+ * ```
+ */
 export function getTreeWalkerRequestTransformer<TState extends TraversalState>(
     visitors: NodeVisitor[],
     initialState: TState,