frogql-wasm 0.5.4 → 0.5.5

package/README.md

@@ -40,6 +40,40 @@ Verified: a fresh project that `npm install`s the package and runs
 `vite build` bundles the `.wasm` (≈300 kB gzip) with no plugin.
 
 - `open_json(json)` → `Connection`. Parses `{ "nodes": [...], "edges": [...] }`.
+- `open_bytes(gdb, ltj?)` → `Connection`. Opens a real `.gdb` image fetched
+  over the network, paged out of RAM. `ltj` is the matching
+  `<db>.gdb.ltj` sidecar, or `null` to rebuild the index at open.
+
+  ```js
+  const [gdb, ltj] = await Promise.all([
+    fetch("/santiago.gdb").then(r => r.arrayBuffer()),
+    fetch("/santiago.gdb.ltj").then(r => r.arrayBuffer()),
+  ]);
+  const conn = open_bytes(new Uint8Array(gdb), new Uint8Array(ltj));
+  ```
+
+  Prefer it over `open_json` for anything large: a JSON document is parsed
+  and rebuilt node by node and carries no index, while a `.gdb` is already
+  in the engine's layout and its catalog supplies the schema instead of
+  it being re-inferred. Measured on a 459 127-node / 2 244 154-edge graph
+  (309 MB `.gdb`): `open_bytes` in 3.7 s, first query 13 ms.
+
+  **Whether to fetch the sidecar depends on size.** It exists so the six
+  LTJ trie orderings are not rebuilt, which is `O(E log E)` — 252 s
+  measured on a 617 M-edge graph. But decoding it is not free either, and
+  on the 2.2 M-edge graph above the 70 MB sidecar *cost* ~0.8 s against
+  rebuilding in ~1.7 s. Fetch it for a graph big enough that the rebuild
+  hurts; skip it otherwise and save the download. A sidecar that does not
+  describe the database is refused and the index rebuilt, so a mismatched
+  pair costs time and never correctness.
+
+  Read-only as to storage: DML works through the same overlay as every
+  other backend, but there is nowhere to write pages back to, so the
+  durable copy stays whatever the server serves. `to_json()` gives a
+  snapshot of the merged view. Two things a file gives that bytes do not,
+  and which are skipped rather than faked: the legacy-format upgrade
+  (re-save such a database with a native build before serving it) and
+  vector sidecars.
 - `Connection.execute(query, limit?)` → rows array (read queries) or a
   counters object (INSERT / SET / REMOVE / DELETE). `limit` defaults to 100.
 - `Connection.to_json()` → JSON string of the live merged view (base +

package/frogql_wasm.d.ts

@@ -2,12 +2,40 @@
 /* eslint-disable */
 
 /**
- * A live in-memory graph plus the caches that keep query latency flat.
+ * A live graph plus the caches that keep query latency flat.
  */
 export class Connection {
     private constructor();
     free(): void;
     [Symbol.dispose](): void;
+    /**
+     * `{ node_labels, edge_labels, node_count, edge_count }`, mirroring
+     * the Python/Node `schema()` summary.
+     * What the typechecker knows about a query, without running it.
+     *
+     * This is the half of froGQL a REPL shows and a bare "0 rows" hides.
+     * `(n:Calle)-[e]->(m)` against a schema where every `EN_CALLE` points
+     * *into* `Calle` is not an empty answer, it is a **provably** empty
+     * one — the checker settles it before the runtime is asked, and
+     * saying "0 filas" instead sends the reader looking for missing data
+     * that was never missing.
+     *
+     * ```json
+     * { "ok": true, "empty": true, "errors": [], "warnings": [...],
+     *   "vars": [{ "name": "n", "type": "(:Calle {...})" }] }
+     * ```
+     *
+     * The pipeline is run here rather than through
+     * `compile_query_with_diagnostics_with` because that returns the
+     * compiled query and drops the `TypeEnvironment` — and the
+     * environment is the interesting part: it is what the checker
+     * *inferred*, per variable, which no amount of reading the query
+     * back tells you.
+     *
+     * Cheap enough to run on every keystroke: parse, elaborate and check,
+     * with no optimizer pass and no graph access at all.
+     */
+    check(query: string): any;
     /**
      * Execute one GQL statement. Read queries return an array of row
      * objects; data-modifying statements return a counters object.
@@ -16,9 +44,43 @@ export class Connection {
      */
     execute(query: string, limit?: number | null): any;
     /**
-     * `{ node_labels, edge_labels, node_count, edge_count }`, mirroring
-     * the Python/Node `schema()` summary.
+     * The active GRAPH TYPE, rendered the way `SHOW GRAPH TYPE DEFAULT`
+     * renders it in the REPL: one line per node type and one per edge
+     * type, with the properties each carries.
+     *
+     * `schema()` answers "which labels exist", which is what a sidebar
+     * needs and all it needs. This answers "what is in them" — the
+     * question anyone writing a query against an unfamiliar database
+     * actually has, and the one that was unanswerable in the browser
+     * because the formatter was never exposed.
+     *
+     * On a `.gdb` this reads the catalog; on a JSON graph it is inferred
+     * from the data, which is the same split `active_schema` makes.
+     */
+    graph_type(): string;
+    /**
+     * The active GRAPH TYPE as data, so it can be **drawn**.
+     *
+     * `graph_type()` renders the same thing as text, which is what the
+     * REPL shows and what a reader skims. A schema is a graph, though —
+     * node types joined by edge types — and the shape of it is the part
+     * a text listing makes you reconstruct in your head. This returns
+     * the pieces a diagram needs and lets the page draw them.
+     *
+     * ```json
+     * { "nodes": [{ "name": "fpl", "labels": ["Fpl"],
+     *               "props": [{ "key": "fplId", "type": "STRING" }] }],
+     *   "edges": [{ "label": "SALE_DE", "from": "fpl", "to": "aerodromo",
+     *               "directed": true, "props": [] }] }
+     * ```
+     *
+     * Endpoints are the *names* `typing::format::NodeTypeNames` derives,
+     * so the diagram and the text call a type the same thing. An edge
+     * whose endpoint matches no declared node type gets `null` there
+     * rather than a name that would misdescribe it — the same care
+     * `format_schema` takes when it declines to borrow a name.
      */
+    graph_type_json(): any;
     schema(): any;
     /**
      * Serialise the live merged view (base + overlay) to a JSON string —
@@ -30,6 +92,33 @@ export class Connection {
     readonly node_count: number;
 }
 
+/**
+ * Open a `.gdb` image fetched over the network, with its `.ltj` sidecar
+ * when the caller has it.
+ *
+ * ```js
+ * const [gdb, ltj] = await Promise.all([
+ *   fetch("/santiago.gdb").then(r => r.arrayBuffer()),
+ *   fetch("/santiago.gdb.ltj").then(r => r.arrayBuffer()),
+ * ]);
+ * const conn = open_bytes(new Uint8Array(gdb), new Uint8Array(ltj));
+ * ```
+ *
+ * `ltj` is optional and is the reason to prefer this over `open_json`
+ * for anything large: without it the six LTJ trie orderings are rebuilt
+ * at open, which is `O(E log E)`. A sidecar that does not describe this
+ * database is **refused, not trusted** — the same `(graph_id,
+ * node_count, edge_count)` fingerprint a file-backed open checks — and
+ * the index is rebuilt instead, so a mismatched pair costs time and
+ * never correctness.
+ *
+ * The connection is read-mostly: DML works, through the same overlay as
+ * every other backend, but there is nowhere to write pages back to, so
+ * the durable copy is whatever the server serves. `to_json()` still
+ * gives a snapshot of the merged view.
+ */
+export function open_bytes(gdb: Uint8Array, ltj?: Uint8Array | null): Connection;
+
 /**
  * Parse a JSON graph document (`{"nodes": [...], "edges": [...]}`) and
  * open a connection over it. Warms the LTJ index eagerly so the first
@@ -42,11 +131,15 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_connection_free: (a: number, b: number) => void;
+    readonly connection_check: (a: number, b: number, c: number) => [number, number, number];
     readonly connection_edge_count: (a: number) => number;
     readonly connection_execute: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly connection_graph_type: (a: number) => [number, number];
+    readonly connection_graph_type_json: (a: number) => [number, number, number];
     readonly connection_node_count: (a: number) => number;
     readonly connection_schema: (a: number) => [number, number, number];
     readonly connection_to_json: (a: number) => [number, number];
+    readonly open_bytes: (a: number, b: number, c: number, d: number) => [number, number, number];
     readonly open_json: (a: number, b: number) => [number, number, number];
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;

package/frogql_wasm.js

@@ -1,7 +1,7 @@
 /* @ts-self-types="./frogql_wasm.d.ts" */
 
 /**
- * A live in-memory graph plus the caches that keep query latency flat.
+ * A live graph plus the caches that keep query latency flat.
  */
 export class Connection {
     static __wrap(ptr) {
@@ -20,6 +20,44 @@ export class Connection {
         const ptr = this.__destroy_into_raw();
         wasm.__wbg_connection_free(ptr, 0);
     }
+    /**
+     * `{ node_labels, edge_labels, node_count, edge_count }`, mirroring
+     * the Python/Node `schema()` summary.
+     * What the typechecker knows about a query, without running it.
+     *
+     * This is the half of froGQL a REPL shows and a bare "0 rows" hides.
+     * `(n:Calle)-[e]->(m)` against a schema where every `EN_CALLE` points
+     * *into* `Calle` is not an empty answer, it is a **provably** empty
+     * one — the checker settles it before the runtime is asked, and
+     * saying "0 filas" instead sends the reader looking for missing data
+     * that was never missing.
+     *
+     * ```json
+     * { "ok": true, "empty": true, "errors": [], "warnings": [...],
+     *   "vars": [{ "name": "n", "type": "(:Calle {...})" }] }
+     * ```
+     *
+     * The pipeline is run here rather than through
+     * `compile_query_with_diagnostics_with` because that returns the
+     * compiled query and drops the `TypeEnvironment` — and the
+     * environment is the interesting part: it is what the checker
+     * *inferred*, per variable, which no amount of reading the query
+     * back tells you.
+     *
+     * Cheap enough to run on every keystroke: parse, elaborate and check,
+     * with no optimizer pass and no graph access at all.
+     * @param {string} query
+     * @returns {any}
+     */
+    check(query) {
+        const ptr0 = passStringToWasm0(query, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.connection_check(this.__wbg_ptr, ptr0, len0);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @returns {number}
      */
@@ -45,6 +83,63 @@ export class Connection {
         }
         return takeFromExternrefTable0(ret[0]);
     }
+    /**
+     * The active GRAPH TYPE, rendered the way `SHOW GRAPH TYPE DEFAULT`
+     * renders it in the REPL: one line per node type and one per edge
+     * type, with the properties each carries.
+     *
+     * `schema()` answers "which labels exist", which is what a sidebar
+     * needs and all it needs. This answers "what is in them" — the
+     * question anyone writing a query against an unfamiliar database
+     * actually has, and the one that was unanswerable in the browser
+     * because the formatter was never exposed.
+     *
+     * On a `.gdb` this reads the catalog; on a JSON graph it is inferred
+     * from the data, which is the same split `active_schema` makes.
+     * @returns {string}
+     */
+    graph_type() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.connection_graph_type(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * The active GRAPH TYPE as data, so it can be **drawn**.
+     *
+     * `graph_type()` renders the same thing as text, which is what the
+     * REPL shows and what a reader skims. A schema is a graph, though —
+     * node types joined by edge types — and the shape of it is the part
+     * a text listing makes you reconstruct in your head. This returns
+     * the pieces a diagram needs and lets the page draw them.
+     *
+     * ```json
+     * { "nodes": [{ "name": "fpl", "labels": ["Fpl"],
+     *               "props": [{ "key": "fplId", "type": "STRING" }] }],
+     *   "edges": [{ "label": "SALE_DE", "from": "fpl", "to": "aerodromo",
+     *               "directed": true, "props": [] }] }
+     * ```
+     *
+     * Endpoints are the *names* `typing::format::NodeTypeNames` derives,
+     * so the diagram and the text call a type the same thing. An edge
+     * whose endpoint matches no declared node type gets `null` there
+     * rather than a name that would misdescribe it — the same care
+     * `format_schema` takes when it declines to borrow a name.
+     * @returns {any}
+     */
+    graph_type_json() {
+        const ret = wasm.connection_graph_type_json(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
     /**
      * @returns {number}
      */
@@ -53,8 +148,6 @@ export class Connection {
         return ret >>> 0;
     }
     /**
-     * `{ node_labels, edge_labels, node_count, edge_count }`, mirroring
-     * the Python/Node `schema()` summary.
      * @returns {any}
      */
     schema() {
@@ -85,6 +178,46 @@ export class Connection {
 }
 if (Symbol.dispose) Connection.prototype[Symbol.dispose] = Connection.prototype.free;
 
+/**
+ * Open a `.gdb` image fetched over the network, with its `.ltj` sidecar
+ * when the caller has it.
+ *
+ * ```js
+ * const [gdb, ltj] = await Promise.all([
+ *   fetch("/santiago.gdb").then(r => r.arrayBuffer()),
+ *   fetch("/santiago.gdb.ltj").then(r => r.arrayBuffer()),
+ * ]);
+ * const conn = open_bytes(new Uint8Array(gdb), new Uint8Array(ltj));
+ * ```
+ *
+ * `ltj` is optional and is the reason to prefer this over `open_json`
+ * for anything large: without it the six LTJ trie orderings are rebuilt
+ * at open, which is `O(E log E)`. A sidecar that does not describe this
+ * database is **refused, not trusted** — the same `(graph_id,
+ * node_count, edge_count)` fingerprint a file-backed open checks — and
+ * the index is rebuilt instead, so a mismatched pair costs time and
+ * never correctness.
+ *
+ * The connection is read-mostly: DML works, through the same overlay as
+ * every other backend, but there is nowhere to write pages back to, so
+ * the durable copy is whatever the server serves. `to_json()` still
+ * gives a snapshot of the merged view.
+ * @param {Uint8Array} gdb
+ * @param {Uint8Array | null} [ltj]
+ * @returns {Connection}
+ */
+export function open_bytes(gdb, ltj) {
+    const ptr0 = passArray8ToWasm0(gdb, wasm.__wbindgen_malloc);
+    const len0 = WASM_VECTOR_LEN;
+    var ptr1 = isLikeNone(ltj) ? 0 : passArray8ToWasm0(ltj, wasm.__wbindgen_malloc);
+    var len1 = WASM_VECTOR_LEN;
+    const ret = wasm.open_bytes(ptr0, len0, ptr1, len1);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return Connection.__wrap(ret[0]);
+}
+
 /**
  * Parse a JSON graph document (`{"nodes": [...], "edges": [...]}`) and
  * open a connection over it. Warms the LTJ index eagerly so the first
@@ -234,6 +367,13 @@ function isLikeNone(x) {
     return x === undefined || x === null;
 }
 
+function passArray8ToWasm0(arg, malloc) {
+    const ptr = malloc(arg.length * 1, 1) >>> 0;
+    getUint8ArrayMemory0().set(arg, ptr / 1);
+    WASM_VECTOR_LEN = arg.length;
+    return ptr;
+}
+
 function passStringToWasm0(arg, malloc, realloc) {
     if (realloc === undefined) {
         const buf = cachedTextEncoder.encode(arg);

package/package.json

@@ -2,7 +2,7 @@
   "name": "frogql-wasm",
   "type": "module",
   "description": "froGQL — embedded GQL graph database with ISO GQL path patterns (Rust core, WebAssembly bindings for the browser)",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "license": "MIT",
   "repository": {
     "type": "git",