@dreaminhex/hexdb 0.0.0-stage → 1.5.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,291 @@
+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>;
+    /** Send raw bytes (or nothing) and get the raw response; throws HexDBError on an error answer. */
+    requestRaw(method: Method, path: string, body?: BodyInit, headers?: Record<string, string>, timeoutMs?: number): Promise<Response>;
+    /** A files tessellation (photos, audio, video, documents: any binary file). */
+    files(name: string): Files;
+    /** 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 {
+    protected readonly db: HexDB;
+    readonly name: string;
+    constructor(db: HexDB, name: string);
+    protected get path(): string;
+    /** 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;
+/** A file's document: its metadata. */
+export type FileDocument = Document & {
+    name: string;
+    path: string;
+    size: number;
+    content_type: string;
+    sha256: string;
+    version: number;
+    meta?: Record<string, unknown>;
+    extract?: {
+        status: "pending" | "done";
+        extractors?: string[];
+        errors?: string[];
+    };
+    thumbnail?: {
+        width: number;
+        height: number;
+        content_type: string;
+    };
+};
+export interface UploadOptions {
+    contentType?: string;
+    /** When the file was last modified (RFC 3339 or epoch milliseconds). */
+    modified?: string | number;
+    /** Bytes sent so far, for progress. */
+    onProgress?: (sent: number) => void;
+}
+/**
+ * A files tessellation: each file's metadata is a document (query it like
+ * any tessellation); its content is uploaded and downloaded here. Paths are
+ * `folder/name`. Uploading to a path that has a file makes a new version.
+ */
+export declare class Files extends Tessellation {
+    /** Create the files tessellation (no error if it exists). */
+    create(): Promise<{
+        name: string;
+        kind: string;
+    }>;
+    /** Upload bytes or a Blob to `path`. Files of 16 MB and more go in resumable parts. */
+    upload(path: string, data: Uint8Array | ArrayBuffer | Blob, options?: UploadOptions): Promise<FileDocument>;
+    private contentPath;
+    /** A file's content (by `folder/name` or ID), or an earlier version's. */
+    download(pathOrId: string, options?: {
+        version?: number;
+    }): Promise<Uint8Array>;
+    /** A file's content as a stream (for large files). */
+    downloadStream(pathOrId: string, options?: {
+        version?: number;
+    }): Promise<ReadableStream<Uint8Array>>;
+    /** Bytes `start` to `end` (exclusive) of a file. */
+    readRange(pathOrId: string, start: number, end: number): Promise<Uint8Array>;
+    /** A file's document (metadata), or null. */
+    stat(pathOrId: string): Promise<FileDocument | null>;
+    /** The files directly in a folder, by name. */
+    list(folder?: string, limit?: number): Promise<FileDocument[]>;
+    /** Files whose name, folders, tags or extracted metadata contain every word of `text`. */
+    search(text: string, filter?: Record<string, unknown>, limit?: number): Promise<FileDocument[]>;
+    /** A small JPEG or PNG of an image (once its metadata has been read). */
+    thumbnail(id: string): Promise<Uint8Array>;
+    versions(id: string): Promise<{
+        id: string;
+        current: Record<string, unknown>;
+        versions: Record<string, unknown>[];
+    }>;
+    /** Make an earlier version current again (as a new version). */
+    restoreVersion(id: string, version: number): Promise<FileDocument>;
+    /** Deleted files (`delete` moves a file to the trash). */
+    trash(): Promise<FileDocument[]>;
+    restore(id: string, options?: {
+        name?: string;
+        path?: string;
+    }): Promise<FileDocument>;
+    /** Delete a trashed file for good. */
+    purge(id: string): Promise<void>;
+    /** Read metadata again (one file, or all); returns how many were queued. */
+    reextract(id?: string): Promise<number>;
+}

package/dist/index.js

@@ -0,0 +1,455 @@
+// 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" })
+//
+//   const media = db.files("media")            // a files tessellation
+//   await media.upload("photos/IMG_1.jpg", bytes)
+//   const hits = await media.search("glacier")  // names, tags and extracted metadata
+/** 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);
+        }
+    }
+    /** Send raw bytes (or nothing) and get the raw response; throws HexDBError on an error answer. */
+    async requestRaw(method, path, body, headers = {}, timeoutMs = 600_000) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let response;
+        try {
+            response = await this.fetcher(this.base + path, {
+                method,
+                headers: { ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}), ...headers },
+                body,
+                signal: controller.signal,
+            });
+        }
+        catch (e) {
+            clearTimeout(timer);
+            throw new HexDBError(0, "unreachable", `Couldn't reach HexDB at ${this.base}: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        // The body may still be streaming; the timer covers the headers only.
+        clearTimeout(timer);
+        if (!response.ok) {
+            const text = await response.text();
+            const error = safeJson(text)?.error;
+            throw new HexDBError(response.status, error?.code ?? "error", error?.message ?? (text || response.statusText));
+        }
+        return response;
+    }
+    /** A files tessellation (photos, audio, video, documents: any binary file). */
+    files(name) {
+        return new Files(this, name);
+    }
+    /** 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;
+const RESUMABLE_FROM = 16 * 1024 * 1024;
+const PART = 8 * 1024 * 1024;
+const ULID = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+function filePath(path) {
+    return path
+        .split(/[\\/]/)
+        .filter(Boolean)
+        .map(enc)
+        .join("/");
+}
+/**
+ * A files tessellation: each file's metadata is a document (query it like
+ * any tessellation); its content is uploaded and downloaded here. Paths are
+ * `folder/name`. Uploading to a path that has a file makes a new version.
+ */
+export class Files extends Tessellation {
+    /** Create the files tessellation (no error if it exists). */
+    async create() {
+        try {
+            return await this.db.request("POST", "/tessellations", { name: this.name, kind: "files" });
+        }
+        catch (e) {
+            if (e instanceof HexDBError && e.status === 409)
+                return this.db.request("GET", `/tessellations/${enc(this.name)}`);
+            throw e;
+        }
+    }
+    /** Upload bytes or a Blob to `path`. Files of 16 MB and more go in resumable parts. */
+    async upload(path, data, options = {}) {
+        const blob = data instanceof Blob ? data : new Blob([data]);
+        const modified = options.modified === undefined ? undefined : String(options.modified);
+        if (blob.size < RESUMABLE_FROM) {
+            const query = modified ? `?modified=${enc(modified)}` : "";
+            const response = await this.db.requestRaw("PUT", `${this.path}/_files/${filePath(path)}${query}`, blob, options.contentType ? { "Content-Type": options.contentType } : {});
+            options.onProgress?.(blob.size);
+            return (await response.json());
+        }
+        const session = await this.db.request("POST", `${this.path}/_uploads`, { path, size: blob.size, content_type: options.contentType, modified });
+        const url = `${this.path}/_uploads/${enc(session.id)}`;
+        for (let offset = 0; offset < blob.size;) {
+            const end = Math.min(offset + PART, blob.size);
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await this.db.requestRaw("PATCH", `${url}?offset=${offset}`, blob.slice(offset, end));
+                    break;
+                }
+                catch (e) {
+                    if (attempt >= 3)
+                        throw e;
+                    await sleep(1000 * (attempt + 1));
+                    const status = await this.db.request("GET", url);
+                    if (status.offset >= end)
+                        break;
+                }
+            }
+            offset = end;
+            options.onProgress?.(offset);
+        }
+        return this.db.request("POST", `${url}/complete`, undefined, {}, 600_000);
+    }
+    contentPath(pathOrId, version) {
+        const query = version === undefined ? "" : `?version=${version}`;
+        return ULID.test(pathOrId) ? `${this.path}/${enc(pathOrId)}/content${query}` : `${this.path}/_files/${filePath(pathOrId)}${query}`;
+    }
+    /** A file's content (by `folder/name` or ID), or an earlier version's. */
+    async download(pathOrId, options = {}) {
+        const response = await this.db.requestRaw("GET", this.contentPath(pathOrId, options.version));
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    /** A file's content as a stream (for large files). */
+    async downloadStream(pathOrId, options = {}) {
+        const response = await this.db.requestRaw("GET", this.contentPath(pathOrId, options.version));
+        if (!response.body)
+            throw new HexDBError(0, "empty", "The response had no body.");
+        return response.body;
+    }
+    /** Bytes `start` to `end` (exclusive) of a file. */
+    async readRange(pathOrId, start, end) {
+        const response = await this.db.requestRaw("GET", this.contentPath(pathOrId), undefined, { Range: `bytes=${start}-${end - 1}` });
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    /** A file's document (metadata), or null. */
+    async stat(pathOrId) {
+        if (ULID.test(pathOrId))
+            return (await this.get(pathOrId));
+        const parts = pathOrId.split(/[\\/]/).filter(Boolean);
+        const name = parts.pop() ?? "";
+        const folder = parts.length ? `/${parts.join("/")}/` : "/";
+        const page = await this.query({ filter: { path: folder, name }, limit: 1 });
+        return page.documents[0] ?? null;
+    }
+    /** The files directly in a folder, by name. */
+    async list(folder = "/", limit = 1000) {
+        const parts = folder.split(/[\\/]/).filter(Boolean);
+        const path = parts.length ? `/${parts.join("/")}/` : "/";
+        return (await this.query({ filter: { path }, sort: "name", limit })).documents;
+    }
+    /** Files whose name, folders, tags or extracted metadata contain every word of `text`. */
+    async search(text, filter = {}, limit = 100) {
+        return (await this.query({ filter: { $text: text, ...filter }, limit })).documents;
+    }
+    /** A small JPEG or PNG of an image (once its metadata has been read). */
+    async thumbnail(id) {
+        const response = await this.db.requestRaw("GET", `${this.path}/${enc(id)}/thumbnail`);
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    versions(id) {
+        return this.db.request("GET", `${this.path}/${enc(id)}/versions`);
+    }
+    /** Make an earlier version current again (as a new version). */
+    restoreVersion(id, version) {
+        return this.db.request("POST", `${this.path}/${enc(id)}/versions/${version}/restore`);
+    }
+    /** Deleted files (`delete` moves a file to the trash). */
+    async trash() {
+        return (await this.db.request("GET", `${this.path}/_trash`)).documents;
+    }
+    restore(id, options = {}) {
+        const params = new URLSearchParams();
+        if (options.name)
+            params.set("name", options.name);
+        if (options.path)
+            params.set("path", options.path);
+        const query = params.toString();
+        return this.db.request("POST", `${this.path}/_trash/${enc(id)}/restore${query ? `?${query}` : ""}`);
+    }
+    /** Delete a trashed file for good. */
+    async purge(id) {
+        await this.db.request("DELETE", `${this.path}/_trash/${enc(id)}`);
+    }
+    /** Read metadata again (one file, or all); returns how many were queued. */
+    async reextract(id) {
+        return (await this.db.request("POST", `${this.path}/_reextract${id ? `?id=${enc(id)}` : ""}`)).queued;
+    }
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@dreaminhex/hexdb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.5.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"
+  }
+}