@xylex-group/athena 1.2.1 → 1.4.0

package/dist/index.cjs

@@ -63,6 +63,10 @@ function isAthenaGatewayError(error) {
 // src/gateway/client.ts
 var DEFAULT_BASE_URL = "https://athena-db.com";
 var DEFAULT_CLIENT = "railway_direct";
+var FALLBACK_SDK_VERSION = "1.3.0";
+var SDK_NAME = "xylex-group/athena";
+var SDK_VERSION = typeof process !== "undefined" && process?.env?.npm_package_version ? process.env.npm_package_version : FALLBACK_SDK_VERSION;
+var SDK_HEADER_VALUE = `${SDK_NAME} ${SDK_VERSION}`;
 function parseResponseBody(rawText, contentType) {
   if (!rawText) {
     return { parsed: null, parseFailed: false };
@@ -201,7 +205,8 @@ function buildHeaders(config, options) {
   const finalApiKey = options?.apiKey ?? config.apiKey;
   const finalPublishEvent = options?.publishEvent ?? config.publishEvent;
   const headers = {
-    "Content-Type": "application/json"
+    "Content-Type": "application/json",
+    "X-Athena-Sdk": SDK_HEADER_VALUE
   };
   if (options?.userId ?? config.userId) {
     headers["X-User-Id"] = options?.userId ?? config.userId ?? "";
@@ -466,6 +471,25 @@ function createFilterMethods(state, addCondition, self) {
       state.offset = count;
       return self;
     },
+    currentPage(value) {
+      state.currentPage = value;
+      return self;
+    },
+    pageSize(value) {
+      state.pageSize = value;
+      return self;
+    },
+    totalPages(value) {
+      state.totalPages = value;
+      return self;
+    },
+    order(column, options) {
+      state.order = {
+        field: column,
+        direction: options?.ascending === false ? "descending" : "ascending"
+      };
+      return self;
+    },
     gt(column, value) {
       addCondition("gt", column, value);
       return self;
@@ -680,6 +704,10 @@ function createTableBuilder(tableName, client) {
       conditions: state.conditions.length ? [...state.conditions] : void 0,
       limit: state.limit,
       offset: state.offset,
+      current_page: state.currentPage,
+      page_size: state.pageSize,
+      total_pages: state.totalPages,
+      sort_by: state.order,
       strip_nulls: options?.stripNulls ?? true,
       count: options?.count,
       head: options?.head
@@ -715,6 +743,10 @@ function createTableBuilder(tableName, client) {
       state.conditions = [];
       state.limit = void 0;
       state.offset = void 0;
+      state.order = void 0;
+      state.currentPage = void 0;
+      state.pageSize = void 0;
+      state.totalPages = void 0;
       return builder;
     },
     select(columns = DEFAULT_COLUMNS, options) {
@@ -806,6 +838,10 @@ function createTableBuilder(tableName, client) {
           conditions: filters,
           strip_nulls: mergedOptions?.stripNulls ?? true
         };
+        if (state.order) payload.sort_by = state.order;
+        if (state.currentPage !== void 0) payload.current_page = state.currentPage;
+        if (state.pageSize !== void 0) payload.page_size = state.pageSize;
+        if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
         if (columns) payload.columns = columns;
         const response = await client.updateGateway(payload, mergedOptions);
         return formatResult(response);
@@ -829,6 +865,10 @@ function createTableBuilder(tableName, client) {
           resource_id: resourceId,
           conditions: filters
         };
+        if (state.order) payload.sort_by = state.order;
+        if (state.currentPage !== void 0) payload.current_page = state.currentPage;
+        if (state.pageSize !== void 0) payload.page_size = state.pageSize;
+        if (state.totalPages !== void 0) payload.total_pages = state.totalPages;
         if (columns) payload.columns = columns;
         const response = await client.deleteGateway(payload, mergedOptions);
         return formatResult(response);
@@ -964,10 +1004,334 @@ var Backend = {
   ScyllaDB: { type: "scylladb" }
 };
 
+// src/auxiliaries.ts
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function safeStringify(value) {
+  try {
+    const serialized = JSON.stringify(value);
+    return serialized ?? String(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+function contextHint(context) {
+  if (!context?.identity) return void 0;
+  const identity = typeof context.identity === "string" ? context.identity : safeStringify(context.identity);
+  return `Identity: ${identity}`;
+}
+function isAthenaResultLike(value) {
+  return isRecord2(value) && "status" in value && "error" in value && "data" in value && typeof value.status === "number";
+}
+function operationFromDetails(details) {
+  if (!details?.endpoint) return void 0;
+  if (details.endpoint === "/gateway/fetch" || details.endpoint === "/gateway/query") return "select";
+  if (details.endpoint === "/gateway/insert") return "insert";
+  if (details.endpoint === "/gateway/update") return "update";
+  if (details.endpoint === "/gateway/delete") return "delete";
+  if (details.endpoint === "/gateway/rpc" || details.endpoint.startsWith("/rpc/")) return "rpc";
+  return void 0;
+}
+function matchRegex(input, patterns) {
+  for (const pattern of patterns) {
+    const match = pattern.exec(input);
+    if (match?.[1]) return match[1];
+  }
+  return void 0;
+}
+function extractConstraint(message) {
+  return matchRegex(message, [
+    /unique constraint\s+["'`]([^"'`]+)["'`]/i,
+    /constraint\s+["'`]([^"'`]+)["'`]/i
+  ]);
+}
+function extractTable(message) {
+  return matchRegex(message, [
+    /(?:table|relation)\s+["'`]([^"'`]+)["'`]/i,
+    /on\s+table\s+([a-zA-Z0-9_.]+)/i
+  ]);
+}
+function classifyKind(status, code, message) {
+  const lower = message.toLowerCase();
+  const hasUniquePattern = lower.includes("unique constraint") || lower.includes("duplicate key") || lower.includes("already exists") || lower.includes("duplicate");
+  const hasNotFoundPattern = lower.includes("not found") || lower.includes("no rows");
+  const hasValidationPattern = lower.includes("validation") || lower.includes("invalid") || lower.includes("malformed");
+  const hasAuthPattern = lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("auth");
+  const hasRateLimitPattern = lower.includes("rate limit") || lower.includes("too many requests");
+  const hasTransientPattern = lower.includes("timeout") || lower.includes("temporar") || lower.includes("connection reset") || lower.includes("socket") || lower.includes("deadlock");
+  if (status === 409 || hasUniquePattern) return "unique_violation";
+  if (status === 404 || hasNotFoundPattern) return "not_found";
+  if (status === 401 || status === 403 || hasAuthPattern) return "auth";
+  if (status === 429 || hasRateLimitPattern) return "rate_limit";
+  if (status === 400 || status === 422 || hasValidationPattern) return "validation";
+  if (code === "NETWORK_ERROR" || status === 0 || status !== void 0 && status >= 500 || hasTransientPattern) {
+    return "transient";
+  }
+  return "unknown";
+}
+function toGatewayCode(kind, status) {
+  if (kind === "transient" && (status === 0 || status === void 0)) return "NETWORK_ERROR";
+  if (kind === "validation") return "INVALID_JSON";
+  if (status !== void 0 && status >= 400) return "HTTP_ERROR";
+  return "UNKNOWN_ERROR";
+}
+function toAthenaGatewayError(source, fallbackMessage, context) {
+  if (isAthenaGatewayError(source)) {
+    return source;
+  }
+  if (isAthenaResultLike(source) && source.errorDetails) {
+    return new AthenaGatewayError({
+      code: source.errorDetails.code,
+      message: source.error ?? source.errorDetails.message,
+      status: source.status,
+      endpoint: source.errorDetails.endpoint,
+      method: source.errorDetails.method,
+      requestId: source.errorDetails.requestId,
+      hint: source.errorDetails.hint,
+      cause: source.errorDetails.cause
+    });
+  }
+  const normalized = normalizeAthenaError(source, context);
+  const message = isAthenaResultLike(source) && source.error == null && source.errorDetails == null ? fallbackMessage : normalized.message || fallbackMessage;
+  return new AthenaGatewayError({
+    code: toGatewayCode(normalized.kind, normalized.status),
+    message,
+    status: normalized.status ?? 0,
+    hint: normalized.constraint != null ? `Constraint: ${normalized.constraint}` : contextHint(context),
+    cause: typeof normalized.raw === "string" ? normalized.raw : safeStringify(normalized.raw)
+  });
+}
+function isOk(result) {
+  return result.error == null && result.status >= 200 && result.status < 300;
+}
+function normalizeAthenaError(resultOrError, context) {
+  if (isAthenaResultLike(resultOrError)) {
+    const details = resultOrError.errorDetails;
+    const message2 = resultOrError.error ?? details?.message ?? `Athena ${context?.operation ?? operationFromDetails(details) ?? "request"} failed`;
+    const operation = context?.operation ?? operationFromDetails(details);
+    const table = context?.table ?? extractTable(message2);
+    const constraint = extractConstraint(message2);
+    const kind = classifyKind(resultOrError.status, details?.code, message2);
+    return {
+      kind,
+      status: resultOrError.status,
+      constraint,
+      table,
+      operation,
+      message: message2,
+      raw: resultOrError.raw
+    };
+  }
+  if (isAthenaGatewayError(resultOrError)) {
+    const details = resultOrError.toDetails();
+    const operation = context?.operation ?? operationFromDetails(details);
+    const table = context?.table ?? extractTable(resultOrError.message);
+    const constraint = extractConstraint(resultOrError.message);
+    const kind = classifyKind(resultOrError.status, resultOrError.code, resultOrError.message);
+    return {
+      kind,
+      status: resultOrError.status,
+      constraint,
+      table,
+      operation,
+      message: resultOrError.message,
+      raw: resultOrError
+    };
+  }
+  if (resultOrError instanceof Error) {
+    const maybeStatus = isRecord2(resultOrError) && typeof resultOrError.status === "number" ? resultOrError.status : void 0;
+    return {
+      kind: classifyKind(maybeStatus, void 0, resultOrError.message),
+      status: maybeStatus,
+      constraint: extractConstraint(resultOrError.message),
+      table: context?.table ?? extractTable(resultOrError.message),
+      operation: context?.operation,
+      message: resultOrError.message,
+      raw: resultOrError
+    };
+  }
+  const message = typeof resultOrError === "string" ? resultOrError : "Unknown Athena error";
+  return {
+    kind: classifyKind(void 0, void 0, message),
+    status: void 0,
+    constraint: extractConstraint(message),
+    table: context?.table ?? extractTable(message),
+    operation: context?.operation,
+    message,
+    raw: resultOrError
+  };
+}
+function unwrapRows(result, options) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(result, "Athena request failed", options?.context);
+  }
+  if (result.data == null) return [];
+  return Array.isArray(result.data) ? result.data : [result.data];
+}
+function unwrap(result, options) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(result, "Athena request failed", options?.context);
+  }
+  if (result.data == null && !options?.allowNull) {
+    throw toAthenaGatewayError(result, "Expected data but received null", options?.context);
+  }
+  return result.data;
+}
+function unwrapOne(result, options) {
+  const rows = unwrapRows(result, options);
+  if (!rows.length) {
+    if (options?.allowNull) return null;
+    throw toAthenaGatewayError(result, "Expected one row but received none", options?.context);
+  }
+  if (options?.requireExactlyOne && rows.length !== 1) {
+    throw toAthenaGatewayError(
+      result,
+      `Expected exactly one row but received ${rows.length}`,
+      options.context
+    );
+  }
+  return rows[0];
+}
+function requireSuccess(result, context) {
+  if (!isOk(result)) {
+    throw toAthenaGatewayError(
+      result,
+      `Athena ${context?.operation ?? "request"} failed`,
+      context
+    );
+  }
+  return result;
+}
+function requireAffected(result, options, context) {
+  requireSuccess(result, context);
+  const minimum = options?.min ?? 1;
+  const count = result.count;
+  if (count == null) {
+    throw new AthenaGatewayError({
+      code: "UNKNOWN_ERROR",
+      status: result.status,
+      message: "Expected affected row count but response.count is missing",
+      hint: 'Set call option { count: "exact" } for mutation postcondition checks.',
+      cause: safeStringify(result.raw)
+    });
+  }
+  if (count < minimum) {
+    throw new AthenaGatewayError({
+      code: "UNKNOWN_ERROR",
+      status: result.status,
+      message: `Expected at least ${minimum} affected rows but received ${count}`,
+      hint: contextHint(context),
+      cause: safeStringify(result.raw)
+    });
+  }
+  return count;
+}
+function applyBounds(value, options) {
+  if (options?.min !== void 0 && value < options.min) return null;
+  if (options?.max !== void 0 && value > options.max) return null;
+  return value;
+}
+function parseIntegerString(value) {
+  const normalized = value.trim();
+  if (!/^[-+]?\d+$/.test(normalized)) return null;
+  const parsed = Number(normalized);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) return null;
+  return parsed;
+}
+function coerceInt(value, options) {
+  if (value == null) return null;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) return null;
+    return applyBounds(value, options);
+  }
+  if (typeof value === "string") {
+    const parsed = parseIntegerString(value);
+    if (parsed == null) return null;
+    return applyBounds(parsed, options);
+  }
+  if (typeof value === "bigint") {
+    if (options?.strictBigInt) {
+      if (value > BigInt(Number.MAX_SAFE_INTEGER) || value < BigInt(Number.MIN_SAFE_INTEGER)) {
+        return null;
+      }
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || !Number.isInteger(parsed)) return null;
+    return applyBounds(parsed, options);
+  }
+  return null;
+}
+function assertInt(value, label = "value", options) {
+  const parsed = coerceInt(value, options);
+  if (parsed == null) {
+    throw new TypeError(`${label} must be a finite integer`);
+  }
+  return parsed;
+}
+function defaultShouldRetry(error) {
+  const normalized = normalizeAthenaError(error);
+  return normalized.kind === "transient" || normalized.kind === "rate_limit";
+}
+function computeDelayMs(attempt, error, config) {
+  const baseDelay = config.baseDelayMs;
+  const rawDelay = typeof config.backoff === "function" ? config.backoff(attempt, error) : config.backoff === "linear" ? baseDelay * attempt : baseDelay * Math.pow(2, attempt - 1);
+  const safeDelay = Number.isFinite(rawDelay) ? Math.max(0, rawDelay) : 0;
+  const clamped = Math.min(config.maxDelayMs, safeDelay);
+  const jitterFactor = typeof config.jitter === "number" ? Math.max(0, Math.min(1, config.jitter)) : config.jitter ? 0.2 : 0;
+  if (!jitterFactor) return clamped;
+  const deviation = clamped * jitterFactor;
+  const offset = (Math.random() * 2 - 1) * deviation;
+  return Math.max(0, clamped + offset);
+}
+function sleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function withRetry(config, fn) {
+  const retries = Math.max(0, Math.trunc(config.retries));
+  const shouldRetry = config.shouldRetry ?? defaultShouldRetry;
+  const resolvedConfig = {
+    baseDelayMs: config.baseDelayMs ?? 100,
+    maxDelayMs: config.maxDelayMs ?? 1e4,
+    backoff: config.backoff ?? "exponential",
+    jitter: config.jitter ?? false
+  };
+  for (let attempts = 0; attempts <= retries; attempts += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (attempts >= retries) {
+        throw error;
+      }
+      const currentAttempt = attempts + 1;
+      const retry = await shouldRetry(error, currentAttempt);
+      if (!retry) {
+        throw error;
+      }
+      const delay = computeDelayMs(currentAttempt, error, resolvedConfig);
+      await sleep(delay);
+    }
+  }
+  throw new Error("withRetry reached an unexpected state");
+}
+
 exports.AthenaClient = AthenaClient;
 exports.AthenaGatewayError = AthenaGatewayError;
 exports.Backend = Backend;
+exports.assertInt = assertInt;
+exports.coerceInt = coerceInt;
 exports.createClient = createClient;
 exports.isAthenaGatewayError = isAthenaGatewayError;
+exports.isOk = isOk;
+exports.normalizeAthenaError = normalizeAthenaError;
+exports.requireAffected = requireAffected;
+exports.requireSuccess = requireSuccess;
+exports.unwrap = unwrap;
+exports.unwrapOne = unwrapOne;
+exports.unwrapRows = unwrapRows;
+exports.withRetry = withRetry;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map