API Reference

Instance-local adapter-factory registry.

Accepts an explicit list of AdapterFactory instances at construction and provides deterministic, immutable lookup by adapter name. Each registry instance owns its own private state; concurrent runtimes never share mutable registration data.

The registry stores and returns the exact factory references supplied by the caller. It does not clone, wrap, initialize, or validate adapter-owned configuration.

Auth configuration block for the unified config.

Groups the config-level auth concerns: the global impersonation fallback and the technical-user permission rules. Request authentication (tokenResolver) and identity resolution (identityResolver) are API-server concerns configured on defineApiConfig (ApiRuntimeConfig), not here, because they run per HTTP request; permissions are declarative data and belong with the rest of the project configuration.

Maps a JWT payload to a ResolvedIdentity. Can be sync or async to support custom identity providers.

Resolves impersonation credentials for a given user and adapter context.

Auth and permission types for the unified LakeQL configuration.

These types are owned by @lakeql/config because they are consumed by both the API and CLI layers. They are transport-neutral — the config package does not interpret JWT, HTTP, or GraphQL details.

JWT-like payload. A plain record from a decoded token.

Permission rule for a technical user, defining which dataSources/tables they can read and write.

Permission rule entry defining catalog, schema, and table access.

Resolved identity information from a JWT token.

Resolves the current user from an incoming request. Returns the JWT payload or null/undefined when unauthenticated.

Composes a LakeQLRuntime from loaded configuration, explicit adapter factories, and an auth resolver.

Construction is sequential: each configured data-source definition is resolved through the registry and its factory methods are called in order (createDataSource, createReadStrategy, optionally createWriteStrategy). The function resolves only after every configured source has been fully composed.

An empty dataSources map produces a valid empty runtime.

If composition fails after one or more data sources have been created, all previously created data sources are closed before the error propagates. Cleanup failures are attached as secondary diagnostics and never replace the primary error.

Validates and normalizes a typed LakeQL configuration.

Accepts an explicit adapter list, a data-source map, and optional application-level config (auth, sourcePath). Validates registrations and individual data-source configurations, merges defaults/overrides, and returns a TypedLakeQLConfig with identity-preserved adapters and a normalized dataSources map.

This is the single point of truth (SPOT) for LakeQL configuration. Both the API and CLI consume the same config object.

This function is pure and stateless — it does not read project files, create runtime instances, or accumulate module-level state.

Manages a single active LakeQL runtime with safe reload semantics.

During reload, a new runtime is created first. The old runtime is only closed after the new one resolves successfully. If creation fails, the old runtime remains active and the construction error propagates to the caller.

If the old runtime’s close() rejects after a successful swap, the new runtime remains active and the close error propagates.

Thrown during configuration validation when an adapter definition’s adapterName does not strictly equal its factory.adapterName.

Exposes both names for programmatic handling and includes them in the error message for diagnostics.

Thrown during defineConfig() processing when a named data source fails validation, merge, adapter resolution, or opaque-value detection.

Carries the affected source name, the optional adapter name, and the original cause for programmatic handling and diagnostics. The cause value is preserved unchanged — non-Error values (strings, null, undefined, numbers, symbols) are never normalized or coerced.

Thrown during registry construction when two or more adapter factories share the same adapter name.

Exposes the conflicting name for programmatic handling and includes it in the error message for diagnostics.

Thrown during runtime composition when a factory method (createDataSource, createReadStrategy, or createWriteStrategy) fails for a configured data-source definition.

Exposes the source name, adapter name, and original error for programmatic handling and diagnostics.

Thrown by getOrThrow() when the requested adapter name is not present in the registry.

Exposes the requested name and a snapshot of all registered adapter names for programmatic handling and diagnostics.

Thrown by runtime accessors (getDataSource, getReadStrategy, getWriteStrategy) when the requested source name is not present in the runtime’s configured data sources.

Exposes the requested name and a frozen snapshot of all configured source names for programmatic handling and diagnostics.

Thrown by getWriteStrategy() when the requested data source exists in the runtime but was configured without a writeConfig field.

Exposes the source name for programmatic handling and includes it in the error message for diagnostics.

Resolves, validates, and normalizes a LakeQL project configuration file.

Uses c12 to locate a lakeql.config.{ts,mts,js,mjs} file within the specified working directory. The resolved module’s default export is validated and normalized into a LoadedLakeQLProject containing serializable data-source definitions and non-serializable adapter factories.

This function is stateless: it maintains no module-level config state and each call returns an independent result.

Options accepted by loadConfig().

Typed adapter definition that combines an adapter’s public name, factory reference, registration options, validation, and optional custom merge logic.

Adapter packages expose definitions implementing this interface to register with defineConfig(). The definition provides the type information necessary for TypeScript inference of data-source configuration without requiring global module augmentation.

Input shape passed to an adapter’s mergeDataSourceConfig() function.

Contains the data-source connection value, optional write configuration, and optional overrides scoped to the adapter’s registration options.

Typed input shape for a single data source within defineConfig().

Uses distributive conditional inference over the adapter tuple to narrow adapter, connection, and overrides based on the selected adapter. This is the INPUT shape accepted by the dataSources map; the normalized output shape (NormalizedDataSourceEntry) omits overrides.

Constrains the dataSources map so that each entry’s adapter field is limited to the union of registered adapter names, and config fields are narrowed to the corresponding adapter’s types.

Result returned by an adapter’s mergeDataSourceConfig() function.

Contains the merged connection value and optional write configuration. The connection is subsequently passed to validateDataSourceConfig().

Normalized output shape for a single data source after merge processing.

Unlike the input DataSourceEntry, this type omits overrides (consumed during merge) and marks all fields readonly. It is used inside TypedLakeQLConfig as the value type of the normalized dataSources map.

Readonly record mapping data-source names to their normalized entries.

This is the OUTPUT type used in TypedLakeQLConfig.dataSources, distinct from the input DataSourcesFor type which carries overrides.

Resolved per-data-source paging limits produced by resolvePaging.

Extends ReadStrategyPaging so resolved values flow to the adapter factory’s createReadStrategy paging argument with compile-time assignability and no cast. The named interface is retained (rather than a type alias) so it reads as a distinct, documented config-layer type.

The return type of defineConfig().

Contains the identity-preserved adapter definitions, a normalized readonly data-sources map, and the unified application-level config fields (auth, sourcePath) shared by API and CLI.

Options accepted by createLakeQLRuntime() to compose a runtime from loaded configuration, explicit adapter factories, and an auth resolver.

A composed LakeQL runtime that owns data-source instances, read strategies, and write strategies created during composition.

Accessors return the exact instances created for each configured source name. The runtime is responsible for closing its owned data sources through LakeQLRuntime.close.

Normalized configuration containing named data-source definitions and application-level settings.

Returned as part of a LoadedLakeQLProject from loadConfig(). The config is serializable data-source metadata; non-serializable runtime objects live in connection and writeConfig opaque fields.

Complete project-level result returned by loadConfig().

Separates the serializable data-source definitions from the non-serializable adapter factory list exported by the project config module.

A single data-source entry within a loaded configuration.

Each definition identifies the adapter that owns it and carries opaque connection and write configuration values that are passed through to the adapter factory without interpretation.