@qualithm/arrow-flight-client 0.1.0

package/dist/client/errors.js

@@ -0,0 +1,106 @@
+/**
+ * Base error class for all Flight client errors.
+ */
+export class FlightError extends Error {
+    /** Error name for identification. */
+    name = "FlightError";
+    /** Original error that caused this error, if any. */
+    cause;
+    constructor(message, cause) {
+        super(message, { cause });
+        this.cause = cause;
+    }
+    /**
+     * Type guard to check if an error is a FlightError.
+     */
+    static isError(error) {
+        return error instanceof FlightError;
+    }
+}
+/**
+ * Error thrown when a connection to the Flight server fails.
+ */
+export class FlightConnectionError extends FlightError {
+    /** Error name for identification. */
+    name = "FlightConnectionError";
+    /** URL that failed to connect. */
+    url;
+    constructor(message, url, cause) {
+        super(message, cause);
+        this.url = url;
+    }
+    /**
+     * Type guard to check if an error is a FlightConnectionError.
+     */
+    static isError(error) {
+        return error instanceof FlightConnectionError;
+    }
+}
+/**
+ * Error thrown when authentication fails.
+ */
+export class FlightAuthError extends FlightError {
+    /** Error name for identification. */
+    name = "FlightAuthError";
+    /**
+     * Type guard to check if an error is a FlightAuthError.
+     */
+    static isError(error) {
+        return error instanceof FlightAuthError;
+    }
+}
+/**
+ * Error thrown when a request times out.
+ */
+export class FlightTimeoutError extends FlightError {
+    /** Error name for identification. */
+    name = "FlightTimeoutError";
+    /** Timeout duration in milliseconds that was exceeded. */
+    timeoutMs;
+    constructor(message, timeoutMs, cause) {
+        super(message, cause);
+        this.timeoutMs = timeoutMs;
+    }
+    /**
+     * Type guard to check if an error is a FlightTimeoutError.
+     */
+    static isError(error) {
+        return error instanceof FlightTimeoutError;
+    }
+}
+/**
+ * Error thrown when the server returns an error response.
+ */
+export class FlightServerError extends FlightError {
+    /** Error name for identification. */
+    name = "FlightServerError";
+    /** gRPC status code from the server. */
+    code;
+    /** Additional error details from the server, if provided. */
+    details;
+    constructor(message, code, details, cause) {
+        super(message, cause);
+        this.code = code;
+        this.details = details;
+    }
+    /**
+     * Type guard to check if an error is a FlightServerError.
+     */
+    static isError(error) {
+        return error instanceof FlightServerError;
+    }
+}
+/**
+ * Error thrown when an operation is cancelled.
+ */
+export class FlightCancelledError extends FlightError {
+    /** Error name for identification. */
+    name = "FlightCancelledError";
+    /**
+     * Type guard to check if an error is a FlightCancelledError.
+     */
+    static isError(error) {
+        return error instanceof FlightCancelledError;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/client/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,qCAAqC;IACnB,IAAI,GAAW,aAAa,CAAA;IAC9C,qDAAqD;IACnC,KAAK,CAAS;IAEhC,YAAY,OAAe,EAAE,KAAe;QAC1C,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,KAAc;QAC3B,OAAO,KAAK,YAAY,WAAW,CAAA;IACrC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,WAAW;IACpD,qCAAqC;IACnB,IAAI,GAAW,uBAAuB,CAAA;IACxD,kCAAkC;IACzB,GAAG,CAAQ;IAEpB,YAAY,OAAe,EAAE,GAAW,EAAE,KAAe;QACvD,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACrB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;IAChB,CAAC;IAED;;OAEG;IACH,MAAM,CAAU,OAAO,CAAC,KAAc;QACpC,OAAO,KAAK,YAAY,qBAAqB,CAAA;IAC/C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,WAAW;IAC9C,qCAAqC;IACnB,IAAI,GAAW,iBAAiB,CAAA;IAElD;;OAEG;IACH,MAAM,CAAU,OAAO,CAAC,KAAc;QACpC,OAAO,KAAK,YAAY,eAAe,CAAA;IACzC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACjD,qCAAqC;IACnB,IAAI,GAAW,oBAAoB,CAAA;IACrD,0DAA0D;IACjD,SAAS,CAAQ;IAE1B,YAAY,OAAe,EAAE,SAAiB,EAAE,KAAe;QAC7D,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACrB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;IAC5B,CAAC;IAED;;OAEG;IACH,MAAM,CAAU,OAAO,CAAC,KAAc;QACpC,OAAO,KAAK,YAAY,kBAAkB,CAAA;IAC5C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,iBAAkB,SAAQ,WAAW;IAChD,qCAAqC;IACnB,IAAI,GAAW,mBAAmB,CAAA;IACpD,wCAAwC;IAC/B,IAAI,CAAQ;IACrB,6DAA6D;IACpD,OAAO,CAAoB;IAEpC,YAAY,OAAe,EAAE,IAAY,EAAE,OAAgB,EAAE,KAAe;QAC1E,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;IAED;;OAEG;IACH,MAAM,CAAU,OAAO,CAAC,KAAc;QACpC,OAAO,KAAK,YAAY,iBAAiB,CAAA;IAC3C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,WAAW;IACnD,qCAAqC;IACnB,IAAI,GAAW,sBAAsB,CAAA;IAEvD;;OAEG;IACH,MAAM,CAAU,OAAO,CAAC,KAAc;QACpC,OAAO,KAAK,YAAY,oBAAoB,CAAA;IAC9C,CAAC;CACF"}

package/dist/client/flight-client.d.ts

@@ -0,0 +1,161 @@
+import { type ActionType, type FlightData, type FlightInfo, type PollInfo, type PutResult, type Result, type SchemaResult } from "../gen/arrow/flight/Flight_pb.js";
+import { type FlightAction, type FlightClientOptions, type FlightCriteria, type FlightDescriptorInput, type FlightTicket } from "./types.js";
+/**
+ * Low-level Arrow Flight client for communicating with Flight servers.
+ *
+ * This client provides access to all core Flight RPC methods.
+ * For SQL operations, use `FlightSqlClient` instead.
+ *
+ * @example
+ * ```ts
+ * const client = new FlightClient({ url: "https://flight.example.com:8815" })
+ *
+ * const info = await client.getFlightInfo({ type: "cmd", cmd: myCommand })
+ * for await (const flight of client.listFlights()) {
+ *   console.log(flight)
+ * }
+ *
+ * client.close()
+ * ```
+ */
+export declare class FlightClient {
+    #private;
+    constructor(options: FlightClientOptions);
+    /**
+     * The base URL of the Flight server.
+     */
+    get url(): string;
+    /**
+     * Whether the client has been closed.
+     */
+    get closed(): boolean;
+    /**
+     * Whether the client has been authenticated via handshake.
+     */
+    get authenticated(): boolean;
+    /**
+     * Close the client and release resources.
+     * After calling close, the client should not be used.
+     */
+    close(): void;
+    /**
+     * Perform Flight Handshake authentication.
+     *
+     * This method is automatically called for clients configured with `auth: { type: "basic" }`.
+     * For custom handshake payloads, call this method directly with raw bytes.
+     *
+     * @param payload - Raw handshake payload (defaults to BasicAuth if auth.type is "basic")
+     * @returns The authentication token from the server
+     */
+    handshake(payload?: Uint8Array): Promise<string>;
+    /**
+     * Authenticate with the server using configured credentials.
+     *
+     * For basic auth, this calls the Handshake RPC.
+     * For bearer auth, no action is needed (token is sent in headers).
+     *
+     * @returns The authentication token (if applicable)
+     */
+    authenticate(): Promise<string | undefined>;
+    /**
+     * Get information about a specific flight.
+     *
+     * @param descriptor - Flight descriptor identifying the dataset
+     * @returns Flight information including schema and endpoints
+     */
+    getFlightInfo(descriptor: FlightDescriptorInput): Promise<FlightInfo>;
+    /**
+     * Poll for updated flight information (useful for long-running queries).
+     *
+     * @param descriptor - Flight descriptor identifying the dataset
+     * @returns Poll information with progress and updated flight info
+     */
+    pollFlightInfo(descriptor: FlightDescriptorInput): Promise<PollInfo>;
+    /**
+     * Get the schema for a flight.
+     *
+     * @param descriptor - Flight descriptor identifying the dataset
+     * @returns Schema result containing the Arrow schema bytes
+     */
+    getSchema(descriptor: FlightDescriptorInput): Promise<SchemaResult>;
+    /**
+     * List available flights matching the given criteria.
+     *
+     * @param criteria - Optional filter criteria for listing flights
+     * @yields FlightInfo for each matching flight
+     */
+    listFlights(criteria?: FlightCriteria): AsyncIterable<FlightInfo>;
+    /**
+     * List available actions supported by the server.
+     *
+     * @yields ActionType describing each available action
+     */
+    listActions(): AsyncIterable<ActionType>;
+    /**
+     * Execute a custom action on the server.
+     *
+     * @param action - The action to execute (type and optional body)
+     * @yields Result messages from the server
+     */
+    doAction(action: FlightAction): AsyncIterable<Result>;
+    /**
+     * Retrieve flight data for the given ticket.
+     * Returns an async iterable of FlightData messages.
+     *
+     * Use the IPC decoding utilities to convert FlightData to Arrow RecordBatches:
+     * - `decodeFlightDataStream()` - decode to RecordBatch stream
+     * - `decodeFlightDataToTable()` - decode to a single Table
+     *
+     * @param ticket - The ticket identifying the data to retrieve
+     * @yields FlightData messages containing Arrow IPC data
+     *
+     * @example
+     * ```ts
+     * import { decodeFlightDataStream } from "@qualithm/arrow-flight-client"
+     *
+     * const stream = client.doGet(ticket)
+     * for await (const batch of decodeFlightDataStream(stream)) {
+     *   console.log(`Received batch with ${batch.numRows} rows`)
+     * }
+     * ```
+     */
+    doGet(ticket: FlightTicket): AsyncIterable<FlightData>;
+    /**
+     * Upload data to the server.
+     * Returns an async iterable of PutResult messages containing server acknowledgements.
+     *
+     * Use the IPC encoding utilities to create FlightData from Arrow data:
+     * - `encodeRecordBatchesToFlightData()` - encode RecordBatch stream
+     * - `encodeTableToFlightData()` - encode a Table
+     *
+     * @param data - Async iterable of FlightData messages to upload (include descriptor in first message)
+     * @yields PutResult messages from the server
+     *
+     * @example
+     * ```ts
+     * import { encodeTableToFlightData } from "@qualithm/arrow-flight-client"
+     *
+     * const descriptor = { type: "path", path: ["my", "table"] }
+     * const flightData = encodeTableToFlightData(table)
+     *
+     * // Add descriptor to first message
+     * async function* withDescriptor() {
+     *   let first = true
+     *   for await (const data of flightData) {
+     *     if (first) {
+     *       yield { ...data, flightDescriptor: descriptor }
+     *       first = false
+     *     } else {
+     *       yield data
+     *     }
+     *   }
+     * }
+     *
+     * for await (const result of client.doPut(withDescriptor())) {
+     *   console.log("Server acknowledged:", result.appMetadata)
+     * }
+     * ```
+     */
+    doPut(data: AsyncIterable<FlightData>): AsyncIterable<PutResult>;
+}
+//# sourceMappingURL=flight-client.d.ts.map

package/dist/client/flight-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flight-client.d.ts","sourceRoot":"","sources":["../../src/client/flight-client.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,UAAU,EAEf,KAAK,UAAU,EAGf,KAAK,QAAQ,EACb,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,YAAY,EAClB,MAAM,kCAAkC,CAAA;AAEzC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EAGlB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,YAAY;;gBAQX,OAAO,EAAE,mBAAmB;IAcxC;;OAEG;IACH,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;OAQG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IA6DtD;;;;;;;OAOG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAgBjD;;;;;OAKG;IACG,aAAa,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,UAAU,CAAC;IAW3E;;;;;OAKG;IACG,cAAc,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAW1E;;;;;OAKG;IACG,SAAS,CAAC,UAAU,EAAE,qBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC;IAWzE;;;;;OAKG;IACI,WAAW,CAAC,QAAQ,CAAC,EAAE,cAAc,GAAG,aAAa,CAAC,UAAU,CAAC;IAexE;;;;OAIG;IACI,WAAW,IAAI,aAAa,CAAC,UAAU,CAAC;IAY/C;;;;;OAKG;IACI,QAAQ,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC;IAe5D;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,KAAK,CAAC,MAAM,EAAE,YAAY,GAAG,aAAa,CAAC,UAAU,CAAC;IAc7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACI,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,SAAS,CAAC;CA4GxE"}

package/dist/client/flight-client.js

@@ -0,0 +1,403 @@
+/* eslint-disable @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access */
+// Disabled due to generated proto types using @ts-nocheck
+import { create, toBinary } from "@bufbuild/protobuf";
+import { createClient } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import { BasicAuthSchema, FlightService } from "../gen/arrow/flight/Flight_pb.js";
+import { FlightAuthError, FlightConnectionError, FlightError, FlightServerError } from "./errors.js";
+import { resolveOptions } from "./types.js";
+/**
+ * Low-level Arrow Flight client for communicating with Flight servers.
+ *
+ * This client provides access to all core Flight RPC methods.
+ * For SQL operations, use `FlightSqlClient` instead.
+ *
+ * @example
+ * ```ts
+ * const client = new FlightClient({ url: "https://flight.example.com:8815" })
+ *
+ * const info = await client.getFlightInfo({ type: "cmd", cmd: myCommand })
+ * for await (const flight of client.listFlights()) {
+ *   console.log(flight)
+ * }
+ *
+ * client.close()
+ * ```
+ */
+export class FlightClient {
+    #options;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generated proto types use @ts-nocheck
+    #client;
+    #closed = false;
+    #authenticated = false;
+    #authToken;
+    constructor(options) {
+        this.#options = resolveOptions(options);
+        // Build node options with TLS configuration if provided
+        const nodeOptions = this.#buildNodeOptions();
+        const transport = createGrpcTransport({
+            baseUrl: this.#options.url,
+            nodeOptions
+        });
+        this.#client = createClient(FlightService, transport);
+    }
+    /**
+     * The base URL of the Flight server.
+     */
+    get url() {
+        return this.#options.url;
+    }
+    /**
+     * Whether the client has been closed.
+     */
+    get closed() {
+        return this.#closed;
+    }
+    /**
+     * Whether the client has been authenticated via handshake.
+     */
+    get authenticated() {
+        return this.#authenticated;
+    }
+    /**
+     * Close the client and release resources.
+     * After calling close, the client should not be used.
+     */
+    close() {
+        this.#closed = true;
+    }
+    /**
+     * Perform Flight Handshake authentication.
+     *
+     * This method is automatically called for clients configured with `auth: { type: "basic" }`.
+     * For custom handshake payloads, call this method directly with raw bytes.
+     *
+     * @param payload - Raw handshake payload (defaults to BasicAuth if auth.type is "basic")
+     * @returns The authentication token from the server
+     */
+    async handshake(payload) {
+        this.#assertOpen();
+        // Use provided payload or build from basic auth credentials
+        let handshakePayload = payload;
+        if (!handshakePayload && this.#options.auth?.type === "basic") {
+            const basicAuth = create(BasicAuthSchema, {
+                username: this.#options.auth.credentials.username,
+                password: this.#options.auth.credentials.password
+            });
+            handshakePayload = toBinary(BasicAuthSchema, basicAuth);
+        }
+        if (!handshakePayload) {
+            throw new FlightError("no handshake payload provided and no basic auth credentials configured");
+        }
+        try {
+            // Create async iterable with single handshake request
+            // eslint-disable-next-line @typescript-eslint/require-await
+            const requests = async function* () {
+                yield {
+                    protocolVersion: 0n,
+                    payload: handshakePayload
+                };
+            };
+            const stream = this.#client.handshake(requests(), {
+                headers: this.#getRequestHeaders()
+            });
+            let response;
+            for await (const msg of stream) {
+                response = msg;
+                break; // Only need first response
+            }
+            if (!response) {
+                throw new FlightAuthError("handshake failed: no response from server");
+            }
+            // Extract token from response payload (typically Bearer token)
+            const token = new TextDecoder().decode(response.payload);
+            this.#authToken = token;
+            this.#authenticated = true;
+            return token;
+        }
+        catch (error) {
+            if (FlightError.isError(error)) {
+                throw error;
+            }
+            throw this.#wrapError(error, "handshake");
+        }
+    }
+    /**
+     * Authenticate with the server using configured credentials.
+     *
+     * For basic auth, this calls the Handshake RPC.
+     * For bearer auth, no action is needed (token is sent in headers).
+     *
+     * @returns The authentication token (if applicable)
+     */
+    async authenticate() {
+        this.#assertOpen();
+        if (this.#options.auth?.type === "basic") {
+            return this.handshake();
+        }
+        if (this.#options.auth?.type === "bearer") {
+            this.#authenticated = true;
+            return this.#options.auth.token;
+        }
+        // No auth configured
+        return undefined;
+    }
+    /**
+     * Get information about a specific flight.
+     *
+     * @param descriptor - Flight descriptor identifying the dataset
+     * @returns Flight information including schema and endpoints
+     */
+    async getFlightInfo(descriptor) {
+        this.#assertOpen();
+        try {
+            return await this.#client.getFlightInfo(this.#toFlightDescriptor(descriptor), {
+                headers: this.#getRequestHeaders()
+            });
+        }
+        catch (error) {
+            throw this.#wrapError(error, "getFlightInfo");
+        }
+    }
+    /**
+     * Poll for updated flight information (useful for long-running queries).
+     *
+     * @param descriptor - Flight descriptor identifying the dataset
+     * @returns Poll information with progress and updated flight info
+     */
+    async pollFlightInfo(descriptor) {
+        this.#assertOpen();
+        try {
+            return await this.#client.pollFlightInfo(this.#toFlightDescriptor(descriptor), {
+                headers: this.#getRequestHeaders()
+            });
+        }
+        catch (error) {
+            throw this.#wrapError(error, "pollFlightInfo");
+        }
+    }
+    /**
+     * Get the schema for a flight.
+     *
+     * @param descriptor - Flight descriptor identifying the dataset
+     * @returns Schema result containing the Arrow schema bytes
+     */
+    async getSchema(descriptor) {
+        this.#assertOpen();
+        try {
+            return await this.#client.getSchema(this.#toFlightDescriptor(descriptor), {
+                headers: this.#getRequestHeaders()
+            });
+        }
+        catch (error) {
+            throw this.#wrapError(error, "getSchema");
+        }
+    }
+    /**
+     * List available flights matching the given criteria.
+     *
+     * @param criteria - Optional filter criteria for listing flights
+     * @yields FlightInfo for each matching flight
+     */
+    async *listFlights(criteria) {
+        this.#assertOpen();
+        try {
+            const stream = this.#client.listFlights({ expression: criteria?.expression ?? new Uint8Array() }, { headers: this.#getRequestHeaders() });
+            for await (const info of stream) {
+                yield info;
+            }
+        }
+        catch (error) {
+            throw this.#wrapError(error, "listFlights");
+        }
+    }
+    /**
+     * List available actions supported by the server.
+     *
+     * @yields ActionType describing each available action
+     */
+    async *listActions() {
+        this.#assertOpen();
+        try {
+            const stream = this.#client.listActions({}, { headers: this.#getRequestHeaders() });
+            for await (const action of stream) {
+                yield action;
+            }
+        }
+        catch (error) {
+            throw this.#wrapError(error, "listActions");
+        }
+    }
+    /**
+     * Execute a custom action on the server.
+     *
+     * @param action - The action to execute (type and optional body)
+     * @yields Result messages from the server
+     */
+    async *doAction(action) {
+        this.#assertOpen();
+        try {
+            const stream = this.#client.doAction({ type: action.type, body: action.body ?? new Uint8Array() }, { headers: this.#getRequestHeaders() });
+            for await (const result of stream) {
+                yield result;
+            }
+        }
+        catch (error) {
+            throw this.#wrapError(error, "doAction");
+        }
+    }
+    /**
+     * Retrieve flight data for the given ticket.
+     * Returns an async iterable of FlightData messages.
+     *
+     * Use the IPC decoding utilities to convert FlightData to Arrow RecordBatches:
+     * - `decodeFlightDataStream()` - decode to RecordBatch stream
+     * - `decodeFlightDataToTable()` - decode to a single Table
+     *
+     * @param ticket - The ticket identifying the data to retrieve
+     * @yields FlightData messages containing Arrow IPC data
+     *
+     * @example
+     * ```ts
+     * import { decodeFlightDataStream } from "@qualithm/arrow-flight-client"
+     *
+     * const stream = client.doGet(ticket)
+     * for await (const batch of decodeFlightDataStream(stream)) {
+     *   console.log(`Received batch with ${batch.numRows} rows`)
+     * }
+     * ```
+     */
+    async *doGet(ticket) {
+        this.#assertOpen();
+        try {
+            const stream = this.#client.doGet(ticket, {
+                headers: this.#getRequestHeaders()
+            });
+            for await (const data of stream) {
+                yield data;
+            }
+        }
+        catch (error) {
+            throw this.#wrapError(error, "doGet");
+        }
+    }
+    /**
+     * Upload data to the server.
+     * Returns an async iterable of PutResult messages containing server acknowledgements.
+     *
+     * Use the IPC encoding utilities to create FlightData from Arrow data:
+     * - `encodeRecordBatchesToFlightData()` - encode RecordBatch stream
+     * - `encodeTableToFlightData()` - encode a Table
+     *
+     * @param data - Async iterable of FlightData messages to upload (include descriptor in first message)
+     * @yields PutResult messages from the server
+     *
+     * @example
+     * ```ts
+     * import { encodeTableToFlightData } from "@qualithm/arrow-flight-client"
+     *
+     * const descriptor = { type: "path", path: ["my", "table"] }
+     * const flightData = encodeTableToFlightData(table)
+     *
+     * // Add descriptor to first message
+     * async function* withDescriptor() {
+     *   let first = true
+     *   for await (const data of flightData) {
+     *     if (first) {
+     *       yield { ...data, flightDescriptor: descriptor }
+     *       first = false
+     *     } else {
+     *       yield data
+     *     }
+     *   }
+     * }
+     *
+     * for await (const result of client.doPut(withDescriptor())) {
+     *   console.log("Server acknowledged:", result.appMetadata)
+     * }
+     * ```
+     */
+    async *doPut(data) {
+        this.#assertOpen();
+        try {
+            const stream = this.#client.doPut(data, {
+                headers: this.#getRequestHeaders()
+            });
+            for await (const result of stream) {
+                yield result;
+            }
+        }
+        catch (error) {
+            throw this.#wrapError(error, "doPut");
+        }
+    }
+    // ── Private helpers ──────────────────────────────────────────────────
+    /** Throws if the client has been closed. */
+    #assertOpen() {
+        if (this.#closed) {
+            throw new FlightError("client is closed");
+        }
+    }
+    /** Converts a FlightDescriptorInput to the proto FlightDescriptor format. */
+    #toFlightDescriptor(input) {
+        if (input.type === "path") {
+            return { type: 1, path: input.path }; // PATH = 1
+        }
+        return { type: 2, cmd: input.cmd }; // CMD = 2
+    }
+    /** Builds Node.js HTTP/2 options including TLS configuration. */
+    #buildNodeOptions() {
+        const nodeOptions = { ...this.#options.nodeOptions };
+        // Apply TLS options if configured
+        if (this.#options.tls) {
+            const { tls } = this.#options;
+            if (tls.cert !== undefined) {
+                nodeOptions.cert = tls.cert;
+            }
+            if (tls.key !== undefined) {
+                nodeOptions.key = tls.key;
+            }
+            if (tls.ca !== undefined) {
+                nodeOptions.ca = tls.ca;
+            }
+            if (tls.passphrase !== undefined && tls.passphrase !== "") {
+                nodeOptions.passphrase = tls.passphrase;
+            }
+            if (tls.rejectUnauthorized !== undefined) {
+                nodeOptions.rejectUnauthorized = tls.rejectUnauthorized;
+            }
+        }
+        return nodeOptions;
+    }
+    /** Returns headers for requests, including auth token if authenticated. */
+    #getRequestHeaders() {
+        const headers = { ...this.#options.headers };
+        // Add auth token if authenticated via handshake
+        if (this.#authToken !== undefined && this.#authToken !== "") {
+            headers.Authorization = `Bearer ${this.#authToken}`;
+        }
+        return headers;
+    }
+    /** Wraps errors in appropriate FlightError subclasses based on error type. */
+    #wrapError(error, operation) {
+        if (FlightError.isError(error)) {
+            return error;
+        }
+        // Handle ConnectRPC errors
+        if (error instanceof Error && "code" in error) {
+            const connectError = error;
+            // Check for authentication-related errors
+            if (connectError.code === "UNAUTHENTICATED" || connectError.code === "PERMISSION_DENIED") {
+                return new FlightAuthError(`${operation} failed: ${connectError.message}`, error);
+            }
+            return new FlightServerError(`${operation} failed: ${connectError.message}`, connectError.code, connectError.rawMessage, error);
+        }
+        // Handle connection errors
+        if (error instanceof Error && error.message.includes("ECONNREFUSED")) {
+            return new FlightConnectionError(`failed to connect to ${this.#options.url}`, this.#options.url, error);
+        }
+        // Generic error wrapping
+        return new FlightError(`${operation} failed: ${error instanceof Error ? error.message : String(error)}`, error);
+    }
+}
+//# sourceMappingURL=flight-client.js.map