@xylex-group/athena 1.2.1 → 1.4.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions } from './errors-DHmpYG46.cjs';
-export { g as AthenaGatewayError, h as AthenaGatewayErrorCode, i as AthenaRpcFilter, j as AthenaRpcFilterOperator, k as AthenaRpcOrder, l as AthenaRpcPayload, m as Backend, n as isAthenaGatewayError } from './errors-DHmpYG46.cjs';
+import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions } from './errors-CB-eJQ7x.cjs';
+export { g as AthenaGatewayError, h as AthenaGatewayErrorCode, i as AthenaRpcFilter, j as AthenaRpcFilterOperator, k as AthenaRpcOrder, l as AthenaRpcPayload, m as Backend, n as isAthenaGatewayError } from './errors-CB-eJQ7x.cjs';
 
 interface AthenaResult<T> {
     data: T | null;
@@ -19,6 +19,9 @@ interface MutationQuery<Result> extends PromiseLike<AthenaResult<Result>> {
     catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | undefined | null): Promise<AthenaResult<Result> | TResult>;
     finally(onfinally?: (() => void) | undefined | null): Promise<AthenaResult<Result>>;
 }
+interface OrderOptions {
+    ascending?: boolean;
+}
 /** Shared filter chain - supports eq, limit, etc. in any order relative to select/update */
 interface FilterChain<Self> {
     eq(column: string, value: AthenaConditionValue): Self;
@@ -26,6 +29,10 @@ interface FilterChain<Self> {
     range(from: number, to: number): Self;
     limit(count: number): Self;
     offset(count: number): Self;
+    currentPage(value: number): Self;
+    pageSize(value: number): Self;
+    totalPages(value: number): Self;
+    order(column: string, options?: OrderOptions): Self;
     gt(column: string, value: AthenaConditionValue): Self;
     gte(column: string, value: AthenaConditionValue): Self;
     lt(column: string, value: AthenaConditionValue): Self;
@@ -123,4 +130,118 @@ declare class AthenaClient {
 /** Create client (convenience wrapper; use AthenaClient.builder() for full control) */
 declare function createClient(url: string, apiKey: string, options?: Pick<AthenaGatewayCallOptions, 'client' | 'headers' | 'backend'>): AthenaSdkClient;
 
-export { AthenaClient, AthenaGatewayCallOptions, AthenaGatewayErrorDetails, type AthenaResult, AthenaRpcCallOptions, type AthenaSdkClient, BackendConfig, BackendType, type RpcOrderOptions, type RpcQueryBuilder, type TableQueryBuilder, createClient };
+type AthenaErrorKind = 'unique_violation' | 'not_found' | 'validation' | 'auth' | 'rate_limit' | 'transient' | 'unknown';
+interface AthenaOperationContext {
+    table?: string;
+    operation?: string;
+    identity?: string | Record<string, unknown>;
+}
+interface NormalizedAthenaError {
+    kind: AthenaErrorKind;
+    status?: number;
+    constraint?: string;
+    table?: string;
+    operation?: string;
+    message: string;
+    raw: unknown;
+}
+interface UnwrapOptions {
+    allowNull?: boolean;
+    context?: AthenaOperationContext;
+}
+interface UnwrapOneOptions extends UnwrapOptions {
+    requireExactlyOne?: boolean;
+}
+interface IntCoercionOptions {
+    strictBigInt?: boolean;
+    min?: number;
+    max?: number;
+}
+type RetryBackoffStrategy = 'linear' | 'exponential' | ((attempt: number, error: unknown) => number);
+interface RetryConfig {
+    retries: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    backoff?: RetryBackoffStrategy;
+    jitter?: boolean | number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+}
+interface RequireAffectedOptions {
+    min?: number;
+}
+/**
+ * Returns `true` when a result is successful (`2xx` status and no `error`).
+ */
+declare function isOk<T>(result: AthenaResult<T>): boolean;
+/**
+ * Normalizes any Athena failure shape into a stable, typed error envelope.
+ *
+ * Accepts `AthenaResult`, `AthenaGatewayError`, native `Error`, or unknown values.
+ * Optional `context` can override inferred table/operation metadata for clearer diagnostics.
+ */
+declare function normalizeAthenaError(resultOrError: unknown, context?: AthenaOperationContext): NormalizedAthenaError;
+/**
+ * Unwraps a successful result into a row array.
+ *
+ * - Throws on failed results.
+ * - Converts `null` data to an empty array.
+ * - Wraps scalar data in a single-element array.
+ */
+declare function unwrapRows<T>(result: AthenaResult<T[] | T | null>, options?: UnwrapOptions): T[];
+/**
+ * Unwraps successful result data from `AthenaResult<T | null>`.
+ *
+ * By default, `null` data throws. Pass `{ allowNull: true }` to permit nullable payloads.
+ */
+declare function unwrap<T>(result: AthenaResult<T | null>, options: UnwrapOptions & {
+    allowNull: true;
+}): T | null;
+declare function unwrap<T>(result: AthenaResult<T | null>, options?: UnwrapOptions): T;
+/**
+ * Unwraps the first row from a successful result that may contain arrays/scalars/null.
+ *
+ * - Throws on failed results.
+ * - Throws when no row exists unless `allowNull: true` is provided.
+ * - Optionally enforces exact cardinality via `requireExactlyOne`.
+ */
+declare function unwrapOne<T>(result: AthenaResult<T[] | T | null>, options: UnwrapOneOptions & {
+    allowNull: true;
+}): T | null;
+declare function unwrapOne<T>(result: AthenaResult<T[] | T | null>, options?: UnwrapOneOptions): T;
+/**
+ * Asserts that an Athena result is successful.
+ *
+ * Returns the original result for fluent composition and throws `AthenaGatewayError` on failure.
+ */
+declare function requireSuccess<T>(result: AthenaResult<T>, context?: AthenaOperationContext): AthenaResult<T>;
+/**
+ * Enforces mutation postconditions based on `result.count`.
+ *
+ * - Validates success first.
+ * - Requires a non-null count in the response.
+ * - Validates `count >= min` (default: `1`).
+ *
+ * Useful for guaranteeing that critical writes actually affected rows.
+ */
+declare function requireAffected<T>(result: AthenaResult<T>, options?: RequireAffectedOptions, context?: AthenaOperationContext): number;
+/**
+ * Safely coerces `unknown` values into finite integers.
+ *
+ * Returns `null` when coercion fails or bounds/strict bigint checks are violated.
+ */
+declare function coerceInt(value: unknown, options?: IntCoercionOptions): number | null;
+/**
+ * Strict integer assertion wrapper around `coerceInt`.
+ *
+ * Throws a `TypeError` with the provided label when coercion fails.
+ */
+declare function assertInt(value: unknown, label?: string, options?: IntCoercionOptions): number;
+/**
+ * Retries an async operation with configurable backoff and retry policy.
+ *
+ * `retries` represents additional attempts after the first failure.
+ * By default, transient and rate-limit errors are retried.
+ */
+declare function withRetry<T>(config: RetryConfig, fn: () => Promise<T>): Promise<T>;
+
+export { AthenaClient, 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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions } from './errors-DHmpYG46.js';
-export { g as AthenaGatewayError, h as AthenaGatewayErrorCode, i as AthenaRpcFilter, j as AthenaRpcFilterOperator, k as AthenaRpcOrder, l as AthenaRpcPayload, m as Backend, n as isAthenaGatewayError } from './errors-DHmpYG46.js';
+import { B as BackendConfig, a as BackendType, A as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator, d as AthenaGatewayCallOptions, e as AthenaGatewayErrorDetails, f as AthenaRpcCallOptions } from './errors-CB-eJQ7x.js';
+export { g as AthenaGatewayError, h as AthenaGatewayErrorCode, i as AthenaRpcFilter, j as AthenaRpcFilterOperator, k as AthenaRpcOrder, l as AthenaRpcPayload, m as Backend, n as isAthenaGatewayError } from './errors-CB-eJQ7x.js';
 
 interface AthenaResult<T> {
     data: T | null;
@@ -19,6 +19,9 @@ interface MutationQuery<Result> extends PromiseLike<AthenaResult<Result>> {
     catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | undefined | null): Promise<AthenaResult<Result> | TResult>;
     finally(onfinally?: (() => void) | undefined | null): Promise<AthenaResult<Result>>;
 }
+interface OrderOptions {
+    ascending?: boolean;
+}
 /** Shared filter chain - supports eq, limit, etc. in any order relative to select/update */
 interface FilterChain<Self> {
     eq(column: string, value: AthenaConditionValue): Self;
@@ -26,6 +29,10 @@ interface FilterChain<Self> {
     range(from: number, to: number): Self;
     limit(count: number): Self;
     offset(count: number): Self;
+    currentPage(value: number): Self;
+    pageSize(value: number): Self;
+    totalPages(value: number): Self;
+    order(column: string, options?: OrderOptions): Self;
     gt(column: string, value: AthenaConditionValue): Self;
     gte(column: string, value: AthenaConditionValue): Self;
     lt(column: string, value: AthenaConditionValue): Self;
@@ -123,4 +130,118 @@ declare class AthenaClient {
 /** Create client (convenience wrapper; use AthenaClient.builder() for full control) */
 declare function createClient(url: string, apiKey: string, options?: Pick<AthenaGatewayCallOptions, 'client' | 'headers' | 'backend'>): AthenaSdkClient;
 
-export { AthenaClient, AthenaGatewayCallOptions, AthenaGatewayErrorDetails, type AthenaResult, AthenaRpcCallOptions, type AthenaSdkClient, BackendConfig, BackendType, type RpcOrderOptions, type RpcQueryBuilder, type TableQueryBuilder, createClient };
+type AthenaErrorKind = 'unique_violation' | 'not_found' | 'validation' | 'auth' | 'rate_limit' | 'transient' | 'unknown';
+interface AthenaOperationContext {
+    table?: string;
+    operation?: string;
+    identity?: string | Record<string, unknown>;
+}
+interface NormalizedAthenaError {
+    kind: AthenaErrorKind;
+    status?: number;
+    constraint?: string;
+    table?: string;
+    operation?: string;
+    message: string;
+    raw: unknown;
+}
+interface UnwrapOptions {
+    allowNull?: boolean;
+    context?: AthenaOperationContext;
+}
+interface UnwrapOneOptions extends UnwrapOptions {
+    requireExactlyOne?: boolean;
+}
+interface IntCoercionOptions {
+    strictBigInt?: boolean;
+    min?: number;
+    max?: number;
+}
+type RetryBackoffStrategy = 'linear' | 'exponential' | ((attempt: number, error: unknown) => number);
+interface RetryConfig {
+    retries: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    backoff?: RetryBackoffStrategy;
+    jitter?: boolean | number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+}
+interface RequireAffectedOptions {
+    min?: number;
+}
+/**
+ * Returns `true` when a result is successful (`2xx` status and no `error`).
+ */
+declare function isOk<T>(result: AthenaResult<T>): boolean;
+/**
+ * Normalizes any Athena failure shape into a stable, typed error envelope.
+ *
+ * Accepts `AthenaResult`, `AthenaGatewayError`, native `Error`, or unknown values.
+ * Optional `context` can override inferred table/operation metadata for clearer diagnostics.
+ */
+declare function normalizeAthenaError(resultOrError: unknown, context?: AthenaOperationContext): NormalizedAthenaError;
+/**
+ * Unwraps a successful result into a row array.
+ *
+ * - Throws on failed results.
+ * - Converts `null` data to an empty array.
+ * - Wraps scalar data in a single-element array.
+ */
+declare function unwrapRows<T>(result: AthenaResult<T[] | T | null>, options?: UnwrapOptions): T[];
+/**
+ * Unwraps successful result data from `AthenaResult<T | null>`.
+ *
+ * By default, `null` data throws. Pass `{ allowNull: true }` to permit nullable payloads.
+ */
+declare function unwrap<T>(result: AthenaResult<T | null>, options: UnwrapOptions & {
+    allowNull: true;
+}): T | null;
+declare function unwrap<T>(result: AthenaResult<T | null>, options?: UnwrapOptions): T;
+/**
+ * Unwraps the first row from a successful result that may contain arrays/scalars/null.
+ *
+ * - Throws on failed results.
+ * - Throws when no row exists unless `allowNull: true` is provided.
+ * - Optionally enforces exact cardinality via `requireExactlyOne`.
+ */
+declare function unwrapOne<T>(result: AthenaResult<T[] | T | null>, options: UnwrapOneOptions & {
+    allowNull: true;
+}): T | null;
+declare function unwrapOne<T>(result: AthenaResult<T[] | T | null>, options?: UnwrapOneOptions): T;
+/**
+ * Asserts that an Athena result is successful.
+ *
+ * Returns the original result for fluent composition and throws `AthenaGatewayError` on failure.
+ */
+declare function requireSuccess<T>(result: AthenaResult<T>, context?: AthenaOperationContext): AthenaResult<T>;
+/**
+ * Enforces mutation postconditions based on `result.count`.
+ *
+ * - Validates success first.
+ * - Requires a non-null count in the response.
+ * - Validates `count >= min` (default: `1`).
+ *
+ * Useful for guaranteeing that critical writes actually affected rows.
+ */
+declare function requireAffected<T>(result: AthenaResult<T>, options?: RequireAffectedOptions, context?: AthenaOperationContext): number;
+/**
+ * Safely coerces `unknown` values into finite integers.
+ *
+ * Returns `null` when coercion fails or bounds/strict bigint checks are violated.
+ */
+declare function coerceInt(value: unknown, options?: IntCoercionOptions): number | null;
+/**
+ * Strict integer assertion wrapper around `coerceInt`.
+ *
+ * Throws a `TypeError` with the provided label when coercion fails.
+ */
+declare function assertInt(value: unknown, label?: string, options?: IntCoercionOptions): number;
+/**
+ * Retries an async operation with configurable backoff and retry policy.
+ *
+ * `retries` represents additional attempts after the first failure.
+ * By default, transient and rate-limit errors are retried.
+ */
+declare function withRetry<T>(config: RetryConfig, fn: () => Promise<T>): Promise<T>;
+
+export { AthenaClient, 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 };