tauri-plugin-configurate-api 0.1.0

package/dist-js/index.d.ts

@@ -0,0 +1,354 @@
+export { BaseDirectory } from "@tauri-apps/api/path";
+import type { BaseDirectory } from "@tauri-apps/api/path";
+/** Supported on-disk storage formats **/
+export type StorageFormat = "json" | "yaml" | "binary";
+/** Phantom symbol used only in the type system – never appears at runtime. */
+declare const _keyringBrandTag: unique symbol;
+/**
+ * Marker type produced by `keyring()`.
+ * `T`  – the runtime type of the secret value.
+ * `Id` – the literal string id used to key the OS keyring entry.
+ */
+export type KeyringField<T, Id extends string> = {
+    readonly [_keyringBrandTag]?: true;
+    readonly _type: T;
+    readonly _id: Id;
+};
+/** Options required when creating a keyring-protected field definition. */
+export interface KeyringFieldOptions<Id extends string> {
+    /** Unique identifier for this keyring entry. Must be unique within a schema. */
+    id: Id;
+}
+/**
+ * Marks a schema field as keyring-protected.
+ *
+ * @example
+ * ```ts
+ * const schema = defineConfig({
+ *   apiKey: keyring(String, { id: "api-key" }),
+ * });
+ * ```
+ */
+export declare function keyring<T, Id extends string>(_type: abstract new (...args: never[]) => T | ((...args: never[]) => T), opts: KeyringFieldOptions<Id>): KeyringField<T, Id>;
+/** Primitive constructor types supported in a schema definition. */
+type PrimitiveConstructor = StringConstructor | NumberConstructor | BooleanConstructor;
+/** Maps a primitive constructor to its corresponding TS type. */
+type InferPrimitive<C> = C extends StringConstructor ? string : C extends NumberConstructor ? number : C extends BooleanConstructor ? boolean : never;
+/** Any value that is valid inside a schema definition. */
+export type SchemaValue = PrimitiveConstructor | KeyringField<unknown, string> | SchemaObject;
+/** A plain object whose values are all `SchemaValue`s. */
+export type SchemaObject = {
+    [key: string]: SchemaValue;
+};
+/**
+ * Recursively collects every keyring id found anywhere inside a schema as a
+ * union of string literals.
+ */
+export type CollectKeyringIds<S extends SchemaObject> = {
+    [K in keyof S]: S[K] extends KeyringField<unknown, infer Id> ? Id : S[K] extends SchemaObject ? CollectKeyringIds<S[K]> : never;
+}[keyof S];
+/**
+ * Produces `never` when a string literal `T` appears more than once inside
+ * the union `All`. Used to detect duplicate keyring ids at compile time.
+ *
+ * The check works by removing `T` from `All` and seeing whether there are
+ * still members left that match `T`.  If after exclusion some member equals
+ * `T`, it means the original union contained `T` at least twice.
+ */
+type IsDuplicate<T extends string, All extends string> = T extends Exclude<All, T> ? true : false;
+/**
+ * Evaluates to `true` if any keyring id appears more than once in the
+ * schema, `false` otherwise.
+ */
+export type HasDuplicateKeyringIds<S extends SchemaObject> = true extends {
+    [Id in CollectKeyringIds<S>]: IsDuplicate<Id, CollectKeyringIds<S>>;
+}[CollectKeyringIds<S>] ? true : false;
+/**
+ * Converts a schema into the "locked" config type where every
+ * `KeyringField<T, Id>` becomes `null`.
+ */
+export type InferLocked<S extends SchemaObject> = {
+    [K in keyof S]: S[K] extends KeyringField<unknown, string> ? null : S[K] extends SchemaObject ? InferLocked<S[K]> : S[K] extends PrimitiveConstructor ? InferPrimitive<S[K]> : never;
+};
+/**
+ * Converts a schema into the "unlocked" config type where every
+ * `KeyringField<T, Id>` is replaced with the actual secret type `T`.
+ */
+export type InferUnlocked<S extends SchemaObject> = {
+    [K in keyof S]: S[K] extends KeyringField<infer T, string> ? T : S[K] extends SchemaObject ? InferUnlocked<S[K]> : S[K] extends PrimitiveConstructor ? InferPrimitive<S[K]> : never;
+};
+/**
+ * Options required to access the OS keyring.
+ * Stored with OS keyring fields:
+ * - service = `{service}`
+ * - user    = `{account}/{id}`
+ */
+export interface KeyringOptions {
+    /** The keyring service name (e.g. your application name). */
+    service: string;
+    /** The keyring account name (e.g. `"default"`). */
+    account: string;
+}
+/**
+ * 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.
+ */
+export declare class LockedConfig<S extends SchemaObject> {
+    private readonly _configurate;
+    readonly data: InferLocked<S>;
+    /** @internal */
+    constructor(data: InferLocked<S>, _configurate: Configurate<S>);
+    /**
+     * Fetches all keyring secrets and returns an `UnlockedConfig`.
+     * Issues a single IPC call (keyring read only – file is not re-read).
+     */
+    unlock(opts: KeyringOptions): Promise<UnlockedConfig<S>>;
+}
+/**
+ * A configuration where all keyring-protected fields contain their real values.
+ * Call `.lock()` to discard in-memory secrets (no IPC required).
+ */
+export declare class UnlockedConfig<S extends SchemaObject> {
+    private _data;
+    /** @internal */
+    constructor(data: InferUnlocked<S>);
+    /**
+     * Returns the unlocked configuration data.
+     * Throws if `lock()` has already been called.
+     */
+    get data(): InferUnlocked<S>;
+    /**
+     * 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(): void;
+}
+/**
+ * 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.
+ */
+export declare class LazyConfigEntry<S extends SchemaObject> {
+    private readonly _configurate;
+    private readonly _op;
+    private readonly _data?;
+    private _keyringOpts;
+    /** @internal */
+    constructor(_configurate: Configurate<S>, _op: "create" | "load" | "save", _data?: InferUnlocked<S> | undefined);
+    /**
+     * 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: KeyringOptions): this;
+    /**
+     * Executes the operation and returns a `LockedConfig` (secrets are null).
+     * Issues a single IPC call.
+     */
+    run(): Promise<LockedConfig<S>>;
+    /**
+     * Executes the operation and returns an `UnlockedConfig` (secrets inlined).
+     * Issues a single IPC call – no extra round-trip compared to `run()`.
+     */
+    unlock(opts: KeyringOptions): Promise<UnlockedConfig<S>>;
+}
+/** Options passed to the `Configurate` constructor. */
+export interface ConfigurateOptions {
+    /** Unique identifier for the configuration file (used as the file stem). */
+    id: string;
+    /** Base directory in which the configuration file will be stored. */
+    dir: BaseDirectory;
+    /**
+     * Optional sub-directory path relative to `dir`.
+     *
+     * Use forward slashes as separators (e.g. `"my-app/config"`).
+     * Each segment is validated on the Rust side; `..` and Windows-forbidden
+     * characters are rejected.
+     *
+     * When omitted, files are written directly into `dir`.
+     *
+     * @example
+     * ```ts
+     * // Stores config at <AppConfig>/my-app/settings.json
+     * new Configurate(schema, {
+     *   id: "settings",
+     *   dir: BaseDirectory.AppConfig,
+     *   format: "json",
+     *   subDir: "my-app",
+     * });
+     * ```
+     */
+    subDir?: string;
+    /** On-disk storage format. */
+    format: StorageFormat;
+    /**
+     * Encryption key for the `"binary"` format.
+     *
+     * When provided, the file is encrypted with **XChaCha20-Poly1305**. The
+     * 32-byte cipher key is derived internally via `SHA-256(encryptionKey)`, so
+     * the value should be high-entropy — for example a random key stored in the
+     * OS keyring. Omit this field when using `"json"` or `"yaml"` formats, or
+     * when backward-compatible unencrypted binary files are required.
+     *
+     * Encrypted binary files use the `.binc` extension instead of `.bin`.
+     */
+    encryptionKey?: string;
+}
+/**
+ * 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" });
+ * ```
+ */
+export declare class Configurate<S extends SchemaObject> {
+    private readonly _schema;
+    private readonly _opts;
+    private readonly _keyringPaths;
+    constructor(schema: S & (true extends HasDuplicateKeyringIds<S> ? never : unknown), opts: ConfigurateOptions);
+    /** Returns a lazy entry that creates the config file on the Rust side. */
+    create(data: InferUnlocked<S>): LazyConfigEntry<S>;
+    /** Returns a lazy entry that loads the config file from the Rust side. */
+    load(): LazyConfigEntry<S>;
+    /** Returns a lazy entry that overwrites the config file on the Rust side. */
+    save(data: InferUnlocked<S>): LazyConfigEntry<S>;
+    /**
+     * 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();
+     * ```
+     */
+    delete(opts?: KeyringOptions | null): Promise<void>;
+    /** @internal */
+    _executeLocked(op: "create" | "load" | "save", data: InferUnlocked<S> | undefined, keyringOpts: KeyringOptions | null): Promise<LockedConfig<S>>;
+    /** @internal */
+    _executeUnlock(op: "create" | "load" | "save", data: InferUnlocked<S> | undefined, keyringOpts: KeyringOptions): Promise<UnlockedConfig<S>>;
+    /**
+     * 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
+     */
+    _unlockFromData(plainData: Record<string, unknown>, opts: KeyringOptions): Promise<UnlockedConfig<S>>;
+    /** @internal */
+    _buildPayload(op: "create" | "load" | "save", data: InferUnlocked<S> | undefined, keyringOpts: KeyringOptions | null, withUnlock: boolean): Record<string, unknown>;
+}
+/**
+ * Base options shared across all configs created by a `ConfigurateFactory`.
+ * `id` is omitted because each config provides its own.
+ */
+export type ConfigurateBaseOptions = Omit<ConfigurateOptions, "id">;
+/**
+ * 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
+ * ```
+ */
+export declare class ConfigurateFactory {
+    private readonly _baseOpts;
+    constructor(_baseOpts: ConfigurateBaseOptions);
+    /**
+     * 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<S extends SchemaObject>(schema: S & (true extends HasDuplicateKeyringIds<S> ? never : unknown), id: string, subDir?: string): Configurate<S>;
+}
+/**
+ * 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" }),
+ *   },
+ * });
+ * ```
+ */
+export declare function defineConfig<S extends SchemaObject>(schema: S & (true extends HasDuplicateKeyringIds<S> ? never : unknown)): S;