aroraql-client 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# aroraql-client
+
+Supabase-inspired, **type-safe fluent query builder** for the frontend. Chain calls, get a JSON payload, and let the client POST it to your AroraQL endpoint — results come back mapped to _your_ types.
+
+```ts
+const employees = await arora
+  .from<Employee>("Employees")
+  .select("Id", "Name", "Department.Name")
+  .where("Age")
+  .gt(18)
+  .where("Country")
+  .eq("Egypt")
+  .orderBy("Name")
+  .asc()
+  .take(50)
+  .many(); // Employee[]
+```
+
+- **Zero dependencies** — just `fetch`
+- **Fully generic** — field names and value types checked against your row type
+- **Runs anywhere** — Bun, Node 18+, and browsers
+
+## Install
+
+```sh
+bun add aroraql-client
+# or
+npm install aroraql-client
+```
+
+## Setup
+
+The client auto-detects the endpoint from the `AroraQL_Api` environment variable:
+
+```sh
+# .env
+AroraQL_Api=https://api.example.com/query
+```
+
+```ts
+import { createClient } from "aroraql-client";
+
+const arora = createClient();
+```
+
+Or configure it explicitly (required in browsers, where env variables don't exist):
+
+```ts
+const arora = createClient({
+  url: "https://api.example.com/query",
+  headers: { authorization: `Bearer ${token}` }, // optional, sent on every request
+});
+```
+
+## Usage
+
+Define your row type once and every part of the query is checked against it:
+
+```ts
+type Employee = {
+  Id: number;
+  Name: string;
+  Age: number;
+  Country: string;
+  Department: { Name: string };
+};
+```
+
+### Fetch many rows
+
+```ts
+const rows = await arora
+  .from<Employee>("Employees")
+  .where("Age")
+  .gte(18)
+  .orderBy("Name")
+  .asc()
+  .many(); // Employee[]
+```
+
+### Fetch a single row
+
+```ts
+// First match or null — never throws on "not found"
+const employee = await arora
+  .from<Employee>("Employees")
+  .where("Id")
+  .eq(42)
+  .maybeSingle(); // Employee | null
+
+// Exactly one row — throws unless precisely 1 match
+const employee = await arora
+  .from<Employee>("Employees")
+  .where("Id")
+  .eq(42)
+  .single(); // Employee
+```
+
+### Build without fetching
+
+```ts
+const payload = arora
+  .from<Employee>("Employees")
+  .select("Id", "Name")
+  .where("Country")
+  .eq("Egypt")
+  .build();
+// { from: "Employees", select: ["Id", "Name"],
+//   where: [{ field: "Country", op: "=", value: "Egypt" }], orderBy: [] }
+```
+
+## API
+
+### Query builder
+
+| Method                              | Description                                                                      |
+| ----------------------------------- | -------------------------------------------------------------------------------- |
+| `.from<T>(table)`                   | Start a query. `T` types everything downstream.                                  |
+| `.select(...fields)`                | Project fields. Supports dotted paths (`"Department.Name"`). Empty = all fields. |
+| `.where(field)`                     | Start a condition — follow with an operator (below).                             |
+| `.orderBy(field).asc()` / `.desc()` | Sort. Chain multiple for multi-field ordering.                                   |
+| `.take(n)`                          | Limit the number of rows.                                                        |
+
+### Where operators
+
+| Method                       | SQL equivalent                       |
+| ---------------------------- | ------------------------------------ |
+| `.eq(value)`                 | `=`                                  |
+| `.ne(value)`                 | `!=`                                 |
+| `.gt(value)` / `.gte(value)` | `>` / `>=`                           |
+| `.lt(value)` / `.lte(value)` | `<` / `<=`                           |
+| `.like(pattern)`             | `LIKE` (`%` any chars, `_` one char) |
+
+Operator values are typed as `T[K]` — `where("Age").eq("old")` is a compile error.
+
+### Executors
+
+| Method           | Returns              | Behavior                                            |
+| ---------------- | -------------------- | --------------------------------------------------- |
+| `.many()`        | `Promise<T[]>`       | All matching rows.                                  |
+| `.maybeSingle()` | `Promise<T \| null>` | First row or `null`.                                |
+| `.single()`      | `Promise<T>`         | Exactly one row — throws `AroraQLError` on 0 or 2+. |
+| `.build()`       | `QueryPayload`       | The raw JSON payload, no request made.              |
+
+## Backend contract
+
+The client sends a single `POST` with a JSON body:
+
+```json
+{
+  "from": "Employees",
+  "select": ["Id", "Name", "Department.Name"],
+  "where": [{ "field": "Age", "op": ">", "value": 18 }],
+  "orderBy": [{ "field": "Name", "dir": "asc" }],
+  "take": 50
+}
+```
+
+Your endpoint maps this onto any data source and responds with:
+
+```json
+{ "data": [ ... ] }
+```
+
+or, on failure (any status):
+
+```json
+{ "error": "Unknown table: Employes" }
+```
+
+Errors are surfaced as `AroraQLError` (with `.status`). A minimal Bun endpoint:
+
+```ts
+import type { QueryPayload } from "aroraql-client";
+
+Bun.serve({
+  port: 3123,
+  async fetch(req) {
+    const payload = (await req.json()) as QueryPayload;
+    return Response.json({ data: runQuery(payload) }); // map payload -> your DB
+  },
+});
+```
+
+All payload types (`QueryPayload`, `WhereCondition`, `OrderByClause`, `Operator`) are exported so your backend can share them.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+export type Operator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "like";
+export type SortDir = "asc" | "desc";
+export interface WhereCondition {
+    field: string;
+    op: Operator;
+    value: unknown;
+}
+export interface OrderByClause {
+    field: string;
+    dir: SortDir;
+}
+/** The JSON shape sent to the backend. */
+export interface QueryPayload {
+    from: string;
+    select: string[];
+    where: WhereCondition[];
+    orderBy: OrderByClause[];
+    take?: number;
+}
+export interface AroraQLConfig {
+    /** Endpoint url. Falls back to the `AroraQL_Api` env variable. */
+    url?: string;
+    /** Extra headers (e.g. auth) sent with every request. */
+    headers?: Record<string, string>;
+    /** Custom fetch implementation (useful for tests). */
+    fetch?: typeof globalThis.fetch;
+}
+export declare class AroraQLError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+type Row = Record<string, unknown>;
+/** keyof T with autocomplete, but still allows dotted paths like "Department.Name". */
+type Field<T> = Extract<keyof T, string> | (string & {});
+/** Value type for a field: exact type when K is a key of T, unknown for dotted paths. */
+type FieldValue<T, K> = K extends keyof T ? T[K] : unknown;
+/**
+ * Create a client. Reads the endpoint from `AroraQL_Api` when no url is given.
+ *
+ * ```ts
+ * const arora = createClient(); // uses process.env.AroraQL_Api
+ * const rows = await arora.from<Employee>("Employees").where("Age").gt(18).many();
+ * ```
+ */
+export declare function createClient(config?: AroraQLConfig): AroraQLClient;
+export declare class AroraQLClient {
+    readonly url: string;
+    private readonly config;
+    constructor(url: string, config?: AroraQLConfig);
+    /** Start a query against a table. Pass your row type for full type safety. */
+    from<T extends Row = Row>(table: string): QueryBuilder<T>;
+    /** @internal Sends the payload and unwraps `{ data, error }`. */
+    execute<T>(payload: QueryPayload): Promise<T[]>;
+}
+export declare class QueryBuilder<T extends Row> {
+    #private;
+    private readonly client;
+    constructor(client: AroraQLClient, table: string);
+    select(...fields: Field<T>[]): this;
+    where<K extends Field<T>>(field: K): WhereBuilder<T, K>;
+    orderBy(field: Field<T>): OrderByBuilder<T>;
+    take(count: number): this;
+    /** @internal */
+    _addWhere(condition: WhereCondition): this;
+    /** @internal */
+    _addOrderBy(order: OrderByClause): this;
+    /** The raw JSON payload (no request is made). */
+    build(): QueryPayload;
+    /** Execute and return all matching rows. */
+    many(): Promise<T[]>;
+    /** Execute and return the first row, or null when nothing matches. */
+    maybeSingle(): Promise<T | null>;
+    /** Execute and return exactly one row — throws on 0 or 2+ matches. */
+    single(): Promise<T>;
+}
+export declare class WhereBuilder<T extends Row, K extends Field<T>> {
+    #private;
+    private readonly query;
+    private readonly field;
+    constructor(query: QueryBuilder<T>, field: K);
+    eq(value: FieldValue<T, K>): QueryBuilder<T>;
+    ne(value: FieldValue<T, K>): QueryBuilder<T>;
+    gt(value: FieldValue<T, K>): QueryBuilder<T>;
+    gte(value: FieldValue<T, K>): QueryBuilder<T>;
+    lt(value: FieldValue<T, K>): QueryBuilder<T>;
+    lte(value: FieldValue<T, K>): QueryBuilder<T>;
+    like(value: string): QueryBuilder<T>;
+}
+export declare class OrderByBuilder<T extends Row> {
+    private readonly query;
+    private readonly field;
+    constructor(query: QueryBuilder<T>, field: Field<T>);
+    asc(): QueryBuilder<T>;
+    desc(): QueryBuilder<T>;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,150 @@
+// AroraQL Client — a tiny, supabase-inspired fluent query client.
+// Builds a JSON query payload and POSTs it to your AroraQL endpoint.
+export class AroraQLError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "AroraQLError";
+    }
+}
+/** Safe env lookup — works in Bun/Node and is a no-op in browsers (pass `url` there). */
+function envVar(name) {
+    const env = globalThis
+        .process?.env;
+    return env?.[name];
+}
+/**
+ * Create a client. Reads the endpoint from `AroraQL_Api` when no url is given.
+ *
+ * ```ts
+ * const arora = createClient(); // uses process.env.AroraQL_Api
+ * const rows = await arora.from<Employee>("Employees").where("Age").gt(18).many();
+ * ```
+ */
+export function createClient(config = {}) {
+    const url = config.url ??
+        envVar("AroraQL_Api") ??
+        envVar("ARORAQL_API");
+    if (!url) {
+        throw new AroraQLError("AroraQL: missing API url. Set the `AroraQL_Api` env variable or pass `createClient({ url })`.");
+    }
+    return new AroraQLClient(url, config);
+}
+export class AroraQLClient {
+    url;
+    config;
+    constructor(url, config = {}) {
+        this.url = url;
+        this.config = config;
+    }
+    /** Start a query against a table. Pass your row type for full type safety. */
+    from(table) {
+        return new QueryBuilder(this, table);
+    }
+    /** @internal Sends the payload and unwraps `{ data, error }`. */
+    async execute(payload) {
+        const doFetch = this.config.fetch ?? globalThis.fetch;
+        const res = await doFetch(this.url, {
+            method: "POST",
+            headers: { "content-type": "application/json", ...this.config.headers },
+            body: JSON.stringify(payload),
+        });
+        const body = (await res.json().catch(() => null));
+        if (!res.ok || !body || body.error) {
+            throw new AroraQLError(body?.error ?? `AroraQL: request failed with status ${res.status}`, res.status);
+        }
+        return body.data ?? [];
+    }
+}
+export class QueryBuilder {
+    client;
+    #query;
+    constructor(client, table) {
+        this.client = client;
+        this.#query = { from: table, select: [], where: [], orderBy: [] };
+    }
+    select(...fields) {
+        this.#query.select.push(...fields);
+        return this;
+    }
+    where(field) {
+        return new WhereBuilder(this, field);
+    }
+    orderBy(field) {
+        return new OrderByBuilder(this, field);
+    }
+    take(count) {
+        this.#query.take = count;
+        return this;
+    }
+    /** @internal */
+    _addWhere(condition) {
+        this.#query.where.push(condition);
+        return this;
+    }
+    /** @internal */
+    _addOrderBy(order) {
+        this.#query.orderBy.push(order);
+        return this;
+    }
+    /** The raw JSON payload (no request is made). */
+    build() {
+        return structuredClone(this.#query);
+    }
+    /** Execute and return all matching rows. */
+    async many() {
+        return this.client.execute(this.build());
+    }
+    /** Execute and return the first row, or null when nothing matches. */
+    async maybeSingle() {
+        const payload = this.build();
+        payload.take = 1;
+        const rows = await this.client.execute(payload);
+        return rows[0] ?? null;
+    }
+    /** Execute and return exactly one row — throws on 0 or 2+ matches. */
+    async single() {
+        const payload = this.build();
+        payload.take = 2;
+        const rows = await this.client.execute(payload);
+        if (rows.length === 0)
+            throw new AroraQLError("AroraQL: single() found no rows");
+        if (rows.length > 1)
+            throw new AroraQLError("AroraQL: single() found more than one row");
+        return rows[0];
+    }
+}
+export class WhereBuilder {
+    query;
+    field;
+    constructor(query, field) {
+        this.query = query;
+        this.field = field;
+    }
+    #add(op, value) {
+        return this.query._addWhere({ field: this.field, op, value });
+    }
+    eq(value) { return this.#add("=", value); }
+    ne(value) { return this.#add("!=", value); }
+    gt(value) { return this.#add(">", value); }
+    gte(value) { return this.#add(">=", value); }
+    lt(value) { return this.#add("<", value); }
+    lte(value) { return this.#add("<=", value); }
+    like(value) { return this.#add("like", value); }
+}
+export class OrderByBuilder {
+    query;
+    field;
+    constructor(query, field) {
+        this.query = query;
+        this.field = field;
+    }
+    asc() {
+        return this.query._addOrderBy({ field: this.field, dir: "asc" });
+    }
+    desc() {
+        return this.query._addOrderBy({ field: this.field, dir: "desc" });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "aroraql-client",
+  "version": "0.1.0",
+  "description": "Supabase-inspired, type-safe fluent query builder that turns chained calls into a JSON payload and POSTs it to your AroraQL endpoint",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "fluent",
+    "query-builder",
+    "json",
+    "typescript",
+    "type-safe",
+    "supabase",
+    "rest",
+    "aroraql"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,209 @@
+// AroraQL Client — a tiny, supabase-inspired fluent query client.
+// Builds a JSON query payload and POSTs it to your AroraQL endpoint.
+
+export type Operator = "=" | "!=" | ">" | ">=" | "<" | "<=" | "like";
+export type SortDir = "asc" | "desc";
+
+export interface WhereCondition {
+  field: string;
+  op: Operator;
+  value: unknown;
+}
+
+export interface OrderByClause {
+  field: string;
+  dir: SortDir;
+}
+
+/** The JSON shape sent to the backend. */
+export interface QueryPayload {
+  from: string;
+  select: string[];
+  where: WhereCondition[];
+  orderBy: OrderByClause[];
+  take?: number;
+}
+
+export interface AroraQLConfig {
+  /** Endpoint url. Falls back to the `AroraQL_Api` env variable. */
+  url?: string;
+  /** Extra headers (e.g. auth) sent with every request. */
+  headers?: Record<string, string>;
+  /** Custom fetch implementation (useful for tests). */
+  fetch?: typeof globalThis.fetch;
+}
+
+export class AroraQLError extends Error {
+  constructor(message: string, readonly status?: number) {
+    super(message);
+    this.name = "AroraQLError";
+  }
+}
+
+type Row = Record<string, unknown>;
+/** keyof T with autocomplete, but still allows dotted paths like "Department.Name". */
+type Field<T> = Extract<keyof T, string> | (string & {});
+/** Value type for a field: exact type when K is a key of T, unknown for dotted paths. */
+type FieldValue<T, K> = K extends keyof T ? T[K] : unknown;
+
+/** Safe env lookup — works in Bun/Node and is a no-op in browsers (pass `url` there). */
+function envVar(name: string): string | undefined {
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+    .process?.env;
+  return env?.[name];
+}
+
+/**
+ * Create a client. Reads the endpoint from `AroraQL_Api` when no url is given.
+ *
+ * ```ts
+ * const arora = createClient(); // uses process.env.AroraQL_Api
+ * const rows = await arora.from<Employee>("Employees").where("Age").gt(18).many();
+ * ```
+ */
+export function createClient(config: AroraQLConfig = {}): AroraQLClient {
+  const url =
+    config.url ??
+    envVar("AroraQL_Api") ??
+    envVar("ARORAQL_API");
+  if (!url) {
+    throw new AroraQLError(
+      "AroraQL: missing API url. Set the `AroraQL_Api` env variable or pass `createClient({ url })`."
+    );
+  }
+  return new AroraQLClient(url, config);
+}
+
+export class AroraQLClient {
+  constructor(
+    readonly url: string,
+    private readonly config: AroraQLConfig = {}
+  ) {}
+
+  /** Start a query against a table. Pass your row type for full type safety. */
+  from<T extends Row = Row>(table: string): QueryBuilder<T> {
+    return new QueryBuilder<T>(this, table);
+  }
+
+  /** @internal Sends the payload and unwraps `{ data, error }`. */
+  async execute<T>(payload: QueryPayload): Promise<T[]> {
+    const doFetch = this.config.fetch ?? globalThis.fetch;
+    const res = await doFetch(this.url, {
+      method: "POST",
+      headers: { "content-type": "application/json", ...this.config.headers },
+      body: JSON.stringify(payload),
+    });
+
+    const body = (await res.json().catch(() => null)) as
+      | { data?: T[]; error?: string }
+      | null;
+
+    if (!res.ok || !body || body.error) {
+      throw new AroraQLError(
+        body?.error ?? `AroraQL: request failed with status ${res.status}`,
+        res.status
+      );
+    }
+    return body.data ?? [];
+  }
+}
+
+export class QueryBuilder<T extends Row> {
+  #query: QueryPayload;
+
+  constructor(private readonly client: AroraQLClient, table: string) {
+    this.#query = { from: table, select: [], where: [], orderBy: [] };
+  }
+
+  select(...fields: Field<T>[]): this {
+    this.#query.select.push(...fields);
+    return this;
+  }
+
+  where<K extends Field<T>>(field: K): WhereBuilder<T, K> {
+    return new WhereBuilder(this, field);
+  }
+
+  orderBy(field: Field<T>): OrderByBuilder<T> {
+    return new OrderByBuilder(this, field);
+  }
+
+  take(count: number): this {
+    this.#query.take = count;
+    return this;
+  }
+
+  /** @internal */
+  _addWhere(condition: WhereCondition): this {
+    this.#query.where.push(condition);
+    return this;
+  }
+
+  /** @internal */
+  _addOrderBy(order: OrderByClause): this {
+    this.#query.orderBy.push(order);
+    return this;
+  }
+
+  /** The raw JSON payload (no request is made). */
+  build(): QueryPayload {
+    return structuredClone(this.#query);
+  }
+
+  /** Execute and return all matching rows. */
+  async many(): Promise<T[]> {
+    return this.client.execute<T>(this.build());
+  }
+
+  /** Execute and return the first row, or null when nothing matches. */
+  async maybeSingle(): Promise<T | null> {
+    const payload = this.build();
+    payload.take = 1;
+    const rows = await this.client.execute<T>(payload);
+    return rows[0] ?? null;
+  }
+
+  /** Execute and return exactly one row — throws on 0 or 2+ matches. */
+  async single(): Promise<T> {
+    const payload = this.build();
+    payload.take = 2;
+    const rows = await this.client.execute<T>(payload);
+    if (rows.length === 0) throw new AroraQLError("AroraQL: single() found no rows");
+    if (rows.length > 1) throw new AroraQLError("AroraQL: single() found more than one row");
+    return rows[0]!;
+  }
+}
+
+export class WhereBuilder<T extends Row, K extends Field<T>> {
+  constructor(
+    private readonly query: QueryBuilder<T>,
+    private readonly field: K
+  ) {}
+
+  #add(op: Operator, value: unknown): QueryBuilder<T> {
+    return this.query._addWhere({ field: this.field, op, value });
+  }
+
+  eq(value: FieldValue<T, K>) { return this.#add("=", value); }
+  ne(value: FieldValue<T, K>) { return this.#add("!=", value); }
+  gt(value: FieldValue<T, K>) { return this.#add(">", value); }
+  gte(value: FieldValue<T, K>) { return this.#add(">=", value); }
+  lt(value: FieldValue<T, K>) { return this.#add("<", value); }
+  lte(value: FieldValue<T, K>) { return this.#add("<=", value); }
+  like(value: string) { return this.#add("like", value); }
+}
+
+export class OrderByBuilder<T extends Row> {
+  constructor(
+    private readonly query: QueryBuilder<T>,
+    private readonly field: Field<T>
+  ) {}
+
+  asc(): QueryBuilder<T> {
+    return this.query._addOrderBy({ field: this.field, dir: "asc" });
+  }
+
+  desc(): QueryBuilder<T> {
+    return this.query._addOrderBy({ field: this.field, dir: "desc" });
+  }
+}