@dreaminhex/hexdb 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @dreaminhex/hexdb
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The JavaScript and TypeScript client for [HexDB](https://github.com/dreaminhex/hexdb), a document database with REST, GraphQL and read-only SQL, encryption at rest and replication with automatic failover.
+
+It covers documents (insert, get, replace, patch, delete), queries with filters, sorting and paging, counts, aggregations, upserts, transactions, idempotency keys, the change feed, streams, functions and GraphQL. It retries `429` and `503` answers for reads, and for writes that carry an idempotency key. Runs on Node.js 18+, Deno, Bun and in browsers, with no dependencies.
+
+```sh
+npm install @dreaminhex/hexdb
+```
+
+```ts
+import { HexDB } from "@dreaminhex/hexdb"
+
+const db = new HexDB({ url: "http://127.0.0.1:7700", apiKey: process.env.HEXDB_API_KEY })
+const orders = db.tessellation("orders")
+await orders.insert({ customer: "ada", total: 12 })
+const page = await orders.query({ filter: { total: { $gt: 10 } }, sort: "-total" })
+```
+
+Create an API key on the admin UI's Account page. The [driver documentation](https://github.com/dreaminhex/hexdb/tree/main/drivers) and the [manual](https://github.com/dreaminhex/hexdb/blob/main/MANUAL.md) cover the rest. Licensed under the Apache License 2.0.

package/dist/index.d.ts

@@ -0,0 +1,210 @@
+export interface Options {
+    /** Base URL of any hex, e.g. http://127.0.0.1:7700 (replicas forward writes to the Overseer). */
+    url: string;
+    /** An API key (hxk_...) or a session token. */
+    apiKey?: string;
+    /** Retries for 429 and 503 answers (honoring Retry-After). Default 3. */
+    retries?: number;
+    /** Per-request timeout in milliseconds. Default 30,000. */
+    timeoutMs?: number;
+    /** A fetch implementation (defaults to the global one). */
+    fetch?: typeof fetch;
+}
+/** An error answer from HexDB: `status` is the HTTP status, `code` HexDB's error code. */
+export declare class HexDBError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryAfter?: number | undefined;
+    constructor(status: number, code: string, message: string, retryAfter?: number | undefined);
+}
+/** A stored document: its fields plus `id` (and `_expires_at` with a TTL). */
+export type Document = {
+    id: string;
+    _expires_at?: string;
+    [field: string]: unknown;
+};
+export interface SortKey {
+    field: string;
+    descending?: boolean;
+}
+export interface Query {
+    /** A filter like `{ status: "paid", total: { $gte: 10 } }` (see the HexDB manual). */
+    filter?: Record<string, unknown>;
+    /** "-total,name" or sort keys. */
+    sort?: string | SortKey[];
+    limit?: number;
+    offset?: number;
+    /** Continue after this document ID (unsorted queries). */
+    after?: string;
+    /** Only these (dotted) fields. */
+    fields?: string[];
+}
+export interface QueryPage {
+    documents: Document[];
+    total: number;
+    next: string | null;
+    plan?: {
+        indexes: string[];
+        scanned: number;
+    };
+}
+export interface WriteOptions {
+    /** Makes retries safe: the same key returns the first result instead of writing again. */
+    idempotencyKey?: string;
+    /** Expire the document after this many seconds. */
+    ttlSeconds?: number;
+}
+export interface Change {
+    seq: number;
+    timestamp: string;
+    op: "put" | "delete" | "drop_tessellation";
+    tessellation: string;
+    id?: string;
+    document?: Document;
+}
+export interface StreamMessage {
+    offset: string;
+    time: number;
+    payload: unknown;
+    key?: string | null;
+    headers?: Record<string, string>;
+}
+type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export declare class HexDB {
+    private readonly base;
+    private token?;
+    private readonly retries;
+    private readonly timeoutMs;
+    private readonly fetcher;
+    constructor(options: Options);
+    /** Send any request to the REST API and return the parsed JSON (undefined for 204). */
+    request<T = unknown>(method: Method, path: string, body?: unknown, headers?: Record<string, string>, timeoutMs?: number): Promise<T>;
+    /** Sign in with a login and password (and a one-time code with MFA); later requests use the session. */
+    login(login: string, password: string, code?: string): Promise<{
+        user: unknown;
+        expires_at: number;
+    }>;
+    /** End the session (a no-op for API keys). */
+    logout(): Promise<void>;
+    /** Whether the server is up (and, signed in, which hex answered). */
+    health(): Promise<{
+        status: string;
+        name?: string;
+        hex_type?: string;
+        version?: string;
+    }>;
+    /** Server status and metrics (needs the status permission). */
+    status(): Promise<Record<string, unknown>>;
+    /** A tessellation (collection of documents). */
+    tessellation(name: string): Tessellation;
+    /** Tessellations you can read. */
+    tessellations(): Promise<{
+        name: string;
+        kind: string;
+        created: string | null;
+        indexes: string[];
+    }[]>;
+    /**
+     * Operations across tessellations, all or nothing:
+     * `[{ op: "insert" | "replace" | "patch" | "delete" | "get" | "check", tessellation, id?, data?, if_version? }]`.
+     */
+    transaction(operations: Record<string, unknown>[], options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        results: unknown[];
+        writes: number;
+    }>;
+    /** Run a GraphQL query or mutation. Throws on GraphQL errors. */
+    graphql<T = Record<string, unknown>>(query: string, variables?: Record<string, unknown>): Promise<T>;
+    /**
+     * Committed changes after `after` (default: from now), as they happen.
+     * Long-polls; stops when `signal` aborts.
+     */
+    changes(options?: {
+        after?: number;
+        tessellation?: string;
+        signal?: AbortSignal;
+    }): AsyncGenerator<Change>;
+    /** A stream (publish/subscribe). */
+    stream(name: string): Stream;
+    /** Run a saved function with parameters; returns its result. */
+    runFunction<T = unknown>(name: string, params?: Record<string, unknown>): Promise<T>;
+}
+export declare class Tessellation {
+    private readonly db;
+    readonly name: string;
+    constructor(db: HexDB, name: string);
+    private get path();
+    /** Insert a document; returns it with its new `id`. */
+    insert(doc: Record<string, unknown>, options?: WriteOptions): Promise<Document>;
+    /** Insert up to 1000 documents atomically; returns their IDs in order. */
+    insertMany(docs: Record<string, unknown>[], options?: WriteOptions): Promise<string[]>;
+    /** A document by ID, or null. */
+    get(id: string, fields?: string[]): Promise<Document | null>;
+    /** Replace a document's fields. */
+    replace(id: string, doc: Record<string, unknown>, options?: WriteOptions): Promise<Document>;
+    /** Merge fields into a document (null removes a field). */
+    patch(id: string, changes: Record<string, unknown>, options?: WriteOptions): Promise<Document>;
+    /** Delete a document; false if it didn't exist. */
+    delete(id: string, options?: {
+        idempotencyKey?: string;
+    }): Promise<boolean>;
+    /** Documents matching a filter, one page at a time. */
+    query(query?: Query): Promise<QueryPage>;
+    /** Every matching document, page by page (unsorted, in ID order). */
+    iterate(query?: Omit<Query, "sort" | "offset" | "after">): AsyncGenerator<Document>;
+    /** How many documents match (all of them without a filter). */
+    count(filter?: Record<string, unknown>): Promise<number>;
+    /** Group and summarize: `{ group_by: ["status"], aggregates: { total: { $sum: "amount" } } }`. */
+    aggregate(spec: Record<string, unknown>): Promise<{
+        rows: Record<string, unknown>[];
+        total_groups: number;
+        matched: number;
+    }>;
+    /** Insert or replace documents matched by key fields (e.g. an ID from another system). */
+    upsert(key: string | string[], docs: Record<string, unknown>[], options?: {
+        idempotencyKey?: string;
+    }): Promise<{
+        inserted: number;
+        replaced: number;
+        ids: string[];
+    }>;
+    /** Merge `update` into every document matching `filter`. */
+    updateWhere(filter: Record<string, unknown>, update: Record<string, unknown>): Promise<{
+        matched: number;
+        modified: number;
+    }>;
+}
+export declare class Stream {
+    private readonly db;
+    readonly name: string;
+    constructor(db: HexDB, name: string);
+    private get path();
+    /** Publish messages; returns their offsets. */
+    publish(...messages: {
+        payload: unknown;
+        key?: string;
+        headers?: Record<string, string>;
+    }[]): Promise<string[]>;
+    /** Messages after an offset or a group's committed offset; waits up to `wait` seconds for new ones. */
+    read(options?: {
+        after?: string;
+        group?: string;
+        limit?: number;
+        wait?: number;
+    }): Promise<{
+        messages: StreamMessage[];
+        next: string | null;
+    }>;
+    /** Commit a consumer group's offset. */
+    commit(group: string, offset: string): Promise<void>;
+    /**
+     * Consume as a group: calls `handle` for each message in order, committing
+     * after each batch it handled. Stops when `signal` aborts.
+     */
+    consume(group: string, handle: (message: StreamMessage) => Promise<void> | void, options?: {
+        signal?: AbortSignal;
+        batch?: number;
+    }): Promise<void>;
+}
+export default HexDB;

package/dist/index.js

@@ -0,0 +1,286 @@
+// HexDB client for Node.js (18+), Deno, Bun and browsers. No dependencies:
+// it speaks HexDB's REST API with fetch.
+//
+//   import { HexDB } from "@dreaminhex/hexdb"
+//   const db = new HexDB({ url: "http://127.0.0.1:7700", apiKey: process.env.HEXDB_API_KEY })
+//   const orders = db.tessellation("orders")
+//   const { id } = await orders.insert({ customer: "ada", total: 12 })
+//   const page = await orders.query({ filter: { total: { $gt: 10 } }, sort: "-total" })
+/** An error answer from HexDB: `status` is the HTTP status, `code` HexDB's error code. */
+export class HexDBError extends Error {
+    status;
+    code;
+    retryAfter;
+    constructor(status, code, message, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.retryAfter = retryAfter;
+        this.name = "HexDBError";
+    }
+}
+const enc = encodeURIComponent;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class HexDB {
+    base;
+    token;
+    retries;
+    timeoutMs;
+    fetcher;
+    constructor(options) {
+        this.base = options.url.replace(/\/+$/, "");
+        this.token = options.apiKey;
+        this.retries = options.retries ?? 3;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.fetcher = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /** Send any request to the REST API and return the parsed JSON (undefined for 204). */
+    async request(method, path, body, headers = {}, timeoutMs = this.timeoutMs) {
+        for (let attempt = 0;; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            let response;
+            try {
+                response = await this.fetcher(this.base + path, {
+                    method,
+                    headers: {
+                        Accept: "application/json",
+                        ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}),
+                        ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                        ...headers,
+                    },
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            catch (e) {
+                throw new HexDBError(0, "unreachable", `Couldn't reach HexDB at ${this.base}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (response.status === 204)
+                return undefined;
+            const text = await response.text();
+            const json = text ? safeJson(text) : undefined;
+            if (response.ok)
+                return json;
+            const retryAfter = Number(response.headers.get("retry-after")) || undefined;
+            // Writes are retried only when they carry an idempotency key.
+            const retryable = (response.status === 429 || response.status === 503) && (method === "GET" || "Idempotency-Key" in headers);
+            if (retryable && attempt < this.retries) {
+                await sleep((retryAfter ?? 2 ** attempt) * 1000);
+                continue;
+            }
+            const error = json?.error;
+            throw new HexDBError(response.status, error?.code ?? "error", error?.message ?? (text || response.statusText), retryAfter);
+        }
+    }
+    /** Sign in with a login and password (and a one-time code with MFA); later requests use the session. */
+    async login(login, password, code) {
+        const result = await this.request("POST", "/auth/login", { login, password, code, return_token: true });
+        this.token = result.token;
+        return { user: result.user, expires_at: result.expires_at };
+    }
+    /** End the session (a no-op for API keys). */
+    async logout() {
+        await this.request("POST", "/auth/logout");
+        this.token = undefined;
+    }
+    /** Whether the server is up (and, signed in, which hex answered). */
+    health() {
+        return this.request("GET", "/health");
+    }
+    /** Server status and metrics (needs the status permission). */
+    status() {
+        return this.request("GET", "/status");
+    }
+    /** A tessellation (collection of documents). */
+    tessellation(name) {
+        return new Tessellation(this, name);
+    }
+    /** Tessellations you can read. */
+    async tessellations() {
+        return (await this.request("GET", "/tessellations")).tessellations;
+    }
+    /**
+     * Operations across tessellations, all or nothing:
+     * `[{ op: "insert" | "replace" | "patch" | "delete" | "get" | "check", tessellation, id?, data?, if_version? }]`.
+     */
+    transaction(operations, options = {}) {
+        return this.request("POST", "/transactions", { operations }, idempotency(options.idempotencyKey));
+    }
+    /** Run a GraphQL query or mutation. Throws on GraphQL errors. */
+    async graphql(query, variables) {
+        const result = await this.request("POST", "/graphql", { query, variables });
+        if (result.errors?.length) {
+            const first = result.errors[0];
+            throw new HexDBError(200, first.extensions?.code ?? "GRAPHQL", first.message);
+        }
+        return result.data;
+    }
+    /**
+     * Committed changes after `after` (default: from now), as they happen.
+     * Long-polls; stops when `signal` aborts.
+     */
+    async *changes(options = {}) {
+        let cursor = options.after;
+        while (!options.signal?.aborted) {
+            const params = new URLSearchParams({ wait: "30", limit: "500" });
+            if (cursor !== undefined)
+                params.set("after", String(cursor));
+            if (options.tessellation)
+                params.set("tessellation", options.tessellation);
+            const page = await this.request("GET", `/changes?${params}`, undefined, {}, 60_000);
+            cursor = page.last_seq;
+            for (const change of page.changes)
+                yield change;
+        }
+    }
+    /** A stream (publish/subscribe). */
+    stream(name) {
+        return new Stream(this, name);
+    }
+    /** Run a saved function with parameters; returns its result. */
+    async runFunction(name, params = {}) {
+        return (await this.request("POST", `/functions/${enc(name)}/run`, { params })).result;
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function idempotency(key) {
+    return key ? { "Idempotency-Key": key } : {};
+}
+function ttl(options) {
+    return options.ttlSeconds ? `?ttl=${options.ttlSeconds}` : "";
+}
+export class Tessellation {
+    db;
+    name;
+    constructor(db, name) {
+        this.db = db;
+        this.name = name;
+    }
+    get path() {
+        return `/${enc(this.name)}`;
+    }
+    /** Insert a document; returns it with its new `id`. */
+    insert(doc, options = {}) {
+        return this.db.request("POST", `${this.path}${ttl(options)}`, doc, idempotency(options.idempotencyKey));
+    }
+    /** Insert up to 1000 documents atomically; returns their IDs in order. */
+    async insertMany(docs, options = {}) {
+        return (await this.db.request("POST", `${this.path}/_bulk${ttl(options)}`, docs, idempotency(options.idempotencyKey))).ids;
+    }
+    /** A document by ID, or null. */
+    async get(id, fields) {
+        try {
+            return await this.db.request("GET", `${this.path}/${enc(id)}${fields ? `?fields=${enc(fields.join(","))}` : ""}`);
+        }
+        catch (e) {
+            if (e instanceof HexDBError && e.status === 404)
+                return null;
+            throw e;
+        }
+    }
+    /** Replace a document's fields. */
+    replace(id, doc, options = {}) {
+        return this.db.request("PUT", `${this.path}/${enc(id)}${ttl(options)}`, doc, idempotency(options.idempotencyKey));
+    }
+    /** Merge fields into a document (null removes a field). */
+    patch(id, changes, options = {}) {
+        return this.db.request("PATCH", `${this.path}/${enc(id)}${ttl(options)}`, changes, idempotency(options.idempotencyKey));
+    }
+    /** Delete a document; false if it didn't exist. */
+    async delete(id, options = {}) {
+        try {
+            await this.db.request("DELETE", `${this.path}/${enc(id)}`, undefined, idempotency(options.idempotencyKey));
+            return true;
+        }
+        catch (e) {
+            if (e instanceof HexDBError && e.status === 404)
+                return false;
+            throw e;
+        }
+    }
+    /** Documents matching a filter, one page at a time. */
+    query(query = {}) {
+        return this.db.request("POST", `${this.path}/_query`, query);
+    }
+    /** Every matching document, page by page (unsorted, in ID order). */
+    async *iterate(query = {}) {
+        let after;
+        for (;;) {
+            const page = await this.query({ ...query, limit: query.limit ?? 500, after });
+            for (const doc of page.documents)
+                yield doc;
+            if (!page.next)
+                return;
+            after = page.next;
+        }
+    }
+    /** How many documents match (all of them without a filter). */
+    async count(filter) {
+        const path = filter ? `${this.path}/count?filter=${enc(JSON.stringify(filter))}` : `${this.path}/count`;
+        return (await this.db.request("GET", path)).count;
+    }
+    /** Group and summarize: `{ group_by: ["status"], aggregates: { total: { $sum: "amount" } } }`. */
+    aggregate(spec) {
+        return this.db.request("POST", `${this.path}/_aggregate`, spec);
+    }
+    /** Insert or replace documents matched by key fields (e.g. an ID from another system). */
+    upsert(key, docs, options = {}) {
+        return this.db.request("POST", `${this.path}/_upsert`, { key, documents: docs }, idempotency(options.idempotencyKey));
+    }
+    /** Merge `update` into every document matching `filter`. */
+    updateWhere(filter, update) {
+        return this.db.request("POST", `${this.path}/_update`, { filter, update });
+    }
+}
+export class Stream {
+    db;
+    name;
+    constructor(db, name) {
+        this.db = db;
+        this.name = name;
+    }
+    get path() {
+        return `/streams/${enc(this.name)}`;
+    }
+    /** Publish messages; returns their offsets. */
+    async publish(...messages) {
+        return (await this.db.request("POST", `${this.path}/messages`, messages)).offsets;
+    }
+    /** Messages after an offset or a group's committed offset; waits up to `wait` seconds for new ones. */
+    read(options = {}) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(options))
+            if (v !== undefined)
+                params.set(k, String(v));
+        return this.db.request("GET", `${this.path}/messages?${params}`, undefined, {}, ((options.wait ?? 0) + 30) * 1000);
+    }
+    /** Commit a consumer group's offset. */
+    commit(group, offset) {
+        return this.db.request("POST", `${this.path}/groups/${enc(group)}/commit`, { offset });
+    }
+    /**
+     * Consume as a group: calls `handle` for each message in order, committing
+     * after each batch it handled. Stops when `signal` aborts.
+     */
+    async consume(group, handle, options = {}) {
+        while (!options.signal?.aborted) {
+            const { messages, next } = await this.read({ group, limit: options.batch ?? 100, wait: 30 });
+            for (const message of messages)
+                await handle(message);
+            if (messages.length > 0 && next)
+                await this.commit(group, next);
+        }
+    }
+}
+export default HexDB;

package/package.json

@@ -1,6 +1,47 @@
-{
-  "name": "@dreaminhex/hexdb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@dreaminhex/hexdb",
+  "version": "1.0.0",
+  "description": "Client for HexDB, the hexagonal document database.",
+  "license": "Apache-2.0",
+  "author": "Dream In Hex",
+  "homepage": "https://hexdb-website.vercel.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dreaminhex/hexdb.git",
+    "directory": "drivers/node"
+  },
+  "bugs": {
+    "url": "https://github.com/dreaminhex/hexdb/issues"
+  },
+  "keywords": [
+    "hexdb",
+    "database",
+    "document",
+    "nosql",
+    "client"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/client.test.mjs"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.3",
+    "@types/node": "^22.15.18"
+  }
+}