@xylex-group/athena 1.4.1 → 1.6.0

package/dist/index.d.ts

@@ -133,6 +133,36 @@ declare class AthenaClient {
 declare function createClient(url: string, apiKey: string, options?: Pick<AthenaGatewayCallOptions, 'client' | 'headers' | 'backend'>): AthenaSdkClient;
 
 type AthenaErrorKind = 'unique_violation' | 'not_found' | 'validation' | 'auth' | 'rate_limit' | 'transient' | 'unknown';
+declare const AthenaErrorKind: {
+    readonly UniqueViolation: "unique_violation";
+    readonly NotFound: "not_found";
+    readonly Validation: "validation";
+    readonly Auth: "auth";
+    readonly RateLimit: "rate_limit";
+    readonly Transient: "transient";
+    readonly Unknown: "unknown";
+};
+type AthenaErrorCode = 'UNIQUE_VIOLATION' | 'NOT_FOUND' | 'VALIDATION_FAILED' | 'AUTH_UNAUTHORIZED' | 'AUTH_FORBIDDEN' | 'RATE_LIMITED' | 'NETWORK_UNAVAILABLE' | 'TRANSIENT_FAILURE' | 'HTTP_FAILURE' | 'UNKNOWN';
+declare const AthenaErrorCode: {
+    readonly UniqueViolation: "UNIQUE_VIOLATION";
+    readonly NotFound: "NOT_FOUND";
+    readonly ValidationFailed: "VALIDATION_FAILED";
+    readonly AuthUnauthorized: "AUTH_UNAUTHORIZED";
+    readonly AuthForbidden: "AUTH_FORBIDDEN";
+    readonly RateLimited: "RATE_LIMITED";
+    readonly NetworkUnavailable: "NETWORK_UNAVAILABLE";
+    readonly TransientFailure: "TRANSIENT_FAILURE";
+    readonly HttpFailure: "HTTP_FAILURE";
+    readonly Unknown: "UNKNOWN";
+};
+type AthenaErrorCategory = 'transport' | 'client' | 'server' | 'database' | 'unknown';
+declare const AthenaErrorCategory: {
+    readonly Transport: "transport";
+    readonly Client: "client";
+    readonly Server: "server";
+    readonly Database: "database";
+    readonly Unknown: "unknown";
+};
 interface AthenaOperationContext {
     table?: string;
     operation?: string;
@@ -140,6 +170,9 @@ interface AthenaOperationContext {
 }
 interface NormalizedAthenaError {
     kind: AthenaErrorKind;
+    code: AthenaErrorCode;
+    category: AthenaErrorCategory;
+    retryable: boolean;
     status?: number;
     constraint?: string;
     table?: string;
@@ -147,6 +180,17 @@ interface NormalizedAthenaError {
     message: string;
     raw: unknown;
 }
+interface AthenaErrorInput {
+    code: AthenaErrorCode;
+    kind: AthenaErrorKind;
+    category: AthenaErrorCategory;
+    message: string;
+    status?: number;
+    retryable?: boolean;
+    requestId?: string;
+    context?: AthenaOperationContext;
+    raw?: unknown;
+}
 interface UnwrapOptions {
     allowNull?: boolean;
     context?: AthenaOperationContext;
@@ -171,6 +215,17 @@ interface RetryConfig {
 interface RequireAffectedOptions {
     min?: number;
 }
+declare class AthenaError extends Error {
+    readonly code: AthenaErrorCode;
+    readonly kind: AthenaErrorKind;
+    readonly category: AthenaErrorCategory;
+    readonly status?: number;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly context?: AthenaOperationContext;
+    readonly raw?: unknown;
+    constructor(input: AthenaErrorInput);
+}
 /**
  * Returns `true` when a result is successful (`2xx` status and no `error`).
  */
@@ -246,4 +301,432 @@ declare function assertInt(value: unknown, label?: string, options?: IntCoercion
  */
 declare function withRetry<T>(config: RetryConfig, fn: () => Promise<T>): Promise<T>;
 
-export { AthenaClient, AthenaConditionCastType, type AthenaErrorKind, AthenaGatewayCallOptions, AthenaGatewayErrorDetails, type AthenaOperationContext, type AthenaResult, AthenaRpcCallOptions, type AthenaSdkClient, BackendConfig, BackendType, type IntCoercionOptions, type NormalizedAthenaError, type RequireAffectedOptions, type RetryBackoffStrategy, type RetryConfig, type RpcOrderOptions, type RpcQueryBuilder, type TableQueryBuilder, type UnwrapOneOptions, type UnwrapOptions, assertInt, coerceInt, createClient, isOk, normalizeAthenaError, requireAffected, requireSuccess, unwrap, unwrapOne, unwrapRows, withRetry };
+/**
+ * Immutable identifier object with consistent SQL rendering.
+ */
+interface SqlIdentifier {
+    readonly segments: string[];
+    toSql(): string;
+    toString(): string;
+}
+/**
+ * Creates a quoted identifier object from segment or dotted inputs.
+ */
+declare function identifier(...segments: string[]): SqlIdentifier;
+
+type ModelKey = string;
+type ColumnKey = string;
+/**
+ * Runtime values that can safely be serialized into tenant-scoped headers.
+ */
+type TenantContextValue = string | number | boolean | null | undefined;
+/**
+ * Compile-time map of tenant context keys to outbound header names.
+ */
+type TenantKeyMap = Record<string, string>;
+/**
+ * Partial tenant context keyed by `TenantKeyMap`.
+ */
+type TenantContext<TMap extends TenantKeyMap> = Partial<Record<keyof TMap, TenantContextValue>>;
+/**
+ * Supported relationship cardinalities for model metadata and introspection snapshots.
+ */
+type ModelRelationKind = 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+/**
+ * Base metadata shape shared by typed model definitions and introspection snapshots.
+ * This type is intentionally row-agnostic so it can be used for generic registries.
+ */
+interface ModelMetadataBase {
+    database?: string;
+    schema?: string;
+    model?: string;
+    tableName?: string;
+    primaryKey: string[];
+    nullable?: Partial<Record<string, boolean>>;
+    relations?: Record<string, ModelRelationMetadata>;
+}
+/**
+ * Strongly-typed model metadata linked to a row shape.
+ */
+type ModelMetadata<Row> = Omit<ModelMetadataBase, 'primaryKey' | 'nullable'> & {
+    primaryKey: Array<Extract<keyof Row, string>>;
+    nullable?: Partial<Record<Extract<keyof Row, string>, boolean>>;
+};
+/**
+ * Relation metadata for model contracts and introspection snapshots.
+ */
+interface ModelRelationMetadata {
+    kind: ModelRelationKind;
+    sourceColumns: ColumnKey[];
+    targetSchema: string;
+    targetModel: ModelKey;
+    targetColumns: ColumnKey[];
+    targetDatabase?: string;
+    through?: {
+        schema: string;
+        model: string;
+        sourceColumns: ColumnKey[];
+        targetColumns: ColumnKey[];
+    };
+}
+/**
+ * Core model definition contract used by typed registries.
+ */
+interface ModelDef<Row, Insert = Partial<Row>, Update = Partial<Insert>, Meta extends ModelMetadataBase = ModelMetadata<Row>> {
+    readonly meta: Meta;
+    readonly __types?: {
+        row: Row;
+        insert: Insert;
+        update: Update;
+    };
+}
+/**
+ * Row-agnostic model definition used as a generic constraint.
+ */
+type AnyModelDef = ModelDef<unknown, unknown, unknown, ModelMetadataBase>;
+/**
+ * Schema-level model registry.
+ */
+interface SchemaDef<Models extends Record<ModelKey, AnyModelDef>> {
+    readonly models: Models;
+}
+/**
+ * Database-level schema registry.
+ */
+interface DatabaseDef<Schemas extends Record<string, SchemaDef<Record<ModelKey, AnyModelDef>>>> {
+    readonly schemas: Schemas;
+}
+/**
+ * Top-level registry keyed by logical database names.
+ */
+type RegistryDef<Databases extends Record<string, DatabaseDef<Record<string, SchemaDef<Record<ModelKey, AnyModelDef>>>>>> = Databases;
+/**
+ * Extracts row type from a model definition.
+ */
+type RowOf<TModel extends AnyModelDef> = TModel extends ModelDef<infer TRow, unknown, unknown, ModelMetadataBase> ? TRow : never;
+/**
+ * Extracts insert type from a model definition.
+ */
+type InsertOf<TModel extends AnyModelDef> = TModel extends ModelDef<unknown, infer TInsert, unknown, ModelMetadataBase> ? TInsert : never;
+/**
+ * Extracts update type from a model definition.
+ */
+type UpdateOf<TModel extends AnyModelDef> = TModel extends ModelDef<unknown, unknown, infer TUpdate, ModelMetadataBase> ? TUpdate : never;
+/**
+ * Resolves a model definition from a registry path.
+ */
+type ModelAt<TRegistry extends RegistryDef<Record<string, DatabaseDef<Record<string, SchemaDef<Record<ModelKey, AnyModelDef>>>>>>, TDatabase extends keyof TRegistry & string, TSchema extends keyof TRegistry[TDatabase]['schemas'] & string, TModel extends keyof TRegistry[TDatabase]['schemas'][TSchema]['models'] & string> = TRegistry[TDatabase]['schemas'][TSchema]['models'][TModel];
+/**
+ * Introspection-level column type families.
+ */
+type IntrospectionTypeKind = 'scalar' | 'enum' | 'domain' | 'range' | 'multirange' | 'composite';
+/**
+ * Introspected column metadata.
+ */
+interface IntrospectionColumn {
+    name: string;
+    dataType: string;
+    udtName: string;
+    typeKind: IntrospectionTypeKind;
+    isNullable: boolean;
+    isPrimaryKey: boolean;
+    hasDefault: boolean;
+    isGenerated: boolean;
+    arrayDimensions: number;
+    enumValues?: string[];
+}
+/**
+ * Introspected relationship metadata.
+ */
+interface IntrospectionRelation {
+    name: string;
+    kind: ModelRelationKind;
+    sourceColumns: string[];
+    targetSchema: string;
+    targetModel: string;
+    targetColumns: string[];
+    targetDatabase?: string;
+    through?: {
+        schema: string;
+        model: string;
+        sourceColumns: string[];
+        targetColumns: string[];
+    };
+}
+/**
+ * Introspected table metadata.
+ */
+interface IntrospectionTable {
+    schema: string;
+    name: string;
+    columns: Record<string, IntrospectionColumn>;
+    primaryKey: string[];
+    relations: Record<string, IntrospectionRelation>;
+}
+/**
+ * Introspected schema metadata.
+ */
+interface IntrospectionSchema {
+    name: string;
+    tables: Record<string, IntrospectionTable>;
+}
+/**
+ * Normalized output of a schema introspection pass.
+ */
+interface IntrospectionSnapshot {
+    backend: BackendType;
+    database: string;
+    generatedAt: string;
+    schemas: Record<string, IntrospectionSchema>;
+}
+/**
+ * Options accepted by introspection providers.
+ */
+interface IntrospectionInspectOptions {
+    schemas?: string[];
+}
+/**
+ * Provider contract implemented by backend-specific introspection adapters.
+ */
+interface SchemaIntrospectionProvider {
+    readonly backend: BackendType;
+    inspect(options?: IntrospectionInspectOptions): Promise<IntrospectionSnapshot>;
+}
+
+/**
+ * Declares a model contract with explicit metadata and typed row/insert/update shapes.
+ */
+declare function defineModel<Row, Insert = Partial<Row>, Update = Partial<Insert>, Meta extends ModelMetadata<Row> = ModelMetadata<Row>>(input: {
+    meta: Meta;
+}): ModelDef<Row, Insert, Update, Meta>;
+/**
+ * Declares a schema-level model map.
+ */
+declare function defineSchema<Models extends Record<string, AnyModelDef>>(models: Models): SchemaDef<Models>;
+/**
+ * Declares a database-level schema map.
+ */
+declare function defineDatabase<Schemas extends Record<string, SchemaDef<Record<string, AnyModelDef>>>>(schemas: Schemas): DatabaseDef<Schemas>;
+/**
+ * Declares a top-level multi-database registry.
+ */
+declare function defineRegistry<Databases extends Record<string, DatabaseDef<Record<string, SchemaDef<Record<string, AnyModelDef>>>>>>(databases: Databases): RegistryDef<Databases>;
+
+type RegistryConstraint = RegistryDef<Record<string, DatabaseDef<Record<string, SchemaDef<Record<string, AnyModelDef>>>>>>;
+/**
+ * Options for creating typed Athena clients.
+ */
+interface TypedClientOptions<TMap extends TenantKeyMap = TenantKeyMap> extends Pick<AthenaGatewayCallOptions, 'backend' | 'client' | 'headers'> {
+    tenantKeyMap?: TMap;
+    tenantContext?: TenantContext<TMap>;
+}
+/**
+ * Typed Athena client with registry-driven model resolution and tenant-context propagation.
+ */
+interface TypedAthenaClient<TRegistry extends RegistryConstraint, TTenantMap extends TenantKeyMap = Record<never, string>> extends AthenaSdkClient {
+    readonly registry: TRegistry;
+    readonly tenantKeyMap: Readonly<TTenantMap>;
+    readonly tenantContext: TenantContext<TTenantMap>;
+    withTenantContext(context: TenantContext<TTenantMap>): TypedAthenaClient<TRegistry, TTenantMap>;
+    fromModel<TDatabase extends keyof TRegistry & string, TSchema extends keyof TRegistry[TDatabase]['schemas'] & string, TModel extends keyof TRegistry[TDatabase]['schemas'][TSchema]['models'] & string>(database: TDatabase, schema: TSchema, model: TModel): TableQueryBuilder<RowOf<ModelAt<TRegistry, TDatabase, TSchema, TModel>>>;
+}
+/**
+ * Creates a typed client bound to a registry contract and optional tenant header mapping.
+ */
+declare function createTypedClient<TRegistry extends RegistryConstraint, TTenantMap extends TenantKeyMap = Record<never, string>>(registry: TRegistry, url: string, apiKey: string, options?: TypedClientOptions<TTenantMap>): TypedAthenaClient<TRegistry, TTenantMap>;
+
+/**
+ * Constructor options for the PostgreSQL introspection provider.
+ */
+interface PostgresIntrospectionProviderOptions {
+    connectionString: string;
+    database?: string;
+}
+/**
+ * Creates a PostgreSQL-backed schema introspection provider.
+ */
+declare function createPostgresIntrospectionProvider(options: PostgresIntrospectionProviderOptions): SchemaIntrospectionProvider;
+
+/**
+ * Supported case transformations for generated symbols and path token variants.
+ */
+type NamingStyle = 'preserve' | 'camel' | 'pascal' | 'snake' | 'kebab';
+/**
+ * Naming configuration for generated TypeScript identifiers.
+ */
+interface GeneratorNamingConfig {
+    modelType: NamingStyle;
+    modelConst: NamingStyle;
+    schemaConst: NamingStyle;
+    databaseConst: NamingStyle;
+    registryConst: NamingStyle;
+}
+/**
+ * Stable feature flags for generator output behavior.
+ */
+interface GeneratorFeatureFlags {
+    emitRelations: boolean;
+    emitRegistry: boolean;
+}
+/**
+ * Experimental toggles for optional/forward-compatible generator behavior.
+ */
+interface GeneratorExperimentalFlags {
+    /**
+     * Legacy compatibility toggle from the initial scaffold.
+     * Gateway introspection is now implemented; this flag is retained for additive config compatibility.
+     */
+    postgresGatewayIntrospection: boolean;
+    /**
+     * Enables contract placeholders for future Scylla provider work.
+     */
+    scyllaProviderContracts: boolean;
+}
+/**
+ * Path templates for each generated artifact category.
+ */
+interface GeneratorOutputTargets {
+    model: string;
+    schema: string;
+    database: string;
+    registry: string;
+}
+/**
+ * Output configuration including dynamic placeholder aliases.
+ */
+interface GeneratorOutputConfig {
+    targets: GeneratorOutputTargets;
+    placeholderMap: Record<string, string>;
+}
+/**
+ * Direct PostgreSQL introspection mode (implemented).
+ */
+interface PostgresDirectProviderConfig {
+    kind: 'postgres';
+    mode: 'direct';
+    connectionString: string;
+    database?: string;
+    schemas?: string[];
+}
+/**
+ * Athena gateway-backed PostgreSQL introspection mode using `/gateway/query`.
+ */
+interface PostgresGatewayProviderConfig {
+    kind: 'postgres';
+    mode: 'gateway';
+    gatewayUrl: string;
+    apiKey: string;
+    database: string;
+    schemas?: string[];
+    backend?: BackendType;
+}
+/**
+ * Scylla introspection provider contract placeholder (phase-two scaffold).
+ */
+interface ScyllaDirectProviderConfig {
+    kind: 'scylla';
+    mode: 'direct';
+    contactPoints: string[];
+    keyspace: string;
+    datacenter?: string;
+}
+type GeneratorProviderConfig = PostgresDirectProviderConfig | PostgresGatewayProviderConfig | ScyllaDirectProviderConfig;
+/**
+ * Root config contract loaded from `athena.config.ts`.
+ */
+interface AthenaGeneratorConfig {
+    provider: GeneratorProviderConfig;
+    output: GeneratorOutputConfig;
+    naming?: Partial<GeneratorNamingConfig>;
+    features?: Partial<GeneratorFeatureFlags>;
+    experimental?: Partial<GeneratorExperimentalFlags>;
+}
+/**
+ * Normalized generator config with defaults applied.
+ */
+interface NormalizedAthenaGeneratorConfig {
+    provider: GeneratorProviderConfig;
+    output: GeneratorOutputConfig;
+    naming: GeneratorNamingConfig;
+    features: GeneratorFeatureFlags;
+    experimental: GeneratorExperimentalFlags;
+}
+/**
+ * Config loader options for CLI/programmatic usage.
+ */
+interface LoadGeneratorConfigOptions {
+    cwd?: string;
+    configPath?: string;
+}
+/**
+ * Fully loaded config result including resolved file path.
+ */
+interface LoadedGeneratorConfig {
+    configPath: string;
+    config: NormalizedAthenaGeneratorConfig;
+}
+type GeneratorArtifactKind = 'model' | 'schema' | 'database' | 'registry';
+/**
+ * One generated output file.
+ */
+interface GeneratedArtifact {
+    kind: GeneratorArtifactKind;
+    path: string;
+    content: string;
+}
+/**
+ * In-memory generator output payload.
+ */
+interface GeneratedArtifacts {
+    snapshot: IntrospectionSnapshot;
+    files: GeneratedArtifact[];
+}
+/**
+ * Runtime options for executing the generator pipeline.
+ */
+interface RunGeneratorOptions {
+    cwd?: string;
+    configPath?: string;
+    dryRun?: boolean;
+    provider?: SchemaIntrospectionProvider;
+}
+/**
+ * Generator execution result including files written to disk.
+ */
+interface RunGeneratorResult extends GeneratedArtifacts {
+    configPath: string;
+    writtenFiles: string[];
+}
+
+declare function normalizeGeneratorConfig(input: AthenaGeneratorConfig): NormalizedAthenaGeneratorConfig;
+/**
+ * Typed identity helper for authoring generator configs.
+ */
+declare function defineGeneratorConfig<TConfig extends AthenaGeneratorConfig>(config: TConfig): TConfig;
+/**
+ * Finds a supported generator config filename in the provided directory.
+ */
+declare function findGeneratorConfigPath(cwd?: string): string | undefined;
+/**
+ * Loads and normalizes `athena.config.*` from disk.
+ */
+declare function loadGeneratorConfig(options?: LoadGeneratorConfigOptions): Promise<LoadedGeneratorConfig>;
+
+/**
+ * Generates model/schema/database/registry source artifacts from an introspection snapshot.
+ */
+declare function generateArtifactsFromSnapshot(snapshot: IntrospectionSnapshot, config: AthenaGeneratorConfig | NormalizedAthenaGeneratorConfig): GeneratedArtifacts;
+
+declare function resolvePostgresColumnType(column: IntrospectionColumn): string;
+
+/**
+ * Resolves a runtime introspection provider from generator config.
+ */
+declare function resolveGeneratorProvider(providerConfig: GeneratorProviderConfig, experimentalFlags: GeneratorExperimentalFlags): SchemaIntrospectionProvider;
+
+/**
+ * End-to-end generator execution: load config, introspect, render, and optionally write files.
+ */
+declare function runSchemaGenerator(options?: RunGeneratorOptions): Promise<RunGeneratorResult>;
+
+export { AthenaClient, AthenaConditionCastType, AthenaError, AthenaErrorCategory, AthenaErrorCode, type AthenaErrorInput, AthenaErrorKind, AthenaGatewayCallOptions, AthenaGatewayErrorDetails, type AthenaGeneratorConfig, type AthenaOperationContext, type AthenaResult, AthenaRpcCallOptions, type AthenaSdkClient, BackendConfig, BackendType, type DatabaseDef, type GeneratedArtifact, type GeneratedArtifacts, type GeneratorArtifactKind, type GeneratorExperimentalFlags, type GeneratorFeatureFlags, type GeneratorNamingConfig, type GeneratorOutputConfig, type GeneratorOutputTargets, type GeneratorProviderConfig, type InsertOf, type IntCoercionOptions, type IntrospectionColumn, type IntrospectionInspectOptions, type IntrospectionRelation, type IntrospectionSchema, type IntrospectionSnapshot, type IntrospectionTable, type IntrospectionTypeKind, type LoadGeneratorConfigOptions, type LoadedGeneratorConfig, type ModelAt, type ModelDef, type ModelMetadata, type ModelRelationKind, type ModelRelationMetadata, type NamingStyle, type NormalizedAthenaError, type NormalizedAthenaGeneratorConfig, type PostgresIntrospectionProviderOptions, type RegistryDef, type RequireAffectedOptions, type RetryBackoffStrategy, type RetryConfig, type RowOf, type RpcOrderOptions, type RpcQueryBuilder, type RunGeneratorOptions, type RunGeneratorResult, type SchemaDef, type SchemaIntrospectionProvider, type TableQueryBuilder, type TenantContext, type TenantContextValue, type TenantKeyMap, type TypedAthenaClient, type TypedClientOptions, type UnwrapOneOptions, type UnwrapOptions, type UpdateOf, assertInt, coerceInt, createClient, createPostgresIntrospectionProvider, createTypedClient, defineDatabase, defineGeneratorConfig, defineModel, defineRegistry, defineSchema, findGeneratorConfigPath, generateArtifactsFromSnapshot, identifier, isOk, loadGeneratorConfig, normalizeAthenaError, normalizeGeneratorConfig, requireAffected, requireSuccess, resolveGeneratorProvider, resolvePostgresColumnType, runSchemaGenerator, unwrap, unwrapOne, unwrapRows, withRetry };