@xylex-group/athena 3.0.2 → 3.1.0

package/dist/pipeline-DuKzYGia.d.cts

@@ -0,0 +1,93 @@
+import { b as GeneratorProviderConfig, a as LoadedGeneratorConfig, R as RunGeneratorOptions, d as RunGeneratorResult } from './types-1ztXDgPa.cjs';
+
+type GeneratorConfigFileAction = 'created' | 'updated' | 'unchanged' | 'skipped';
+type GeneratorConfigProviderMode = 'direct' | 'gateway' | 'auto';
+interface EnsureGeneratorConfigFileOptions {
+    cwd?: string;
+    /** Explicit path relative to cwd or absolute. Defaults to discovered path or `athena.config.ts`. */
+    configPath?: string;
+    /** Provider mode preference when creating a new file. */
+    mode?: GeneratorConfigProviderMode;
+    /**
+     * Discover live schemas and auto-fill `provider.schemas`.
+     * Defaults to true.
+     */
+    discoverSchemas?: boolean;
+    /**
+     * When false, never write to disk (report would-be action only).
+     * Defaults to false.
+     */
+    dryRun?: boolean;
+    /**
+     * When true, rewrite the full modern template even if a file already exists.
+     * Defaults to false (intelligent surgical update only).
+     */
+    force?: boolean;
+    /**
+     * Pre-resolved provider used for schema discovery (avoids re-normalizing).
+     */
+    provider?: GeneratorProviderConfig;
+    /**
+     * Optional pre-loaded config (skips a second disk load).
+     */
+    loaded?: LoadedGeneratorConfig;
+    /**
+     * Explicit schemas to write when discovery is disabled or fails.
+     */
+    schemas?: readonly string[];
+}
+interface EnsureGeneratorConfigFileResult {
+    action: GeneratorConfigFileAction;
+    path: string;
+    absolutePath: string;
+    content?: string;
+    schemas: string[];
+    changes: string[];
+    mode: 'direct' | 'gateway';
+    reason?: string;
+}
+type DetectedMode = 'direct' | 'gateway';
+/**
+ * Picks a provider mode from env when the caller did not force one.
+ * Prefers direct when a connection string is present; otherwise gateway.
+ */
+declare function detectGeneratorProviderMode(preferred?: GeneratorConfigProviderMode): DetectedMode;
+/**
+ * Renders a modern, typed `athena.config.ts` using `defineGeneratorConfig` + `generatorEnv`.
+ * Secrets stay env-backed so gateway and direct modes both work without hardcoding keys.
+ */
+declare function renderGeneratorConfigFile(options: {
+    mode: DetectedMode;
+    schemas?: readonly string[];
+}): string;
+/**
+ * Updates only the `schemas:` value inside an existing TypeScript config source.
+ * Supports:
+ * - `schemas: ["public", "athena"]`
+ * - `schemas: generatorEnv.list("...", { default: ["public"] })`
+ *
+ * Returns undefined when the file cannot be updated surgically (caller may full-render).
+ */
+declare function patchSchemasInConfigSource(source: string, schemas: readonly string[]): string | undefined;
+/**
+ * Creates or intelligently updates `athena.config.ts`.
+ *
+ * Intelligence rules:
+ * - missing file → write modern direct/gateway template with env-backed secrets
+ * - existing file + force → full rewrite
+ * - existing file → only patch `provider.schemas` when auto-fill finds new values
+ * - skip write when content/schemas already match (no churn, safe for typecheck CI)
+ * - never removes user-listed schemas that discovery did not return
+ * - gateway mode uses the same template surface as direct (generatorEnv for url/key)
+ */
+declare function ensureGeneratorConfigFile(options?: EnsureGeneratorConfigFileOptions): Promise<EnsureGeneratorConfigFileResult>;
+
+/**
+ * End-to-end generator execution: load config, introspect, render, and optionally write files.
+ *
+ * When `writeConfig` is enabled (default), also ensures `athena.config.ts` exists and
+ * auto-fills discovered schemas without clobbering custom config fields.
+ */
+declare function runSchemaGenerator(options?: RunGeneratorOptions): Promise<RunGeneratorResult>;
+
+export { type EnsureGeneratorConfigFileOptions as E, type GeneratorConfigFileAction as G, type EnsureGeneratorConfigFileResult as a, type GeneratorConfigProviderMode as b, renderGeneratorConfigFile as c, detectGeneratorProviderMode as d, ensureGeneratorConfigFile as e, patchSchemasInConfigSource as p, runSchemaGenerator as r };

package/dist/pipeline-wer2G9xW.d.ts

@@ -0,0 +1,93 @@
+import { b as GeneratorProviderConfig, a as LoadedGeneratorConfig, R as RunGeneratorOptions, d as RunGeneratorResult } from './types-CccOiXPo.js';
+
+type GeneratorConfigFileAction = 'created' | 'updated' | 'unchanged' | 'skipped';
+type GeneratorConfigProviderMode = 'direct' | 'gateway' | 'auto';
+interface EnsureGeneratorConfigFileOptions {
+    cwd?: string;
+    /** Explicit path relative to cwd or absolute. Defaults to discovered path or `athena.config.ts`. */
+    configPath?: string;
+    /** Provider mode preference when creating a new file. */
+    mode?: GeneratorConfigProviderMode;
+    /**
+     * Discover live schemas and auto-fill `provider.schemas`.
+     * Defaults to true.
+     */
+    discoverSchemas?: boolean;
+    /**
+     * When false, never write to disk (report would-be action only).
+     * Defaults to false.
+     */
+    dryRun?: boolean;
+    /**
+     * When true, rewrite the full modern template even if a file already exists.
+     * Defaults to false (intelligent surgical update only).
+     */
+    force?: boolean;
+    /**
+     * Pre-resolved provider used for schema discovery (avoids re-normalizing).
+     */
+    provider?: GeneratorProviderConfig;
+    /**
+     * Optional pre-loaded config (skips a second disk load).
+     */
+    loaded?: LoadedGeneratorConfig;
+    /**
+     * Explicit schemas to write when discovery is disabled or fails.
+     */
+    schemas?: readonly string[];
+}
+interface EnsureGeneratorConfigFileResult {
+    action: GeneratorConfigFileAction;
+    path: string;
+    absolutePath: string;
+    content?: string;
+    schemas: string[];
+    changes: string[];
+    mode: 'direct' | 'gateway';
+    reason?: string;
+}
+type DetectedMode = 'direct' | 'gateway';
+/**
+ * Picks a provider mode from env when the caller did not force one.
+ * Prefers direct when a connection string is present; otherwise gateway.
+ */
+declare function detectGeneratorProviderMode(preferred?: GeneratorConfigProviderMode): DetectedMode;
+/**
+ * Renders a modern, typed `athena.config.ts` using `defineGeneratorConfig` + `generatorEnv`.
+ * Secrets stay env-backed so gateway and direct modes both work without hardcoding keys.
+ */
+declare function renderGeneratorConfigFile(options: {
+    mode: DetectedMode;
+    schemas?: readonly string[];
+}): string;
+/**
+ * Updates only the `schemas:` value inside an existing TypeScript config source.
+ * Supports:
+ * - `schemas: ["public", "athena"]`
+ * - `schemas: generatorEnv.list("...", { default: ["public"] })`
+ *
+ * Returns undefined when the file cannot be updated surgically (caller may full-render).
+ */
+declare function patchSchemasInConfigSource(source: string, schemas: readonly string[]): string | undefined;
+/**
+ * Creates or intelligently updates `athena.config.ts`.
+ *
+ * Intelligence rules:
+ * - missing file → write modern direct/gateway template with env-backed secrets
+ * - existing file + force → full rewrite
+ * - existing file → only patch `provider.schemas` when auto-fill finds new values
+ * - skip write when content/schemas already match (no churn, safe for typecheck CI)
+ * - never removes user-listed schemas that discovery did not return
+ * - gateway mode uses the same template surface as direct (generatorEnv for url/key)
+ */
+declare function ensureGeneratorConfigFile(options?: EnsureGeneratorConfigFileOptions): Promise<EnsureGeneratorConfigFileResult>;
+
+/**
+ * End-to-end generator execution: load config, introspect, render, and optionally write files.
+ *
+ * When `writeConfig` is enabled (default), also ensures `athena.config.ts` exists and
+ * auto-fills discovered schemas without clobbering custom config fields.
+ */
+declare function runSchemaGenerator(options?: RunGeneratorOptions): Promise<RunGeneratorResult>;
+
+export { type EnsureGeneratorConfigFileOptions as E, type GeneratorConfigFileAction as G, type EnsureGeneratorConfigFileResult as a, type GeneratorConfigProviderMode as b, renderGeneratorConfigFile as c, detectGeneratorProviderMode as d, ensureGeneratorConfigFile as e, patchSchemasInConfigSource as p, runSchemaGenerator as r };

package/dist/react.cjs

@@ -413,7 +413,7 @@ function buildAthenaRequestHeaders(input) {
 
 // package.json
 var package_default = {
-  version: "3.0.2"
+  version: "3.1.0"
 };
 
 // src/sdk-version.ts
@@ -1997,6 +1997,402 @@ function useMutation(options) {
     lastRequest: snapshot.lastRequest
   };
 }
+
+// src/query-debug-ast.ts
+var ATHENA_DEBUG_AST_KEY = "__athenaDebugAst";
+function getAthenaDebugAst(value) {
+  if (!value || typeof value !== "object" && typeof value !== "function") {
+    return null;
+  }
+  return value[ATHENA_DEBUG_AST_KEY] ?? null;
+}
+
+// src/query/read-query.ts
+function normalizeAthenaReadQueryOrderBy(orderBy) {
+  if (!orderBy) {
+    return [];
+  }
+  const list = Array.isArray(orderBy) ? orderBy : [orderBy];
+  return list.filter(
+    (entry) => entry && typeof entry.column === "string" && entry.column.trim().length > 0
+  );
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function flattenAthenaRowValue(row, column) {
+  if (!column.relation) {
+    return row[column.column];
+  }
+  const relationValue = row[column.relation.name];
+  if (Array.isArray(relationValue)) {
+    return relationValue.map((entry) => isRecord3(entry) ? entry[column.column] : void 0).filter((entry) => entry !== void 0);
+  }
+  if (isRecord3(relationValue)) {
+    return relationValue[column.column];
+  }
+  return void 0;
+}
+function resolveFlatRowKey(row, index, preferredKey) {
+  const preferredValue = preferredKey && preferredKey in row ? row[preferredKey] : void 0;
+  if (preferredValue !== void 0 && preferredValue !== null && `${preferredValue}`.trim().length > 0) {
+    return String(preferredValue);
+  }
+  for (const [key, value] of Object.entries(row)) {
+    if (key === "__rowKey") {
+      continue;
+    }
+    if (value === void 0 || value === null) {
+      continue;
+    }
+    if (Array.isArray(value)) {
+      if (value.length > 0) {
+        return `${key}-${value.join("-")}`;
+      }
+      continue;
+    }
+    const nextValue = String(value).trim();
+    if (nextValue.length > 0) {
+      return nextValue;
+    }
+  }
+  return `row-${index + 1}`;
+}
+function flattenAthenaReadQueryRows(rows, columns, preferredKey) {
+  return rows.map((entry, index) => {
+    const sourceRow = isRecord3(entry) ? entry : {};
+    const flatRow = columns.reduce(
+      (currentRow, column) => {
+        currentRow[column.key] = flattenAthenaRowValue(sourceRow, column);
+        return currentRow;
+      },
+      { __rowKey: "" }
+    );
+    flatRow.__rowKey = resolveFlatRowKey(flatRow, index, preferredKey);
+    return flatRow;
+  });
+}
+function buildAthenaReadQuerySelectString(columns) {
+  const baseColumns = columns.filter((column) => !column.relation).map((column) => column.column);
+  const relationGroups = /* @__PURE__ */ new Map();
+  for (const column of columns) {
+    if (!column.relation) {
+      continue;
+    }
+    const groupKey = [
+      column.relation.name,
+      column.relation.schema ?? "",
+      column.relation.table
+    ].join(":");
+    const existingGroup = relationGroups.get(groupKey);
+    if (existingGroup) {
+      if (!existingGroup.columns.includes(column.column)) {
+        existingGroup.columns.push(column.column);
+      }
+      continue;
+    }
+    relationGroups.set(groupKey, {
+      columns: [column.column],
+      relation: column.relation
+    });
+  }
+  const relationColumns = [...relationGroups.values()].map(
+    ({ columns: relationColumns2, relation }) => {
+      const relationTarget = relation.schema ? `${relation.schema}.${relation.table}` : relation.table;
+      return `${relation.name}:${relationTarget}(${relationColumns2.join(",")})`;
+    }
+  );
+  return [...baseColumns, ...relationColumns].join(",");
+}
+function buildAthenaReadQueryFindManySelect(columns) {
+  const select = {};
+  for (const column of columns) {
+    if (!column.relation) {
+      select[column.column] = true;
+      continue;
+    }
+    const existingRelation = select[column.relation.name];
+    if (existingRelation && existingRelation !== true && isRecord3(existingRelation.select)) {
+      existingRelation.select[column.column] = true;
+      continue;
+    }
+    select[column.relation.name] = {
+      ...column.relation.schema ? { schema: column.relation.schema } : {},
+      select: {
+        [column.column]: true
+      }
+    };
+  }
+  return select;
+}
+function buildAthenaReadQueryFindManyWhere(filters) {
+  if (!filters?.length) {
+    return;
+  }
+  return filters.reduce(
+    (where, filter) => {
+      const operator = filter.operator ?? "eq";
+      where[filter.column] = operator === "eq" ? filter.value : { [operator]: filter.value };
+      return where;
+    },
+    {}
+  );
+}
+function buildAthenaReadQueryFindManyOrderBy(orderBy) {
+  const normalized = normalizeAthenaReadQueryOrderBy(orderBy);
+  if (normalized.length === 0) {
+    return;
+  }
+  if (normalized.length === 1) {
+    const primary = normalized[0];
+    if (!primary) {
+      return;
+    }
+    return {
+      ascending: primary.direction !== "desc",
+      column: primary.column
+    };
+  }
+  return Object.fromEntries(
+    normalized.map((entry) => [
+      entry.column,
+      entry.direction === "desc" ? "desc" : "asc"
+    ])
+  );
+}
+function applyAthenaReadQueryFilters(queryBuilder, filters) {
+  if (!filters?.length) {
+    return queryBuilder;
+  }
+  return filters.reduce((currentBuilder, filter) => {
+    const operator = filter.operator ?? "eq";
+    const builderMethod = currentBuilder[operator];
+    if (typeof builderMethod !== "function") {
+      return currentBuilder;
+    }
+    return builderMethod.call(currentBuilder, filter.column, filter.value);
+  }, queryBuilder);
+}
+function applyAthenaReadQuerySelectOrder(queryBuilder, orderBy) {
+  const normalized = normalizeAthenaReadQueryOrderBy(orderBy);
+  if (normalized.length === 0) {
+    return queryBuilder;
+  }
+  return normalized.reduce(
+    (builder, entry) => builder.order(entry.column, {
+      ascending: entry.direction !== "desc"
+    }),
+    queryBuilder
+  );
+}
+function applyAthenaReadQuerySelectLimit(queryBuilder, limit) {
+  if (!limit || limit < 1) {
+    return queryBuilder;
+  }
+  return queryBuilder.limit(limit);
+}
+function clampAthenaReadQueryTotalItems(totalItems, limit) {
+  if (!limit || limit < 1) {
+    return totalItems;
+  }
+  return Math.min(totalItems, limit);
+}
+function resolveCountValue(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isFinite(candidate)) {
+      return Math.max(0, Math.trunc(candidate));
+    }
+  }
+  return 0;
+}
+function resolveTotalItemsFromPage({
+  countCandidates,
+  limit,
+  page,
+  pageSize,
+  rowCount
+}) {
+  const exactCount = resolveCountValue(...countCandidates);
+  if (exactCount > 0) {
+    return clampAthenaReadQueryTotalItems(exactCount, limit);
+  }
+  if (rowCount > 0) {
+    const base = (page - 1) * pageSize + rowCount;
+    const synthetic = rowCount >= pageSize ? base + 1 : base;
+    return clampAthenaReadQueryTotalItems(synthetic, limit);
+  }
+  return clampAthenaReadQueryTotalItems(exactCount, limit);
+}
+async function executeAthenaReadQuery({
+  client,
+  page,
+  pageSize,
+  query
+}) {
+  const db = client.db;
+  const baseBuilder = db.from(query.table, {
+    schema: query.schema
+  });
+  const countBuilder = applyAthenaReadQueryFilters(
+    db.from(query.table, { schema: query.schema }),
+    query.filters
+  );
+  const countResult = await countBuilder.select(query.countColumn, {
+    count: "exact",
+    head: true
+  });
+  if ((query.mode ?? "findMany") === "select") {
+    const selectBuilder = applyAthenaReadQuerySelectLimit(
+      applyAthenaReadQuerySelectOrder(
+        applyAthenaReadQueryFilters(baseBuilder, query.filters),
+        query.orderBy
+      ),
+      query.limit
+    );
+    const result2 = await selectBuilder.currentPage(page).pageSize(pageSize).select(buildAthenaReadQuerySelectString(query.columns), {
+      count: "exact"
+    });
+    const rows2 = flattenAthenaReadQueryRows(
+      Array.isArray(result2.data) ? result2.data : [],
+      query.columns,
+      query.rowKey
+    );
+    return {
+      debugAst: getAthenaDebugAst(result2) ?? void 0,
+      rows: rows2,
+      totalItems: resolveTotalItemsFromPage({
+        countCandidates: [countResult.count, result2.count],
+        limit: query.limit,
+        page,
+        pageSize,
+        rowCount: rows2.length
+      })
+    };
+  }
+  const findManyOrderBy = buildAthenaReadQueryFindManyOrderBy(query.orderBy);
+  const findManyOptions = {
+    ...query.limit ? { limit: query.limit } : {},
+    ...findManyOrderBy ? { orderBy: findManyOrderBy } : {},
+    select: buildAthenaReadQueryFindManySelect(query.columns),
+    ...query.filters?.length ? { where: buildAthenaReadQueryFindManyWhere(query.filters) } : {}
+  };
+  const result = await baseBuilder.currentPage(page).pageSize(pageSize).findMany(findManyOptions);
+  const rows = flattenAthenaReadQueryRows(
+    Array.isArray(result.data) ? result.data : [],
+    query.columns,
+    query.rowKey
+  );
+  return {
+    debugAst: getAthenaDebugAst(result) ?? void 0,
+    rows,
+    totalItems: resolveTotalItemsFromPage({
+      countCandidates: [countResult.count, result.count],
+      limit: query.limit,
+      page,
+      pageSize,
+      rowCount: rows.length
+    })
+  };
+}
+
+// src/react/use-athena-read-query.ts
+var DEFAULT_PAGE = 1;
+var DEFAULT_PAGE_SIZE = 10;
+function isReadQueryRunnable(query) {
+  return query.table.trim().length > 0 && query.columns.length > 0 && query.countColumn.trim().length > 0;
+}
+function useAthenaReadQuery({
+  client,
+  query,
+  page = DEFAULT_PAGE,
+  pageSize = DEFAULT_PAGE_SIZE,
+  enabled = true,
+  queryKey,
+  queryKeyPrefix,
+  refetchOnMount,
+  refetchOnWindowFocus,
+  refetchOnReconnect,
+  retry
+}) {
+  const resolvedPage = page > 0 ? Math.trunc(page) : DEFAULT_PAGE;
+  const resolvedPageSize = pageSize > 0 ? Math.trunc(pageSize) : DEFAULT_PAGE_SIZE;
+  const queryEnabled = enabled && !!client && isReadQueryRunnable(query);
+  const defaultQueryKey = React.useMemo(
+    () => [
+      "athena",
+      "read-query",
+      query.mode ?? "findMany",
+      query.table,
+      query.schema,
+      query.columns,
+      query.filters,
+      query.limit,
+      query.orderBy,
+      query.rowKey,
+      query.countColumn,
+      resolvedPage,
+      resolvedPageSize
+    ],
+    [
+      query.columns,
+      query.countColumn,
+      query.filters,
+      query.limit,
+      query.mode,
+      query.orderBy,
+      query.rowKey,
+      query.schema,
+      query.table,
+      resolvedPage,
+      resolvedPageSize
+    ]
+  );
+  const resolvedQueryKey = React.useMemo(() => {
+    if (queryKey !== void 0) {
+      return queryKey;
+    }
+    if (queryKeyPrefix !== void 0) {
+      const prefix = Array.isArray(queryKeyPrefix) ? queryKeyPrefix : [queryKeyPrefix];
+      return [...prefix, ...defaultQueryKey];
+    }
+    return defaultQueryKey;
+  }, [defaultQueryKey, queryKey, queryKeyPrefix]);
+  const result = useQuery({
+    enabled: queryEnabled,
+    queryKey: resolvedQueryKey,
+    queryFn: async () => {
+      if (!client) {
+        throw new Error("Athena client is required to run the read query.");
+      }
+      return executeAthenaReadQuery({
+        client,
+        page: resolvedPage,
+        pageSize: resolvedPageSize,
+        query
+      });
+    },
+    refetchOnMount,
+    refetchOnWindowFocus,
+    refetchOnReconnect,
+    retry
+  });
+  return {
+    data: result.data,
+    rows: result.data?.rows ?? [],
+    totalItems: result.data?.totalItems ?? 0,
+    debugAst: result.data?.debugAst,
+    page: resolvedPage,
+    pageSize: resolvedPageSize,
+    error: result.error,
+    isLoading: result.isLoading,
+    isFetching: result.isFetching,
+    isSuccess: result.isSuccess,
+    isError: result.isError,
+    status: result.status,
+    refetch: result.refetch,
+    reset: result.reset
+  };
+}
 function resolveGetSession(authClient) {
   if ("getSession" in authClient && typeof authClient.getSession === "function") {
     return authClient.getSession;
@@ -2291,7 +2687,7 @@ function resolveNullishValue(mode) {
   if (mode === "null") return null;
   return "";
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function isNullableColumn(model, key) {
@@ -2300,7 +2696,7 @@ function isNullableColumn(model, key) {
 }
 function toModelFormDefaults(model, values, options) {
   const source = values;
-  if (!isRecord3(source)) {
+  if (!isRecord4(source)) {
     return {};
   }
   const mode = options?.nullishMode ?? "empty-string";
@@ -2357,6 +2753,7 @@ exports.toModelFormDefaults = toModelFormDefaults;
 exports.toModelPayload = toModelPayload;
 exports.useAthenaGateway = useAthenaGateway;
 exports.useAthenaQueryClient = useAthenaQueryClient;
+exports.useAthenaReadQuery = useAthenaReadQuery;
 exports.useAthenaSessionClient = useAthenaSessionClient;
 exports.useMutation = useMutation;
 exports.useQuery = useQuery;