@dreaminhex/hexdb 1.0.0 → 1.5.0

package/dist/index.d.ts

@@ -79,6 +79,10 @@ export declare class HexDB {
     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;
@@ -131,10 +135,10 @@ export declare class HexDB {
     runFunction<T = unknown>(name: string, params?: Record<string, unknown>): Promise<T>;
 }
 export declare class Tessellation {
-    private readonly db;
+    protected readonly db: HexDB;
     readonly name: string;
     constructor(db: HexDB, name: string);
-    private get path();
+    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. */
@@ -208,3 +212,80 @@ export declare class Stream {
     }): 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

@@ -6,6 +6,10 @@
 //   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;
@@ -76,6 +80,36 @@ export class HexDB {
             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 });
@@ -284,3 +318,138 @@ export class Stream {
     }
 }
 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,47 +1,47 @@
-{
-  "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"
-  }
-}
+{
+  "name": "@dreaminhex/hexdb",
+  "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"
+  }
+}