@xylex-group/athena 0.1.0 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Floris (XYLEX Group)
+Copyright (c) 2026 Floris (XYLEX Group)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,63 +1,293 @@
-# athena-js
-
-Athena is a database driver + API gateway SDK that lets you interact with SQL backends using the familiar `supabase-js` syntax.
-
-## Gateway query builder
-
-```ts
-import { createClient } from "athena-js";
-
-const athena = createClient(
-  "https://athena-db.com",
-  process.env.ATHENA_API_KEY,
-);
-
-const { data, error } = await athena.from("characters").select(`
-    id,
-    name,
-    from:sender_id(name),
-    to:receiver_id(name)
-  `);
-
-if (error) {
-  console.error("gateway error", error);
-} else {
-  console.table(data);
-}
-```
-
-Use `select`, `insert`, `update`, and `delete` just like Supabase. The builder supports `.eq()`, `.match()`, `.limit()`, `.offset()`, and `.single()` / `.maybeSingle()`.
-
-## React hook
-
-```tsx
-"use client";
-
-import { useAthenaGateway } from "athena-js/react";
-import { useEffect } from "react";
-
-export function UsersPanel() {
-  const { fetchGateway, lastResponse, isLoading, error } = useAthenaGateway({
-    baseUrl: "https://athena-db.com",
-    apiKey: process.env.NEXT_PUBLIC_ATHENA_API_KEY,
-  });
-
-  useEffect(() => {
-    fetchGateway({
-      table_name: "users",
-      columns: ["id", "email"],
-      limit: 25,
-    });
-  }, [fetchGateway]);
-
-  if (error) return <div>Error: {error}</div>;
-  if (isLoading) return <div>Loading…</div>;
-
-  return <pre>{JSON.stringify(lastResponse?.data, null, 2)}</pre>;
-}
-```
-
-## Learn more
-
-- [API reference](docs/api-reference.md)
-- [Getting started](docs/getting-started.md)
+# athena-js
+
+`@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
+
+```bash
+npm install @xylex-group/athena
+# or
+pnpm add @xylex-group/athena
+# or
+yarn add @xylex-group/athena
+```
+
+React peer dependency is optional — only needed if you use `useAthenaGateway`.
+
+```bash
+npm install react  # React >=17 required for the hook
+```
+
+## Quick start
+
+```ts
+import { createClient } from "@xylex-group/athena";
+
+const athena = createClient(
+  "https://athena-db.com",
+  process.env.ATHENA_API_KEY,
+);
+
+const { data, error } = await athena.from("characters").select(`
+    id,
+    name,
+    from:sender_id(name),
+    to:receiver_id(name)
+  `);
+
+if (error) {
+  console.error("gateway error", error);
+} else {
+  console.table(data);
+}
+```
+
+Every query resolves to `{ data, error, status, raw }`. `data` is `null` on error; `error` is `null` on success.
+
+## Query builder
+
+### 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");
+
+// select with type annotation
+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
+  .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
+  .lte("created_at", "2024-01-01") // column <= value
+  .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
+  .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
+```
+
+### Pagination
+
+```ts
+// explicit limit and offset
+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);
+```
+
+### Single row
+
+```ts
+// returns the first row or null instead of an array
+const { data: user } = await athena
+  .from("users")
+  .select("id, name")
+  .eq("id", 42)
+  .single();
+```
+
+`maybeSingle` behaves identically — both return the first element of the result set.
+
+### 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`) |
+
+```ts
+const { data } = await athena
+  .from("orders")
+  .select("id", { count: "exact", stripNulls: false });
+```
+
+## Mutations
+
+Insert, update, upsert, and delete all return a `MutationQuery` that you can await directly or chain further calls onto before the request fires.
+
+### Insert
+
+```ts
+const { data: inserted } = await athena
+  .from("countries")
+  .insert({ name: "Mordor" })
+  .select("id, name");
+
+// insert multiple rows
+const { data } = await athena
+  .from("characters")
+  .insert([{ name: "Frodo" }, { name: "Sam" }])
+  .select();
+```
+
+### Update
+
+```ts
+const { data: updated } = await athena
+  .from("countries")
+  .update({ name: "Gondor" })
+  .eq("id", 1)
+  .select();
+```
+
+Filters (`.eq()`, `.match()`, etc.) applied before `.update()` are used as `WHERE` conditions.
+
+### Upsert
+
+```ts
+const { data } = await athena
+  .from("countries")
+  .upsert(
+    { id: 2, name: "Rohan" },
+    { updateBody: { name: "Rohan" }, onConflict: "id" },
+  )
+  .select();
+```
+
+| 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
+
+```ts
+// delete by id filter
+await athena.from("countries").eq("id", 1).delete();
+
+// delete with explicit resourceId option
+await athena.from("countries").delete({ resourceId: "abc-123" });
+
+// chain .select() to get the deleted row back
+const { data: deleted } = await athena
+  .from("countries")
+  .eq("resource_id", "abc-123")
+  .delete()
+  .select("id, name");
+```
+
+Delete requires either `.eq("resource_id", …)`, `.eq("id", …)`, or `options.resourceId` — calling `.delete()` without any of these throws an error.
+
+### MutationQuery chaining
+
+All mutation methods return a `MutationQuery` which supports:
+
+```ts
+const mutation = athena.from("users").insert({ name: "Alice" });
+
+await mutation.select("id, name");        // fire request, return rows
+await mutation.returning("id");           // alias for .select()
+await mutation.single("id");              // return first row or null
+await mutation.maybeSingle("id");         // same as .single()
+await mutation;                           // fire request, return default columns
+mutation.then(({ data }) => …);           // thenable
+mutation.catch(err => …);
+mutation.finally(() => …);
+```
+
+The request fires only once regardless of how many times you call `.then()` or await the object.
+
+## React hook
+
+```tsx
+"use client";
+
+import { useAthenaGateway } from "@xylex-group/athena/react";
+import { useEffect } from "react";
+
+export function UsersPanel() {
+  const { fetchGateway, lastResponse, isLoading, error } = useAthenaGateway({
+    baseUrl: "https://athena-db.com",
+    apiKey: process.env.NEXT_PUBLIC_ATHENA_API_KEY,
+  });
+
+  useEffect(() => {
+    fetchGateway({
+      table_name: "users",
+      columns: ["id", "email"],
+      limit: 25,
+    });
+  }, [fetchGateway]);
+
+  if (error) return <div>Error: {error}</div>;
+  if (isLoading) return <div>Loading…</div>;
+
+  return <pre>{JSON.stringify(lastResponse?.data, null, 2)}</pre>;
+}
+```
+
+The hook returns `fetchGateway`, `insertGateway`, `updateGateway`, `deleteGateway`, `isLoading`, `error`, `lastRequest`, `lastResponse`, and `baseUrl`.
+
+Hook config options mirror the client options: `baseUrl`, `apiKey`, `stripNulls`, `headers`, `userId`, `companyId`, `organizationId`, `supabaseUrl`, `supabaseKey`, `publishEvent`.
+
+## User context 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, {
+  userId: currentUser.id,
+  companyId: currentUser.companyId,
+  organizationId: currentUser.organizationId,
+});
+```
+
+These are sent as `X-User-Id`, `X-Company-Id`, and `X-Organization-Id` request headers. You can override them per-call by passing the same options to `.select()` or any mutation method.
+
+## Custom headers
+
+```ts
+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.
+
+## TypeScript
+
+The package is written in TypeScript and ships declaration files. Pass a row type to `.from()` for fully-typed builder methods and results:
+
+```ts
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  active: boolean;
+}
+
+const { data } = await athena.from<User>("users").select("id, name").eq("active", true);
+// data is User[] | null
+```
+
+## Learn more
+
+- [Getting started](docs/getting-started.md) — step-by-step walkthrough
+- [API reference](docs/api-reference.md) — complete method and type reference

package/bin/athena-js.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import('../dist/cli/index.js').then(({ runCLI }) => {
   runCLI(process.argv.slice(2))

package/dist/index.d.mts

@@ -1,24 +1,51 @@
-import { A as AthenaGatewayCallOptions } from './types-DFvltfTX.mjs';
-export { a as AthenaDeletePayload, b as AthenaFetchPayload, c as AthenaGatewayBaseOptions, d as AthenaGatewayCallLog, e as AthenaGatewayCondition, f as AthenaGatewayEndpointPath, g as AthenaGatewayHookConfig, h as AthenaGatewayHookResult, i as AthenaGatewayMethod, j as AthenaGatewayResponse, k as AthenaGatewayResponseLog, l as AthenaInsertPayload, m as AthenaUpdatePayload } from './types-DFvltfTX.mjs';
+import { A as AthenaGatewayCallOptions, a as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator } from './types-DzCf3v76.mjs';
+export { d as AthenaDeletePayload, e as AthenaFetchPayload, f as AthenaGatewayBaseOptions, g as AthenaGatewayCallLog, h as AthenaGatewayCondition, i as AthenaGatewayEndpointPath, j as AthenaGatewayHookConfig, k as AthenaGatewayHookResult, l as AthenaGatewayMethod, m as AthenaGatewayResponse, n as AthenaGatewayResponseLog, o as AthenaInsertPayload, p as AthenaUpdatePayload } from './types-DzCf3v76.mjs';
 
-type AthenaConditionValue = string | number | boolean | null;
 interface SupabaseResult<T> {
     data: T | null;
     error: string | null;
     status: number;
     raw: unknown;
 }
+type MutationSingleResult<Result> = Result extends Array<infer Item> ? Item | null : Result | null;
+interface MutationQuery<Result> extends PromiseLike<SupabaseResult<Result>> {
+    select(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<Result>>;
+    returning(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<Result>>;
+    single(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<MutationSingleResult<Result>>>;
+    maybeSingle(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<MutationSingleResult<Result>>>;
+    then<TResult1 = SupabaseResult<Result>, TResult2 = never>(onfulfilled?: ((value: SupabaseResult<Result>) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | undefined | null): Promise<SupabaseResult<Result> | TResult>;
+    finally(onfinally?: (() => void) | undefined | null): Promise<SupabaseResult<Result>>;
+}
 interface TableQueryBuilder<Row> {
     select<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T>>;
-    insert(values: Row | Row[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<Row | Row[]>>;
-    update(values: Partial<Row>, options?: AthenaGatewayCallOptions): Promise<SupabaseResult<Row[]>>;
+    insert(values: Row | Row[], options?: AthenaGatewayCallOptions): MutationQuery<Row | Row[]>;
+    upsert(values: Row | Row[], options?: AthenaGatewayCallOptions & {
+        updateBody?: Partial<Row>;
+        onConflict?: string | string[];
+    }): MutationQuery<Row | Row[]>;
+    update(values: Partial<Row>, options?: AthenaGatewayCallOptions): MutationQuery<Row[]>;
     delete(options?: AthenaGatewayCallOptions & {
         resourceId?: string;
-    }): Promise<SupabaseResult<null>>;
+    }): MutationQuery<Row | null>;
     eq(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
     match(filters: Record<string, AthenaConditionValue>): TableQueryBuilder<Row>;
+    range(from: number, to: number): TableQueryBuilder<Row>;
     limit(count: number): TableQueryBuilder<Row>;
     offset(count: number): TableQueryBuilder<Row>;
+    gt(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    gte(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    lt(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    lte(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    neq(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    like(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    ilike(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    is(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    in(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
+    contains(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
+    containedBy(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
+    not(columnOrExpression: string, operator?: AthenaConditionOperator, value?: AthenaConditionValue): TableQueryBuilder<Row>;
+    or(expression: string): TableQueryBuilder<Row>;
     single<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
     maybeSingle<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
     reset(): TableQueryBuilder<Row>;

package/dist/index.d.ts

@@ -1,24 +1,51 @@
-import { A as AthenaGatewayCallOptions } from './types-DFvltfTX.js';
-export { a as AthenaDeletePayload, b as AthenaFetchPayload, c as AthenaGatewayBaseOptions, d as AthenaGatewayCallLog, e as AthenaGatewayCondition, f as AthenaGatewayEndpointPath, g as AthenaGatewayHookConfig, h as AthenaGatewayHookResult, i as AthenaGatewayMethod, j as AthenaGatewayResponse, k as AthenaGatewayResponseLog, l as AthenaInsertPayload, m as AthenaUpdatePayload } from './types-DFvltfTX.js';
+import { A as AthenaGatewayCallOptions, a as AthenaConditionValue, b as AthenaConditionArrayValue, c as AthenaConditionOperator } from './types-DzCf3v76.js';
+export { d as AthenaDeletePayload, e as AthenaFetchPayload, f as AthenaGatewayBaseOptions, g as AthenaGatewayCallLog, h as AthenaGatewayCondition, i as AthenaGatewayEndpointPath, j as AthenaGatewayHookConfig, k as AthenaGatewayHookResult, l as AthenaGatewayMethod, m as AthenaGatewayResponse, n as AthenaGatewayResponseLog, o as AthenaInsertPayload, p as AthenaUpdatePayload } from './types-DzCf3v76.js';
 
-type AthenaConditionValue = string | number | boolean | null;
 interface SupabaseResult<T> {
     data: T | null;
     error: string | null;
     status: number;
     raw: unknown;
 }
+type MutationSingleResult<Result> = Result extends Array<infer Item> ? Item | null : Result | null;
+interface MutationQuery<Result> extends PromiseLike<SupabaseResult<Result>> {
+    select(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<Result>>;
+    returning(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<Result>>;
+    single(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<MutationSingleResult<Result>>>;
+    maybeSingle(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<MutationSingleResult<Result>>>;
+    then<TResult1 = SupabaseResult<Result>, TResult2 = never>(onfulfilled?: ((value: SupabaseResult<Result>) => TResult1 | PromiseLike<TResult1>) | undefined | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | undefined | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | undefined | null): Promise<SupabaseResult<Result> | TResult>;
+    finally(onfinally?: (() => void) | undefined | null): Promise<SupabaseResult<Result>>;
+}
 interface TableQueryBuilder<Row> {
     select<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T>>;
-    insert(values: Row | Row[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<Row | Row[]>>;
-    update(values: Partial<Row>, options?: AthenaGatewayCallOptions): Promise<SupabaseResult<Row[]>>;
+    insert(values: Row | Row[], options?: AthenaGatewayCallOptions): MutationQuery<Row | Row[]>;
+    upsert(values: Row | Row[], options?: AthenaGatewayCallOptions & {
+        updateBody?: Partial<Row>;
+        onConflict?: string | string[];
+    }): MutationQuery<Row | Row[]>;
+    update(values: Partial<Row>, options?: AthenaGatewayCallOptions): MutationQuery<Row[]>;
     delete(options?: AthenaGatewayCallOptions & {
         resourceId?: string;
-    }): Promise<SupabaseResult<null>>;
+    }): MutationQuery<Row | null>;
     eq(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
     match(filters: Record<string, AthenaConditionValue>): TableQueryBuilder<Row>;
+    range(from: number, to: number): TableQueryBuilder<Row>;
     limit(count: number): TableQueryBuilder<Row>;
     offset(count: number): TableQueryBuilder<Row>;
+    gt(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    gte(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    lt(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    lte(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    neq(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    like(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    ilike(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    is(column: string, value: AthenaConditionValue): TableQueryBuilder<Row>;
+    in(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
+    contains(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
+    containedBy(column: string, values: AthenaConditionArrayValue): TableQueryBuilder<Row>;
+    not(columnOrExpression: string, operator?: AthenaConditionOperator, value?: AthenaConditionValue): TableQueryBuilder<Row>;
+    or(expression: string): TableQueryBuilder<Row>;
     single<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
     maybeSingle<T = Row>(columns?: string | string[], options?: AthenaGatewayCallOptions): Promise<SupabaseResult<T | null>>;
     reset(): TableQueryBuilder<Row>;