@xylex-group/athena 2.3.0 → 2.4.0

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `2.3.0`
+current version: `2.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 plus Athena-native React hooks for client-side use.
 
 ## Install
@@ -24,36 +24,36 @@ npm install react  # React >=17 required for the hook
 ```ts
 import { createClient } from "@xylex-group/athena";
 
-const athenaClient = createClient(ATHENA_URL, ATHENA_API_KEY, {
-  client: "CLIENT_NAME",
-  backend: { type: "athena" },
-});
-
-const { data, error } = await athenaClient.from("orchestral_sections").findMany({
-  select: {
-    name: true,
-    instruments: {
-      select: {
-        name: true,
-      },
-    },
-  },
-});
-
-if (error) {
-  console.error("gateway error", error);
-} else {
-  console.table(data);
-}
-```
-
-Example version baseline: SDK `@xylex-group/athena` `2.3.0`, Athena server `3.12.3` verified on 2026-06-04.
-
-`.findMany({ select, where, orderBy, limit })` is the clean canonical read surface.
-The existing string-based `.select(...)` chain remains fully supported for compatibility,
-including alias/FK patterns like `from:sender_id(name)`.
-For the full AST model, route contract, error behavior, and Athena server implications,
-see [`docs/findmany-ast-and-server-contract.md`](docs/findmany-ast-and-server-contract.md).
+const athenaClient = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  client: "CLIENT_NAME",
+  backend: { type: "athena" },
+});
+
+const { data, error } = await athenaClient.from("orchestral_sections").findMany({
+  select: {
+    name: true,
+    instruments: {
+      select: {
+        name: true,
+      },
+    },
+  },
+});
+
+if (error) {
+  console.error("gateway error", error);
+} else {
+  console.table(data);
+}
+```
+
+Example version baseline: SDK `@xylex-group/athena` `2.4.0`, Athena server `3.12.3` verified on 2026-06-04.
+
+`.findMany({ select, where, orderBy, limit })` is the clean canonical read surface.
+The existing string-based `.select(...)` chain remains fully supported for compatibility,
+including alias/FK patterns like `from:sender_id(name)`.
+For the full AST model, route contract, error behavior, and Athena server implications,
+see [`docs/findmany-ast-and-server-contract.md`](docs/findmany-ast-and-server-contract.md).
 
 ### Auth client (Athena Auth server)
 
@@ -245,19 +245,19 @@ For prompt-ready documentation handoff text, see [`docs/generator-codex-handoff-
 - `athena-rs` for Rust backend throughput
 - `athena-js` for app/tooling layers that need TypeScript contracts and frontend-facing ergonomics
 
-Every query resolves to `{ data, error, errorDetails?, status, statusText?, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
-
-Failed results now include a structured `error` object with the useful fields inline:
-
-- `message`
-- `code`
-- `details`
-- `hint`
-- `status`
-- `statusText`
-- normalized metadata such as `kind`, `table`, `operation`, and `retryable`
-
-`errorDetails` is still present as a compatibility alias for low-level gateway metadata (`gatewayCode`, `endpoint`, `method`, `requestId`, etc.).
+Every query resolves to `{ data, error, errorDetails?, status, statusText?, count?, raw }`. `data` is `null` on error; `error` is `null` on success.
+
+Failed results now include a structured `error` object with the useful fields inline:
+
+- `message`
+- `code`
+- `details`
+- `hint`
+- `status`
+- `statusText`
+- normalized metadata such as `kind`, `table`, `operation`, and `retryable`
+
+`errorDetails` is still present as a compatibility alias for low-level gateway metadata (`gatewayCode`, `endpoint`, `method`, `requestId`, etc.).
 
 ## Reliability helper APIs
 
@@ -296,26 +296,26 @@ requireAffected(inserted, { min: 1 }, { table: "users", operation: "insert" });
 
 `requireAffected` uses `result.count`; request it on writes with `{ count: "exact" }` when you need enforced postconditions.
 
-### Structured errors by default
-
-```ts
-import { createClient, normalizeAthenaError } from "@xylex-group/athena";
-
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
-
-const { data, error, status, statusText } = await athena.from("users").insert({ id: 1 }).select();
-if (error) {
-  console.error(error);
-  console.error(error.hint ?? error.message, status, statusText);
-  if (error.kind === "unique_violation") {
-    // deterministic conflict handling
-  }
-}
-```
-
-`result.error` already carries normalized `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
-
-`normalizeAthenaError(result)` still exists when you need the normalized envelope from an arbitrary thrown value or mixed unknown input.
+### Structured errors by default
+
+```ts
+import { createClient, normalizeAthenaError } from "@xylex-group/athena";
+
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
+
+const { data, error, status, statusText } = await athena.from("users").insert({ id: 1 }).select();
+if (error) {
+  console.error(error);
+  console.error(error.hint ?? error.message, status, statusText);
+  if (error.kind === "unique_violation") {
+    // deterministic conflict handling
+  }
+}
+```
+
+`result.error` already carries normalized `kind` values (`unique_violation`, `validation`, `auth`, `rate_limit`, `transient`, etc.) plus operation metadata.
+
+`normalizeAthenaError(result)` still exists when you need the normalized envelope from an arbitrary thrown value or mixed unknown input.
 
 ### Query tracing (experimental)
 
@@ -325,49 +325,49 @@ const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
 });
 ```
 
-With `traceQueries: true`, the SDK logs every runtime execution (`select`, `insert`, `upsert`, `update`, `delete`, `rpc`, `query`) and includes:
-
-- the gateway endpoint used
-- synthesized SQL (or raw SQL for `query(...)` and SQL fallback reads)
-- payload and call options
-- full outcome (`status`, `error`, `count`, `data`, `raw`)
-- callsite metadata (`filePath`, `fileName`, `line`, `column`)
-
-For deferred chains, Athena captures that callsite from the public SDK seam that declared or finalized the operation and reuses it for the eventual network execution. That keeps traces pinned to user code instead of drifting into SDK internals when async stack shapes differ between local runs and CI.
+With `traceQueries: true`, the SDK logs every runtime execution (`select`, `insert`, `upsert`, `update`, `delete`, `rpc`, `query`) and includes:
+
+- the gateway endpoint used
+- synthesized SQL (or raw SQL for `query(...)` and SQL fallback reads)
+- payload and call options
+- full outcome (`status`, `error`, `count`, `data`, `raw`)
+- callsite metadata (`filePath`, `fileName`, `line`, `column`)
+
+For deferred chains, Athena captures that callsite from the public SDK seam that declared or finalized the operation and reuses it for the eventual network execution. That keeps traces pinned to user code instead of drifting into SDK internals when async stack shapes differ between local runs and CI.
 
 Use a custom sink:
 
-```ts
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
-  experimental: {
-    traceQueries: {
-      logger(event) {
-        // Forward into your logger/observability sink
-        console.log(event.operation, event.endpoint, event.sql, event.callsite);
-      },
-    },
-  },
-});
-```
-
-### findMany AST transport (experimental)
-
-```ts
-const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
-  experimental: {
-    findManyAst: true,
-  },
-});
-```
-
-With `findManyAst: true`, clean `findMany(...)` calls send the original object AST body to `/gateway/fetch` instead of compiling the select tree down to `columns` and `conditions` first.
-
-- this is opt-in and meant for gateways that explicitly support direct AST bodies
-- existing compiled `findMany(...)` transport remains the default
-- chained builder filters or pagination state that the AST body cannot represent losslessly yet continue to use the legacy compiled path
-- trace output still includes synthesized SQL so diagnostics stay readable
-
-### Numeric coercion
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: {
+    traceQueries: {
+      logger(event) {
+        // Forward into your logger/observability sink
+        console.log(event.operation, event.endpoint, event.sql, event.callsite);
+      },
+    },
+  },
+});
+```
+
+### findMany AST transport (experimental)
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: {
+    findManyAst: true,
+  },
+});
+```
+
+With `findManyAst: true`, clean `findMany(...)` calls send the original object AST body to `/gateway/fetch` instead of compiling the select tree down to `columns` and `conditions` first.
+
+- this is opt-in and meant for gateways that explicitly support direct AST bodies
+- existing compiled `findMany(...)` transport remains the default
+- chained builder filters or pagination state that the AST body cannot represent losslessly yet continue to use the legacy compiled path
+- trace output still includes synthesized SQL so diagnostics stay readable
+
+### Numeric coercion
 
 ```ts
 import { coerceInt, assertInt } from "@xylex-group/athena";
@@ -583,15 +583,33 @@ const { data: user } = await athena
 
 ### Table schema targeting
 
-Use `schema` in table call options to qualify unqualified table names:
+Use `schema` either on `from(...)` itself or in table call options to qualify unqualified table names:
 
 ```ts
 const { data } = await athena
+  .from("users", { schema: "public" })
+  .select("id,email");
+
+const { data: sameTarget } = await athena
   .from("users")
   .select("id,email", { schema: "public" });
+
+const { data: crossSchema } = await athena
+  .from("chat_subscriptions", { schema: "private" })
+  .findMany({
+    select: {
+      user_id: true,
+      user: {
+        schema: "athena",
+        select: {
+          id: true,
+        },
+      },
+    },
+  });
 ```
 
-This resolves the table target to `public.users`.
+Both resolve the table target to `public.users`.
 
 ### RPC