refactor(experimental): a comparator for commitments (#1698)

# Summary

A handy utility that lets you know if one commitment is ‘lower’ than the other.

# Test Plan

```
cd packages/rpc-core
pnpm test:unit:browser
pnpm test:unit:node
```

Author: steveluscher

packages/rpc-core/src/__tests__/commitment-test.ts

@@ -0,0 +1,11 @@
+import { Commitment, commitmentComparator } from '../commitment';
+
+describe('commitmentComparator', () => {
+    it('sorts commitments according to their level of finality ascending', () => {
+        expect((['finalized', 'processed', 'confirmed'] as Commitment[]).sort(commitmentComparator)).toEqual([
+            'processed',
+            'confirmed',
+            'finalized',
+        ]);
+    });
+});

packages/rpc-core/src/commitment.ts

@@ -0,0 +1,23 @@
+export type Commitment = 'confirmed' | 'finalized' | 'processed';
+
+function getCommitmentScore(commitment: Commitment): number {
+    switch (commitment) {
+        case 'finalized':
+            return 2;
+        case 'confirmed':
+            return 1;
+        case 'processed':
+            return 0;
+        default:
+            return ((_: never) => {
+                throw new Error(`Unrecognized commitment \`${commitment}\`.`);
+            })(commitment);
+    }
+}
+
+export function commitmentComparator(a: Commitment, b: Commitment): -1 | 0 | 1 {
+    if (a === b) {
+        return 0;
+    }
+    return getCommitmentScore(a) < getCommitmentScore(b) ? -1 : 1;
+}

packages/rpc-core/src/index.ts

@@ -1,3 +1,4 @@
+export * from './commitment';
 export * from './lamports';
 export * from './rpc-methods';
 export * from './rpc-subscriptions';

packages/rpc-core/src/rpc-methods/__tests__/get-account-info-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-balance-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getBalance', () => {

packages/rpc-core/src/rpc-methods/__tests__/get-block-height.ts

@@ -3,7 +3,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getBlockHeight', () => {

packages/rpc-core/src/rpc-methods/__tests__/get-block-production-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-epoch-info-test.ts

@@ -3,7 +3,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getEpochInfo', () => {

packages/rpc-core/src/rpc-methods/__tests__/get-fee-for-message-test.ts

@@ -5,7 +5,7 @@ import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import { Blockhash, SerializedMessageBytesBase64 } from '@solana/transactions';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-inflation-governor-test.ts

@@ -2,7 +2,7 @@ import { createHttpTransport, createJsonRpc } from '@solana/rpc-transport';
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getInflationGovernor', () => {

packages/rpc-core/src/rpc-methods/__tests__/get-inflation-reward-test.ts

@@ -3,7 +3,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getInflationReward', () => {

packages/rpc-core/src/rpc-methods/__tests__/get-largest-accounts-test.ts

@@ -7,7 +7,7 @@ import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 import path from 'path';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-latest-blockhash-test.ts

@@ -3,7 +3,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-leader-schedule-test.ts

@@ -7,7 +7,7 @@ import { open } from 'fs/promises';
 import fetchMock from 'jest-fetch-mock-fork';
 import path from 'path';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const validatorKeypairPath = path.resolve(__dirname, '../../../../../test-ledger/validator-keypair.json');

packages/rpc-core/src/rpc-methods/__tests__/get-minimum-balance-for-rent-exemption-test.ts

@@ -2,7 +2,7 @@ import { createHttpTransport, createJsonRpc } from '@solana/rpc-transport';
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getMinimumBalanceForRentExemption', () => {

packages/rpc-core/src/rpc-methods/__tests__/get-multiple-accounts-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-program-accounts-test.ts

@@ -8,7 +8,7 @@ import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 import path from 'path';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-slot-test.ts

@@ -3,7 +3,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getSlot', () => {

packages/rpc-core/src/rpc-methods/__tests__/get-stake-activation-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 // See scripts/fixtures/stake-account.json

packages/rpc-core/src/rpc-methods/__tests__/get-stake-minimum-delegation-test.ts

@@ -2,7 +2,7 @@ import { createHttpTransport, createJsonRpc } from '@solana/rpc-transport';
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getStakeMinimumDelegation', () => {

packages/rpc-core/src/rpc-methods/__tests__/get-supply-test.ts

@@ -2,7 +2,7 @@ import { createHttpTransport, createJsonRpc } from '@solana/rpc-transport';
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-token-account-balance-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-token-accounts-by-delegate-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-token-accounts-by-owner-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-token-largest-accounts-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-token-supply-test.ts

@@ -4,7 +4,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/__tests__/get-transaction-count-test.ts

@@ -3,7 +3,7 @@ import type { SolanaJsonRpcErrorCode } from '@solana/rpc-transport/dist/types/js
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('getTransactionCount', () => {

packages/rpc-core/src/rpc-methods/__tests__/is-blockhash-valid-test.ts

@@ -3,7 +3,7 @@ import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import { Blockhash } from '@solana/transactions';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('isBlockhashValid', () => {

packages/rpc-core/src/rpc-methods/__tests__/request-airdrop-test.ts

@@ -4,8 +4,8 @@ import { createHttpTransport, createJsonRpc } from '@solana/rpc-transport';
 import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import fetchMock from 'jest-fetch-mock-fork';
 
+import { Commitment } from '../../commitment';
 import { LamportsUnsafeBeyond2Pow53Minus1 } from '../../lamports';
-import { Commitment } from '../common';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 describe('requestAirdrop', () => {

packages/rpc-core/src/rpc-methods/__tests__/send-transaction-test.ts

@@ -5,7 +5,7 @@ import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import { Base64EncodedWireTransaction } from '@solana/transactions';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Commitment } from '../common';
+import { Commitment } from '../../commitment';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 function getMockTransactionMessage({

packages/rpc-core/src/rpc-methods/__tests__/simulate-transaction-test.ts

@@ -6,7 +6,8 @@ import type { Rpc } from '@solana/rpc-transport/dist/types/json-rpc-types';
 import { Base64EncodedWireTransaction } from '@solana/transactions';
 import fetchMock from 'jest-fetch-mock-fork';
 
-import { Base58EncodedBytes, Commitment } from '../common';
+import { Commitment } from '../../commitment';
+import { Base58EncodedBytes } from '../common';
 import { createSolanaRpcApi, SolanaRpcMethods } from '../index';
 
 const CONTEXT_MATCHER = expect.objectContaining({

packages/rpc-core/src/rpc-methods/common.ts

@@ -4,8 +4,6 @@ import { LamportsUnsafeBeyond2Pow53Minus1 } from '../lamports';
 import { StringifiedBigInt } from '../stringified-bigint';
 import { StringifiedNumber } from '../stringified-number';
 
-export type Commitment = 'confirmed' | 'finalized' | 'processed';
-
 export type DataSlice = Readonly<{
     offset: number;
     length: number;

packages/rpc-core/src/rpc-methods/getAccountInfo.ts

@@ -1,13 +1,13 @@
 import { Base58EncodedAddress } from '@solana/addresses';
 
+import { Commitment } from '../commitment';
 import {
     AccountInfoBase,
     AccountInfoWithBase58Bytes,
     AccountInfoWithBase58EncodedData,
     AccountInfoWithBase64EncodedData,
     AccountInfoWithBase64EncodedZStdCompressedData,
     AccountInfoWithJsonData,
-    Commitment,
     DataSlice,
     RpcResponse,
     Slot,

packages/rpc-core/src/rpc-methods/getBalance.ts

@@ -1,7 +1,8 @@
 import { Base58EncodedAddress } from '@solana/addresses';
 
+import { Commitment } from '../commitment';
 import { LamportsUnsafeBeyond2Pow53Minus1 } from '../lamports';
-import { Commitment, RpcResponse, Slot } from './common';
+import { RpcResponse, Slot } from './common';
 
 type GetBalanceApiResponse = RpcResponse<LamportsUnsafeBeyond2Pow53Minus1>;
 

packages/rpc-core/src/rpc-methods/getBlock.ts

@@ -1,7 +1,8 @@
 import { Blockhash, TransactionVersion } from '@solana/transactions';
 
+import { Commitment } from '../commitment';
 import { UnixTimestamp } from '../unix-timestamp';
-import { Base58EncodedBytes, Commitment, Slot, U64UnsafeBeyond2Pow53Minus1 } from './common';
+import { Base58EncodedBytes, Slot, U64UnsafeBeyond2Pow53Minus1 } from './common';
 import {
     Reward,
     TransactionForAccounts,

packages/rpc-core/src/rpc-methods/getBlockHeight.ts

@@ -1,4 +1,5 @@
-import { Commitment, Slot, U64UnsafeBeyond2Pow53Minus1 } from './common';
+import { Commitment } from '../commitment';
+import { Slot, U64UnsafeBeyond2Pow53Minus1 } from './common';
 
 type GetBlockHeightApiResponse = U64UnsafeBeyond2Pow53Minus1;
 

packages/rpc-core/src/rpc-methods/getBlockProduction.ts

@@ -1,6 +1,7 @@
 import { Base58EncodedAddress } from '@solana/addresses';
 
-import { Commitment, RpcResponse, U64UnsafeBeyond2Pow53Minus1 } from './common';
+import { Commitment } from '../commitment';
+import { RpcResponse, U64UnsafeBeyond2Pow53Minus1 } from './common';
 
 type NumberOfLeaderSlots = U64UnsafeBeyond2Pow53Minus1;
 type NumberOfBlocksProduced = U64UnsafeBeyond2Pow53Minus1;

packages/rpc-core/src/rpc-methods/getBlocks.ts

@@ -1,4 +1,5 @@
-import { Commitment, Slot } from './common';
+import { Commitment } from '../commitment';
+import { Slot } from './common';
 
 type GetBlocksApiResponse = Slot[];
 

packages/rpc-core/src/rpc-methods/getBlocksWithLimit.ts

@@ -1,4 +1,5 @@
-import { Commitment, Slot } from './common';
+import { Commitment } from '../commitment';
+import { Slot } from './common';
 
 type GetBlocksWithLimitApiResponse = Slot[];
 

packages/rpc-core/src/rpc-methods/getEpochInfo.ts

@@ -1,4 +1,5 @@
-import { Commitment, Slot, U64UnsafeBeyond2Pow53Minus1 } from './common';
+import { Commitment } from '../commitment';
+import { Slot, U64UnsafeBeyond2Pow53Minus1 } from './common';
 
 type GetEpochInfoApiResponse = Readonly<{
     /** the current slot */

packages/rpc-core/src/rpc-methods/getFeeForMessage.ts

@@ -1,6 +1,7 @@
 import { SerializedMessageBytesBase64 } from '@solana/transactions';
 
-import { Commitment, RpcResponse, Slot, U64UnsafeBeyond2Pow53Minus1 } from './common';
+import { Commitment } from '../commitment';
+import { RpcResponse, Slot, U64UnsafeBeyond2Pow53Minus1 } from './common';
 
 /** Fee corresponding to the message at the specified blockhash */
 type GetFeeForMessageApiResponse = RpcResponse<U64UnsafeBeyond2Pow53Minus1 | null>;

packages/rpc-core/src/rpc-methods/getInflationGovernor.ts

@@ -1,4 +1,5 @@
-import { Commitment, F64UnsafeSeeDocumentation } from './common';
+import { Commitment } from '../commitment';
+import { F64UnsafeSeeDocumentation } from './common';
 
 type GetInflationGovernorApiResponse = Readonly<{
     /** The initial inflation percentage from time 0 */