subgraph-sync/dist/types/index.d.ts

React hooks and components for tracking subgraph synchronization states with Apollo Client

/**
 * Represents a blockchain block with its number and timestamp.
 */
export interface Block {
    /** Block number */
    number: number;
    /** Block timestamp (Unix timestamp in seconds) */
    timestamp: number;
    /** Optional block hash */
    hash?: string;
}
/**
 * Subgraph metadata and indexing status.
 */
export interface SubgraphStatus {
    /** Current block information */
    block: Block;
    /** Whether the subgraph has indexing errors */
    hasIndexingErrors: boolean;
    /** Optional deployment identifier */
    deployment?: string;
}
/**
 * Configuration options for subgraph synchronization.
 */
export interface SyncConfig {
    /** Polling interval in milliseconds (default: 2000) */
    pollInterval?: number;
    /** Timeout duration in milliseconds (default: 120000) */
    timeout?: number;
    /** Maximum number of retry attempts (default: 3) */
    maxRetries?: number;
    /** Callback invoked when sync times out */
    onTimeout?: () => void;
    /** Callback invoked when an error occurs after max retries */
    onError?: (error: Error) => void;
    /** Callback invoked when sync completes successfully */
    onSyncComplete?: (status: SubgraphStatus) => void;
}
/**
 * Target block or timestamp for synchronization.
 * At least one property should be specified.
 */
export interface SyncTarget {
    /** Target block number to wait for */
    blockNumber?: number;
    /** Target timestamp to wait for (Unix timestamp in seconds) */
    timestamp?: number;
    /** Optional transaction hash (not currently used) */
    txHash?: string;
}
/**
 * Current state of subgraph synchronization.
 */
export interface SyncState {
    /** Whether the subgraph is currently indexing to reach the target */
    isIndexing: boolean;
    /** Whether the subgraph has reached the target block/timestamp */
    isSynced: boolean;
    /** Whether the sync operation has timed out */
    isTimeout: boolean;
    /** Whether an error occurred during syncing */
    isError: boolean;
    /** Current block that the subgraph has indexed */
    currentBlock: Block | null;
    /** Target block that we're waiting for */
    targetBlock: Block | null;
    /** Progress percentage (0-100) */
    progress: number;
    /** Error message if an error occurred */
    error: string | null;
    /** Number of retry attempts made */
    retries: number;
}
/**
 * Return type of useSubgraphSync hook, extending SyncState with control functions.
 */
export interface UseSubgraphSyncResult extends SyncState {
    /** Manually refetch the current subgraph status */
    refetch: () => Promise<any>;
    /** Reset the sync state to initial values */
    reset: () => void;
}
/**
 * Options for useSubgraphQuery, combining Apollo query options with sync tracking.
 */
export interface QueryWithSyncOptions<TVariables = any> {
    /** Sync configuration options */
    syncConfig?: SyncConfig;
    /** Target block number to wait for */
    targetBlockNumber?: number;
    /** Target timestamp to wait for */
    targetTimestamp?: number;
    /** GraphQL query variables */
    variables?: TVariables;
}