@xylex-group/athena 1.2.1 → 1.4.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `1.2.1`
+current version: `1.4.0`
 `@xylex-group/athena` is a database driver and API gateway SDK that lets you interact with SQL backends over HTTP through a fluent builder API. It ships a typed query builder for Node.js / server environments and a React hook for client-side use.
 
 ## Install
@@ -43,9 +43,94 @@ if (error) {
 }
 ```
 
-Every query resolves to `{ data, error, errorDetails?, status, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
-
-For richer handling, inspect `errorDetails` (`code`, `status`, `endpoint`, `method`, `requestId`, etc.) or use `AthenaGatewayError` / `isAthenaGatewayError` from the package exports.
+Every query resolves to `{ data, error, errorDetails?, status, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
+
+For richer handling, inspect `errorDetails` (`code`, `status`, `endpoint`, `method`, `requestId`, etc.) or use `AthenaGatewayError` / `isAthenaGatewayError` from the package exports.
+
+## Reliability helper APIs
+
+The SDK exports composable helpers to reduce repetitive route-handler logic.
+
+### Result unwrapping and success guards
+
+```ts
+import {
+  isOk,
+  unwrap,
+  unwrapRows,
+  unwrapOne,
+  requireSuccess,
+  requireAffected,
+} from "@xylex-group/athena";
+
+const result = await athena.from("users").select("id,name");
+
+if (isOk(result)) {
+  const rows = unwrapRows(result); // typed User[]
+  console.log(rows.length);
+}
+
+const one = await athena.from("users").eq("id", 1).single("id,name");
+const user = unwrapOne(one, { allowNull: true });
+
+const inserted = await athena
+  .from("users")
+  .insert({ name: "Alice" })
+  .select("id", { count: "exact" });
+
+requireSuccess(inserted, { table: "users", operation: "insert" });
+requireAffected(inserted, { min: 1 }, { table: "users", operation: "insert" });
+```
+
+`requireAffected` uses `result.count`; request it on writes with `{ count: "exact" }` when you need enforced postconditions.
+
+### Error normalization
+
+```ts
+import { normalizeAthenaError } from "@xylex-group/athena";
+
+const result = await athena.from("users").insert({ id: 1 }).select();
+if (result.error) {
+  const err = normalizeAthenaError(result, {
+    table: "users",
+    operation: "insert",
+  });
+  if (err.kind === "unique_violation") {
+    // deterministic conflict handling
+  }
+}
+```
+
+Normalized errors expose stable `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
+
+### Numeric coercion
+
+```ts
+import { coerceInt, assertInt } from "@xylex-group/athena";
+
+const maybeCaseId = coerceInt(req.query.case_id, { min: 1 });
+if (maybeCaseId == null) throw new Error("Invalid case id");
+
+const caseId = assertInt(req.query.case_id, "case_id", { min: 1 });
+```
+
+### Retry helper
+
+```ts
+import { withRetry } from "@xylex-group/athena";
+
+const result = await withRetry(
+  {
+    retries: 3,
+    backoff: "exponential",
+    baseDelayMs: 100,
+    jitter: true,
+  },
+  () => athena.from("users").select("id,name"),
+);
+```
+
+By default, retries target transient/rate-limit failures; use `shouldRetry` for custom policies.
 
 ## Query builder
 
@@ -64,48 +149,107 @@ const { data } = await athena.from<User>("users").select("id, name");
 
 ### Filters
 
-Filters accumulate on the builder and are sent together when the query executes.
-
-```ts
-const { data } = await athena
+Filters accumulate on the builder and are sent together when the query executes.
+
+```ts
+const { data } = await athena
   .from("characters")
   .select("id, name")
-  .eq("active", true)           // column = value
-  .neq("role", "guest")         // column != value
-  .gt("level", 5)               // column > value
-  .gte("score", 100)            // column >= value
-  .lt("age", 30)                // column < value
+  .eq("active", true) // column = value
+  .neq("role", "guest") // column != value
+  .gt("level", 5) // column > value
+  .gte("score", 100) // column >= value
+  .lt("age", 30) // column < value
   .lte("created_at", "2024-01-01") // column <= value
-  .like("name", "Ali%")         // SQL LIKE (case-sensitive)
+  .like("name", "Ali%") // SQL LIKE (case-sensitive)
   .ilike("email", "%@example%") // SQL ILIKE (case-insensitive)
-  .is("deleted_at", null)       // IS NULL / IS TRUE etc.
-  .in("status", ["active", "pending"])    // IN (…)
-  .contains("tags", ["hero"])             // array contains value
+  .is("deleted_at", null) // IS NULL / IS TRUE etc.
+  .in("status", ["active", "pending"]) // IN (…)
+  .contains("tags", ["hero"]) // array contains value
   .containedBy("tags", ["hero", "villain"]) // array is subset of value
   .match({ role: "admin", active: true }) // multiple eq filters at once
-  .not("role", "eq", "banned")  // NOT col op val
-  .or("status.eq.active,status.eq.pending"); // OR expression
-```
-
-Canonical style for reads is to call `.select(...)` first, then apply filters:
-
-```ts
-const { data } = await athena
-  .from("instruments")
-  .select("name, section_id")
-  .eq("name", "violin");
-```
+  .not("role", "eq", "banned") // NOT col op val
+  .or("status.eq.active,status.eq.pending"); // OR expression
+```
+
+Canonical style for reads is to call `.select(...)` first, then apply filters:
+
+```ts
+const { data } = await athena
+  .from("instruments")
+  .select("name, section_id")
+  .eq("name", "violin");
+```
 
 ### Pagination
 
+Two styles, pick whichever matches your UI / backend. Both live on the shared `FilterChain`, so they work before or after `.select()`.
+
 ```ts
-// explicit limit and offset
+// 1. offset / limit — contiguous windows
 const { data } = await athena.from("users").select().limit(25).offset(50);
 
-// range shorthand — equivalent to offset(from).limit(to - from + 1)
-const { data } = await athena.from("users").select().range(0, 24);
+// range shorthand: offset = from, limit = to - from + 1
+const { data: firstTwentyFive } = await athena.from("users").select().range(0, 24);
+
+// 2. page based — maps to current_page / page_size / total_pages
+const { data: page2 } = await athena
+  .from("orders")
+  .select("id, total")
+  .currentPage(2)
+  .pageSize(25);
+
+// .totalPages() is an optional hint some backends use in the response envelope
+const { data: hinted } = await athena
+  .from("orders")
+  .select("id, total")
+  .currentPage(1)
+  .pageSize(25)
+  .totalPages(10);
 ```
 
+| Method | Body field |
+|--------|------------|
+| `.limit(n)` | `limit` |
+| `.offset(n)` | `offset` |
+| `.range(from, to)` | `offset` + `limit` |
+| `.currentPage(n)` | `current_page` |
+| `.pageSize(n)` | `page_size` |
+| `.totalPages(n)` | `total_pages` |
+
+### Ordering
+
+`.order(column, { ascending? })` is available on the table builder, select chain, update chain, and delete — before or after the operation terminator. It serializes to `sort_by: { field, direction }` on the gateway payload and defaults to ascending.
+
+```ts
+// descending + limit
+// SELECT * FROM rsf_messages WHERE room_id = $1 ORDER BY created_at DESC LIMIT 100
+const { data } = await athena
+  .from("rsf_messages")
+  .eq("room_id", roomId)
+  .select("*", { stripNulls: false })
+  .order("created_at", { ascending: false })
+  .limit(100);
+
+// ascending (default) + page-based pagination
+const { data: page } = await athena
+  .from("orders")
+  .select("id, total, created_at")
+  .order("created_at")
+  .currentPage(1)
+  .pageSize(25);
+
+// combine with .single() to grab the newest / oldest row
+const { data: latest } = await athena
+  .from("messages")
+  .eq("room_id", roomId)
+  .select("*")
+  .order("created_at", { ascending: false })
+  .single();
+```
+
+Only the last `.order()` wins — the SDK does not support multi-column ordering on the table builder. Use `.rpc()` or `.query()` for that.
+
 ### Single row
 
 ```ts
@@ -119,40 +263,47 @@ const { data: user } = await athena
 
 `maybeSingle` behaves identically — both return the first element of the result set.
 
-### RPC
-
-Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
-
-```ts
-const { data, count } = await athena
-  .rpc("list_users", { role: "admin" }, { count: "exact", schema: "public" })
-  .eq("active", true)
-  .order("created_at", { ascending: false })
-  .range(0, 24)
-  .select(["id", "email"]);
-
-const { data: firstUser } = await athena
-  .rpc<{ id: number; email: string }>("list_users", { role: "admin" })
-  .single("id,email");
-
-const { data: readOnlyUser } = await athena
-  .rpc<{ id: number; email: string }>("list_users", { role: "admin" }, { get: true, count: "planned", head: true })
-  .eq("id", 1)
-  .single("id,email");
-```
-
-RPC chain methods: `.eq()`, `.neq()`, `.gt()`, `.gte()`, `.lt()`, `.lte()`, `.like()`, `.ilike()`, `.is()`, `.in()`, `.order()`, `.limit()`, `.offset()`, `.range()`, `.select()`, `.single()`, `.maybeSingle()`.
-RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `get`.
-
-### Options
+### RPC
+
+Use `athena.rpc(...)` for Postgres function calls. By default it calls `POST /gateway/rpc`, and with `{ get: true }` it uses the compatibility route `GET /rpc/{function_name}`.
+
+```ts
+const { data, count } = await athena
+  .rpc("list_users", { role: "admin" }, { count: "exact", schema: "public" })
+  .eq("active", true)
+  .order("created_at", { ascending: false })
+  .range(0, 24)
+  .select(["id", "email"]);
+
+const { data: firstUser } = await athena
+  .rpc<{ id: number; email: string }>("list_users", { role: "admin" })
+  .single("id,email");
+
+const { data: readOnlyUser } = await athena
+  .rpc<{
+    id: number;
+    email: string;
+  }>(
+    "list_users",
+    { role: "admin" },
+    { get: true, count: "planned", head: true },
+  )
+  .eq("id", 1)
+  .single("id,email");
+```
+
+RPC chain methods: `.eq()`, `.neq()`, `.gt()`, `.gte()`, `.lt()`, `.lte()`, `.like()`, `.ilike()`, `.is()`, `.in()`, `.order()`, `.limit()`, `.offset()`, `.range()`, `.select()`, `.single()`, `.maybeSingle()`.
+RPC options: `schema`, `count` (`"exact" | "planned" | "estimated"`), `head`, `get`.
+
+### Options
 
 Pass options as the second argument to `.select()`:
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `count` | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data |
-| `head` | `boolean` | return response headers only (no rows) |
-| `stripNulls` | `boolean` | strip null values from rows (default `true`) |
+| Option       | Type                                  | Description                                  |
+| ------------ | ------------------------------------- | -------------------------------------------- |
+| `count`      | `"exact" \| "planned" \| "estimated"` | request a row count alongside the data       |
+| `head`       | `boolean`                             | return response headers only (no rows)       |
+| `stripNulls` | `boolean`                             | strip null values from rows (default `true`) |
 
 ```ts
 const { data } = await athena
@@ -178,9 +329,9 @@ const { data } = await athena
   .insert([{ name: "Frodo" }, { name: "Sam" }])
   .select();
 
-// Type inference differs by payload shape:
-// - insert(one) => AthenaResult<Row>
-// - insert(many) => AthenaResult<Row[]>
+// Type inference differs by payload shape:
+// - insert(one) => AthenaResult<Row>
+// - insert(many) => AthenaResult<Row[]>
 ```
 
 ### Update
@@ -206,18 +357,18 @@ const { data } = await athena
   )
   .select();
 
-// Type inference differs by payload shape:
-// - upsert(one) => AthenaResult<Row>
-// - upsert(many) => AthenaResult<Row[]>
+// Type inference differs by payload shape:
+// - upsert(one) => AthenaResult<Row>
+// - upsert(many) => AthenaResult<Row[]>
 ```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `onConflict` | `string \| string[]` | column(s) that determine a conflict |
-| `updateBody` | `object` | fields to apply when a conflict occurs |
-| `defaultToNull` | `boolean` | write explicit `null` for missing fields |
-| `count` | `"exact" \| "planned" \| "estimated"` | request a row count |
-| `head` | `boolean` | return headers only |
+| Option          | Type                                  | Description                              |
+| --------------- | ------------------------------------- | ---------------------------------------- |
+| `onConflict`    | `string \| string[]`                  | column(s) that determine a conflict      |
+| `updateBody`    | `object`                              | fields to apply when a conflict occurs   |
+| `defaultToNull` | `boolean`                             | write explicit `null` for missing fields |
+| `count`         | `"exact" \| "planned" \| "estimated"` | request a row count                      |
+| `head`          | `boolean`                             | return headers only                      |
 
 ### Delete
 
@@ -286,7 +437,7 @@ export function UsersPanel() {
 }
 ```
 
-The hook returns `fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `rpcGateway`, `isLoading`, `error`, `lastRequest`, `lastResponse`, and `baseUrl`.
+The hook returns `fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `rpcGateway`, `isLoading`, `error`, `lastRequest`, `lastResponse`, and `baseUrl`.
 
 Hook config options mirror the client options: `baseUrl`, `apiKey`, `headers`, `userId`, `organizationId`, `publishEvent`.
 
@@ -295,28 +446,40 @@ Hook config options mirror the client options: `baseUrl`, `apiKey`, `headers`, `
 Pass user and tenant context to every request without repeating it on each call:
 
 ```ts
-const athena = createClient("https://athena-db.com", process.env.ATHENA_API_KEY, {
-  headers: {
-    "X-User-Id": currentUser.id,
-    "X-Organization-Id": currentUser.organizationId ?? "",
+const athena = createClient(
+  "https://athena-db.com",
+  process.env.ATHENA_API_KEY,
+  {
+    headers: {
+      "X-User-Id": currentUser.id,
+      "X-Organization-Id": currentUser.organizationId ?? "",
+    },
   },
-});
+);
 ```
 
-Or pass per-call via options. The Athena server interprets `url` and `key` based on the configured backend type.
+Or pass per-call via options. The Athena server interprets `url` and `key` based on the configured backend type.
 
 ## Custom headers
 
 ```ts
-const athena = createClient("https://athena-db.com", process.env.ATHENA_API_KEY, {
-  headers: {
-    "X-Custom-Header": "value",
+const athena = createClient(
+  "https://athena-db.com",
+  process.env.ATHENA_API_KEY,
+  {
+    headers: {
+      "X-Custom-Header": "value",
+    },
   },
-});
+);
 ```
 
 Per-call headers are merged with the client-level headers, with per-call values winning on conflict.
 
+The SDK also sends a standard identification header on every request:
+
+- `X-Athena-Sdk: xylex-group/athena <version>`
+
 ## TypeScript
 
 The package is written in TypeScript and ships declaration files. Pass a row type to `.from()` for fully-typed builder methods and results:
@@ -329,7 +492,10 @@ interface User {
   active: boolean;
 }
 
-const { data } = await athena.from<User>("users").select("id, name").eq("active", true);
+const { data } = await athena
+  .from<User>("users")
+  .select("id, name")
+  .eq("active", true);
 // data is User[] | null
 ```
 

package/dist/{errors-DHmpYG46.d.cts → errors-CB-eJQ7x.d.cts}

@@ -17,6 +17,11 @@ interface AthenaGatewayCondition {
     eq_column?: string;
     eq_value?: AthenaConditionValue | AthenaConditionArrayValue | string;
 }
+type AthenaSortDirection = 'ascending' | 'descending';
+interface AthenaSortBy {
+    field: string;
+    direction: AthenaSortDirection;
+}
 interface AthenaFetchPayload {
     view_name?: string;
     table_name?: string;
@@ -33,6 +38,7 @@ interface AthenaFetchPayload {
     aggregation_column?: string;
     aggregation_strategy?: 'cumulative_sum';
     aggregation_dedup?: boolean;
+    sort_by?: AthenaSortBy;
 }
 interface AthenaInsertPayload {
     table_name: string;
@@ -49,6 +55,10 @@ interface AthenaDeletePayload {
     resource_id?: string;
     columns?: string[] | string;
     conditions?: AthenaGatewayCondition[];
+    sort_by?: AthenaSortBy;
+    current_page?: number;
+    page_size?: number;
+    total_pages?: number;
 }
 interface AthenaUpdatePayload extends AthenaFetchPayload {
     set?: Record<string, unknown>;

package/dist/{errors-DHmpYG46.d.ts → errors-CB-eJQ7x.d.ts}

@@ -17,6 +17,11 @@ interface AthenaGatewayCondition {
     eq_column?: string;
     eq_value?: AthenaConditionValue | AthenaConditionArrayValue | string;
 }
+type AthenaSortDirection = 'ascending' | 'descending';
+interface AthenaSortBy {
+    field: string;
+    direction: AthenaSortDirection;
+}
 interface AthenaFetchPayload {
     view_name?: string;
     table_name?: string;
@@ -33,6 +38,7 @@ interface AthenaFetchPayload {
     aggregation_column?: string;
     aggregation_strategy?: 'cumulative_sum';
     aggregation_dedup?: boolean;
+    sort_by?: AthenaSortBy;
 }
 interface AthenaInsertPayload {
     table_name: string;
@@ -49,6 +55,10 @@ interface AthenaDeletePayload {
     resource_id?: string;
     columns?: string[] | string;
     conditions?: AthenaGatewayCondition[];
+    sort_by?: AthenaSortBy;
+    current_page?: number;
+    page_size?: number;
+    total_pages?: number;
 }
 interface AthenaUpdatePayload extends AthenaFetchPayload {
     set?: Record<string, unknown>;