@qualithm/arrow-flight-sql-js 0.0.1

package/dist/arrow.js

@@ -0,0 +1,250 @@
+/**
+ * Arrow IPC utilities for parsing Flight data
+ *
+ * Flight SQL transmits data in Arrow IPC format. This module provides
+ * utilities for parsing schemas and record batches from raw IPC bytes.
+ */
+import { MessageHeader, MessageReader, RecordBatchReader, RecordBatchStreamWriter, Table, tableFromIPC } from "apache-arrow";
+// ============================================================================
+// Schema Parsing
+// ============================================================================
+/**
+ * Parse an Arrow schema from IPC format bytes
+ *
+ * The schema bytes format from Flight:
+ *   - 4 bytes: IPC_CONTINUATION_TOKEN (0xFFFFFFFF)
+ *   - 4 bytes: message length
+ *   - flatbuffer Message with Schema header
+ *
+ * Uses MessageReader to parse schema-only IPC messages, which is the correct
+ * approach for FlightInfo.schema bytes (as opposed to RecordBatchReader which
+ * expects a full IPC stream with record batches).
+ */
+export function parseSchema(schemaBytes) {
+    if (schemaBytes.length === 0) {
+        throw new Error("Cannot parse empty schema bytes");
+    }
+    // Use MessageReader which can parse schema-only IPC messages
+    const reader = new MessageReader(schemaBytes);
+    const schema = reader.readSchema();
+    if (!schema) {
+        throw new Error("Failed to parse schema from IPC message");
+    }
+    return schema;
+}
+/**
+ * Parse schema from FlightInfo response
+ * Returns null if schema is empty or cannot be parsed
+ */
+export function tryParseSchema(schemaBytes) {
+    if (schemaBytes.length === 0) {
+        return null;
+    }
+    try {
+        return parseSchema(schemaBytes);
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Record Batch Streaming
+// ============================================================================
+/**
+ * Parse a single FlightData message into a RecordBatch
+ *
+ * Flight sends data in a streaming format where:
+ *   - First message: Schema (dataHeader only, no dataBody)
+ *   - Subsequent messages: RecordBatch (dataHeader + dataBody)
+ *
+ * The dataHeader is a raw flatbuffer Message (without IPC framing).
+ * We need to frame it before passing to apache-arrow.
+ *
+ * @param dataHeader - IPC Message flatbuffer (without continuation/length prefix)
+ * @param dataBody - IPC Message body (raw data buffers)
+ * @param schema - Schema to use for parsing (from FlightInfo or first message)
+ */
+export function parseFlightData(dataHeader, dataBody, schema) {
+    if (dataHeader.length === 0) {
+        return null;
+    }
+    // Frame the header with IPC continuation marker + length prefix
+    const framedData = frameAsIPC(dataHeader, dataBody);
+    // Check if this is a schema message (skip it, we already have schema)
+    const msgReader = new MessageReader(framedData);
+    const msg = msgReader.readMessage();
+    if (!msg || msg.headerType === MessageHeader.Schema) {
+        return null; // Schema message, no batch to return
+    }
+    // For RecordBatch messages, we need a complete IPC stream with schema + batch
+    // Create a minimal stream with schema first, then this batch
+    const schemaBytes = serializeSchemaMessage(schema);
+    const fullStream = concatArrays([schemaBytes, framedData]);
+    try {
+        const reader = RecordBatchReader.from(fullStream);
+        const batch = reader.next();
+        if (batch.value !== null && batch.value !== undefined) {
+            return batch.value;
+        }
+    }
+    catch {
+        // If parsing fails, return null
+    }
+    return null;
+}
+/**
+ * Frame raw flatbuffer bytes with IPC continuation marker and length prefix
+ */
+function frameAsIPC(header, body) {
+    const continuationToken = new Uint8Array([0xff, 0xff, 0xff, 0xff]);
+    const metadataLength = new Uint8Array(4);
+    new DataView(metadataLength.buffer).setInt32(0, header.length, true);
+    // Calculate padding for 8-byte alignment
+    const headerPadding = (8 - ((header.length + 4 + 4) % 8)) % 8;
+    const padding = new Uint8Array(headerPadding);
+    return concatArrays([continuationToken, metadataLength, header, padding, body]);
+}
+/**
+ * Serialize a schema to IPC message format
+ */
+function serializeSchemaMessage(schema) {
+    // The schema from FlightInfo is already in IPC format with framing
+    // We need to extract just the schema portion
+    // For now, use a workaround: create an empty table with the schema
+    // and extract the schema message from the IPC representation
+    const emptyTable = new Table(schema);
+    const ipcBytes = tableToIPCBytes(emptyTable);
+    // The IPC stream starts with schema message - extract just that part
+    // Read the first message (schema)
+    const reader = new MessageReader(ipcBytes);
+    const msg = reader.readMessage();
+    if (msg && msg.headerType === MessageHeader.Schema) {
+        // Return the schema portion
+        // The reader consumes: continuation(4) + length(4) + header + padding
+        const metadataLength = new DataView(ipcBytes.buffer, 4, 4).getInt32(0, true);
+        const headerPadding = (8 - ((metadataLength + 4 + 4) % 8)) % 8;
+        const schemaEnd = 4 + 4 + metadataLength + headerPadding;
+        return ipcBytes.slice(0, schemaEnd);
+    }
+    // Fallback: shouldn't happen
+    return new Uint8Array(0);
+}
+/**
+ * Helper to serialize a Table to IPC stream bytes
+ */
+function tableToIPCBytes(table) {
+    const writer = RecordBatchStreamWriter.throughNode();
+    const chunks = [];
+    // Collect chunks synchronously
+    writer.on("data", (chunk) => {
+        chunks.push(chunk);
+    });
+    // Write all batches
+    for (const batch of table.batches) {
+        writer.write(batch);
+    }
+    writer.end();
+    return concatArrays(chunks);
+}
+/**
+ * Concatenate multiple Uint8Arrays
+ */
+function concatArrays(arrays) {
+    const totalLength = arrays.reduce((sum, arr) => sum + arr.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const arr of arrays) {
+        result.set(arr, offset);
+        offset += arr.length;
+    }
+    return result;
+}
+// ============================================================================
+// Stream Processing
+// ============================================================================
+/**
+ * Async iterable that parses FlightData messages into RecordBatches
+ */
+export async function* parseFlightDataStream(flightDataStream, schema) {
+    for await (const flightData of flightDataStream) {
+        if (!flightData.dataHeader || flightData.dataHeader.length === 0) {
+            continue;
+        }
+        const batch = parseFlightData(flightData.dataHeader, flightData.dataBody ?? new Uint8Array(), schema);
+        if (batch !== null) {
+            yield batch;
+        }
+    }
+}
+/**
+ * Collect all record batches into a Table
+ */
+export async function collectToTable(batches, schema) {
+    const batchArray = [];
+    // Handle both async and sync iterables
+    if (Symbol.asyncIterator in batches) {
+        for await (const batch of batches) {
+            batchArray.push(batch);
+        }
+    }
+    else {
+        for (const batch of batches) {
+            batchArray.push(batch);
+        }
+    }
+    // Use tableFromIPC to combine batches
+    // First, we need to serialize the batches to IPC format
+    if (batchArray.length === 0) {
+        // Return empty table with schema
+        return tableFromIPC(serializeEmptyTable(schema));
+    }
+    // For now, return a table from the collected batches
+    // The Table constructor can accept an array of RecordBatches
+    return new Table(batchArray);
+}
+/**
+ * Serialize an empty table with the given schema to IPC format
+ */
+function serializeEmptyTable(schema) {
+    // Create minimal IPC stream with just schema and EOS marker
+    // This is a simplified implementation
+    const schemaMessage = serializeSchemaMessage(schema);
+    const eosMarker = new Uint8Array([0xff, 0xff, 0xff, 0xff, 0x00, 0x00, 0x00, 0x00]);
+    const result = new Uint8Array(schemaMessage.length + eosMarker.length);
+    result.set(schemaMessage, 0);
+    result.set(eosMarker, schemaMessage.length);
+    return result;
+}
+// serializeSchemaMessage is defined above
+// ============================================================================
+// Table Utilities
+// ============================================================================
+/**
+ * Get column names from a schema
+ */
+export function getColumnNames(schema) {
+    return schema.fields.map((field) => field.name);
+}
+/**
+ * Get the number of rows in a table
+ */
+export function getRowCount(table) {
+    return table.numRows;
+}
+/**
+ * Convert a Table to an array of plain objects
+ */
+export function tableToObjects(table) {
+    const result = [];
+    const columns = table.schema.fields.map((f) => f.name);
+    for (let i = 0; i < table.numRows; i++) {
+        const row = {};
+        for (const col of columns) {
+            const column = table.getChild(col);
+            row[col] = column?.get(i);
+        }
+        result.push(row);
+    }
+    return result;
+}
+//# sourceMappingURL=arrow.js.map

package/dist/arrow.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,416 @@
+/**
+ * Arrow Flight SQL Client
+ *
+ * A TypeScript client for communicating with Arrow Flight SQL servers.
+ * Modeled after the official Arrow Flight SQL clients (Java, C++, Go).
+ */
+import { type RecordBatch, type Schema, type Table } from "apache-arrow";
+import type { Action, ActionResult, ActionType, CatalogInfo, ExecuteOptions, FlightDescriptor, FlightInfo, FlightSqlClientOptions, ForeignKeyInfo, PrimaryKeyInfo, SchemaInfo, SchemaResult, TableInfo, TableType, Ticket } from "./types";
+/**
+ * Flight SQL client for executing queries and managing data with Arrow Flight SQL servers.
+ *
+ * @example
+ * ```typescript
+ * const client = new FlightSqlClient({
+ *   host: "localhost",
+ *   port: 50051,
+ *   tls: false,
+ *   auth: { type: "bearer", token: "my-token" }
+ * })
+ *
+ * await client.connect()
+ *
+ * const result = await client.execute("SELECT * FROM my_table")
+ * for await (const batch of result.stream()) {
+ *   console.log(batch.numRows)
+ * }
+ *
+ * await client.close()
+ * ```
+ */
+export declare class FlightSqlClient {
+    private readonly options;
+    private grpcClient;
+    private flightService;
+    private authToken;
+    private connected;
+    constructor(options: FlightSqlClientOptions);
+    /**
+     * Establish connection to the Flight SQL server and perform authentication.
+     *
+     * @throws {ConnectionError} If connection cannot be established
+     * @throws {AuthenticationError} If authentication fails
+     */
+    connect(): Promise<void>;
+    /**
+     * Close the connection and release resources.
+     */
+    close(): void;
+    /**
+     * Check if the client is connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Execute a SQL query and return a QueryResult for retrieving results.
+     *
+     * @param query - SQL query string
+     * @param options - Optional execution options
+     * @returns QueryResult with stream() and collect() methods
+     *
+     * @example
+     * ```typescript
+     * const result = await client.query("SELECT * FROM users")
+     *
+     * // Stream record batches
+     * for await (const batch of result.stream()) {
+     *   console.log(batch.numRows)
+     * }
+     *
+     * // Or collect all into a table
+     * const table = await result.collect()
+     * ```
+     */
+    query(query: string, options?: ExecuteOptions): Promise<QueryResult>;
+    /**
+     * Execute a SQL query and return flight info for retrieving results.
+     * @deprecated Use query() instead for a more ergonomic API
+     *
+     * @param query - SQL query string
+     * @param options - Optional execution options
+     * @returns FlightInfo containing endpoints for data retrieval
+     */
+    execute(query: string, options?: ExecuteOptions): Promise<FlightInfo>;
+    /**
+     * Execute a SQL update statement (INSERT, UPDATE, DELETE).
+     *
+     * @param query - SQL statement
+     * @param options - Optional execution options
+     * @returns Number of rows affected
+     */
+    executeUpdate(query: string, options?: ExecuteOptions): Promise<bigint>;
+    /**
+     * Create a prepared statement for repeated execution.
+     *
+     * @param query - SQL query with optional parameter placeholders
+     * @param options - Optional prepared statement options
+     * @returns PreparedStatement that can be executed multiple times
+     *
+     * @example
+     * ```typescript
+     * const stmt = await client.prepare("SELECT * FROM users WHERE id = ?")
+     * const result = await stmt.executeQuery()
+     * await stmt.close()
+     * ```
+     */
+    prepare(query: string, options?: ExecuteOptions): Promise<PreparedStatement>;
+    /**
+     * Get the list of catalogs available on the server.
+     *
+     * @returns Array of catalog information
+     *
+     * @example
+     * ```typescript
+     * const catalogs = await client.getCatalogs()
+     * for (const catalog of catalogs) {
+     *   console.log(catalog.catalogName)
+     * }
+     * ```
+     */
+    getCatalogs(): Promise<CatalogInfo[]>;
+    /**
+     * Get the list of schemas available in a catalog.
+     *
+     * @param catalog - Optional catalog name to filter by
+     * @param schemaFilterPattern - Optional SQL LIKE pattern to filter schema names
+     * @returns Array of schema information
+     *
+     * @example
+     * ```typescript
+     * // Get all schemas
+     * const schemas = await client.getSchemas()
+     *
+     * // Get schemas in specific catalog
+     * const schemas = await client.getSchemas("my_catalog")
+     *
+     * // Get schemas matching pattern
+     * const schemas = await client.getSchemas(undefined, "public%")
+     * ```
+     */
+    getSchemas(catalog?: string, schemaFilterPattern?: string): Promise<SchemaInfo[]>;
+    /**
+     * Get the list of tables available.
+     *
+     * @param options - Filter options
+     * @returns Array of table information
+     *
+     * @example
+     * ```typescript
+     * // Get all tables
+     * const tables = await client.getTables()
+     *
+     * // Get tables in specific catalog/schema
+     * const tables = await client.getTables({
+     *   catalog: "my_catalog",
+     *   schemaPattern: "public"
+     * })
+     *
+     * // Get only views
+     * const views = await client.getTables({ tableTypes: ["VIEW"] })
+     * ```
+     */
+    getTables(options?: {
+        catalog?: string;
+        schemaPattern?: string;
+        tablePattern?: string;
+        tableTypes?: string[];
+        includeSchema?: boolean;
+    }): Promise<TableInfo[]>;
+    /**
+     * Get the list of table types supported by the server.
+     *
+     * @returns Array of table type names (e.g., "TABLE", "VIEW", "SYSTEM TABLE")
+     *
+     * @example
+     * ```typescript
+     * const tableTypes = await client.getTableTypes()
+     * console.log(tableTypes) // [{ tableType: "TABLE" }, { tableType: "VIEW" }, ...]
+     * ```
+     */
+    getTableTypes(): Promise<TableType[]>;
+    /**
+     * Get the primary keys for a table.
+     *
+     * @param table - Table name
+     * @param catalog - Optional catalog name
+     * @param schema - Optional schema name
+     * @returns Array of primary key information
+     *
+     * @example
+     * ```typescript
+     * const primaryKeys = await client.getPrimaryKeys("users")
+     * for (const pk of primaryKeys) {
+     *   console.log(`${pk.columnName} (sequence: ${pk.keySequence})`)
+     * }
+     * ```
+     */
+    getPrimaryKeys(table: string, catalog?: string, schema?: string): Promise<PrimaryKeyInfo[]>;
+    /**
+     * Get the foreign keys that reference a table's primary key (exported keys).
+     *
+     * @param table - Table name
+     * @param catalog - Optional catalog name
+     * @param schema - Optional schema name
+     * @returns Array of foreign key information
+     *
+     * @example
+     * ```typescript
+     * // Find all tables that reference the "users" table
+     * const exportedKeys = await client.getExportedKeys("users")
+     * ```
+     */
+    getExportedKeys(table: string, catalog?: string, schema?: string): Promise<ForeignKeyInfo[]>;
+    /**
+     * Get the foreign keys in a table (imported keys).
+     *
+     * @param table - Table name
+     * @param catalog - Optional catalog name
+     * @param schema - Optional schema name
+     * @returns Array of foreign key information
+     *
+     * @example
+     * ```typescript
+     * // Find all foreign keys in the "orders" table
+     * const importedKeys = await client.getImportedKeys("orders")
+     * ```
+     */
+    getImportedKeys(table: string, catalog?: string, schema?: string): Promise<ForeignKeyInfo[]>;
+    /**
+     * Helper to fetch catalog results and map rows to typed objects
+     */
+    private fetchCatalogResults;
+    /**
+     * Helper to fetch foreign key results with the complex schema
+     */
+    private fetchForeignKeyResults;
+    /**
+     * Get flight information for a descriptor.
+     *
+     * @param descriptor - Flight descriptor
+     * @returns FlightInfo with schema and endpoints
+     */
+    getFlightInfo(descriptor: FlightDescriptor): Promise<FlightInfo>;
+    /**
+     * Get the schema for a flight descriptor without fetching data.
+     *
+     * @param descriptor - Flight descriptor
+     * @returns Schema result
+     */
+    getSchema(descriptor: FlightDescriptor): Promise<SchemaResult>;
+    /**
+     * Retrieve data for a ticket as an async iterator of FlightData.
+     *
+     * @param ticket - Ticket from FlightInfo endpoint
+     * @yields FlightData chunks containing dataHeader and dataBody
+     */
+    doGet(ticket: Ticket): AsyncGenerator<{
+        dataHeader?: Uint8Array;
+        dataBody?: Uint8Array;
+    }, void, unknown>;
+    /**
+     * Upload Arrow data to the server.
+     *
+     * @param descriptor - Flight descriptor describing the data
+     * @param dataStream - Async iterable of FlightData messages
+     * @returns Async iterator of PutResult messages
+     */
+    doPut(descriptor: FlightDescriptor, dataStream: AsyncIterable<{
+        dataHeader: Uint8Array;
+        dataBody: Uint8Array;
+        appMetadata?: Uint8Array;
+    }>): AsyncGenerator<{
+        appMetadata?: Uint8Array;
+    }, void, unknown>;
+    /**
+     * Helper to get the first item from an async iterable without consuming the rest
+     */
+    private getFirstFromIterable;
+    /**
+     * Execute an action on the server.
+     *
+     * @param action - Action to execute
+     * @returns Async iterator of results
+     */
+    doAction(action: Action): AsyncGenerator<ActionResult, void, unknown>;
+    /**
+     * List available action types.
+     *
+     * @returns Array of available action types
+     */
+    listActions(): Promise<ActionType[]>;
+    private authenticate;
+    private handshake;
+    private encodeBasicAuth;
+    private createCredentials;
+    private waitForReady;
+    private createRequestMetadata;
+    private cleanup;
+    private ensureConnected;
+    private wrapGrpcError;
+    /**
+     * Wraps a gRPC stream to convert errors to FlightSqlError types.
+     * gRPC streams are already async iterable, so we just need error handling.
+     */
+    private wrapStream;
+    private serializeFlightDescriptor;
+    private parseFlightInfo;
+    private parseSchemaResult;
+}
+/**
+ * Result of a query execution with methods to stream or collect data.
+ *
+ * @example
+ * ```typescript
+ * const result = await client.query("SELECT * FROM users")
+ *
+ * // Option 1: Stream record batches (memory efficient)
+ * for await (const batch of result.stream()) {
+ *   console.log(`Batch with ${batch.numRows} rows`)
+ * }
+ *
+ * // Option 2: Collect all data into a table
+ * const table = await result.collect()
+ * console.log(`Total rows: ${table.numRows}`)
+ * ```
+ */
+export declare class QueryResult {
+    private readonly client;
+    private readonly info;
+    private readonly parsedSchema;
+    constructor(client: FlightSqlClient, flightInfo: FlightInfo, schema: Schema | null);
+    /**
+     * Get the FlightInfo for this query result
+     */
+    get flightInfo(): FlightInfo;
+    /**
+     * Get the Arrow schema for this query result
+     * May be null if schema could not be parsed
+     */
+    get schema(): Schema | null;
+    /**
+     * Get the total number of records (if known)
+     * Returns -1 if unknown
+     */
+    get totalRecords(): bigint;
+    /**
+     * Stream record batches from all endpoints.
+     * This is memory-efficient for large result sets.
+     *
+     * Flight SQL streams data as:
+     *   1. Schema message (dataHeader only)
+     *   2. RecordBatch messages (dataHeader + dataBody)
+     *
+     * We collect all messages and parse them as a complete IPC stream.
+     */
+    stream(): AsyncGenerator<RecordBatch, void, unknown>;
+    /**
+     * Frame raw flatbuffer bytes with IPC continuation marker and length prefix
+     */
+    private frameAsIPC;
+    /**
+     * Concatenate multiple Uint8Arrays
+     */
+    private concatArrays;
+    /**
+     * Collect all data from all endpoints into a single Table.
+     * Warning: This loads the entire result set into memory.
+     */
+    collect(): Promise<Table>;
+    /**
+     * Helper to convert batches array to async generator
+     */
+    private streamBatches;
+}
+/**
+ * A prepared statement that can be executed multiple times with different parameters.
+ *
+ * @example
+ * ```typescript
+ * const stmt = await client.prepare("SELECT * FROM users WHERE id = ?")
+ *
+ * // Execute with parameters
+ * const result = await stmt.execute()
+ * const table = await result.collect()
+ *
+ * // Clean up
+ * await stmt.close()
+ * ```
+ */
+export declare class PreparedStatement {
+    private readonly client;
+    private handle;
+    private datasetSchema;
+    private parameterSchema;
+    private closed;
+    constructor(client: FlightSqlClient, handle: Uint8Array, datasetSchema: Schema | null, parameterSchema: Schema | null);
+    /**
+     * Get the schema of the result set
+     */
+    get resultSchema(): Schema | null;
+    /**
+     * Get the schema of the parameters
+     */
+    get parametersSchema(): Schema | null;
+    /**
+     * Check if the prepared statement is closed
+     */
+    get isClosed(): boolean;
+    /**
+     * Execute the prepared statement as a query
+     */
+    executeQuery(): Promise<QueryResult>;
+    /**
+     * Close the prepared statement and release server resources
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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