@usearete/sdk 0.25.0 → 0.26.0

package/dist/index.d.ts

@@ -751,15 +751,15 @@ declare function createInstructionHandler<TParams = Record<string, unknown>, TEr
  */
 interface BuildOptions {
     /** Wallet, used only for accounts explicitly marked with signerKind: 'wallet'. */
-    wallet?: WalletAdapter;
+    wallet?: WalletAdapter | undefined;
     /** Explicit account-address overrides, including signer slots when needed. */
-    accounts?: Record<string, string>;
+    accounts?: Record<string, string> | undefined;
     /**
      * Extra account metas appended after the instruction's declared accounts
      * (Anchor's `remainingAccounts`) — for routers, transfer hooks, and other
      * composition patterns the IDL cannot express.
      */
-    remainingAccounts?: BuiltAccountMeta[];
+    remainingAccounts?: BuiltAccountMeta[] | undefined;
 }
 /**
  * Options for executing (building + sending) an instruction.
@@ -1163,6 +1163,14 @@ interface WatchOptions<TSchema = unknown> {
     /** Maximum number of entities to include in snapshot */
     snapshotLimit?: number;
 }
+/** Options for the one-shot reads `get` and `getOne`. */
+interface GetOptions extends WatchOptions {
+    /**
+     * How long to wait for the initial snapshot before rejecting with
+     * `InitialDataTimeoutError` (defaults to 5000). `null` waits forever.
+     */
+    timeoutMs?: number | null;
+}
 interface AreteOptions<TStack extends StackDefinition> {
     stack: TStack;
     /** Connect immediately when the client is created (defaults to true). */
@@ -1328,14 +1336,32 @@ interface TypedStateView<T, TKey = string> {
     use<TSchema = T>(key: TKey, options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
     watch(key: TKey, options?: WatchOptions): AsyncIterable<Update<T>>;
     watchRich(key: TKey, options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
-    get(key: TKey, options?: WatchOptions): Promise<T | null>;
+    /**
+     * Open (or reuse) the equivalent subscription, wait for its initial
+     * snapshot, and release it. Resolves `null` when the entity is absent.
+     */
+    get(key: TKey, options?: GetOptions): Promise<T | null>;
+    /**
+     * Read an already active equivalent subscription without waiting;
+     * `undefined` when none is active (absent is not the same as empty).
+     */
     getSync(key: TKey, options?: WatchOptions): T | null | undefined;
 }
 interface TypedListView<T> {
     use<TSchema = T>(options?: WatchOptions<TSchema>): AsyncIterable<TSchema>;
     watch(options?: WatchOptions): AsyncIterable<Update<T>>;
     watchRich(options?: WatchOptions): AsyncIterable<RichUpdate<T>>;
-    get(options?: WatchOptions): Promise<T[]>;
+    /**
+     * Open (or reuse) the equivalent subscription, wait for its initial
+     * snapshot, and release it.
+     */
+    get(options?: GetOptions): Promise<T[]>;
+    /** Like `get` with `take: 1`: the first item, or `null` when the list is empty. */
+    getOne(options?: Omit<GetOptions, 'take'>): Promise<T | null>;
+    /**
+     * Read an already active equivalent subscription without waiting;
+     * `undefined` when none is active (absent is not the same as empty).
+     */
     getSync(options?: WatchOptions): T[] | undefined;
 }
 type SubscribeCallback<T> = (update: Update<T>) => void;
@@ -1812,6 +1838,8 @@ declare class SubscriptionRegistry {
     private readonly queryStore;
     private readonly subscriptions;
     private readonly subscriptionsById;
+    private readonly failureListeners;
+    private connectionError;
     constructor(connection: ConnectionManager, queryStore: QueryStore);
     subscribe(query: SubscriptionQuery, snapshotEnabled?: boolean): QueryLease;
     refresh(query: SubscriptionQuery, snapshotEnabled?: boolean): Promise<void>;
@@ -1824,8 +1852,16 @@ declare class SubscriptionRegistry {
     getRefCount(query: SubscriptionQuery, snapshotEnabled?: boolean): number;
     getActiveSubscriptions(): Subscription[];
     getSnapshot<T>(query: SubscriptionQuery, snapshotEnabled?: boolean): QuerySnapshot<T> | undefined;
-    handleConnectionState(state: ConnectionState): void;
+    handleConnectionState(state: ConnectionState, message?: string): void;
+    /** The terminal connection failure while the connection is in the `error` state. */
+    getConnectionError(): AreteError | undefined;
+    /**
+     * Called when pending queries can no longer resolve: the connection failed
+     * terminally, or a disconnect cleared every subscription.
+     */
+    onFailure(callback: (error: AreteError) => void): UnsubscribeFn;
     clear(): void;
+    private notifyFailure;
     private createLease;
     private getTracker;
     private refreshTracker;
@@ -1984,18 +2020,18 @@ interface CreatePreparedInstructionInput<TArtifacts> {
     name: string;
     instruction: BuiltInstruction;
     artifacts: TArtifacts;
-    requiredSignerAddresses?: readonly string[];
-    signers?: readonly unknown[];
-    errors?: readonly ErrorMetadata[];
+    requiredSignerAddresses?: readonly string[] | undefined;
+    signers?: readonly unknown[] | undefined;
+    errors?: readonly ErrorMetadata[] | undefined;
 }
 type PreparedTransactionInstruction = BuiltInstruction | PreparedInstruction<unknown>;
 type PreparedTransactionOperation = PreparedInstruction<unknown> | PreparedTransaction<unknown>;
 interface CreatePreparedTransactionBaseInput<TArtifacts> {
     name: string;
     artifacts: TArtifacts;
-    requiredSignerAddresses?: readonly string[];
-    signers?: readonly unknown[];
-    errors?: readonly ErrorMetadata[];
+    requiredSignerAddresses?: readonly string[] | undefined;
+    signers?: readonly unknown[] | undefined;
+    errors?: readonly ErrorMetadata[] | undefined;
 }
 type CreatePreparedTransactionInput<TArtifacts> = CreatePreparedTransactionBaseInput<TArtifacts> & ({
     instructions: readonly PreparedTransactionInstruction[];
@@ -2012,9 +2048,9 @@ interface CreatePreparedFlowInput<TArtifacts> {
 declare function createPreparedTransactionBody(input: {
     name: string;
     instructions: readonly BuiltInstruction[];
-    requiredSignerAddresses?: readonly string[];
-    signers?: readonly unknown[];
-    errors?: readonly ErrorMetadata[];
+    requiredSignerAddresses?: readonly string[] | undefined;
+    signers?: readonly unknown[] | undefined;
+    errors?: readonly ErrorMetadata[] | undefined;
 }): PreparedTransactionBody;
 declare function createPreparedInstruction<TArtifacts>(input: CreatePreparedInstructionInput<TArtifacts>): PreparedInstruction<TArtifacts>;
 declare function createPreparedTransaction<TArtifacts>(input: CreatePreparedTransactionInput<TArtifacts>): PreparedTransaction<TArtifacts>;
@@ -2200,6 +2236,13 @@ type MaybeField<TKey extends string, TValue> = [TValue] extends [never] ? {} : {
     readonly [K in TKey]: TValue;
 };
 type Field<TValue, TKey extends PropertyKey> = TKey extends keyof TValue ? TValue[TKey] : never;
+/**
+ * A field an extension provides. The helpers skip an extension value that is
+ * `undefined`, so an optional field is never `undefined` on the result either
+ * (which `exactOptionalPropertyTypes` would reject where the result is used as
+ * a `ProgramSdkDefinition`).
+ */
+type ExtensionField<TValue, TKey extends PropertyKey> = Exclude<Field<TValue, TKey>, undefined>;
 type DeepMerge<TBase, TExtension> = TBase extends Record<string, unknown> ? TExtension extends Record<string, unknown> ? Omit<TBase, keyof TExtension> & {
     readonly [K in keyof TExtension]: K extends keyof TBase ? DeepMerge<TBase[K], TExtension[K]> : TExtension[K];
 } : TExtension : TExtension;
@@ -2251,7 +2294,7 @@ type DefinedProgramExtensions<TBase extends ProgramSdkDefinition, TAddresses, TC
     readonly createRead?: (context: ProgramOperationContext<ExtendedProgramDefinition<TBase, TAddresses, TConstants, TDefaults, ProgramOperations, TMath, never>>) => TRead;
 };
 declare function defineProgramExtensions<TBase extends ProgramSdkDefinition>(): <TAddresses = never, TConstants = never, TDefaults = never, TOperations extends AnyProgramOperations = ProgramOperations, TMath = never, TRead = never>(extensions: DefinedProgramExtensions<TBase, TAddresses, TConstants, TDefaults, TOperations, TMath, TRead>) => DefinedProgramExtensions<TBase, TAddresses, TConstants, TDefaults, TOperations, TMath, TRead>;
-declare function extendProgram<TBase extends ProgramSdkDefinition, TExtension extends ProgramExtensionInput<any, any, any, any, any, any, any>>(program: TBase, extensions: TExtension): ExtendedProgramDefinition<TBase, MergeField<Field<TBase, 'addresses'>, Field<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, Field<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, Field<TExtension, 'defaults'>>, Extract<FactoryReturn<TExtension, 'createOperations'>, AnyProgramOperations>, MergeField<Field<TBase, 'math'>, Field<TExtension, 'math'>>, FactoryReturn<TExtension, 'createRead'>>;
+declare function extendProgram<TBase extends ProgramSdkDefinition, TExtension extends ProgramExtensionInput<any, any, any, any, any, any, any>>(program: TBase, extensions: TExtension): ExtendedProgramDefinition<TBase, MergeField<Field<TBase, 'addresses'>, ExtensionField<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, ExtensionField<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, ExtensionField<TExtension, 'defaults'>>, Extract<FactoryReturn<TExtension, 'createOperations'>, AnyProgramOperations>, MergeField<Field<TBase, 'math'>, ExtensionField<TExtension, 'math'>>, FactoryReturn<TExtension, 'createRead'>>;
 declare function extendPrograms<TPrograms extends Record<string, ProgramSdkDefinition>, TExtensions extends Partial<{
     [K in keyof TPrograms]: ProgramExtensionInput<any, any, any, any, any, any, any>;
 }>>(programs: TPrograms, extensions: TExtensions): {
@@ -2290,7 +2333,7 @@ declare function defineStackExtensions<TBase extends StackDefinition>(): <const
     readonly createRead?: (client: StackExtensionClient<TBase, any, any, any, any>) => unknown;
     readonly createFlows?: (client: StackExtensionClient<TBase, any, any, any, any>) => FlowOperationNamespace | EmptyRecord;
 }) => TExtension;
-declare function extendStack<TBase extends StackDefinition, TExtension extends StackExtensionInput<any, any, any, any, any, any, any>>(stack: TBase, extensions: TExtension & ReadArgumentCountRequirement<TExtension>): ExtendedStackDefinition<TBase, MergeField<Field<TBase, 'addresses'>, Field<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, Field<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, Field<TExtension, 'defaults'>>, MergeField<Field<TBase, 'math'>, Field<TExtension, 'math'>>, MergeField<StackReadOf<TBase>, FactoryReturn<TExtension, 'createRead'>>, Extract<MergeField<StackFlowsOf<TBase>, FactoryReturn<TExtension, 'createFlows'>>, FlowOperationNamespace | EmptyRecord>>;
+declare function extendStack<TBase extends StackDefinition, TExtension extends StackExtensionInput<any, any, any, any, any, any, any>>(stack: TBase, extensions: TExtension & ReadArgumentCountRequirement<TExtension>): ExtendedStackDefinition<TBase, MergeField<Field<TBase, 'addresses'>, ExtensionField<TExtension, 'addresses'>>, MergeField<Field<TBase, 'constants'>, ExtensionField<TExtension, 'constants'>>, MergeField<Field<TBase, 'defaults'>, ExtensionField<TExtension, 'defaults'>>, MergeField<Field<TBase, 'math'>, ExtensionField<TExtension, 'math'>>, MergeField<StackReadOf<TBase>, FactoryReturn<TExtension, 'createRead'>>, Extract<MergeField<StackFlowsOf<TBase>, FactoryReturn<TExtension, 'createFlows'>>, FlowOperationNamespace | EmptyRecord>>;
 declare function getStackRuntimeExtensions<TStack extends StackDefinition>(stack: TStack): StackRuntimeExtensions<StackReadOf<TStack>> | undefined;
 declare function applyConnectedStackExtensions<TClient extends object, TStack extends StackDefinition>(client: TClient, stack: TStack): ConnectedStackClient<TClient, TStack>;
 
@@ -2773,7 +2816,8 @@ type AmountInput = bigint | {
 interface AmountResolutionInput {
     mint: string;
     amount: AmountInput;
-    decimals?: number;
+    /** The mint's decimals; read from the mint when absent. */
+    decimals?: number | undefined;
 }
 /** Convert a UI amount ("1.5") to raw base units using string math (no float precision loss). */
 declare function parseUiAmountToRaw(value: string | number, decimals: number): bigint;
@@ -2903,6 +2947,18 @@ declare function createUpdateStream<T>(_storage: StorageAdapter, subscriptionReg
 declare function createEntityStream<T>(_storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, query: SubscriptionQuery, options?: WatchOptions<any>, keyFilter?: string): AsyncIterable<T>;
 declare function createRichUpdateStream<T>(_storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry, query: SubscriptionQuery, keyFilter?: string, snapshotEnabled?: boolean): AsyncIterable<RichUpdate<T>>;
 
+/** How long `get` and `getOne` wait for an initial snapshot, as in the Rust and Python SDKs. */
+declare const DEFAULT_INITIAL_DATA_TIMEOUT_MS = 5000;
+/**
+ * `get` or `getOne` gave up waiting for the initial snapshot: the socket never
+ * delivered it (no connection, a reconnect storm, a server that never
+ * answers). The read's subscription is released before this is thrown.
+ */
+declare class InitialDataTimeoutError extends AreteError {
+    readonly view: string;
+    readonly timeoutMs: number;
+    constructor(view: string, timeoutMs: number);
+}
 declare function serializeViewKey<TKey>(viewDef: ViewDef<unknown, 'state', TKey>, key: TKey): string;
 declare function createTypedStateView<T, TKey = unknown>(viewDef: ViewDef<T, 'state', TKey>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedStateView<T, DefaultViewKey<TKey>>;
 declare function createTypedListView<T>(viewDef: ViewDef<T, 'list'>, storage: StorageAdapter, subscriptionRegistry: SubscriptionRegistry): TypedListView<T>;
@@ -2912,5 +2968,5 @@ declare const Arete: typeof Arete$1 & {
     session: typeof createSession;
 };
 
-export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InstructionError, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
-export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AmountInput, AnyOperation, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, AuthTokenResult, AuthTokenTarget, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ChainFailedTransactionOutcome, CompositionSessionOptions, ConfirmationLevel, ConfirmedTransactionOutcome, ConnectOptions, ConnectedArete, ConnectedStackClient, ConnectionState, ConnectionStateCallback, ContextSlotOptions, CreatePreparedFlowInput, CreatePreparedInstructionInput, CreatePreparedTransactionInput, DefaultViewKey, EntityFrame, ErrorFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, ExtendedProgramDefinition, ExtendedStackDefinition, FlowOperation, FlowOperationNamespace, FlowOperationReceipt, Frame, FrameMode, FrameOp, FrameProcessorConfig, FrameValidationDiagnostic, HostedSolanaGatewayBindings, HostedSolanaGatewayCapabilityBinding, HostedSolanaGatewayTransportOptions, HostedSolanaGatewayTransports, HttpAuthMetadata, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, LatestBlockhashResult, MergeProgramMaps, MintAccountInfo, NativeBalanceInfo, NonEmptyReadonlyArray, NotSubmittedTransactionOutcome, OperationCallbackPhase, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationInspection, OperationInspectionOptions, OperationKind, OperationKindBrand, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaDeriveContext, PdaFactory, PdaProgram, PdaProgramSelector, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountBatchItem, ProgramAccountBatchResult, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramIdentityMatch, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramReadBinding, ProgramReadBindingAuthTarget, ProgramReadDescriptor, ProgramReadDescriptors, ProgramReadOf, ProgramReadOverride, ProgramReadOverrides, ProgramReadRequest, ProgramReadTransport, ProgramReleaseReference, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramSdkIdentity, ProgramsInterface, QueriesInterface, QueryLease, QuerySnapshot, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadArgumentCount, ReadArgumentCounts, ReadTransportMethod, ReplayErrorCode, ReplayWindow, ResolvedAccount, ResolvedAccounts, ResolvedTransactionBuildOptions, ResolvedTransactionResourceOptions, ResourceLamports, ResourceUnits, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SolanaGatewayAuthMetadata, SolanaGatewayAuthScope, SolanaGatewayBindingAuthTarget, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRelease, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackVersionRefusal, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubmittedUnknownTransactionOutcome, SubscribeCallback, SubscribedFrame, Subscription, SubscriptionIdentity, SubscriptionOptions, SubscriptionQuery, SubscriptionRequest, SubscriptionSnapshotOptions, TokenAccountInfo, TokenBalanceInfo, TokenBalanceInput, TransactionBuildCapability, TransactionBuildOptions, TransactionCommitment, TransactionFailureOutcome, TransactionFailurePhase, TransactionFailureStatus, TransactionFeeResult, TransactionInspectionOptions, TransactionInspectionResult, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TransactionOptionsErrorCode, TransactionOutcome, TransactionRequestContext, TransactionResourceOptionKey, TransactionResourceOptions, TransactionSendOptions, TransactionSendResult, TransactionSignatureStatus, TransactionSimulationOptions, TransactionSimulationResult, TransactionTransport, TransactionTransportErrorBody, TransactionVersion, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, UnsubscribedFrame, Update, UpdateCallback, ViewDef, ViewGroup, ViewKeyFields, ViewKeyValue, ViewSortConfig, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletExecutionContext, WalletState, WatchOptions, WebSocketFactoryInit };
+export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_INITIAL_DATA_TIMEOUT_MS, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InitialDataTimeoutError, InstructionError, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
+export type { AccountCategory, AccountLoader, AccountMeta, AccountResolutionOptions, AccountResolutionResult, AmountInput, AnyOperation, AreteConfig, AreteOptions, AreteOptionsWithStorage, ArgSchema, ArgType, AuthConfig, AuthTokenRequest, AuthTokenResult, AuthTokenTarget, BuildOptions, BuiltAccountMeta, BuiltInstruction, ChainClient, ChainClock, ChainFailedTransactionOutcome, CompositionSessionOptions, ConfirmationLevel, ConfirmedTransactionOutcome, ConnectOptions, ConnectedArete, ConnectedStackClient, ConnectionState, ConnectionStateCallback, ContextSlotOptions, CreatePreparedFlowInput, CreatePreparedInstructionInput, CreatePreparedTransactionInput, DefaultViewKey, EntityFrame, ErrorFrame, ErrorMetadata, ExecuteOptions, ExecutionResult, ExtendedProgramDefinition, ExtendedStackDefinition, FlowOperation, FlowOperationNamespace, FlowOperationReceipt, Frame, FrameMode, FrameOp, FrameProcessorConfig, FrameValidationDiagnostic, GetOptions, HostedSolanaGatewayBindings, HostedSolanaGatewayCapabilityBinding, HostedSolanaGatewayTransportOptions, HostedSolanaGatewayTransports, HttpAuthMetadata, InstructionExecutor, InstructionHandler, InstructionHandlerConfig, InstructionOperation, InstructionOperationNamespace, JsonObject, JsonPrimitive, JsonValue, LatestBlockhashResult, MergeProgramMaps, MintAccountInfo, NativeBalanceInfo, NonEmptyReadonlyArray, NotSubmittedTransactionOutcome, OperationCallbackPhase, OperationExecutionEvent, OperationExecutionHost, OperationExecutionOptions, OperationExecutionSuccessEvent, OperationInspection, OperationInspectionOptions, OperationKind, OperationKindBrand, OperationNamespace, OperationPlan, OperationReceiptFor, OperationTransactionReceipt, PdaConfig, PdaDeriveContext, PdaFactory, PdaProgram, PdaProgramSelector, PdaSeed, PreparedFlow, PreparedInstruction, PreparedOperation, PreparedOperationDescription, PreparedTransaction, PreparedTransactionBody, PreparedTransactionInstruction, PreparedTransactionOperation, ProgramAccountBatchItem, ProgramAccountBatchResult, ProgramAccountReadDefinition, ProgramError, ProgramExtensionInput, ProgramIdentityMatch, ProgramInterface, ProgramOperationContext, ProgramOperations, ProgramOperationsOf, ProgramPdas, ProgramQueryDefinition, ProgramReadBinding, ProgramReadBindingAuthTarget, ProgramReadDescriptor, ProgramReadDescriptors, ProgramReadOf, ProgramReadOverride, ProgramReadOverrides, ProgramReadRequest, ProgramReadTransport, ProgramReleaseReference, ProgramRuntimeExtensionCarrier, ProgramRuntimeExtensions, ProgramSdkDefinition, ProgramSdkIdentity, ProgramsInterface, QueriesInterface, QueryLease, QuerySnapshot, RawAccountInfo, RawInstructionsInterface, RawProgramsInterface, ReadArgumentCount, ReadArgumentCounts, ReadTransportMethod, ReplayErrorCode, ReplayWindow, ResolvedAccount, ResolvedAccounts, ResolvedTransactionBuildOptions, ResolvedTransactionResourceOptions, ResourceLamports, ResourceUnits, RichUpdate, RichUpdateCallback, Schema, SchemaResult, SeedDef, SendOptions, SendResult, Session, SessionDefinition, SessionMemberOptions, SessionOptions, SignerRegistry, SingleTransactionOperationReceipt, SnapshotEntity, SnapshotFrame, SocketIssue, SocketIssueCallback, SolanaGatewayAuthMetadata, SolanaGatewayAuthScope, SolanaGatewayBindingAuthTarget, SortConfig, SortOrder, StackConnectedExtensions, StackDefinition, StackEndpoints, StackExtensionClient, StackExtensionInput, StackQueryDefinition, StackRelease, StackRuntimeExtensionCarrier, StackRuntimeExtensions, StackVersionRefusal, StackWithAttachedPrograms, StorageAdapter, StorageAdapterConfig, StringifiedBigints, SubmittedUnknownTransactionOutcome, SubscribeCallback, SubscribedFrame, Subscription, SubscriptionIdentity, SubscriptionOptions, SubscriptionQuery, SubscriptionRequest, SubscriptionSnapshotOptions, TokenAccountInfo, TokenBalanceInfo, TokenBalanceInput, TransactionBuildCapability, TransactionBuildOptions, TransactionCommitment, TransactionFailureOutcome, TransactionFailurePhase, TransactionFailureStatus, TransactionFeeResult, TransactionInspectionOptions, TransactionInspectionResult, TransactionOperation, TransactionOperationNamespace, TransactionOptions, TransactionOptionsErrorCode, TransactionOutcome, TransactionRequestContext, TransactionResourceOptionKey, TransactionResourceOptions, TransactionSendOptions, TransactionSendResult, TransactionSignatureStatus, TransactionSimulationOptions, TransactionSimulationResult, TransactionTransport, TransactionTransportErrorBody, TransactionVersion, TypedAccountReader, TypedInstruction, TypedListView, TypedQueryExecutor, TypedStateView, TypedViewGroup, TypedViews, UnsubscribeFn, UnsubscribedFrame, Update, UpdateCallback, ViewDef, ViewGroup, ViewKeyFields, ViewKeyValue, ViewSortConfig, WaitForProcessedSlotOptions, WalletAdapter, WalletConnectOptions, WalletExecutionContext, WalletState, WatchOptions, WebSocketFactoryInit };

package/dist/index.esm.js

@@ -442,6 +442,7 @@ class SubscriptionRegistry {
         this.queryStore = queryStore;
         this.subscriptions = new Map();
         this.subscriptionsById = new Map();
+        this.failureListeners = new Set();
     }
     subscribe(query, snapshotEnabled = true) {
         const request = normalizeSubscriptionRequest({
@@ -504,12 +505,30 @@ class SubscriptionRegistry {
             ? this.queryStore.getSnapshot(tracker.subscription.subscriptionId)
             : undefined;
     }
-    handleConnectionState(state) {
+    handleConnectionState(state, message) {
         if (state === 'reconnecting')
             this.queryStore.beginReconnect();
-        if (state === 'error') {
-            this.queryStore.failRefreshing(new AreteError('Connection failed while refreshing subscriptions', 'CONNECTION_ERROR'));
+        if (state !== 'error') {
+            this.connectionError = undefined;
+            return;
         }
+        this.queryStore.failRefreshing(new AreteError('Connection failed while refreshing subscriptions', 'CONNECTION_ERROR'));
+        // Queries still waiting for their first snapshot are not failed above;
+        // one-shot reads learn about the failure here instead of timing out.
+        this.connectionError = new AreteError(message ?? 'Connection failed', 'CONNECTION_ERROR');
+        this.notifyFailure(this.connectionError);
+    }
+    /** The terminal connection failure while the connection is in the `error` state. */
+    getConnectionError() {
+        return this.connectionError;
+    }
+    /**
+     * Called when pending queries can no longer resolve: the connection failed
+     * terminally, or a disconnect cleared every subscription.
+     */
+    onFailure(callback) {
+        this.failureListeners.add(callback);
+        return () => this.failureListeners.delete(callback);
     }
     clear() {
         for (const { subscription } of this.subscriptions.values()) {
@@ -525,6 +544,11 @@ class SubscriptionRegistry {
         }
         this.subscriptions.clear();
         this.subscriptionsById.clear();
+        this.notifyFailure(new AreteError('Subscriptions were cleared by a disconnect', 'CONNECTION_CANCELLED'));
+    }
+    notifyFailure(error) {
+        for (const listener of [...this.failureListeners])
+            listener(error);
     }
     createLease(tracker) {
         let released = false;
@@ -3563,10 +3587,90 @@ function createRichUpdateStream(_storage, subscriptionRegistry, query, keyFilter
     };
 }
 
+/** How long `get` and `getOne` wait for an initial snapshot, as in the Rust and Python SDKs. */
+const DEFAULT_INITIAL_DATA_TIMEOUT_MS = 5000;
+/**
+ * `get` or `getOne` gave up waiting for the initial snapshot: the socket never
+ * delivered it (no connection, a reconnect storm, a server that never
+ * answers). The read's subscription is released before this is thrown.
+ */
+class InitialDataTimeoutError extends AreteError {
+    constructor(view, timeoutMs) {
+        super(`Timed out after ${timeoutMs}ms waiting for the initial snapshot of view '${view}'`, 'INITIAL_DATA_TIMEOUT', { view, timeoutMs });
+        this.view = view;
+        this.timeoutMs = timeoutMs;
+        this.name = 'InitialDataTimeoutError';
+    }
+}
 function queryOptions(options) {
-    const { schema: _schema, withSnapshot, ...query } = options ?? {};
+    const { schema: _schema, withSnapshot, timeoutMs: _timeoutMs, ...query } = options ?? {};
     return { query, snapshotEnabled: withSnapshot ?? true };
 }
+function resolveTimeout(options) {
+    const timeoutMs = options?.timeoutMs === undefined
+        ? DEFAULT_INITIAL_DATA_TIMEOUT_MS
+        : options.timeoutMs;
+    if (timeoutMs !== null && (!Number.isFinite(timeoutMs) || timeoutMs <= 0)) {
+        throw new RangeError('timeoutMs must be a positive finite number or null');
+    }
+    return timeoutMs;
+}
+/**
+ * Open (or reuse) the equivalent subscription, wait until its snapshot has
+ * resolved or its query has failed, and release it. A terminal connection
+ * failure or a disconnect rejects with that reason. Bounded by `timeoutMs`
+ * (`null` waits forever) so a socket that never delivers cannot hang the caller.
+ */
+async function readResolved(registry, query, snapshotEnabled, timeoutMs) {
+    const lease = registry.subscribe(query, snapshotEnabled);
+    try {
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            let stop = () => { };
+            let timer;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                stop();
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const check = () => {
+                const error = lease.getError();
+                if (error)
+                    finish(error);
+                else if (!lease.getSnapshot().isLoading)
+                    finish();
+                else {
+                    const connectionError = registry.getConnectionError();
+                    if (connectionError)
+                        finish(connectionError);
+                }
+            };
+            check();
+            if (settled)
+                return;
+            const stopChanges = lease.onChange(check);
+            const stopFailures = registry.onFailure(finish);
+            stop = () => {
+                stopChanges();
+                stopFailures();
+            };
+            if (timeoutMs !== null) {
+                timer = setTimeout(() => finish(new InitialDataTimeoutError(query.view, timeoutMs)), timeoutMs);
+            }
+        });
+        return lease.getSnapshot();
+    }
+    finally {
+        lease.release();
+    }
+}
 function serializeViewKeyValue(value, view, field) {
     const location = field === undefined ? `view '${view}'` : `key field '${field}' for view '${view}'`;
     if (typeof value === 'string')
@@ -3617,7 +3721,10 @@ function createTypedStateView(viewDef, storage, subscriptionRegistry) {
             return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, key: serializedKey, ...query }, serializedKey, snapshotEnabled);
         },
         async get(key, options) {
-            return this.getSync(key, options) ?? null;
+            const timeoutMs = resolveTimeout(options);
+            const { query, snapshotEnabled } = queryOptions(options);
+            const snapshot = await readResolved(subscriptionRegistry, { view: viewDef.view, key: wireKey(key), ...query }, snapshotEnabled, timeoutMs);
+            return snapshot.data[0] ?? null;
         },
         getSync(key, options) {
             const { query, snapshotEnabled } = queryOptions(options);
@@ -3645,7 +3752,14 @@ function createTypedListView(viewDef, storage, subscriptionRegistry) {
             return createRichUpdateStream(storage, subscriptionRegistry, { view: viewDef.view, ...query }, undefined, snapshotEnabled);
         },
         async get(options) {
-            return this.getSync(options) ?? [];
+            const timeoutMs = resolveTimeout(options);
+            const { query, snapshotEnabled } = queryOptions(options);
+            const snapshot = await readResolved(subscriptionRegistry, { view: viewDef.view, ...query }, snapshotEnabled, timeoutMs);
+            return [...snapshot.data];
+        },
+        async getOne(options) {
+            const items = await this.get({ ...options, take: 1 });
+            return items[0] ?? null;
         },
         getSync(options) {
             const { query, snapshotEnabled } = queryOptions(options);
@@ -7563,8 +7677,8 @@ let Arete$1 = class Arete {
         this.connection.onFrame((frame) => {
             this.processor.handleFrame(frame);
         });
-        this.connection.onStateChange((state) => {
-            this.subscriptionRegistry.handleConnectionState(state);
+        this.connection.onStateChange((state, error) => {
+            this.subscriptionRegistry.handleConnectionState(state, error);
         });
         this._views = createTypedViews(this.stack, this.storage, this.subscriptionRegistry);
         this._queries = this.buildQueries();
@@ -8547,5 +8661,5 @@ function stringifyBigints(value) {
 
 const Arete = Object.assign(Arete$1, { session: createSession });
 
-export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InstructionError, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
+export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_INITIAL_DATA_TIMEOUT_MS, DEFAULT_MAX_ENTRIES_PER_VIEW, EXTENSION_API_VERSION, FrameProcessor, InitialDataTimeoutError, InstructionError, MemoryAdapter, OPERATION_KIND, OperationCallbackError, OperationExecutionError, PROGRAM_KEY_CONFLICT, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, StreamGapError, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TRANSACTION_RESOURCE_OPTION_KEYS, TransactionExecutionError, TransactionOptionsError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, compareProgramIdentity, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getOperationKind, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, hostedWebsocketSuffixes, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isReplayErrorCode, isSameProgramSdk, isSnapshotFrame, isStackVersionRefusalCode, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, resolveTransactionBuildOptions, safeToRawAmount, serializeInstructionData, serializeViewKey, setHostedWebsocketSuffixes, stackQuery, stringifyBigints, toJsonValue, toRawAmount, toWireResourceOptions, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withProgramIdentity, withProgramRead, withPrograms };
 //# sourceMappingURL=index.esm.js.map