@xylex-group/athena 1.7.0 → 2.0.0

package/dist/types-BnzoaNRC.d.cts

@@ -0,0 +1,380 @@
+/**
+ * athena gateway types
+ *
+ * type definitions for the athena gateway api client and react hook
+ */
+type AthenaGatewayMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
+type AthenaGatewayEndpointPath = '/gateway/fetch' | '/gateway/insert' | '/gateway/update' | '/gateway/delete' | '/gateway/rpc' | '/gateway/query' | `/rpc/${string}`;
+type AthenaCountOption = 'exact' | 'planned' | 'estimated';
+type AthenaJsonPrimitive = string | number | boolean | null;
+type AthenaJsonValue = AthenaJsonPrimitive | AthenaJsonObject | AthenaJsonArray;
+interface AthenaJsonObject {
+    [key: string]: AthenaJsonValue;
+}
+type AthenaJsonArray = AthenaJsonValue[];
+type AthenaConditionValue = AthenaJsonPrimitive;
+type AthenaConditionArrayValue = Array<AthenaConditionValue>;
+type AthenaConditionCastType = string;
+type AthenaConditionOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in' | 'contains' | 'containedBy' | 'not' | 'or';
+interface AthenaGatewayCondition {
+    column?: string;
+    operator: AthenaConditionOperator;
+    value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+    /**
+     * Optional explicit cast for `value` (for example `"uuid"`).
+     * Older gateways ignore unknown fields; newer gateways may use this hint.
+     */
+    value_cast?: AthenaConditionCastType;
+    /**
+     * Optional explicit cast for `column` (for example `"text"`).
+     * Used by SDK SQL fallback for typed comparisons.
+     */
+    column_cast?: AthenaConditionCastType;
+    /** Back-compat shape expected by older gateway implementations */
+    eq_column?: string;
+    eq_value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+    /** Optional cast hint aligned with legacy eq_* fields */
+    eq_value_cast?: AthenaConditionCastType;
+    /** Optional cast hint aligned with legacy eq_* fields */
+    eq_column_cast?: AthenaConditionCastType;
+}
+type AthenaSortDirection = 'ascending' | 'descending';
+interface AthenaSortBy {
+    field: string;
+    direction: AthenaSortDirection;
+}
+interface AthenaFetchPayload {
+    view_name?: string;
+    table_name?: string;
+    columns?: string[] | string;
+    conditions?: AthenaGatewayCondition[];
+    limit?: number;
+    offset?: number;
+    current_page?: number;
+    page_size?: number;
+    total_pages?: number;
+    strip_nulls?: boolean;
+    group_by?: string;
+    time_granularity?: 'day' | 'hour' | 'minute';
+    aggregation_column?: string;
+    aggregation_strategy?: 'cumulative_sum';
+    aggregation_dedup?: boolean;
+    sort_by?: AthenaSortBy;
+}
+interface AthenaInsertPayload<TInsertBody = AthenaJsonObject, TUpdateBody = AthenaJsonObject> {
+    table_name: string;
+    insert_body: TInsertBody | TInsertBody[];
+    update_body?: TUpdateBody;
+    columns?: string[] | string;
+    count?: AthenaCountOption;
+    head?: boolean;
+    default_to_null?: boolean;
+    on_conflict?: string | string[];
+}
+interface AthenaDeletePayload {
+    table_name: string;
+    resource_id?: string;
+    columns?: string[] | string;
+    conditions?: AthenaGatewayCondition[];
+    sort_by?: AthenaSortBy;
+    current_page?: number;
+    page_size?: number;
+    total_pages?: number;
+}
+interface AthenaUpdatePayload<TUpdateBody = AthenaJsonObject> extends AthenaFetchPayload {
+    set?: TUpdateBody;
+    data?: TUpdateBody;
+}
+type AthenaRpcFilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'like' | 'ilike' | 'is' | 'in';
+interface AthenaRpcFilter {
+    column: string;
+    operator: AthenaRpcFilterOperator;
+    value?: AthenaConditionValue | AthenaConditionArrayValue | string;
+}
+interface AthenaRpcOrder {
+    column: string;
+    ascending?: boolean;
+}
+interface AthenaRpcPayload<TArgs = AthenaJsonObject> {
+    function: string;
+    function_name?: string;
+    schema?: string;
+    args?: TArgs;
+    select?: string;
+    filters?: AthenaRpcFilter[];
+    count?: AthenaCountOption;
+    head?: boolean;
+    limit?: number;
+    offset?: number;
+    order?: AthenaRpcOrder;
+}
+/** Backend type for Athena client (aligns with athena-rs) */
+type BackendType = 'athena' | 'postgrest' | 'postgresql' | 'scylladb';
+/** Backend config: type from SDK + backend-scoped options */
+interface BackendConfig {
+    type: BackendType;
+    options?: AthenaJsonObject;
+}
+/** Pre-defined backends for lean usage: backend: Backend.Athena */
+declare const Backend: {
+    readonly Athena: {
+        readonly type: "athena";
+    };
+    readonly Postgrest: {
+        readonly type: "postgrest";
+    };
+    readonly PostgreSQL: {
+        readonly type: "postgresql";
+    };
+    readonly ScyllaDB: {
+        readonly type: "scylladb";
+    };
+};
+type BackendOption = BackendConfig | BackendType;
+interface AthenaGatewayBaseOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    client?: string;
+    backend?: BackendOption;
+    publishEvent?: string;
+    headers?: Record<string, string>;
+    userId?: string | null;
+    organizationId?: string | null;
+}
+type AthenaGatewayHookConfig = AthenaGatewayBaseOptions;
+interface AthenaGatewayCallOptions extends AthenaGatewayBaseOptions {
+    schema?: string;
+    count?: AthenaCountOption;
+    head?: boolean;
+    defaultToNull?: boolean;
+    stripNulls?: boolean;
+    onConflict?: string | string[];
+    updateBody?: AthenaJsonObject;
+}
+interface AthenaRpcCallOptions extends AthenaGatewayCallOptions {
+    count?: AthenaCountOption;
+    get?: boolean;
+}
+interface AthenaGatewayResponse<T = unknown> {
+    ok: boolean;
+    status: number;
+    data: T | null;
+    count?: number | null;
+    error?: string;
+    errorDetails?: AthenaGatewayErrorDetails | null;
+    raw: unknown;
+}
+type AthenaGatewayErrorCode = 'NETWORK_ERROR' | 'HTTP_ERROR' | 'INVALID_JSON' | 'UNKNOWN_ERROR';
+interface AthenaGatewayErrorDetails {
+    code: AthenaGatewayErrorCode;
+    message: string;
+    status: number;
+    endpoint?: AthenaGatewayEndpointPath;
+    method?: AthenaGatewayMethod;
+    requestId?: string;
+    hint?: string;
+    cause?: string;
+}
+interface AthenaGatewayResponseLog extends AthenaGatewayResponse {
+    timestamp: string;
+}
+interface AthenaGatewayCallLog {
+    endpoint: AthenaGatewayEndpointPath;
+    method: AthenaGatewayMethod;
+    payload: unknown;
+    headers: Record<string, string>;
+    timestamp: string;
+}
+interface AthenaGatewayHookResult {
+    fetchGateway: <T = unknown>(payload: AthenaFetchPayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
+    insertGateway: <T = unknown>(payload: AthenaInsertPayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
+    updateGateway: <T = unknown>(payload: AthenaUpdatePayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
+    deleteGateway: <T = unknown>(payload: AthenaDeletePayload, options?: AthenaGatewayCallOptions) => Promise<AthenaGatewayResponse<T>>;
+    rpcGateway: <T = unknown>(payload: AthenaRpcPayload, options?: AthenaRpcCallOptions) => Promise<AthenaGatewayResponse<T>>;
+    isLoading: boolean;
+    error: string | null;
+    lastRequest: AthenaGatewayCallLog | null;
+    lastResponse: AthenaGatewayResponseLog | null;
+    baseUrl: string;
+}
+
+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>;
+}
+
+export { type AthenaJsonValue as A, type BackendConfig as B, type IntrospectionRelation as C, type DatabaseDef as D, type IntrospectionSchema as E, type IntrospectionTable as F, type IntrospectionTypeKind as G, type ModelRelationKind as H, type InsertOf as I, type ModelRelationMetadata as J, type TenantContextValue as K, type AthenaGatewayHookConfig as L, type ModelMetadata as M, type AthenaGatewayHookResult as N, type AthenaDeletePayload as O, type AthenaFetchPayload as P, type AthenaGatewayResponse as Q, type RegistryDef as R, type SchemaDef as S, type TenantKeyMap as T, type UpdateOf as U, type AthenaInsertPayload as V, type AthenaUpdatePayload as W, type AthenaGatewayEndpointPath as X, type AthenaGatewayMethod as Y, type BackendType as a, type AthenaConditionValue as b, type AthenaConditionCastType as c, type AthenaConditionArrayValue as d, type AthenaConditionOperator as e, type AthenaGatewayCallOptions as f, type AthenaGatewayErrorDetails as g, type AthenaJsonObject as h, type AthenaRpcCallOptions as i, type AnyModelDef as j, type ModelDef as k, type TenantContext as l, type RowOf as m, type ModelAt as n, type SchemaIntrospectionProvider as o, type IntrospectionSnapshot as p, type IntrospectionColumn as q, type AthenaGatewayErrorCode as r, type AthenaJsonArray as s, type AthenaJsonPrimitive as t, type AthenaRpcFilter as u, type AthenaRpcFilterOperator as v, type AthenaRpcOrder as w, type AthenaRpcPayload as x, Backend as y, type IntrospectionInspectOptions as z };