refactor(experimental): add generic createJsonRpcSubscriptionsApi for custom APIs

buffalojoec · web-flow · commit ae3f1f0873b1 · 2023-12-11T19:36:27.000-06:00
Continuing the work from #1781, this PR adds a generic function for creating an RPC Subscriptions API, and drives this function from the main `@solana/web3.js`.
diff --git a/packages/rpc-core/src/rpc-subscriptions/index.ts b/packages/rpc-core/src/rpc-subscriptions/index.ts
@@ -1,4 +1,4 @@
-import type { IRpcSubscriptionsApi, RpcSubscription } from '@solana/rpc-transport';
+import { createJsonRpcSubscriptionsApi, IRpcSubscriptionsApi } from '@solana/rpc-transport';
 
 import { patchParamsForSolanaLabsRpc } from '../params-patcher';
 import { patchResponseForSolanaLabsRpcSubscriptions } from '../response-patcher';
@@ -25,63 +25,38 @@ export type SolanaRpcSubscriptions = AccountNotificationsApi &
     SlotNotificationsApi;
 export type SolanaRpcSubscriptionsUnstable = SlotsUpdatesNotificationsApi & VoteNotificationsApi;
 
-export function createSolanaRpcSubscriptionsApi(
+export function createSolanaRpcSubscriptionsApi_INTERNAL(
     config?: Config,
 ): IRpcSubscriptionsApi<SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable> {
-    return new Proxy({} as IRpcSubscriptionsApi<SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable>, {
-        defineProperty() {
-            return false;
-        },
-        deleteProperty() {
-            return false;
-        },
-        get<
-            TNotificationName extends keyof IRpcSubscriptionsApi<
-                SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable
-            >,
-        >(
-            ...args: Parameters<
-                NonNullable<
-                    ProxyHandler<IRpcSubscriptionsApi<SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable>>['get']
-                >
-            >
-        ) {
-            const [_, p] = args;
-            const notificationName = p.toString() as keyof (SolanaRpcSubscriptions &
-                SolanaRpcSubscriptionsUnstable) as string;
-            return function (
-                ...rawParams: Parameters<
-                    (SolanaRpcSubscriptions &
-                        SolanaRpcSubscriptionsUnstable)[TNotificationName] extends CallableFunction
-                        ? (SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable)[TNotificationName]
-                        : never
-                >
-            ): RpcSubscription<
-                ReturnType<(SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable)[TNotificationName]>
-            > {
-                const handleIntegerOverflow = config?.onIntegerOverflow;
-                const params = patchParamsForSolanaLabsRpc(
-                    rawParams,
-                    handleIntegerOverflow
-                        ? (keyPath, value) => handleIntegerOverflow(notificationName, keyPath, value)
-                        : undefined,
-                );
-                return {
-                    params,
-                    responseTransformer: rawResponse =>
-                        patchResponseForSolanaLabsRpcSubscriptions(rawResponse, notificationName),
-                    subscribeMethodName: notificationName.replace(/Notifications$/, 'Subscribe'),
-                    unsubscribeMethodName: notificationName.replace(/Notifications$/, 'Unsubscribe'),
-                };
-            };
-        },
+    const handleIntegerOverflow = config?.onIntegerOverflow;
+    return createJsonRpcSubscriptionsApi<SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable>({
+        parametersTransformer: <T>(rawParams: T, methodName: string) =>
+            patchParamsForSolanaLabsRpc(
+                rawParams,
+                handleIntegerOverflow
+                    ? (keyPath, value) => handleIntegerOverflow(methodName, keyPath, value)
+                    : undefined,
+            ) as unknown[],
+        responseTransformer: <T>(rawResponse: unknown, methodName: string): T =>
+            patchResponseForSolanaLabsRpcSubscriptions(
+                rawResponse,
+                methodName as keyof (SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable),
+            ),
+        subscribeNotificationNameTransformer: (notificationName: string) =>
+            notificationName.replace(/Notifications$/, 'Subscribe'),
+        unsubscribeNotificationNameTransformer: (notificationName: string) =>
+            notificationName.replace(/Notifications$/, 'Unsubscribe'),
     });
 }
 
+export function createSolanaRpcSubscriptionsApi(config?: Config): IRpcSubscriptionsApi<SolanaRpcSubscriptions> {
+    return createSolanaRpcSubscriptionsApi_INTERNAL(config) as IRpcSubscriptionsApi<SolanaRpcSubscriptions>;
+}
+
 export function createSolanaRpcSubscriptionsApi_UNSTABLE(
     config?: Config,
 ): IRpcSubscriptionsApi<SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable> {
-    return createSolanaRpcSubscriptionsApi(config) as IRpcSubscriptionsApi<
+    return createSolanaRpcSubscriptionsApi_INTERNAL(config) as IRpcSubscriptionsApi<
         SolanaRpcSubscriptions & SolanaRpcSubscriptionsUnstable
     >;
 }
diff --git a/packages/rpc-transport/src/__tests__/json-rpc-subscription-test.ts b/packages/rpc-transport/src/__tests__/json-rpc-subscription-test.ts
@@ -328,7 +328,7 @@ describe('JSON-RPC 2.0 Subscriptions', () => {
                 .thingNotifications()
                 .subscribe({ abortSignal: new AbortController().signal });
             await thingNotifications[Symbol.asyncIterator]().next();
-            expect(responseTransformer).toHaveBeenCalledWith(123);
+            expect(responseTransformer).toHaveBeenCalledWith(123, 'thingSubscribe');
         });
         it('returns the processed response', async () => {
             expect.assertions(1);
diff --git a/packages/rpc-transport/src/apis/__typetests__/subscriptions-api-typetest.ts b/packages/rpc-transport/src/apis/__typetests__/subscriptions-api-typetest.ts
@@ -0,0 +1,23 @@
+import { IRpcSubscriptionsApi } from '../../json-rpc-types';
+import { IRpcApiMethods } from '../api-types';
+import { createJsonRpcSubscriptionsApi } from '../subscriptions/subscriptions-api';
+
+type NftCollectionDetailsApiResponse = Readonly<{
+    address: string;
+    circulatingSupply: number;
+    description: string;
+    erc721: boolean;
+    erc1155: boolean;
+    genesisBlock: string;
+    genesisTransaction: string;
+    name: string;
+    totalSupply: number;
+}>;
+
+interface NftCollectionDetailsApi extends IRpcApiMethods {
+    qn_fetchNFTCollectionDetails(args: { contracts: string[] }): NftCollectionDetailsApiResponse;
+}
+
+type QuickNodeRpcMethods = NftCollectionDetailsApi;
+
+createJsonRpcSubscriptionsApi<QuickNodeRpcMethods>() satisfies IRpcSubscriptionsApi<QuickNodeRpcMethods>;
diff --git a/packages/rpc-transport/src/apis/api-types.ts b/packages/rpc-transport/src/apis/api-types.ts
@@ -13,13 +13,15 @@ export interface IRpcApiMethods {
 
 // RPC Subscription Methods
 export type RpcSubscriptionsApiConfig = Readonly<{
-    parametersTransformer?: <T>(params: T, methodName: string) => unknown[];
-    responseTransformer?: <T>(response: unknown, methodName: string) => T;
+    parametersTransformer?: <T>(params: T, notificationName: string) => unknown[];
+    responseTransformer?: <T>(response: unknown, notificationName: string) => T;
+    subscribeNotificationNameTransformer?: (notificationName: string) => string;
+    unsubscribeNotificationNameTransformer?: (notificationName: string) => string;
 }>;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type RpcSubscription = (...args: any) => any;
 
 export interface IRpcApiSubscriptions {
-    [methodName: string]: RpcSubscription;
+    [notificationName: string]: RpcSubscription;
 }
diff --git a/packages/rpc-transport/src/apis/subscriptions/subscriptions-api.ts b/packages/rpc-transport/src/apis/subscriptions/subscriptions-api.ts
@@ -0,0 +1,47 @@
+import { IRpcSubscriptionsApi, RpcSubscription } from '../../json-rpc-types';
+import { IRpcApiSubscriptions, RpcSubscriptionsApiConfig } from '../api-types';
+
+export function createJsonRpcSubscriptionsApi<TRpcSubscriptions extends IRpcApiSubscriptions>(
+    config?: RpcSubscriptionsApiConfig,
+): IRpcSubscriptionsApi<TRpcSubscriptions> {
+    return new Proxy({} as IRpcSubscriptionsApi<TRpcSubscriptions>, {
+        defineProperty() {
+            return false;
+        },
+        deleteProperty() {
+            return false;
+        },
+        get<TNotificationName extends keyof IRpcSubscriptionsApi<TRpcSubscriptions>>(
+            ...args: Parameters<NonNullable<ProxyHandler<IRpcSubscriptionsApi<TRpcSubscriptions>>['get']>>
+        ) {
+            const [_, p] = args;
+            const notificationName = p.toString() as keyof TRpcSubscriptions as string;
+            return function (
+                ...rawParams: Parameters<
+                    TRpcSubscriptions[TNotificationName] extends CallableFunction
+                        ? TRpcSubscriptions[TNotificationName]
+                        : never
+                >
+            ): RpcSubscription<ReturnType<TRpcSubscriptions[TNotificationName]>> {
+                const params = config?.parametersTransformer
+                    ? config?.parametersTransformer(rawParams, notificationName)
+                    : rawParams;
+                const responseTransformer = config?.responseTransformer
+                    ? config?.responseTransformer<ReturnType<TRpcSubscriptions[TNotificationName]>>
+                    : (rawResponse: unknown) => rawResponse as ReturnType<TRpcSubscriptions[TNotificationName]>;
+                const subscribeMethodName = config?.subscribeNotificationNameTransformer
+                    ? config?.subscribeNotificationNameTransformer(notificationName)
+                    : notificationName;
+                const unsubscribeMethodName = config?.unsubscribeNotificationNameTransformer
+                    ? config?.unsubscribeNotificationNameTransformer(notificationName)
+                    : notificationName;
+                return {
+                    params,
+                    responseTransformer,
+                    subscribeMethodName,
+                    unsubscribeMethodName,
+                };
+            };
+        },
+    });
+}
diff --git a/packages/rpc-transport/src/index.ts b/packages/rpc-transport/src/index.ts
@@ -1,5 +1,6 @@
 export * from './apis/api-types';
 export * from './apis/methods/methods-api';
+export * from './apis/subscriptions/subscriptions-api';
 export * from './json-rpc';
 export type { SolanaJsonRpcErrorCode } from './json-rpc-errors';
 export * from './json-rpc-subscription';
diff --git a/packages/rpc-transport/src/json-rpc-subscription.ts b/packages/rpc-transport/src/json-rpc-subscription.ts
@@ -94,7 +94,9 @@ function createPendingRpcSubscription<TRpcSubscriptionMethods, TNotification>(
                             continue;
                         }
                         const notification = message.params.result as TNotification;
-                        yield responseTransformer ? responseTransformer(notification) : notification;
+                        yield responseTransformer
+                            ? responseTransformer(notification, subscribeMethodName)
+                            : notification;
                     }
                 },
             };
diff --git a/packages/rpc-transport/src/json-rpc-types.ts b/packages/rpc-transport/src/json-rpc-types.ts
@@ -30,7 +30,7 @@ export type RpcRequest<TResponse> = {
 };
 export type RpcSubscription<TResponse> = {
     params: unknown[];
-    responseTransformer?: (response: unknown) => TResponse;
+    responseTransformer?: (response: unknown, notificationName: string) => TResponse;
     subscribeMethodName: string;
     unsubscribeMethodName: string;
 };

Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,9 @@ function createPendingRpcSubscription<TRpcSubscriptionMethods, TNotification>(`
`94`	`94`	`continue;`
`95`	`95`	`}`
`96`	`96`	`const notification = message.params.result as TNotification;`
`97`		`- yield responseTransformer ? responseTransformer(notification) : notification;`
	`97`	`+ yield responseTransformer`
	`98`	`+ ? responseTransformer(notification, subscribeMethodName)`
	`99`	`+ : notification;`
`98`	`100`	`}`
`99`	`101`	`},`
`100`	`102`	`};`