javascript/lib/types.ts

// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

import { RecordBatchReader, Table, Schema } from 'apache-arrow'

/**
 * Bitmask flags controlling how the driver manager resolves a driver name.
 *
 * These values correspond to the `ADBC_LOAD_FLAG_*` constants in the ADBC spec.
 * Flags can be combined with bitwise OR. When `loadFlags` is omitted in
 * `ConnectOptions`, `LoadFlags.Default` is used.
 *
 * @example
 * // Only search system paths, disallow relative paths
 * const db = new AdbcDatabase({
 *   driver: 'sqlite',
 *   loadFlags: LoadFlags.SearchSystem,
 * })
 */
export const LoadFlags = {
  /** Search directory paths in the `ADBC_DRIVER_PATH` environment variable (and the conda environment, if installed via conda). */
  SearchEnv: 1 << 1,
  /** Search the user configuration directory. */
  SearchUser: 1 << 2,
  /** Search the system configuration directory. */
  SearchSystem: 1 << 3,
  /** Allow a relative path to be provided as the driver name. */
  AllowRelativePaths: 1 << 4,
  /** All defined flags enabled. This is the default when `loadFlags` is omitted. */
  Default: (1 << 1) | (1 << 2) | (1 << 3) | (1 << 4),
} as const
export type LoadFlags = (typeof LoadFlags)[keyof typeof LoadFlags]

/**
 * Depth values for the `getObjects` metadata call.
 *
 * These correspond to the `ADBC_OBJECT_DEPTH_*` constants in the ADBC spec.
 *
 * @example
 * // Retrieve catalogs and schemas only
 * await conn.getObjects({ depth: ObjectDepth.Schemas })
 */
export const ObjectDepth = {
  /** Catalogs, schemas, tables, and columns (default). */
  All: 0,
  /** Catalogs only. */
  Catalogs: 1,
  /** Catalogs and schemas. */
  Schemas: 2,
  /** Catalogs, schemas, and tables. */
  Tables: 3,
} as const
export type ObjectDepth = (typeof ObjectDepth)[keyof typeof ObjectDepth]

/**
 * Info codes for the `getInfo` metadata call.
 *
 * These correspond to the `ADBC_INFO_*` constants in the ADBC spec.
 * Pass a subset to `getInfo()` to retrieve only specific metadata fields.
 *
 * @example
 * const table = await conn.getInfo([InfoCode.VendorName, InfoCode.DriverVersion])
 */
export const InfoCode = {
  /** The database vendor/product name (string). */
  VendorName: 0,
  /** The database vendor/product version (string). */
  VendorVersion: 1,
  /** The Arrow library version used by the vendor (string). */
  VendorArrowVersion: 2,
  /** Whether the vendor supports SQL queries (bool). */
  VendorSql: 3,
  /** Whether the vendor supports Substrait queries (bool). */
  VendorSubstrait: 4,
  /** Minimum supported Substrait version, or null (string). */
  VendorSubstraitMinVersion: 5,
  /** Maximum supported Substrait version, or null (string). */
  VendorSubstraitMaxVersion: 6,
  /** The driver name (string). */
  DriverName: 100,
  /** The driver version (string). */
  DriverVersion: 101,
  /** The Arrow library version used by the driver (string). */
  DriverArrowVersion: 102,
  /** The ADBC API version implemented by the driver (int64). Available since ADBC 1.1.0. */
  DriverAdbcVersion: 103,
} as const
export type InfoCode = (typeof InfoCode)[keyof typeof InfoCode]

/**
 * Options for connecting to a driver/database.
 *
 * These options configure how the ADBC driver is loaded and how the initial connection is established.
 */
interface ConnectOptionsBase {
  /**
   * Name of the entrypoint function (optional).
   * If not provided, ADBC will attempt to guess the entrypoint symbol name based on the driver name.
   */
  entrypoint?: string
  /**
   * Additional directories to search for drivers and driver manifest (`.toml`) files (optional).
   * Searched before the default system and user configuration directories.
   */
  manifestSearchPaths?: string[]
  /**
   * Additional directories to search for connection profile (`.toml`) files (optional).
   * Searched before the default system and user configuration directories.
   */
  profileSearchPaths?: string[]
  /**
   * Bitmask controlling how the driver name is resolved (optional).
   * Use the {@link LoadFlags} constants to compose a value.
   * Defaults to {@link LoadFlags.Default} (all search locations enabled) when omitted.
   */
  loadFlags?: number
}

export type ConnectOptions =
  | (ConnectOptionsBase & {
      /**
       * Driver to load. Accepts any of the following forms:
       * - Short name: `"sqlite"`, `"postgresql"` — the driver manager searches for a matching
       *   manifest file (e.g. `sqlite.toml`) in the configured directories, then falls back to
       *   `LD_LIBRARY_PATH` / `PATH`.
       * - Absolute path to a shared library: `"/usr/lib/libadbc_driver_sqlite.so"`
       * - Absolute path to a driver manifest `.toml` file (with or without the `.toml` extension).
       * - Relative path (only valid when {@link LoadFlags.AllowRelativePaths} is set).
       * - URI-style string: `"sqlite:file::memory:"`, `"postgresql://user:pass@host/db"` — the
       *   driver name is the URI scheme and the remainder is passed as the connection URI.
       * - Connection profile URI: `"profile://my_profile"` — loads a named profile from a
       *   `.toml` file found in {@link profileSearchPaths} or the default search directories.
       */
      driver: string
      /** Database-specific options passed to the driver during initialization. */
      databaseOptions?: Record<string, string>
    })
  | (ConnectOptionsBase & {
      /**
       * Database-specific options passed to the driver during initialization.
       *
       * When `driver` is omitted, either `uri` or `profile` is required:
       * - `uri` — passed directly to the driver manager (e.g. `"sqlite::memory:"`, `"profile://name"`)
       * - `profile` — bare connection profile name; the profile file specifies the driver
       */
      databaseOptions: ({ uri: string } | { profile: string }) & Record<string, string>
    })

/**
 * Ingestion modes for the `ingest` convenience method.
 *
 * These correspond to the `adbc.ingest.mode.*` option values in the ADBC spec.
 *
 * @example
 * await conn.ingest('my_table', data, { mode: IngestMode.Append })
 */
export const IngestMode = {
  /** Append to an existing table. Fails if the table does not exist. */
  Append: 'adbc.ingest.mode.append',
  /** Create a new table and insert. Fails if the table already exists. */
  Create: 'adbc.ingest.mode.create',
  /** Create the table if it does not exist, then append. */
  CreateAppend: 'adbc.ingest.mode.create_append',
  /** Drop the existing table (if any) and recreate it, then insert. */
  Replace: 'adbc.ingest.mode.replace',
} as const
export type IngestMode = (typeof IngestMode)[keyof typeof IngestMode]

/** Options for the `ingest` convenience method. */
export interface IngestOptions {
  /**
   * How to handle an existing table.
   * Defaults to {@link IngestMode.Create}.
   */
  mode?: IngestMode
  /** The catalog to create/locate the target table in (optional). */
  catalog?: string
  /** The database schema to create/locate the target table in (optional). */
  dbSchema?: string
  /** Whether to ingest into a temporary table (optional). */
  temporary?: boolean
}

/** Options for getObjects metadata call. */
export interface GetObjectsOptions {
  /**
   * The level of depth to retrieve. Use the {@link ObjectDepth} constants.
   * Defaults to {@link ObjectDepth.All} when omitted.
   */
  depth?: ObjectDepth
  /** Filter by catalog name pattern. */
  catalog?: string
  /** Filter by database schema name pattern. */
  dbSchema?: string
  /** Filter by table name pattern. */
  tableName?: string
  /** Filter by table type (e.g., ["table", "view"]). */
  tableType?: string[]
  /** Filter by column name pattern. */
  columnName?: string
}

/**
 * Represents an ADBC Database.
 *
 * An AdbcDatabase represents a handle to a database. This may be a single file (SQLite),
 * a connection configuration (PostgreSQL), or an in-memory database.
 * It holds state that is shared across multiple connections.
 */
export interface AdbcDatabase {
  /**
   * Open a new connection to the database.
   *
   * @returns A Promise resolving to a new AdbcConnection.
   */
  connect(): Promise<AdbcConnection>

  /**
   * Release the database resources.
   * After closing, the database object should not be used.
   */
  close(): Promise<void>
}

/**
 * Represents a single connection to a database.
 *
 * An AdbcConnection maintains the state of a connection to the database, such as
 * current transaction state and session options.
 */
export interface AdbcConnection {
  /**
   * Create a new statement for executing queries.
   *
   * @returns A Promise resolving to a new AdbcStatement.
   */
  createStatement(): Promise<AdbcStatement>

  /**
   * Set an option on the connection.
   *
   * @param key The option name (e.g., "adbc.connection.autocommit").
   * @param value The option value.
   */
  setOption(key: string, value: string): void

  /**
   * Toggle autocommit behavior.
   *
   * @param enabled Whether autocommit should be enabled.
   */
  setAutoCommit(enabled: boolean): void

  /**
   * Toggle read-only mode.
   *
   * @param enabled Whether the connection should be read-only.
   */
  setReadOnly(enabled: boolean): void

  /**
   * Get a hierarchical view of database objects (catalogs, schemas, tables, columns).
   *
   * @param options Filtering options for the metadata query.
   * @returns A Promise resolving to an Apache Arrow Table containing the metadata.
   */
  getObjects(options?: GetObjectsOptions): Promise<Table>

  /**
   * Get the Arrow schema for a specific table.
   *
   * @param options An object containing catalog, dbSchema, and tableName.
   * @param options.catalog The catalog name (or undefined).
   * @param options.dbSchema The schema name (or undefined).
   * @param options.tableName The table name.
   * @returns A Promise resolving to the Arrow Schema of the table.
   */
  getTableSchema(options: { catalog?: string; dbSchema?: string; tableName: string }): Promise<Schema>

  /**
   * Get a list of table types supported by the database.
   *
   * @returns A Promise resolving to an Apache Arrow Table with a single string column of table types.
   */
  getTableTypes(): Promise<Table>

  /**
   * Get metadata about the driver and database.
   *
   * @param infoCodes Optional list of info codes to retrieve. Use the {@link InfoCode} constants.
   *   If omitted, all available info is returned.
   * @returns A Promise resolving to an Apache Arrow Table containing the requested metadata info.
   */
  getInfo(infoCodes?: InfoCode[]): Promise<Table>

  /**
   * Execute a SQL query and return all results as an Arrow Table.
   *
   * Convenience method that creates a statement, sets the SQL, optionally binds
   * parameters, executes the query, and closes the statement.
   * For large result sets, use {@link queryStream} to avoid loading everything into memory.
   *
   * @param sql The SQL query to execute.
   * @param params Optional Arrow Table to bind as parameters.
   * @returns A Promise resolving to an Apache Arrow Table.
   */
  query(sql: string, params?: Table): Promise<Table>

  /**
   * Execute a SQL query and return the results as a RecordBatchReader for streaming.
   *
   * Use this instead of {@link query} when working with large result sets that should
   * not be fully loaded into memory. The reader remains valid after the statement is
   * closed because the underlying iterator holds its own reference to the native resources.
   *
   * @param sql The SQL query to execute.
   * @param params Optional Arrow Table to bind as parameters.
   * @returns A Promise resolving to an Apache Arrow RecordBatchReader.
   */
  queryStream(sql: string, params?: Table): Promise<RecordBatchReader>

  /**
   * Ingest Arrow data into a database table.
   *
   * Convenience method that sets the ingestion options, binds the data, and
   * calls executeUpdate. Depending on the driver, this can avoid per-row
   * overhead compared to a prepare-bind-insert loop.
   *
   * @param tableName The target table name.
   * @param data Arrow Table to ingest.
   * @param options Ingestion options (mode, catalog, dbSchema, temporary).
   * @returns A Promise resolving to the number of rows ingested, or -1 if unknown.
   */
  ingest(tableName: string, data: Table, options?: IngestOptions): Promise<number>

  /**
   * Ingest Arrow data from a stream into a database table.
   *
   * Unlike {@link ingest}, this method streams data batch-by-batch, avoiding
   * full materialization in memory. Use this for large datasets that should
   * not be buffered entirely.
   *
   * @param tableName The target table name.
   * @param reader Arrow RecordBatchReader to stream.
   * @param options Ingestion options (mode, catalog, dbSchema, temporary).
   * @returns A Promise resolving to the number of rows ingested, or -1 if unknown.
   */
  ingestStream(tableName: string, reader: RecordBatchReader, options?: IngestOptions): Promise<number>

  /**
   * Execute a SQL statement (INSERT, UPDATE, DELETE, DDL) and return the row count.
   *
   * Convenience method that creates a statement, sets the SQL, optionally binds
   * parameters, executes the update, and closes the statement.
   *
   * @param sql The SQL statement to execute.
   * @param params Optional Arrow Table to bind as parameters.
   * @returns A Promise resolving to the number of rows affected, or -1 if unknown.
   */
  execute(sql: string, params?: Table): Promise<number>

  /**
   * Commit any pending transactions.
   * Only valid if autocommit is disabled.
   */
  commit(): Promise<void>

  /**
   * Rollback any pending transactions.
   * Only valid if autocommit is disabled.
   */
  rollback(): Promise<void>

  /**
   * Close the connection and release resources.
   */
  close(): Promise<void>
}

/**
 * Represents a query statement.
 *
 * An AdbcStatement is used to execute SQL queries or prepare bulk insertions.
 * State such as the SQL query string or bound parameters is held by the statement.
 */
export interface AdbcStatement {
  /**
   * Set the SQL query string.
   *
   * @param query The SQL query to execute.
   */
  setSqlQuery(query: string): Promise<void>

  /**
   * Set an option on the statement.
   *
   * @param key The option name (e.g., "adbc.ingest.target_table").
   * @param value The option value.
   */
  setOption(key: string, value: string): void

  /**
   * Execute the query and return a stream of results.
   *
   * @returns A Promise resolving to an Apache Arrow RecordBatchReader.
   * The reader must be consumed or closed to release resources.
   */
  executeQuery(): Promise<RecordBatchReader>

  /**
   * Execute an update command (e.g., INSERT, UPDATE, DELETE) that returns no data.
   *
   * @returns A Promise resolving to the number of rows affected (if known), or -1.
   */
  executeUpdate(): Promise<number>

  /**
   * Bind parameters or data for ingestion.
   *
   * This is used for bulk ingestion or parameterized queries.
   *
   * @param data Arrow Table containing the data to bind.
   */
  bind(data: Table): Promise<void>

  /**
   * Bind a stream of data for ingestion or parameterized queries.
   *
   * Streams batches one at a time to the driver, avoiding full
   * materialization of the reader in memory.
   *
   * @param reader Arrow RecordBatchReader to bind.
   */
  bindStream(reader: RecordBatchReader): Promise<void>

  /**
   * Close the statement and release resources.
   */
  close(): Promise<void>
}