@xylex-group/athena 2.0.0 → 2.1.2

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `2.0.0`
+current version: `2.1.2`
 `@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
@@ -206,24 +206,27 @@ 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.
+### Error normalization
+
+```ts
+import { createClient, normalizeAthenaError } from "@xylex-group/athena";
+
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: { enableErrorNormalization: true },
+});
+
+const result = await athena.from("users").insert({ id: 1 }).select();
+if (result.error) {
+  const err = normalizeAthenaError(result);
+  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.
+
+`experimental.enableErrorNormalization` keeps the existing `AthenaResult<T>` shape intact and pre-attaches context-aware metadata so `normalizeAthenaError(result)` can resolve table/operation without extra per-call context objects.
 
 ### Numeric coercion
 
@@ -254,13 +257,31 @@ const result = await withRetry(
 
 By default, retries target transient/rate-limit failures; use `shouldRetry` for custom policies.
 
-## Query builder
-
-### Reading rows
-
-```ts
-// select all columns
-const { data } = await athena.from("users").select();
+## Query builder
+
+### DB module namespace
+
+`createClient()` keeps root methods (`from`, `rpc`, `query`) and now also exposes `db` as an additive namespace.
+
+```ts
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
+
+await athena.db.from("users").select("id,name").eq("active", true).limit(20);
+
+await athena.db.select("users", "id,name").eq("id", 1).single();
+
+await athena.db.insert("users", { id: 1, name: "Alice" }).select("id");
+await athena.db.update("users", { name: "Updated" }).eq("id", 1).select("id,name");
+await athena.db.delete("users", { resourceId: "r-1" }).select("id");
+```
+
+`db` mirrors the existing query builder semantics while providing a module seam for future database-surface expansion.
+
+### Reading rows
+
+```ts
+// select all columns
+const { data } = await athena.from("users").select();
 
 // select specific columns
 const { data } = await athena.from("users").select("id, name, email");