nucleation 0.10.22 → 0.10.23

package/renderer/Store.mjs

@@ -0,0 +1,369 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import { Schematic } from "./Schematic.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Store_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Store_destroy(ptr);
+});
+
+/**
+ * A key/value store opened from a URL (e.g. `mem://`, `file:///path`,
+ * `ssh://user@host/path`, `s3://bucket/prefix`, `redis://…`, `postgres://…`).
+ */
+export class Store {
+    // Internal ptr reference:
+    #ptr = null;
+
+    // Lifetimes are only to keep dependencies alive.
+    // Since JS won't garbage collect until there are no incoming edges.
+    #selfEdge = [];
+
+    #internalConstructor(symbol, ptr, selfEdge) {
+        if (symbol !== diplomatRuntime.internalConstructor) {
+            console.error("Store is an Opaque type. You cannot call its constructor.");
+            return;
+        }
+        this.#ptr = ptr;
+        this.#selfEdge = selfEdge;
+
+        // Are we being borrowed? If not, we can register.
+        if (this.#selfEdge.length === 0) {
+            Store_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Open a store from a URL. Errors with `Store` on an unknown scheme or
+     * connection failure.
+     */
+    static open(url) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const urlSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, url)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Store_open(diplomatReceive.buffer, urlSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return new Store(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Fetch `key`, writing the value as base64 (PORTING rule 6). Errors with
+     * `NotFound` when the key is absent.
+     */
+    getB64(key) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keySlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, key)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Store_get_b64(diplomatReceive.buffer, this.ffiValue, keySlice.ptr, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Store `data` at `key`.
+     */
+    put(key, data) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keySlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, key)));
+        const dataSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, data, "u8")));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Store_put(diplomatReceive.buffer, this.ffiValue, keySlice.ptr, dataSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Whether `key` exists.
+     */
+    exists(key) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keySlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, key)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 1, true);
+
+
+        const result = wasm.Store_exists(diplomatReceive.buffer, this.ffiValue, keySlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return (new Uint8Array(wasm.memory.buffer, diplomatReceive.buffer, 1))[0] === 1;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Delete `key` (idempotent).
+     */
+    delete_(key) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keySlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, key)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Store_delete(diplomatReceive.buffer, this.ffiValue, keySlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * List keys under `prefix`, written as a JSON array string.
+     */
+    list(prefix) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const prefixSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, prefix)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Store_list(diplomatReceive.buffer, this.ffiValue, prefixSlice.ptr, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Atomically write `data` at `key` only if it does not already exist.
+     * Returns `true` if written, `false` if the key existed.
+     */
+    putIfAbsent(key, data) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keySlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, key)));
+        const dataSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, data, "u8")));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 1, true);
+
+
+        const result = wasm.Store_put_if_absent(diplomatReceive.buffer, this.ffiValue, keySlice.ptr, dataSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return (new Uint8Array(wasm.memory.buffer, diplomatReceive.buffer, 1))[0] === 1;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * A keyset page of keys under `prefix`. `after` is the exclusive cursor
+     * (empty string for the first page); at most `limit` keys are returned.
+     * Writes a JSON object string `{"keys":[...],"next":"…"|null}`.
+     */
+    listPaginated(prefix, after, limit) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const prefixSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, prefix)));
+        const afterSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, after)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Store_list_paginated(diplomatReceive.buffer, this.ffiValue, prefixSlice.ptr, afterSlice.ptr, limit, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Health check: `Ok` when the store is usable.
+     */
+    health() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Store_health(diplomatReceive.buffer, this.ffiValue);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Open a schematic stored at `key` in this store. Works for every
+     * backend, including `redis://`/`postgres://`/`mem://` that the
+     * single-string URI form (`StoreIo::open`) rejects.
+     */
+    openSchematic(key) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keySlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, key)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Store_open_schematic(diplomatReceive.buffer, this.ffiValue, keySlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return new Schematic(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Save a schematic at `key` in this store. `version` selects the format
+     * version (empty string = format default). Works for every backend,
+     * including `redis://`/`postgres://`/`mem://` that the single-string URI
+     * form (`StoreIo::save`) rejects.
+     */
+    saveSchematic(schematic, key, version) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keySlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, key)));
+        const versionSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, version)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Store_save_schematic(diplomatReceive.buffer, this.ffiValue, schematic.ffiValue, keySlice.ptr, versionSlice.ptr);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/StoreIo.d.mts

@@ -0,0 +1,71 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Namespace type for the URI-based transparent I/O and format-manager
+ * queries (PORTING rule 12).
+ */
+export class StoreIo {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Open a schematic from a URI: a local path, `file://...`, or
+     * `s3://bucket/key.schem`. The format is auto-detected from the URI's
+     * extension. Single-string URIs for `redis://`, `postgres://`, and
+     * `mem://` are rejected by the core resolver; use `Store::open_schematic`
+     * with an explicit store for those backends.
+     */
+    static open(uri: string): Schematic;
+
+    /**
+     * Save a schematic to a URI: a local path, `file://...`, or
+     * `s3://bucket/key.schem`. The format is auto-detected from the URI's
+     * extension; `version` selects the format version (empty string =
+     * format default). Single-string URIs for `redis://`, `postgres://`, and
+     * `mem://` are rejected by the core resolver; use `Store::save_schematic`
+     * with an explicit store for those backends.
+     */
+    static save(schematic: Schematic, uri: string, version: string): void;
+
+    /**
+     * The JSON schema describing the export settings of `format`. Errors
+     * with `NotFound` for an unknown format.
+     */
+    static exportSettingsSchema(format: string): string;
+
+    /**
+     * The JSON schema describing the import settings of `format`. Errors
+     * with `NotFound` for an unknown format.
+     */
+    static importSettingsSchema(format: string): string;
+
+    /**
+     * The supported import formats, written as a JSON array string.
+     */
+    static supportedImportFormats(): string;
+
+    /**
+     * The supported export formats, written as a JSON array string.
+     */
+    static supportedExportFormats(): string;
+
+    /**
+     * The known versions of an export format, written as a JSON array string
+     * (empty array for an unknown format, matching the old ABI).
+     */
+    static formatVersions(format: string): string;
+
+    /**
+     * The default version of an export format. Errors with `NotFound` for an
+     * unknown format.
+     */
+    static defaultFormatVersion(format: string): string;
+}

package/renderer/StoreIo.d.ts

@@ -0,0 +1,71 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Namespace type for the URI-based transparent I/O and format-manager
+ * queries (PORTING rule 12).
+ */
+export class StoreIo {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Open a schematic from a URI: a local path, `file://...`, or
+     * `s3://bucket/key.schem`. The format is auto-detected from the URI's
+     * extension. Single-string URIs for `redis://`, `postgres://`, and
+     * `mem://` are rejected by the core resolver; use `Store::open_schematic`
+     * with an explicit store for those backends.
+     */
+    static open(uri: string): Schematic;
+
+    /**
+     * Save a schematic to a URI: a local path, `file://...`, or
+     * `s3://bucket/key.schem`. The format is auto-detected from the URI's
+     * extension; `version` selects the format version (empty string =
+     * format default). Single-string URIs for `redis://`, `postgres://`, and
+     * `mem://` are rejected by the core resolver; use `Store::save_schematic`
+     * with an explicit store for those backends.
+     */
+    static save(schematic: Schematic, uri: string, version: string): void;
+
+    /**
+     * The JSON schema describing the export settings of `format`. Errors
+     * with `NotFound` for an unknown format.
+     */
+    static exportSettingsSchema(format: string): string;
+
+    /**
+     * The JSON schema describing the import settings of `format`. Errors
+     * with `NotFound` for an unknown format.
+     */
+    static importSettingsSchema(format: string): string;
+
+    /**
+     * The supported import formats, written as a JSON array string.
+     */
+    static supportedImportFormats(): string;
+
+    /**
+     * The supported export formats, written as a JSON array string.
+     */
+    static supportedExportFormats(): string;
+
+    /**
+     * The known versions of an export format, written as a JSON array string
+     * (empty array for an unknown format, matching the old ABI).
+     */
+    static formatVersions(format: string): string;
+
+    /**
+     * The default version of an export format. Errors with `NotFound` for an
+     * unknown format.
+     */
+    static defaultFormatVersion(format: string): string;
+}