@xylex-group/athena 2.7.0 → 2.8.2

package/README.md

@@ -1,6 +1,6 @@
 # athena-js
 
-current version: `2.7.0`
+current version: `2.8.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
@@ -24,10 +24,14 @@ 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 athenaClient = createClient(
+  ATHENA_URL,
+  ATHENA_API_KEY,
+  {
+    client: "CLIENT_NAME",
+    backend: { type: "athena" },
+  },
+);
 
 const { data, error } = await athenaClient.from("orchestral_sections").findMany({
   select: {
@@ -47,6 +51,34 @@ if (error) {
 }
 ```
 
+`createClient(url, key)` is the canonical SDK shape. The SDK treats `url` as the public unified Athena base URL and derives:
+
+- DB: `${url}/db`
+- Auth: `${url}/auth`
+- Storage: `${url}/storage`
+
+You can still override individual services when needed:
+
+```ts
+const athena = createClient({
+  key: ATHENA_API_KEY,
+  db: { url: process.env.ATHENA_DB_URL },
+  auth: { url: process.env.ATHENA_AUTH_URL },
+  storage: { url: process.env.ATHENA_STORAGE_URL },
+});
+```
+
+Legacy top-level aliases are also supported:
+
+```ts
+const athena = createClient({
+  key: ATHENA_API_KEY,
+  gatewayUrl: process.env.ATHENA_DB_URL,
+  authUrl: process.env.ATHENA_AUTH_URL,
+  storageUrl: process.env.ATHENA_STORAGE_URL,
+});
+```
+
 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.
@@ -238,28 +270,38 @@ It also supports dynamic `baseURL` host resolution plus static/dynamic
 
 For the full details and current scope, see [`docs/auth/server-bootstrap.mdx`](docs/auth/server-bootstrap.mdx).
 
-### Typed schema registry (model-first)
+### Typed schema registry (table-first)
 
-You can keep `createClient(...).from<T>(...)` as-is, or opt into a typed registry:
+You can keep `createClient(...).from<T>(...)` as-is, or opt into a typed registry with the new Zero-style table DSL:
 
 ```ts
 import {
+  boolean,
   createTypedClient,
   defineDatabase,
-  defineModel,
   defineRegistry,
   defineSchema,
+  enumeration,
+  json,
+  string,
+  table,
 } from "@xylex-group/athena";
 
+const users = table("users")
+  .schema("public")
+  .columns({
+    id: string().generated(),
+    email: string(),
+    active: boolean().defaulted(),
+    mood: enumeration(["happy", "sad"] as const).optional(),
+    settings: json<{ theme: "light" | "dark" }>(),
+  })
+  .primaryKey("id");
+
 const registry = defineRegistry({
   primary: defineDatabase({
     public: defineSchema({
-      users: defineModel<{ id: string; email: string }>({
-        meta: {
-          primaryKey: ["id"],
-          nullable: { id: false, email: false },
-        },
-      }),
+      users,
     }),
   }),
 });
@@ -274,8 +316,45 @@ await typed
   .withTenantContext({ organizationId: "org_1" })
   .fromModel("primary", "public", "users")
   .select("*");
+
+const insert = users.schemas.form.parse({
+  email: "ada@example.com",
+  mood: "",
+  settings: { theme: "light" },
+});
+```
+
+You can also pass that native Athena table/model value directly into the root client to avoid repeating the string table target:
+
+```ts
+const result = await athena.from(users)
+  .select("id, email, active")
+  .eq("active", true)
+  .order("created_at", { ascending: false })
+  .limit(25);
 ```
 
+This is the viable opt-in short form because the `users` value carries runtime target metadata. A generic-only call like `from<UserPublicSchema>()` cannot resolve a table at runtime after TypeScript erases types.
+
+If you want compile-time validation for simple string selects and RPC column names, enable the experimental strict mode:
+
+```ts
+const strictAthena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: {
+    typecheckColumns: true,
+  },
+});
+
+await strictAthena.from(users).select("id, email").order("created_at");
+
+// compile-time error
+strictAthena.from(users).select("id, missing_column");
+```
+
+For the DB helper surface, use `strictAthena.db.from<UserRow>("users").select("id, email")` when you want inline typed column validation. `strictAthena.db.select<UserRow>("users")` still gives a typed row-aware chain, but it does not accept inline typed column arguments.
+
+`defineModel(...)` remains fully supported for compatibility and manual contracts.
+
 For full details, see [`docs/typed-schema-registry.md`](./docs/typed-schema-registry.md).
 
 For exhaustive method-by-method documentation with usage snippets (root client, runtime builders, auth bindings, react runtime, cookies, and utils), see [`docs/complete-method-reference.md`](./docs/complete-method-reference.md).
@@ -294,15 +373,98 @@ athena-js generate --help
 athena-js help generate
 ```
 
+Out of the box, `athena-js generate` now works without an `athena.config.*` file in the common cases:
+
+```bash
+DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/app_db athena-js generate --dry-run
+```
+
+```bash
+ATHENA_URL=https://athena-db.com ATHENA_API_KEY=secret ATHENA_GENERATOR_DB=app_db athena-js generate --dry-run
+```
+
+Smallest direct-mode config file:
+
+```ts
+import { defineGeneratorConfig } from "@xylex-group/athena";
+
+export default defineGeneratorConfig({
+  provider: {
+    kind: "postgres",
+    mode: "direct",
+  },
+});
+```
+
+Smallest table-builder config:
+
+```ts
+import { defineGeneratorConfig } from "@xylex-group/athena";
+
+export default defineGeneratorConfig({
+  provider: {
+    kind: "postgres",
+    mode: "direct",
+  },
+  output: {
+    format: "table-builder",
+  },
+});
+```
+
+Important:
+
+- `output.format = "table-builder"` is stable generator behavior, not an experimental flag.
+- `experimental.findManyAst` is a separate runtime transport opt-in for `findMany(...)`; it does not enable generated table artifacts.
+- the default generator mode is still legacy `define-model`, and the default model target is still schema-scoped (`athena/models/{schema_kebab}/{model_kebab}.ts`)
+- if you want flat `athena/models/*.ts` files, set `output.targets.model = "athena/models/{model_kebab}.ts"` (or `ATHENA_GENERATOR_MODEL_TARGET=athena/models/{model_kebab}.ts`); multi-schema collisions are still auto-scoped by schema when needed
+
+Common copy-paste starts:
+
+```bash
+# direct postgres, no config file
+DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/app_db athena-js generate --dry-run
+
+# direct postgres + Zero-style output + multiple schemas
+DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/app_db \
+ATHENA_GENERATOR_OUTPUT_FORMAT=table-builder \
+ATHENA_GENERATOR_SCHEMAS=public,analytics \
+athena-js generate --dry-run
+
+# gateway-only CI job, no config file
+ATHENA_URL=https://athena-db.com \
+ATHENA_API_KEY=secret \
+ATHENA_GENERATOR_DB=app_db \
+athena-js generate --dry-run
+```
+
+Smallest gateway table-builder config:
+
+```ts
+import { defineGeneratorConfig } from "@xylex-group/athena";
+
+export default defineGeneratorConfig({
+  provider: {
+    kind: "postgres",
+    mode: "gateway",
+  },
+  output: {
+    format: "table-builder",
+  },
+});
+```
+
 Generator supports:
 
 - PostgreSQL direct introspection (`provider.mode = "direct"`, `provider.connectionString` from your `PG_URL`/`DATABASE_URL`)
 - PostgreSQL gateway-only introspection (`provider.mode = "gateway"` via Athena `POST /gateway/query`)
-- Multiple schema syncs such as `public` plus `athena`, with schema-safe default output paths
+- Multiple schema syncs such as `public` plus `athena`, with schema-safe default output paths
+- Two output formats: legacy `define-model` artifacts (default) or the new Zero-style `table-builder` format via `output.format`
 - Placeholder-driven output paths
 - Feature flags (`features.emitRegistry`, `features.emitRelations`)
 - Typed env-backed config fields via `generatorEnv(...)` for connection strings, schema lists, naming styles, flags, and placeholder maps
 
+For copy-paste quickstarts and more example profiles, see [`docs/generator-quickstart.md`](./docs/generator-quickstart.md).
 For full generator configuration and troubleshooting, see [`docs/generator-config.md`](./docs/generator-config.md).
 For full CLI commands, help behavior, and troubleshooting, see [`docs/cli-command-reference.md`](./docs/cli-command-reference.md).
 For CI/CD pipelines and generated-file branch policy, see [`docs/generator-cicd.md`](./docs/generator-cicd.md).
@@ -375,7 +537,7 @@ requireAffected(inserted, { min: 1 }, { table: "users", operation: "insert" });
 ### Structured errors by default
 
 ```ts
-import { createClient, normalizeAthenaError } from "@xylex-group/athena";
+import { createClient } from "@xylex-group/athena";
 
 const athena = createClient(ATHENA_URL, ATHENA_API_KEY);
 
@@ -391,13 +553,13 @@ if (error) {
 
 `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.
+`normalizeAthenaError(...)` is deprecated. Prefer `result.error` on failed results and the structured fields already attached to thrown SDK errors.
 
 ### Query tracing (experimental)
 
 ```ts
 const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
-  experimental: { traceQueries: true },
+  experimental: { traceQueries: true, debugAst: true },
 });
 ```
 
@@ -426,6 +588,44 @@ const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
 });
 ```
 
+If you also enable `debugAst: true`, every traced operation includes a normalized AST, and successful results expose the same AST through `getAthenaDebugAst(...)`:
+
+```ts
+import { createClient, getAthenaDebugAst } from "@xylex-group/athena";
+
+const athena = createClient(ATHENA_URL, ATHENA_API_KEY, {
+  experimental: {
+    debugAst: true,
+  },
+});
+
+const result = await athena.from("users").eq("id", 1).select("id");
+const ast = getAthenaDebugAst(result);
+```
+
+This works across the runtime operation families too:
+
+```ts
+const inserted = await athena
+  .from("users")
+  .insert({ email: "ada@example.com" })
+  .select("id,email");
+
+const insertedAst = getAthenaDebugAst(inserted);
+
+const rpcResult = await athena
+  .rpc("list_users", { role: "admin" })
+  .eq("active", true)
+  .select("id,email");
+
+const rpcAst = getAthenaDebugAst(rpcResult);
+
+const sqlResult = await athena.query<{ id: number }>("select id from users where active = true");
+const sqlAst = getAthenaDebugAst(sqlResult);
+```
+
+If `traceQueries` is enabled too, the same normalized AST is emitted on each `AthenaQueryTraceEvent.ast`.
+
 ### Read retries (experimental)
 
 ```ts