@xylex-group/athena 1.4.1 → 1.6.0

package/README.md

@@ -1,7 +1,7 @@
 # athena-js
 
-current version: `1.4.1`
-`@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.
+current version: `1.6.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
 
@@ -13,7 +13,7 @@ pnpm add @xylex-group/athena
 yarn add @xylex-group/athena
 ```
 
-React peer dependency is optional — only needed if you use `useAthenaGateway`.
+React peer dependency is optional — only needed if you use `@xylex-group/athena/react` hooks.
 
 ```bash
 npm install react  # React >=17 required for the hook
@@ -43,6 +43,62 @@ if (error) {
 }
 ```
 
+### Typed schema registry (model-first)
+
+You can keep `createClient(...).from<T>(...)` as-is, or opt into a typed registry:
+
+```ts
+import {
+  createTypedClient,
+  defineDatabase,
+  defineModel,
+  defineRegistry,
+  defineSchema,
+} from "@xylex-group/athena";
+
+const registry = defineRegistry({
+  primary: defineDatabase({
+    public: defineSchema({
+      users: defineModel<{ id: string; email: string }>({
+        meta: {
+          primaryKey: ["id"],
+          nullable: { id: false, email: false },
+        },
+      }),
+    }),
+  }),
+});
+
+const typed = createTypedClient(registry, ATHENA_URL, ATHENA_API_KEY, {
+  tenantKeyMap: {
+    organizationId: "X-Organization-Id",
+  },
+});
+
+await typed
+  .withTenantContext({ organizationId: "org_1" })
+  .fromModel("primary", "public", "users")
+  .select("*");
+```
+
+For full details, see [`docs/typed-schema-registry.md`](./docs/typed-schema-registry.md).
+
+### Typed schema generator (phase 2 scaffolding)
+
+The SDK now includes a project-root generator config system (`athena.config.ts`) and CLI command:
+
+```bash
+athena-js generate
+athena-js generate --dry-run
+athena-js generate --config ./athena.config.ts
+```
+
+Generator output paths support placeholder tokens (database/schema/model + case variants), feature flags, and experimental provider contracts.
+PostgreSQL introspection works both via direct `pg_url` and gateway-only `/gateway/query` execution.
+
+For full generator configuration, see [`docs/generator-config.md`](./docs/generator-config.md).
+For prompt-ready documentation handoff text, see [`docs/generator-codex-handoff-prompt-pack.md`](./docs/generator-codex-handoff-prompt-pack.md).
+
 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.
@@ -153,12 +209,12 @@ 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
-  .eqUuid("session_id", "550e8400-e29b-41d4-a716-446655440000") // explicit UUID cast
-  .eqCast("session_id", "550e8400-e29b-41d4-a716-446655440000", "uuid") // explicit cast type
-  .neq("role", "guest") // column != value
+  .from("characters")
+  .select("id, name")
+  .eq("active", true) // column = value
+  .eqUuid("session_id", "550e8400-e29b-41d4-a716-446655440000") // explicit UUID cast
+  .eqCast("session_id", "550e8400-e29b-41d4-a716-446655440000", "uuid") // explicit cast type
+  .neq("role", "guest") // column != value
   .gt("level", 5) // column > value
   .gte("score", 100) // column >= value
   .lt("age", 30) // column < value
@@ -171,10 +227,10 @@ const { data } = await athena
   .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
-```
-
-`eq()` now auto-detects UUID-like values on identifier columns (for example `id`, `*_id`, `*uuid*`) and uses a safe typed comparison path so UUID columns no longer require app-side manual `::uuid` / `::text` casts.
+  .or("status.eq.active,status.eq.pending"); // OR expression
+```
+
+`eq()` now auto-detects UUID-like values on identifier columns (for example `id`, `*_id`, `*uuid*`) and uses a safe typed comparison path so UUID columns no longer require app-side manual `::uuid` / `::text` casts.
 
 Canonical style for reads is to call `.select(...)` first, then apply filters:
 
@@ -412,11 +468,105 @@ mutation.finally(() => …);
 
 The request fires only once regardless of how many times you call `.then()` or await the object.
 
-## React hook
+## React hooks
 
 ```tsx
 "use client";
 
+import {
+  AthenaQueryClientProvider,
+  createAthenaQueryClient,
+  useAthenaGateway,
+  useMutation,
+  useQuery,
+} from "@xylex-group/athena/react";
+import { createClient } from "@xylex-group/athena";
+
+const queryClient = createAthenaQueryClient({
+  cache: { mode: "none" }, // default: no persistent data cache, inflight dedupe only
+});
+
+const athena = createClient(
+  process.env.NEXT_PUBLIC_ATHENA_URL!,
+  process.env.NEXT_PUBLIC_ATHENA_API_KEY!,
+);
+
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+};
+
+type CreateProductInput = {
+  name: string;
+  price: number;
+};
+
+function ProductsInner() {
+  const products = useQuery<Product[]>({
+    queryKey: ["products"],
+    queryFn: () =>
+      athena.from("products").select("id,name,price").limit(50),
+  });
+
+  const createProduct = useMutation<CreateProductInput, Product>({
+    mutationFn: (input) =>
+      athena.from("products").insert(input).select("id,name,price").single(),
+    onSuccess: () => {
+      void products.refetch();
+    },
+  });
+
+  if (products.isLoading) return <div>Loading...</div>;
+  if (products.error) return <div>{products.error.message}</div>;
+
+  return (
+    <div>
+      <button
+        onClick={() => {
+          createProduct.mutate({ name: "New product", price: 99 });
+        }}
+      >
+        Add Product
+      </button>
+      {products.data?.map((product) => (
+        <div key={product.id}>
+          {product.name} - {product.price}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export function Products() {
+  return (
+    <AthenaQueryClientProvider client={queryClient}>
+      <ProductsInner />
+    </AthenaQueryClientProvider>
+  );
+}
+```
+
+Available React APIs:
+
+- `useAthenaGateway`: low-level gateway hook (`fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `rpcGateway`) with request/response logging.
+- `createAthenaQueryClient` + `AthenaQueryClientProvider`: Athena query runtime boundary for scoped state and subscriptions.
+- `useQuery`: lightweight read lifecycle hook (`status`, `isFetching`, `refetch`, `reset`) with normalized Athena error/result handling.
+- `useMutation`: lightweight write lifecycle hook (`mutate`, `mutateAsync`, `reset`) with manual refetch/invalidation flow.
+
+By design this is not a cache-heavy React Query clone:
+
+- No TanStack/React Query dependency.
+- No persistent data cache by default (`cache.mode = "none"`).
+- Inflight dedupe for identical query keys is enabled.
+- Manual `refetch()` after mutations is the default invalidation strategy.
+
+`test-sdk` includes runnable local examples for these hooks in
+`test-sdk/examples/react-hooks`, where `queryFn`/`mutationFn` call Athena directly via `createClient(...).from(...).select()/insert()/eq()`.
+
+`useAthenaGateway` example:
+
+```tsx
 import { useAthenaGateway } from "@xylex-group/athena/react";
 import { useEffect } from "react";
 
@@ -427,7 +577,7 @@ export function UsersPanel() {
   });
 
   useEffect(() => {
-    fetchGateway({
+    void fetchGateway({
       table_name: "users",
       columns: ["id", "email"],
       limit: 25,
@@ -441,9 +591,7 @@ export function UsersPanel() {
 }
 ```
 
-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`.
+`useAthenaGateway` config options mirror the client options: `baseUrl`, `apiKey`, `headers`, `userId`, `organizationId`, `publishEvent`.
 
 ## User context headers
 
@@ -516,5 +664,8 @@ CI and publish workflows run `typecheck` before build/publish.
 
 ## Learn more
 
+- [Documentation index](docs/index.md) — complete documentation map
 - [Getting started](docs/getting-started.md) — step-by-step walkthrough
+- [Typed schema registry](docs/typed-schema-registry.md) — typed contracts and migration path
+- [Generator config](docs/generator-config.md) — generator provider and output pipeline
 - [API reference](docs/api-reference.md) — complete method and type reference

package/bin/athena-js.js

@@ -1,9 +1,8 @@
-#!/usr/bin/env node
-
-import('../dist/cli/index.js').then(({ runCLI }) => {
-  runCLI(process.argv.slice(2))
-}).catch(err => {
-  console.error('Failed to start athena-js CLI:', err)
-  process.exit(1)
-})
+#!/usr/bin/env node
 
+import('../dist/cli/index.js')
+  .then(({ runCLI }) => runCLI(process.argv.slice(2)))
+  .catch(err => {
+    console.error('Failed to start athena-js CLI:', err)
+    process.exit(1)
+  })