@qualithm/arrow-flight-sql-js 0.0.1

package/dist/retry.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Retry logic with exponential backoff for transient failures.
+ *
+ * Implements configurable retry strategies with:
+ * - Exponential backoff between attempts
+ * - Optional jitter to prevent thundering herd
+ * - Customizable retry conditions
+ * - gRPC status code awareness
+ */
+import type { RetryOptions } from "./types";
+/**
+ * Check if a gRPC error is retryable based on its status code
+ */
+export declare function isRetryableGrpcError(error: unknown): boolean;
+/**
+ * Default function to determine if an error is retryable.
+ * Handles gRPC errors and common network errors.
+ */
+export declare function defaultIsRetryable(error: unknown): boolean;
+/**
+ * Calculate delay for a retry attempt with optional jitter
+ */
+export declare function calculateBackoffDelay(attempt: number, options: Required<Omit<RetryOptions, "isRetryable">>): number;
+/**
+ * Result of a retry operation
+ */
+export interface RetryResult<T> {
+    /** The successful result value */
+    value: T;
+    /** Number of attempts made (1 = succeeded on first try) */
+    attempts: number;
+    /** Total time spent including delays (ms) */
+    totalTimeMs: number;
+}
+/**
+ * Execute a function with automatic retries on transient failures.
+ *
+ * @param operation - The async function to execute
+ * @param options - Retry configuration
+ * @returns The result of the operation
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => await client.query("SELECT 1"),
+ *   { maxRetries: 3, initialDelayMs: 100 }
+ * )
+ * ```
+ */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<RetryResult<T>>;
+/**
+ * A retry policy that can be reused across multiple operations.
+ * Useful for applying consistent retry behavior.
+ */
+export declare class RetryPolicy {
+    private readonly config;
+    private readonly isRetryable;
+    constructor(options?: RetryOptions);
+    /**
+     * Execute an operation with this policy's retry configuration
+     */
+    execute<T>(operation: () => Promise<T>): Promise<RetryResult<T>>;
+    /**
+     * Create a wrapped version of an async function that automatically retries
+     */
+    wrap<T, TArgs extends unknown[]>(fn: (...args: TArgs) => Promise<T>): (...args: TArgs) => Promise<T>;
+    /**
+     * Check if an error would be retried by this policy
+     */
+    wouldRetry(error: unknown): boolean;
+    /**
+     * Get the delay that would be used for a specific attempt
+     */
+    getDelayForAttempt(attempt: number): number;
+}
+/**
+ * Pre-configured retry policies for common use cases
+ */
+export declare const retryPolicies: {
+    /** No retries - fail immediately */
+    readonly none: RetryPolicy;
+    /** Fast retries for low-latency operations */
+    readonly fast: RetryPolicy;
+    /** Default retry policy with moderate settings */
+    readonly default: RetryPolicy;
+    /** Aggressive retries for critical operations */
+    readonly aggressive: RetryPolicy;
+    /** Very long retries for reconnection scenarios */
+    readonly reconnection: RetryPolicy;
+};
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAsB3C;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM5D;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoB1D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,GACnD,MAAM,CAeR;AASD;;GAEG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;IACR,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAA;IAChB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAqCzB;AAED;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IACpE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;gBAE7C,OAAO,GAAE,YAAiB;IAQtC;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAOtE;;OAEG;IACH,IAAI,CAAC,CAAC,EAAE,KAAK,SAAS,OAAO,EAAE,EAC7B,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,GACjC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC;IAOjC;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAInC;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAG5C;AAED;;GAEG;AACH,eAAO,MAAM,aAAa;IACxB,oCAAoC;;IAGpC,8CAA8C;;IAQ9C,kDAAkD;;IAQlD,iDAAiD;;IAQjD,mDAAmD;;CAO3C,CAAA"}

package/dist/retry.js

@@ -0,0 +1,212 @@
+/**
+ * Retry logic with exponential backoff for transient failures.
+ *
+ * Implements configurable retry strategies with:
+ * - Exponential backoff between attempts
+ * - Optional jitter to prevent thundering herd
+ * - Customizable retry conditions
+ * - gRPC status code awareness
+ */
+import * as grpc from "@grpc/grpc-js";
+// Default retry configuration
+const defaultRetryOptions = {
+    maxRetries: 3,
+    initialDelayMs: 100,
+    maxDelayMs: 10_000,
+    backoffMultiplier: 2,
+    jitter: true
+};
+/**
+ * gRPC status codes that indicate transient failures worth retrying
+ */
+const retryableGrpcCodes = new Set([
+    grpc.status.UNAVAILABLE, // Server temporarily unavailable
+    grpc.status.RESOURCE_EXHAUSTED, // Rate limited or quota exceeded
+    grpc.status.ABORTED, // Transaction aborted, can retry
+    grpc.status.DEADLINE_EXCEEDED, // Timeout, might succeed on retry
+    grpc.status.INTERNAL // Internal error, might be transient
+]);
+/**
+ * Check if a gRPC error is retryable based on its status code
+ */
+export function isRetryableGrpcError(error) {
+    if (error instanceof Error && "code" in error) {
+        const code = error.code;
+        return retryableGrpcCodes.has(code);
+    }
+    return false;
+}
+/**
+ * Default function to determine if an error is retryable.
+ * Handles gRPC errors and common network errors.
+ */
+export function defaultIsRetryable(error) {
+    // Check gRPC status codes
+    if (isRetryableGrpcError(error)) {
+        return true;
+    }
+    // Check for common network errors
+    if (error instanceof Error) {
+        const message = error.message.toLowerCase();
+        return (message.includes("econnreset") ||
+            message.includes("econnrefused") ||
+            message.includes("etimedout") ||
+            message.includes("socket hang up") ||
+            message.includes("network error") ||
+            message.includes("connection reset"));
+    }
+    return false;
+}
+/**
+ * Calculate delay for a retry attempt with optional jitter
+ */
+export function calculateBackoffDelay(attempt, options) {
+    // Exponential backoff: initialDelay * (multiplier ^ attempt)
+    const exponentialDelay = options.initialDelayMs * Math.pow(options.backoffMultiplier, attempt);
+    // Cap at maximum delay
+    const cappedDelay = Math.min(exponentialDelay, options.maxDelayMs);
+    // Add jitter (±25% of the delay) to prevent thundering herd
+    if (options.jitter) {
+        const jitterRange = cappedDelay * 0.25;
+        const jitter = Math.random() * jitterRange * 2 - jitterRange;
+        return Math.max(0, Math.round(cappedDelay + jitter));
+    }
+    return Math.round(cappedDelay);
+}
+/**
+ * Sleep for a specified duration
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Execute a function with automatic retries on transient failures.
+ *
+ * @param operation - The async function to execute
+ * @param options - Retry configuration
+ * @returns The result of the operation
+ * @throws The last error if all retries are exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => await client.query("SELECT 1"),
+ *   { maxRetries: 3, initialDelayMs: 100 }
+ * )
+ * ```
+ */
+export async function withRetry(operation, options = {}) {
+    const config = {
+        ...defaultRetryOptions,
+        ...options
+    };
+    const isRetryable = options.isRetryable ?? defaultIsRetryable;
+    const startTime = Date.now();
+    let lastError;
+    let attempt = 0;
+    while (attempt <= config.maxRetries) {
+        try {
+            const value = await operation();
+            return {
+                value,
+                attempts: attempt + 1,
+                totalTimeMs: Date.now() - startTime
+            };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if we should retry
+            if (attempt >= config.maxRetries || !isRetryable(error)) {
+                break;
+            }
+            // Calculate and wait for backoff delay
+            const delay = calculateBackoffDelay(attempt, config);
+            await sleep(delay);
+            attempt++;
+        }
+    }
+    // All retries exhausted or non-retryable error
+    // lastError is guaranteed to be set if we reach here (we only break after catching)
+    throw lastError ?? new Error("Retry failed with unknown error");
+}
+/**
+ * A retry policy that can be reused across multiple operations.
+ * Useful for applying consistent retry behavior.
+ */
+export class RetryPolicy {
+    config;
+    isRetryable;
+    constructor(options = {}) {
+        this.config = {
+            ...defaultRetryOptions,
+            ...options
+        };
+        this.isRetryable = options.isRetryable ?? defaultIsRetryable;
+    }
+    /**
+     * Execute an operation with this policy's retry configuration
+     */
+    async execute(operation) {
+        return withRetry(operation, {
+            ...this.config,
+            isRetryable: this.isRetryable
+        });
+    }
+    /**
+     * Create a wrapped version of an async function that automatically retries
+     */
+    wrap(fn) {
+        return async (...args) => {
+            const result = await this.execute(() => fn(...args));
+            return result.value;
+        };
+    }
+    /**
+     * Check if an error would be retried by this policy
+     */
+    wouldRetry(error) {
+        return this.isRetryable(error);
+    }
+    /**
+     * Get the delay that would be used for a specific attempt
+     */
+    getDelayForAttempt(attempt) {
+        return calculateBackoffDelay(attempt, this.config);
+    }
+}
+/**
+ * Pre-configured retry policies for common use cases
+ */
+export const retryPolicies = {
+    /** No retries - fail immediately */
+    none: new RetryPolicy({ maxRetries: 0 }),
+    /** Fast retries for low-latency operations */
+    fast: new RetryPolicy({
+        maxRetries: 3,
+        initialDelayMs: 50,
+        maxDelayMs: 500,
+        backoffMultiplier: 2
+    }),
+    /** Default retry policy with moderate settings */
+    default: new RetryPolicy({
+        maxRetries: 3,
+        initialDelayMs: 100,
+        maxDelayMs: 10_000,
+        backoffMultiplier: 2
+    }),
+    /** Aggressive retries for critical operations */
+    aggressive: new RetryPolicy({
+        maxRetries: 5,
+        initialDelayMs: 200,
+        maxDelayMs: 30_000,
+        backoffMultiplier: 2
+    }),
+    /** Very long retries for reconnection scenarios */
+    reconnection: new RetryPolicy({
+        maxRetries: 10,
+        initialDelayMs: 1_000,
+        maxDelayMs: 60_000,
+        backoffMultiplier: 2
+    })
+};
+//# sourceMappingURL=retry.js.map

package/dist/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,325 @@
+/**
+ * Arrow Flight SQL TypeScript type definitions
+ *
+ * These types map to the Protocol Buffer messages defined in:
+ * - Flight.proto (arrow.flight.protocol)
+ * - FlightSql.proto (arrow.flight.protocol.sql)
+ */
+import type { ChannelCredentials } from "@grpc/grpc-js";
+import type { RecordBatch, Schema, Table } from "apache-arrow";
+/**
+ * Configuration options for creating a FlightSqlClient
+ */
+export interface FlightSqlClientOptions {
+    /** Host address of the Flight SQL server */
+    host: string;
+    /** Port number (default: 443 for TLS, 80 for insecure) */
+    port: number;
+    /** Use TLS for connection (default: true) */
+    tls?: boolean;
+    /** Custom channel credentials (overrides tls option) */
+    credentials?: ChannelCredentials;
+    /** Authentication configuration */
+    auth?: AuthConfig;
+    /** Connection timeout in milliseconds (default: 30000) */
+    connectTimeoutMs?: number;
+    /** Request timeout in milliseconds (default: 60000) */
+    requestTimeoutMs?: number;
+    /** Custom metadata to include with every request */
+    metadata?: Record<string, string>;
+}
+/**
+ * Authentication configuration
+ */
+export type AuthConfig = {
+    type: "bearer";
+    token: string;
+} | {
+    type: "basic";
+    username: string;
+    password: string;
+} | {
+    type: "none";
+};
+/**
+ * Result of a handshake operation
+ */
+export interface HandshakeResult {
+    /** Protocol version negotiated with server */
+    protocolVersion: bigint;
+    /** Authentication token or other payload from server */
+    payload: Uint8Array;
+}
+/**
+ * Describes what type of FlightDescriptor is defined
+ */
+export declare const DescriptorType: {
+    readonly UNKNOWN: 0;
+    /** A named path identifying a dataset */
+    readonly PATH: 1;
+    /** An opaque command to generate a dataset */
+    readonly CMD: 2;
+};
+export type DescriptorType = (typeof DescriptorType)[keyof typeof DescriptorType];
+/**
+ * The name or tag for a Flight. Used to retrieve or generate a flight.
+ */
+export interface FlightDescriptor {
+    type: DescriptorType;
+    /** Opaque command value (when type = CMD) */
+    cmd?: Uint8Array;
+    /** List of strings identifying a dataset (when type = PATH) */
+    path?: string[];
+}
+/**
+ * An opaque identifier for retrieving a portion of a stream
+ */
+export interface Ticket {
+    ticket: Uint8Array;
+}
+/**
+ * A location where a Flight service accepts retrieval requests
+ */
+export interface Location {
+    uri: string;
+}
+/**
+ * A particular stream or split associated with a flight
+ */
+export interface FlightEndpoint {
+    /** Token used to retrieve this stream */
+    ticket: Ticket;
+    /** URIs where this ticket can be redeemed */
+    locations: Location[];
+    /** Expiration time for this endpoint */
+    expirationTime?: Date;
+    /** Application-defined metadata */
+    appMetadata?: Uint8Array;
+}
+/**
+ * Access coordinates for retrieval of a dataset
+ */
+export interface FlightInfo {
+    /** Arrow schema in IPC format */
+    schema: Uint8Array;
+    /** The descriptor associated with this info */
+    flightDescriptor?: FlightDescriptor;
+    /** Endpoints to consume the flight data */
+    endpoints: FlightEndpoint[];
+    /** Total number of records (-1 if unknown) */
+    totalRecords: bigint;
+    /** Total size in bytes (-1 if unknown) */
+    totalBytes: bigint;
+    /** Whether endpoints are ordered */
+    ordered: boolean;
+    /** Application-defined metadata */
+    appMetadata?: Uint8Array;
+}
+/**
+ * Schema result from GetSchema call
+ */
+export interface SchemaResult {
+    /** Arrow schema in IPC format */
+    schema: Uint8Array;
+}
+/**
+ * A batch of Arrow data as part of a stream
+ */
+export interface FlightData {
+    /** Descriptor of the data (for DoPut streams) */
+    flightDescriptor?: FlightDescriptor;
+    /** Message header as described in Message.fbs */
+    dataHeader: Uint8Array;
+    /** Application-defined metadata */
+    appMetadata?: Uint8Array;
+    /** The actual Arrow data batch */
+    dataBody: Uint8Array;
+}
+/**
+ * Response from DoPut submission
+ */
+export interface PutResult {
+    appMetadata?: Uint8Array;
+}
+/**
+ * An action to execute on the Flight service
+ */
+export interface Action {
+    type: string;
+    body?: Uint8Array;
+}
+/**
+ * Result from executing an action
+ */
+export interface ActionResult {
+    body: Uint8Array;
+}
+/**
+ * Describes an available action type
+ */
+export interface ActionType {
+    type: string;
+    description: string;
+}
+/**
+ * Options for executing SQL statements
+ */
+export interface ExecuteOptions {
+    /** Query timeout in seconds */
+    timeoutSeconds?: number;
+    /** Transaction ID for transactional queries */
+    transactionId?: Uint8Array;
+}
+/**
+ * Options for prepared statements
+ */
+export interface PreparedStatementOptions {
+    /** Transaction ID for transactional operations */
+    transactionId?: Uint8Array;
+}
+/**
+ * Result from creating a prepared statement
+ */
+export interface PreparedStatementResult {
+    /** Opaque handle for the prepared statement */
+    handle: Uint8Array;
+    /** Schema of the result set (if query returns data) */
+    datasetSchema?: Schema;
+    /** Schema of the parameters */
+    parameterSchema?: Schema;
+}
+/**
+ * Update result from DML statements
+ */
+export interface UpdateResult {
+    /** Number of rows affected */
+    recordCount: bigint;
+}
+/**
+ * Catalog information
+ */
+export interface CatalogInfo {
+    catalogName: string;
+}
+/**
+ * Schema information within a catalog
+ */
+export interface SchemaInfo {
+    catalogName?: string;
+    schemaName: string;
+}
+/**
+ * Table information
+ */
+export interface TableInfo {
+    catalogName?: string;
+    schemaName?: string;
+    tableName: string;
+    tableType: string;
+    schema?: Schema;
+}
+/**
+ * Table type names (e.g., "TABLE", "VIEW", "SYSTEM TABLE")
+ */
+export interface TableType {
+    tableType: string;
+}
+/**
+ * Primary key information
+ */
+export interface PrimaryKeyInfo {
+    catalogName?: string;
+    schemaName?: string;
+    tableName: string;
+    columnName: string;
+    keySequence: number;
+    keyName?: string;
+}
+/**
+ * Foreign key information
+ */
+export interface ForeignKeyInfo {
+    pkCatalogName?: string;
+    pkSchemaName?: string;
+    pkTableName: string;
+    pkColumnName: string;
+    fkCatalogName?: string;
+    fkSchemaName?: string;
+    fkTableName: string;
+    fkColumnName: string;
+    keySequence: number;
+    fkKeyName?: string;
+    pkKeyName?: string;
+    updateRule: number;
+    deleteRule: number;
+}
+/**
+ * Async iterator for streaming Arrow record batches
+ */
+export type RecordBatchStream = AsyncIterable<RecordBatch>;
+/**
+ * Result from a query execution
+ */
+export interface QueryResult {
+    /** Flight info containing endpoints for data retrieval */
+    flightInfo: FlightInfo;
+    /** Parsed Arrow schema */
+    schema: Schema;
+    /**
+     * Stream all record batches from all endpoints
+     */
+    stream(): RecordBatchStream;
+    /**
+     * Collect all data into a single Table
+     * Warning: Loads entire result set into memory
+     */
+    collect(): Promise<Table>;
+}
+/**
+ * Connection pool configuration
+ */
+export interface PoolOptions {
+    /** Minimum number of connections to maintain */
+    minConnections?: number;
+    /** Maximum number of connections allowed */
+    maxConnections?: number;
+    /** Time in ms before an idle connection is closed */
+    idleTimeoutMs?: number;
+    /** Time in ms to wait for a connection from the pool */
+    acquireTimeoutMs?: number;
+    /** Enable connection health checking */
+    healthCheck?: boolean;
+    /** Interval in ms between health checks */
+    healthCheckIntervalMs?: number;
+}
+/**
+ * Pool statistics for monitoring
+ */
+export interface PoolStats {
+    /** Total connections in pool */
+    totalConnections: number;
+    /** Connections currently in use */
+    activeConnections: number;
+    /** Connections available for use */
+    idleConnections: number;
+    /** Requests waiting for a connection */
+    pendingRequests: number;
+}
+/**
+ * Retry configuration for transient failures
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts */
+    maxRetries?: number;
+    /** Initial delay in ms before first retry */
+    initialDelayMs?: number;
+    /** Maximum delay in ms between retries */
+    maxDelayMs?: number;
+    /** Multiplier for exponential backoff */
+    backoffMultiplier?: number;
+    /** Add random jitter to delays */
+    jitter?: boolean;
+    /** Custom function to determine if error is retryable */
+    isRetryable?: (error: unknown) => boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,cAAc,CAAA;AAM9D;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAA;IAEZ,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAA;IAEZ,6CAA6C;IAC7C,GAAG,CAAC,EAAE,OAAO,CAAA;IAEb,wDAAwD;IACxD,WAAW,CAAC,EAAE,kBAAkB,CAAA;IAEhC,mCAAmC;IACnC,IAAI,CAAC,EAAE,UAAU,CAAA;IAEjB,0DAA0D;IAC1D,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,uDAAuD;IACvD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAMpB;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,eAAe,EAAE,MAAM,CAAA;IAEvB,wDAAwD;IACxD,OAAO,EAAE,UAAU,CAAA;CACpB;AAED;;GAEG;AACH,eAAO,MAAM,cAAc;;IAEzB,yCAAyC;;IAEzC,8CAA8C;;CAEtC,CAAA;AAEV,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAA;AAEjF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,cAAc,CAAA;IAEpB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,UAAU,CAAA;IAEhB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,MAAM,EAAE,UAAU,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAA;IAEd,6CAA6C;IAC7C,SAAS,EAAE,QAAQ,EAAE,CAAA;IAErB,wCAAwC;IACxC,cAAc,CAAC,EAAE,IAAI,CAAA;IAErB,mCAAmC;IACnC,WAAW,CAAC,EAAE,UAAU,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iCAAiC;IACjC,MAAM,EAAE,UAAU,CAAA;IAElB,+CAA+C;IAC/C,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAEnC,2CAA2C;IAC3C,SAAS,EAAE,cAAc,EAAE,CAAA;IAE3B,8CAA8C;IAC9C,YAAY,EAAE,MAAM,CAAA;IAEpB,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAA;IAElB,oCAAoC;IACpC,OAAO,EAAE,OAAO,CAAA;IAEhB,mCAAmC;IACnC,WAAW,CAAC,EAAE,UAAU,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,MAAM,EAAE,UAAU,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAEnC,iDAAiD;IACjD,UAAU,EAAE,UAAU,CAAA;IAEtB,mCAAmC;IACnC,WAAW,CAAC,EAAE,UAAU,CAAA;IAExB,kCAAkC;IAClC,QAAQ,EAAE,UAAU,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,CAAC,EAAE,UAAU,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;CACpB;AAMD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,+CAA+C;IAC/C,aAAa,CAAC,EAAE,UAAU,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,kDAAkD;IAClD,aAAa,CAAC,EAAE,UAAU,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,+CAA+C;IAC/C,MAAM,EAAE,UAAU,CAAA;IAElB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB,+BAA+B;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,8BAA8B;IAC9B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;CACnB;AAMD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,WAAW,CAAC,CAAA;AAE1D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,UAAU,EAAE,UAAU,CAAA;IAEtB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,MAAM,IAAI,iBAAiB,CAAA;IAE3B;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,CAAA;CAC1B;AAMD;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,gDAAgD;IAChD,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,4CAA4C;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,qDAAqD;IACrD,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB,wDAAwD;IACxD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,wCAAwC;IACxC,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB,2CAA2C;IAC3C,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,gBAAgB,EAAE,MAAM,CAAA;IAExB,mCAAmC;IACnC,iBAAiB,EAAE,MAAM,CAAA;IAEzB,oCAAoC;IACpC,eAAe,EAAE,MAAM,CAAA;IAEvB,wCAAwC;IACxC,eAAe,EAAE,MAAM,CAAA;CACxB;AAMD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB,yCAAyC;IACzC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAE1B,kCAAkC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB,yDAAyD;IACzD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CAC1C"}

package/dist/types.js

@@ -0,0 +1,18 @@
+/**
+ * Arrow Flight SQL TypeScript type definitions
+ *
+ * These types map to the Protocol Buffer messages defined in:
+ * - Flight.proto (arrow.flight.protocol)
+ * - FlightSql.proto (arrow.flight.protocol.sql)
+ */
+/**
+ * Describes what type of FlightDescriptor is defined
+ */
+export const DescriptorType = {
+    UNKNOWN: 0,
+    /** A named path identifying a dataset */
+    PATH: 1,
+    /** An opaque command to generate a dataset */
+    CMD: 2
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6DH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,OAAO,EAAE,CAAC;IACV,yCAAyC;IACzC,IAAI,EAAE,CAAC;IACP,8CAA8C;IAC9C,GAAG,EAAE,CAAC;CACE,CAAA"}