tauri-plugin-configurate-api 0.1.0

package/dist-js/index.js

@@ -0,0 +1,485 @@
+import { invoke } from '@tauri-apps/api/core';
+export { BaseDirectory } from '@tauri-apps/api/path';
+
+// ---------------------------------------------------------------------------
+// Keyring marker types
+// ---------------------------------------------------------------------------
+/**
+ * Brand key used to tag keyring-protected fields at runtime.
+ *
+ * A plain string property is used instead of a `Symbol` because some bundlers
+ * (Vite / esbuild pre-bundling) incorrectly hoist computed `Symbol` property
+ * keys out of scope, causing `_keyringBrand is not defined` errors at runtime.
+ *
+ * The string is long and namespaced to avoid accidental collisions with
+ * user-defined keys.
+ */
+const KEYRING_BRAND_KEY = "__configurate_keyring__";
+/**
+ * Marks a schema field as keyring-protected.
+ *
+ * @example
+ * ```ts
+ * const schema = defineConfig({
+ *   apiKey: keyring(String, { id: "api-key" }),
+ * });
+ * ```
+ */
+function keyring(_type, opts) {
+    // Avoid computed property key syntax `{ [KEYRING_BRAND_KEY]: true }` in an
+    // object literal.  Some bundlers (Vite / esbuild pre-bundling) incorrectly
+    // hoist the evaluated key expression out of the enclosing function scope,
+    // producing a "X is not defined" ReferenceError at runtime.
+    // Assigning via bracket notation after construction is semantically
+    // identical but is never subject to that hoisting behaviour.
+    const field = { _type: undefined, _id: opts.id };
+    field[KEYRING_BRAND_KEY] = true;
+    return field;
+}
+// ---------------------------------------------------------------------------
+// Internal runtime helpers
+// ---------------------------------------------------------------------------
+/** Runtime check: is this value a KeyringField marker? */
+function isKeyringField(val) {
+    return (typeof val === "object" &&
+        val !== null &&
+        val[KEYRING_BRAND_KEY] === true);
+}
+/** Runtime check: is this value a nested SchemaObject? */
+function isSchemaObject(val) {
+    return typeof val === "object" && val !== null && !isKeyringField(val);
+}
+/**
+ * Recursively collects all keyring ids from a schema as a flat string array.
+ * Used for runtime duplicate validation.
+ */
+function collectKeyringIds(schema) {
+    const ids = [];
+    for (const val of Object.values(schema)) {
+        if (isKeyringField(val)) {
+            ids.push(val._id);
+        }
+        else if (isSchemaObject(val)) {
+            ids.push(...collectKeyringIds(val));
+        }
+    }
+    return ids;
+}
+/**
+ * Recursively collects all keyring entries as `{ id, dotpath }` pairs.
+ * `dotpath` is the dot-separated path to the field inside the config object.
+ */
+function collectKeyringPaths(schema, prefix = "") {
+    const result = [];
+    for (const [key, val] of Object.entries(schema)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (isKeyringField(val)) {
+            result.push({ id: val._id, dotpath: path });
+        }
+        else if (isSchemaObject(val)) {
+            result.push(...collectKeyringPaths(val, path));
+        }
+    }
+    return result;
+}
+/**
+ * Separates a data object into non-secret plain fields and keyring entries.
+ * Secret values are extracted from their dotpath locations and serialized to
+ * strings so the Rust side can store them in the OS keyring.
+ * The corresponding dotpath in `plain` is set to `null` so secrets are never
+ * persisted to disk.
+ */
+function separateSecrets(data, keyringPaths) {
+    const plain = structuredClone(data);
+    const keyringEntries = [];
+    for (const { id, dotpath } of keyringPaths) {
+        const parts = dotpath.split(".");
+        let node = plain;
+        for (let i = 0; i < parts.length - 1; i++) {
+            if (node === null || typeof node !== "object")
+                break;
+            node = node[parts[i] ?? ""];
+        }
+        const last = parts.at(-1) ?? "";
+        // Guard: after traversal node must still be a plain object.
+        if (node === null || typeof node !== "object")
+            continue;
+        const parent = node;
+        if (last in parent) {
+            const secret = parent[last];
+            const serialized = typeof secret === "string" ? secret : JSON.stringify(secret);
+            keyringEntries.push({ id, dotpath, value: serialized });
+            // Nullify the secret in the plain data so it is never written to disk.
+            parent[last] = null;
+        }
+    }
+    return { plain, keyringEntries };
+}
+// ---------------------------------------------------------------------------
+// LockedConfig
+// ---------------------------------------------------------------------------
+/**
+ * A loaded configuration where keyring-protected fields are `null`.
+ * Call `.unlock(opts)` to fetch secrets and obtain an `UnlockedConfig<S>`.
+ *
+ * `unlock()` issues a single IPC call that only reads from the OS keyring —
+ * it does **not** re-read the file from disk.
+ */
+class LockedConfig {
+    _configurate;
+    data;
+    /** @internal */
+    constructor(data, _configurate) {
+        this._configurate = _configurate;
+        this.data = data;
+    }
+    /**
+     * Fetches all keyring secrets and returns an `UnlockedConfig`.
+     * Issues a single IPC call (keyring read only – file is not re-read).
+     */
+    async unlock(opts) {
+        return this._configurate._unlockFromData(this.data, opts);
+    }
+}
+// ---------------------------------------------------------------------------
+// UnlockedConfig
+// ---------------------------------------------------------------------------
+/**
+ * A configuration where all keyring-protected fields contain their real values.
+ * Call `.lock()` to discard in-memory secrets (no IPC required).
+ */
+class UnlockedConfig {
+    _data;
+    /** @internal */
+    constructor(data) {
+        this._data = data;
+    }
+    /**
+     * Returns the unlocked configuration data.
+     * Throws if `lock()` has already been called.
+     */
+    get data() {
+        if (this._data === null) {
+            throw new Error("Cannot access data after lock() has been called. " +
+                "Load or unlock the config again to get a fresh instance.");
+        }
+        return this._data;
+    }
+    /**
+     * Discards in-memory secrets. Callers should drop all references to this
+     * object after calling `lock()`.
+     *
+     * > **Security note** — JavaScript does not provide a guaranteed way to
+     * > zero-out memory. Calling `lock()` nullifies the top-level reference
+     * > but the secret values remain in the JS heap until the GC collects them.
+     * > Avoid long-lived `UnlockedConfig` objects when handling sensitive data.
+     */
+    lock() {
+        this._data = null;
+    }
+}
+// ---------------------------------------------------------------------------
+// LazyConfigEntry
+// ---------------------------------------------------------------------------
+/**
+ * A lazy handle returned by `Configurate.load()`, `.create()` and `.save()`.
+ *
+ * - `await entry.run()` → `LockedConfig<S>` (one IPC, secrets are null)
+ * - `await entry.unlock(opts)` → `UnlockedConfig<S>` (one IPC, secrets inlined)
+ * - `.lock(opts)` (before awaiting) → write secrets to keyring in the same IPC
+ *
+ * Use `await entry.run()` instead of `await entry` directly to avoid the
+ * `no-thenable` lint rule and unintended Promise behaviour.
+ */
+class LazyConfigEntry {
+    _configurate;
+    _op;
+    _data;
+    _keyringOpts = null;
+    /** @internal */
+    constructor(_configurate, _op, _data) {
+        this._configurate = _configurate;
+        this._op = _op;
+        this._data = _data;
+    }
+    /**
+     * Attaches keyring options so secrets are written to / read from the OS
+     * keyring in the same IPC call as the main operation.
+     *
+     * Returns `this` to allow chaining: `entry.lock(opts).run()`.
+     */
+    lock(opts) {
+        this._keyringOpts = opts;
+        return this;
+    }
+    /**
+     * Executes the operation and returns a `LockedConfig` (secrets are null).
+     * Issues a single IPC call.
+     */
+    run() {
+        return this._configurate._executeLocked(this._op, this._data, this._keyringOpts);
+    }
+    /**
+     * Executes the operation and returns an `UnlockedConfig` (secrets inlined).
+     * Issues a single IPC call – no extra round-trip compared to `run()`.
+     */
+    unlock(opts) {
+        return this._configurate._executeUnlock(this._op, this._data, opts);
+    }
+}
+/**
+ * Main entry point for managing application configuration.
+ *
+ * @example
+ * ```ts
+ * import { Configurate, defineConfig, keyring, BaseDirectory } from "tauri-plugin-configurate-api";
+ *
+ * const schema = defineConfig({
+ *   appName: String,
+ *   port: Number,
+ *   apiKey: keyring(String, { id: "api-key" }),
+ * });
+ *
+ * const config = new Configurate(schema, {
+ *   id: "app-config",
+ *   dir: BaseDirectory.AppConfig,
+ *   format: "json",
+ * });
+ *
+ * // Create – IPC ×1
+ * await config
+ *   .create({ appName: "MyApp", port: 3000, apiKey: "secret" })
+ *   .lock({ service: "my-app", account: "default" })
+ *   .run();
+ *
+ * // Load locked – IPC ×1
+ * const locked = await config.load().run();
+ * locked.data.apiKey; // null
+ *
+ * // Unlock from locked – IPC ×1 (keyring only, file is not re-read)
+ * const unlocked = await locked.unlock({ service: "my-app", account: "default" });
+ * unlocked.data.apiKey; // "secret"
+ *
+ * // Load and unlock in one shot – IPC ×1
+ * const unlocked2 = await config.load().unlock({ service: "my-app", account: "default" });
+ * ```
+ */
+class Configurate {
+    _schema;
+    _opts;
+    _keyringPaths;
+    constructor(schema, opts) {
+        if (opts.encryptionKey !== undefined && opts.format !== "binary") {
+            throw new Error(`encryptionKey is only supported with format "binary", got "${opts.format}". ` +
+                `Remove encryptionKey or change format to "binary".`);
+        }
+        this._schema = schema;
+        this._opts = opts;
+        this._keyringPaths = collectKeyringPaths(this._schema);
+    }
+    // -------------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------------
+    /** Returns a lazy entry that creates the config file on the Rust side. */
+    create(data) {
+        return new LazyConfigEntry(this, "create", data);
+    }
+    /** Returns a lazy entry that loads the config file from the Rust side. */
+    load() {
+        return new LazyConfigEntry(this, "load");
+    }
+    /** Returns a lazy entry that overwrites the config file on the Rust side. */
+    save(data) {
+        return new LazyConfigEntry(this, "save", data);
+    }
+    /**
+     * Deletes the configuration file from disk **and** removes all associated
+     * keyring entries from the OS keyring in a single IPC call.
+     *
+     * Pass `opts` when the schema contains `keyring()` fields so the plugin
+     * knows which keyring entries to wipe. Omit `opts` (or pass `null`) when
+     * the schema has no keyring fields.
+     *
+     * Returns `Promise<void>`. Resolves even if the file did not exist.
+     *
+     * @example
+     * ```ts
+     * // Schema with keyring fields – pass keyring opts to wipe secrets too.
+     * await config.delete({ service: "my-app", account: "default" });
+     *
+     * // Schema with no keyring fields – opts may be omitted.
+     * await config.delete();
+     * ```
+     */
+    async delete(opts) {
+        const payload = this._buildPayload("load", undefined, opts ?? null, false);
+        await invoke("plugin:configurate|delete", { payload });
+    }
+    // -------------------------------------------------------------------------
+    // Internal helpers (called by LazyConfigEntry / LockedConfig)
+    // -------------------------------------------------------------------------
+    /** @internal */
+    async _executeLocked(op, data, keyringOpts) {
+        const payload = this._buildPayload(op, data, keyringOpts, false);
+        const result = await invoke("plugin:configurate|" + op, {
+            payload,
+        });
+        return new LockedConfig(result, this);
+    }
+    /** @internal */
+    async _executeUnlock(op, data, keyringOpts) {
+        const payload = this._buildPayload(op, data, keyringOpts, true);
+        const result = await invoke("plugin:configurate|" + op, {
+            payload,
+        });
+        return new UnlockedConfig(result);
+    }
+    /**
+     * Fetches keyring secrets and merges them into already-loaded plain data
+     * without re-reading the file from disk.
+     * Issues a single IPC call to `plugin:configurate|unlock`.
+     *
+     * @internal
+     */
+    async _unlockFromData(plainData, opts) {
+        if (this._keyringPaths.length === 0) {
+            return new UnlockedConfig(plainData);
+        }
+        const payload = {
+            data: plainData,
+            keyringEntries: this._keyringPaths.map(({ id, dotpath }) => ({
+                id,
+                dotpath,
+                value: "",
+            })),
+            keyringOptions: opts,
+        };
+        const result = await invoke("plugin:configurate|unlock", {
+            payload,
+        });
+        return new UnlockedConfig(result);
+    }
+    // -------------------------------------------------------------------------
+    // Payload builder
+    // -------------------------------------------------------------------------
+    /** @internal */
+    _buildPayload(op, data, keyringOpts, withUnlock) {
+        const base = {
+            id: this._opts.id,
+            dir: this._opts.dir,
+            format: this._opts.format,
+            withUnlock,
+        };
+        if (this._opts.subDir) {
+            base.subDir = this._opts.subDir;
+        }
+        if (this._opts.encryptionKey) {
+            base.encryptionKey = this._opts.encryptionKey;
+        }
+        if (op === "load") {
+            // For load we only need the keyring ids and dotpaths so the Rust side
+            // knows which dotpaths to populate when with_unlock is true.
+            if (keyringOpts && this._keyringPaths.length > 0) {
+                base.keyringEntries = this._keyringPaths.map(({ id, dotpath }) => ({
+                    id,
+                    dotpath,
+                    value: "",
+                }));
+                base.keyringOptions = keyringOpts;
+            }
+        }
+        else if (data !== undefined) {
+            const { plain, keyringEntries } = separateSecrets(data, this._keyringPaths);
+            base.data = plain;
+            if (keyringOpts && keyringEntries.length > 0) {
+                base.keyringEntries = keyringEntries;
+                base.keyringOptions = keyringOpts;
+            }
+        }
+        return base;
+    }
+}
+/**
+ * A factory that creates `Configurate` instances with pre-set shared options
+ * (`dir`, `format`, and optionally `encryptionKey`).
+ *
+ * Each call to `build()` creates a fresh `Configurate` instance — schema,
+ * `id`, and all other options can differ freely.  This is the recommended
+ * way to manage multiple config files with different schemas in a single
+ * application.
+ *
+ * @example
+ * ```ts
+ * import { ConfigurateFactory, defineConfig, BaseDirectory } from "tauri-plugin-configurate-api";
+ *
+ * const appSchema   = defineConfig({ theme: String, language: String });
+ * const cacheSchema = defineConfig({ lastSync: Number });
+ * const secretSchema = defineConfig({ token: String });
+ *
+ * const factory = new ConfigurateFactory({
+ *   dir: BaseDirectory.AppConfig,
+ *   format: "json",
+ * });
+ *
+ * const appConfig    = factory.build(appSchema,    "app");     // → app.json
+ * const cacheConfig  = factory.build(cacheSchema,  "cache");   // → cache.json
+ * const secretConfig = factory.build(secretSchema, "secrets"); // → secrets.json
+ * ```
+ */
+class ConfigurateFactory {
+    _baseOpts;
+    constructor(_baseOpts) {
+        this._baseOpts = _baseOpts;
+    }
+    /**
+     * Creates a `Configurate<S>` for the given schema and id, applying the
+     * shared base options.
+     *
+     * The optional `subDir` argument overrides the factory-level `subDir` for
+     * this specific instance.
+     */
+    build(schema, id, subDir) {
+        const opts = { ...this._baseOpts, id };
+        if (subDir !== undefined) {
+            opts.subDir = subDir;
+        }
+        // Explicitly pass <S> to prevent TypeScript from re-inferring the type
+        // parameter from the argument and double-evaluating HasDuplicateKeyringIds
+        // on the already-constrained type.  The duplicate-id guarantee was already
+        // enforced at the call-site when the schema was created.
+        return new Configurate(schema, opts);
+    }
+}
+// ---------------------------------------------------------------------------
+// defineConfig helper
+// ---------------------------------------------------------------------------
+/**
+ * Defines a configuration schema. Provides a convenient declaration site and
+ * compile-time duplicate keyring id checks.
+ *
+ * @example
+ * ```ts
+ * const schema = defineConfig({
+ *   appName: String,
+ *   port: Number,
+ *   database: {
+ *     host: String,
+ *     password: keyring(String, { id: "db-password" }),
+ *   },
+ * });
+ * ```
+ */
+function defineConfig(schema) {
+    // Runtime duplicate id validation (belt-and-suspenders on top of type checks).
+    const ids = collectKeyringIds(schema);
+    const seen = new Set();
+    for (const id of ids) {
+        if (seen.has(id)) {
+            throw new Error(`Duplicate keyring id: '${id}'. Each keyring() call must use a unique id within the same schema.`);
+        }
+        seen.add(id);
+    }
+    return schema;
+}
+
+export { Configurate, ConfigurateFactory, LazyConfigEntry, LockedConfig, UnlockedConfig, defineConfig, keyring };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "tauri-plugin-configurate-api",
+  "version": "0.1.0",
+  "description": "A Tauri v2 plugin for type-safe application configuration management.",
+  "author": "Crysta1221",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Crysta1221/tauri-plugin-configurate.git"
+  },
+  "homepage": "https://github.com/Crysta1221/tauri-plugin-configurate",
+  "bugs": {
+    "url": "https://github.com/Crysta1221/tauri-plugin-configurate/issues"
+  },
+  "keywords": [
+    "tauri",
+    "tauri-plugin",
+    "config",
+    "keyring",
+    "configuration"
+  ],
+  "files": [
+    "dist-js",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist-js/index.cjs",
+  "module": "./dist-js/index.js",
+  "types": "./dist-js/index.d.ts",
+  "exports": {
+    "types": "./dist-js/index.d.ts",
+    "import": "./dist-js/index.js",
+    "require": "./dist-js/index.cjs"
+  },
+  "scripts": {
+    "build": "rollup -c",
+    "build:sync": "rollup -c && cd examples/tauri-app && pnpm install",
+    "prepublishOnly": "bun run build",
+    "pretest": "pnpm build",
+    "fmt": "oxfmt",
+    "fmt:check": "oxfmt --check",
+    "lint": "oxlint --type-aware",
+    "lint:fix": "oxlint --type-aware --fix"
+  },
+  "peerDependencies": {
+    "@tauri-apps/api": "^2.0.0"
+  },
+  "dependencies": {
+    "oxlint-tsgolint": "^0.14.2"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.0.0",
+    "oxfmt": "^0.35.0",
+    "oxlint": "^1.50.0",
+    "rollup": "^4.9.6",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  }
+}