API Reference

Open adapter name type.

Adapter identifiers are plain strings so that third-party adapters do not require changes to a central union type.

Shared source configuration that identifies a table within a data source without coupling to adapter-specific connection details.

Neutral authentication types for data source access.

These types live in @lakeql/datasource (design decision 4) because they are required by the adapter factory and read strategy contracts.

Discriminated union of authentication credentials that can be transported through the core without adapter-specific knowledge.

The set of variants may be extended by a future auth design, but the core must carry request auth without interpreting adapter-level credential details.

Auth resolution function injected into read strategies and adapter factories. Given a data source name and an opaque request context, it returns optional credentials and adapter-level options.

Describes actual support for operations, metadata discovery, write modes, and DDL provided by a data source.

Adapters populate this at construction time so that the runtime can avoid selecting unsupported operations.

Adapter-neutral data source contract.

Every adapter package implements this interface to provide query execution, streaming, metadata discovery, DDL, and lifecycle management without coupling the core to adapter-specific details.

Metadata describing a single column in a table.

Parameters for executing a SQL query against a data source.

Definition for creating a new table.

Adapter-neutral type mapping between engine-specific data types and the canonical LakeQL primitive type system.

The canonical LakeQL primitive types used across codegen and metadata.

This union mirrors PrimitiveType in @lakeql/schema-generator (the source of truth). It is duplicated here on purpose: this contract package must not depend on an implementation package. Keep the two in sync.

Maps between an adapter’s engine-specific data types and LakeQL PrimitiveTypes.

Each adapter provides its own implementation that understands its engine’s native type system (Trino, T-SQL, etc.).

Shared read input that types common values while leaving filter, schema, and context generic for adapter- or API-specific extensibility.

Neutral read result exposing total count, page information, and typed result nodes.

Strategy contract for reading data from a data source. Adapter-specific read implementations conform to this interface.

Resolved per-data-source paging limits.

Owned by @lakeql/datasource so resolved config values flow to the adapter factory and read strategies with compile-time assignability.

Shared write configuration containing table coordinates and optional common write settings. Storage-backed strategies may require basePath; direct-insert strategies omit it.

Schema-library-agnostic write input containing records, a generic schema value, and write configuration.

Strategy contract for writing data to a data source. Adapter-specific write implementations conform to this interface.

Supported load strategies for write operations.

• full_load — replace the target table completely
• full_load_append — replace existing partitions; append new ones
• append — add records without removing existing data

Adapter factory contract.

Every adapter package exposes a single factory that the runtime uses to construct a data source, read strategy, and write strategy without adapter-specific switch statements.

Config parameters use unknown to keep the core free of adapter-specific type imports. Adapter factories own validation and narrowing of their configuration objects.

Environment-based connection configuration is NOT part of this contract. If an adapter needs environment parsing, it provides a separate config-layer provider that feeds the central config loader.

Operational error for authentication or authorization failures.

Fixes category to "auth".

Operational error for explicitly cancelled operations.

Fixes category to "cancelled".

Base operational error for datasource failures.

Every instance carries a fixed category, the adapter name and dataSource identifier that produced the failure, and optionally the lower-level cause.

Adapter-owned configuration and connection errors remain the adapter’s responsibility — they should extend their own error types, not this one.

Category strings that classify operational datasource errors.

Each category maps to a specific DataSourceError subclass, allowing consumers to branch on the category without instanceof checks or message parsing.

Validation error for core contract values.

Identifies the invalid field and value when the validation logic can reasonably determine them. Field identification is optional.

Operational error for network-level failures (connection refused, DNS resolution, TLS handshake, etc.).

Fixes category to "network".

Operational error for query execution failures.

Fixes category to "query".

Operational error for operations that exceeded a time limit.

Fixes category to "timeout".

Operational error for operations that an adapter does not support.

Fixes category to "unsupported" and exposes the rejected operation name.

A write strategy that rejects every write with an UnsupportedOperationError.

Adapter factories use this to satisfy the DataSourceWriteStrategy contract when the adapter does not yet provide a real write path.

Builds a TypeMapper from an adapter’s engine↔primitive lookup tables.

The returned toPrimitiveType normalizes its input before the lookup and falls back to "String" for unknown engine types. toEngineType reads the mapping for the closed PrimitiveType union.

Lookup tables that define an adapter’s type mapping in both directions.

Default upper bound for perPage when no ReadValidationConfig override is supplied.

Validates paging (and optional sorting) parameters before query building.

Read-strategy implementations MUST call this before building or executing any query. Invalid input throws a DataSourceValidationError to block query construction.

Rules:

• page : finite integer ≥ 1.
• perPage : finite integer between 1 and config.maxPerPage (default {@link DEFAULT_MAX_PER_PAGE}).
• sorting (when present): must be an array.

Configuration for read-input validation.

Escape a value as a SQL string literal.

The input is treated as a string literal value. Embedded single-quote characters are escaped by doubling them (' → ''), and the result is wrapped in single quotes. The escaping is identical across the Trino and Fabric dialects.

Returns true if value is a non-null plain object: its prototype is Object.prototype or null, and it is not an array.

This is the strict variant shared across all adapter modules. It rejects class instances, Date, RegExp, and other exotic objects, and it is safe for prototype-less objects created via Object.create(null).

Quote a fully-qualified identifier composed of one or more segments.

Applies the dialect-specific quoteFn independently to each segment and joins them with literal dots. Requires at least one segment. The per-segment quoting semantics are owned by the caller’s quoteFn.

Throws if value contains any C0 (U+0000–U+001F) or C1 (U+007F–U+009F) control character.