@miaixz/sdk 0.5.0

package/dist/storage/index.js

@@ -0,0 +1,2 @@
+export * from "./storage.js";
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC","sourcesContent":["export * from \"./storage.js\";\n"]}

package/dist/storage/storage.d.ts

@@ -0,0 +1,246 @@
+import type { MiaixzResponseParser } from "../api/request.js";
+/**
+ * Defines the browser-compatible storage operations required by the SDK.
+ *
+ * @public
+ */
+export interface MiaixzKeyValueStorage {
+    /**
+     * Reads a serialized value or returns `null` when the key is absent.
+     *
+     * @param key - Storage key to read.
+     * @returns Serialized value or null when the key is absent.
+     */
+    getItem(key: string): string | null;
+    /**
+     * Stores a serialized value under the supplied key.
+     *
+     * @param key - Storage key to write.
+     * @param value - Serialized value to store.
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * Removes the supplied key.
+     *
+     * @param key - Storage key to remove.
+     */
+    removeItem(key: string): void;
+}
+/**
+ * Wraps persisted data with its schema version.
+ *
+ * @typeParam T - Persisted application value type.
+ * @public
+ */
+export interface MiaixzVersionedValue<T> {
+    /**
+     * Identifies the schema used to serialize the value.
+     */
+    readonly schemaVersion: number;
+    /**
+     * Contains the persisted application value.
+     */
+    readonly value: T;
+}
+/**
+ * Migrates one persisted schema version to its immediate successor.
+ *
+ * @public
+ */
+export interface MiaixzStorageMigration {
+    /**
+     * Identifies the source schema version.
+     */
+    readonly from: number;
+    /**
+     * Identifies the immediate target schema version.
+     */
+    readonly to: number;
+    /**
+     * Converts one untrusted persisted value to the next schema.
+     *
+     * @param value - Value produced by storage or the previous migration.
+     * @returns Value represented in the target schema.
+     */
+    migrate(value: unknown): unknown;
+}
+/**
+ * Identifies the application and optional tenant owning persisted data.
+ *
+ * @public
+ */
+export interface MiaixzStorageScope {
+    /**
+     * Identifies the consuming frontend application.
+     */
+    readonly appId: string;
+    /**
+     * Identifies the optional tenant-specific persistence boundary.
+     */
+    readonly tenantId?: string;
+}
+/**
+ * Configures validated versioned storage reads.
+ *
+ * @typeParam T - Parsed application value type.
+ * @public
+ */
+export interface MiaixzVersionedStorageOptions<T> {
+    /**
+     * Supplies the optional physical storage adapter.
+     */
+    readonly storage?: MiaixzKeyValueStorage;
+    /**
+     * Selects the application and tenant persistence boundary.
+     */
+    readonly scope: Readonly<MiaixzStorageScope>;
+    /**
+     * Selects the fixed persisted data category.
+     */
+    readonly kind: "appearance" | "context" | "preferences";
+    /**
+     * Identifies the current target schema version.
+     */
+    readonly schemaVersion: number;
+    /**
+     * Supplies an optional continuous sequence of one-version migrations.
+     */
+    readonly migrations?: readonly MiaixzStorageMigration[];
+    /**
+     * Parses the current-schema value into its normalized application representation.
+     */
+    readonly parse: MiaixzResponseParser<T>;
+}
+/**
+ * Builds a collision-safe physical key for versioned Miaixz data.
+ *
+ * @param scope - Application and optional tenant persistence boundary.
+ * @param kind - Fixed persisted data category.
+ * @returns Physical storage key using the Miaixz version-one namespace.
+ * @throws MiaixzSdkError When the application, tenant, or kind is invalid.
+ * @public
+ */
+export declare function createMiaixzStorageKey(scope: Readonly<MiaixzStorageScope>, kind: "appearance" | "context" | "preferences"): string;
+/**
+ * Reads, migrates, validates, and optionally upgrades one versioned value.
+ *
+ * @typeParam T - Parsed application value type.
+ * @param options - Scope, schema, migration, parser, and storage configuration.
+ * @returns Parsed normalized value, or undefined when data is absent or unusable.
+ * @throws MiaixzSdkError When scope, schema, or migration configuration is invalid.
+ * @public
+ */
+export declare function readMiaixzVersionedValue<T>(options: Readonly<MiaixzVersionedStorageOptions<T>>): T | undefined;
+/**
+ * Writes or removes one versioned value without affecting caller memory on persistence failure.
+ *
+ * @typeParam T - Persisted application value type.
+ * @param options - Scope, target schema, and optional storage configuration.
+ * @param value - Value to persist, or undefined to remove the physical key.
+ * @throws MiaixzSdkError When scope, kind, or target schema is invalid.
+ * @public
+ */
+export declare function writeMiaixzVersionedValue<T>(options: Readonly<Omit<MiaixzVersionedStorageOptions<T>, "migrations" | "parse">>, value: T | undefined): void;
+/**
+ * In-memory storage adapter suitable for tests, SSR, and isolated runtimes.
+ *
+ * @public
+ */
+export declare class MiaixzMemoryStorage implements MiaixzKeyValueStorage {
+    #private;
+    /**
+     * Reads a value from memory.
+     *
+     * @param key - Storage key to read.
+     * @returns Serialized value or null when the key is absent.
+     */
+    getItem(key: string): string | null;
+    /**
+     * Stores a value in memory.
+     *
+     * @param key - Storage key to write.
+     * @param value - Serialized value to store.
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * Removes one in-memory value.
+     *
+     * @param key - Storage key to remove.
+     */
+    removeItem(key: string): void;
+    /**
+     * Removes every in-memory value.
+     */
+    clear(): void;
+}
+/**
+ * Prefixes storage keys so multiple services can safely share one backend.
+ *
+ * @public
+ */
+export declare class MiaixzNamespacedStorage implements MiaixzKeyValueStorage {
+    #private;
+    /**
+     * Underlying storage adapter receiving the namespaced keys.
+     */
+    readonly storage: MiaixzKeyValueStorage;
+    /**
+     * Prefix applied to every logical storage key.
+     */
+    readonly namespace: string;
+    /**
+     * Creates a namespaced storage adapter.
+     *
+     * @param storage - Underlying adapter.
+     * @param namespace - Key prefix.
+     */
+    constructor(storage: MiaixzKeyValueStorage, namespace: string);
+    /**
+     * Reads a namespaced value.
+     *
+     * @param key - Logical storage key to read.
+     * @returns Serialized value or null when the key is absent.
+     */
+    getItem(key: string): string | null;
+    /**
+     * Stores a namespaced value.
+     *
+     * @param key - Logical storage key to write.
+     * @param value - Serialized value to store.
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * Removes a namespaced value.
+     *
+     * @param key - Logical storage key to remove.
+     */
+    removeItem(key: string): void;
+}
+/**
+ * Safely obtains local or session storage when running in a browser.
+ *
+ * @param type - Browser storage area to obtain.
+ * @returns `undefined` during SSR or when browser storage is blocked.
+ * @public
+ */
+export declare function getMiaixzBrowserStorage(type?: "local" | "session"): MiaixzKeyValueStorage | undefined;
+/**
+ * Parses and optionally validates JSON stored by a key-value adapter.
+ *
+ * @param storage - Optional storage adapter to read.
+ * @param key - Storage key containing JSON.
+ * @param validate - Optional type guard for parsed data.
+ * @returns Parsed and validated value when available.
+ * @public
+ */
+export declare function readMiaixzJson<T>(storage: MiaixzKeyValueStorage | undefined, key: string, validate?: (value: unknown) => value is T): T | undefined;
+/**
+ * Serializes a value as JSON, or removes the key for `undefined`.
+ *
+ * @param storage - Optional storage adapter to update.
+ * @param key - Storage key to write or remove.
+ * @param value - Value to serialize, or undefined to remove the key.
+ * @public
+ */
+export declare function writeMiaixzJson<T>(storage: MiaixzKeyValueStorage | undefined, key: string, value: T | undefined): void;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/storage/storage.ts"],"names":[],"mappings":"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"}

package/dist/storage/storage.js

@@ -0,0 +1,358 @@
+import { MiaixzSdkError } from "../api/errors.js";
+import { translateMiaixzDefaultMessage } from "../i18n/default-translator.js";
+const miaixzApplicationIdPattern = /^[a-z][a-z0-9-]{1,63}$/;
+const miaixzTenantIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const miaixzStorageKinds = new Set(["appearance", "context", "preferences"]);
+/**
+ * Creates the fixed localized error for an invalid storage scope or kind.
+ *
+ * @returns Stable SDK storage-scope error.
+ */
+function createStorageScopeError() {
+    return new MiaixzSdkError(translateMiaixzDefaultMessage("sdk.error.storage.scopeInvalid"), {
+        code: "STORAGE_SCOPE_INVALID",
+    });
+}
+/**
+ * Creates the fixed localized error for invalid schema or migration configuration.
+ *
+ * @returns Stable SDK migration-chain error.
+ */
+function createMigrationChainError() {
+    return new MiaixzSdkError(translateMiaixzDefaultMessage("sdk.error.storage.migrationChainInvalid"), { code: "STORAGE_MIGRATION_CHAIN_INVALID" });
+}
+/**
+ * Reports whether a number is a non-negative safe schema version.
+ *
+ * @param value - Version candidate to inspect.
+ * @returns Whether the value is a supported persisted or migration version.
+ */
+function isNonNegativeSchemaVersion(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+/**
+ * Validates a current target schema version.
+ *
+ * @param schemaVersion - Target version to validate.
+ * @throws MiaixzSdkError When the target is not a positive safe integer.
+ */
+function validateTargetSchemaVersion(schemaVersion) {
+    if (!Number.isSafeInteger(schemaVersion) || schemaVersion < 1) {
+        throw createMigrationChainError();
+    }
+}
+/**
+ * Validates the complete configured migration sequence in caller order.
+ *
+ * @param migrations - Optional migration chain to validate.
+ * @throws MiaixzSdkError When a version is invalid, duplicated, or discontinuous.
+ */
+function validateMigrationChain(migrations = []) {
+    let previousTarget;
+    for (const migration of migrations) {
+        if (!migration ||
+            typeof migration !== "object" ||
+            !isNonNegativeSchemaVersion(migration.from) ||
+            !isNonNegativeSchemaVersion(migration.to) ||
+            migration.to !== migration.from + 1 ||
+            (previousTarget !== undefined && migration.from !== previousTarget) ||
+            typeof migration.migrate !== "function") {
+            throw createMigrationChainError();
+        }
+        previousTarget = migration.to;
+    }
+}
+/**
+ * Builds a collision-safe physical key for versioned Miaixz data.
+ *
+ * @param scope - Application and optional tenant persistence boundary.
+ * @param kind - Fixed persisted data category.
+ * @returns Physical storage key using the Miaixz version-one namespace.
+ * @throws MiaixzSdkError When the application, tenant, or kind is invalid.
+ * @public
+ */
+export function createMiaixzStorageKey(scope, kind) {
+    if (!scope ||
+        !miaixzApplicationIdPattern.test(scope.appId) ||
+        (scope.tenantId !== undefined &&
+            (!miaixzTenantIdPattern.test(scope.tenantId) || scope.tenantId === "global")) ||
+        !miaixzStorageKinds.has(kind)) {
+        throw createStorageScopeError();
+    }
+    return `miaixz:v1:${scope.tenantId ?? "global"}:${scope.appId}:${kind}`;
+}
+/**
+ * Reports whether parsed JSON uses the exact versioned-value envelope.
+ *
+ * @param value - Parsed JSON candidate to inspect.
+ * @returns Whether the value contains exactly schemaVersion and value fields.
+ */
+function isVersionedEnvelope(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return (keys.length === 2 &&
+        keys.includes("schemaVersion") &&
+        keys.includes("value") &&
+        "schemaVersion" in value &&
+        "value" in value);
+}
+/**
+ * Removes one physical storage key while swallowing adapter failures.
+ *
+ * @param storage - Storage adapter to update.
+ * @param key - Exact physical key to remove.
+ */
+function safelyRemoveStorageValue(storage, key) {
+    try {
+        storage.removeItem(key);
+    }
+    catch {
+        // Persistence failures never change the caller's in-memory state.
+    }
+}
+/**
+ * Reads, migrates, validates, and optionally upgrades one versioned value.
+ *
+ * @typeParam T - Parsed application value type.
+ * @param options - Scope, schema, migration, parser, and storage configuration.
+ * @returns Parsed normalized value, or undefined when data is absent or unusable.
+ * @throws MiaixzSdkError When scope, schema, or migration configuration is invalid.
+ * @public
+ */
+export function readMiaixzVersionedValue(options) {
+    const key = createMiaixzStorageKey(options.scope, options.kind);
+    validateTargetSchemaVersion(options.schemaVersion);
+    validateMigrationChain(options.migrations);
+    if (!options.storage)
+        return undefined;
+    let serialized;
+    try {
+        serialized = options.storage.getItem(key);
+    }
+    catch {
+        return undefined;
+    }
+    if (serialized === null)
+        return undefined;
+    try {
+        const envelope = JSON.parse(serialized);
+        if (!isVersionedEnvelope(envelope) || !isNonNegativeSchemaVersion(envelope.schemaVersion)) {
+            safelyRemoveStorageValue(options.storage, key);
+            return undefined;
+        }
+        if (envelope.schemaVersion > options.schemaVersion) {
+            safelyRemoveStorageValue(options.storage, key);
+            return undefined;
+        }
+        let currentVersion = envelope.schemaVersion;
+        let migratedValue = envelope.value;
+        while (currentVersion < options.schemaVersion) {
+            const migration = options.migrations?.find((candidate) => candidate.from === currentVersion);
+            if (!migration) {
+                safelyRemoveStorageValue(options.storage, key);
+                return undefined;
+            }
+            migratedValue = migration.migrate(migratedValue);
+            currentVersion = migration.to;
+        }
+        const parsed = options.parse(migratedValue);
+        if (envelope.schemaVersion < options.schemaVersion) {
+            writeMiaixzVersionedValue({
+                storage: options.storage,
+                scope: options.scope,
+                kind: options.kind,
+                schemaVersion: options.schemaVersion,
+            }, parsed);
+        }
+        return parsed;
+    }
+    catch {
+        safelyRemoveStorageValue(options.storage, key);
+        return undefined;
+    }
+}
+/**
+ * Writes or removes one versioned value without affecting caller memory on persistence failure.
+ *
+ * @typeParam T - Persisted application value type.
+ * @param options - Scope, target schema, and optional storage configuration.
+ * @param value - Value to persist, or undefined to remove the physical key.
+ * @throws MiaixzSdkError When scope, kind, or target schema is invalid.
+ * @public
+ */
+export function writeMiaixzVersionedValue(options, value) {
+    const key = createMiaixzStorageKey(options.scope, options.kind);
+    validateTargetSchemaVersion(options.schemaVersion);
+    if (!options.storage)
+        return;
+    if (value === undefined) {
+        safelyRemoveStorageValue(options.storage, key);
+        return;
+    }
+    try {
+        const envelope = {
+            schemaVersion: options.schemaVersion,
+            value,
+        };
+        options.storage.setItem(key, JSON.stringify(envelope));
+    }
+    catch {
+        // Serialization and adapter failures intentionally degrade to non-persistence.
+    }
+}
+/**
+ * In-memory storage adapter suitable for tests, SSR, and isolated runtimes.
+ *
+ * @public
+ */
+export class MiaixzMemoryStorage {
+    #values = new Map();
+    /**
+     * Reads a value from memory.
+     *
+     * @param key - Storage key to read.
+     * @returns Serialized value or null when the key is absent.
+     */
+    getItem(key) {
+        return this.#values.get(key) ?? null;
+    }
+    /**
+     * Stores a value in memory.
+     *
+     * @param key - Storage key to write.
+     * @param value - Serialized value to store.
+     */
+    setItem(key, value) {
+        this.#values.set(key, value);
+    }
+    /**
+     * Removes one in-memory value.
+     *
+     * @param key - Storage key to remove.
+     */
+    removeItem(key) {
+        this.#values.delete(key);
+    }
+    /**
+     * Removes every in-memory value.
+     */
+    clear() {
+        this.#values.clear();
+    }
+}
+/**
+ * Prefixes storage keys so multiple services can safely share one backend.
+ *
+ * @public
+ */
+export class MiaixzNamespacedStorage {
+    /**
+     * Underlying storage adapter receiving the namespaced keys.
+     */
+    storage;
+    /**
+     * Prefix applied to every logical storage key.
+     */
+    namespace;
+    /**
+     * Creates a namespaced storage adapter.
+     *
+     * @param storage - Underlying adapter.
+     * @param namespace - Key prefix.
+     */
+    constructor(storage, namespace) {
+        this.storage = storage;
+        this.namespace = namespace;
+    }
+    /**
+     * Builds the physical key used by the underlying adapter.
+     *
+     * @param key - Logical storage key.
+     * @returns Namespaced physical storage key.
+     */
+    #key(key) {
+        return `${this.namespace}:${key}`;
+    }
+    /**
+     * Reads a namespaced value.
+     *
+     * @param key - Logical storage key to read.
+     * @returns Serialized value or null when the key is absent.
+     */
+    getItem(key) {
+        return this.storage.getItem(this.#key(key));
+    }
+    /**
+     * Stores a namespaced value.
+     *
+     * @param key - Logical storage key to write.
+     * @param value - Serialized value to store.
+     */
+    setItem(key, value) {
+        this.storage.setItem(this.#key(key), value);
+    }
+    /**
+     * Removes a namespaced value.
+     *
+     * @param key - Logical storage key to remove.
+     */
+    removeItem(key) {
+        this.storage.removeItem(this.#key(key));
+    }
+}
+/**
+ * Safely obtains local or session storage when running in a browser.
+ *
+ * @param type - Browser storage area to obtain.
+ * @returns `undefined` during SSR or when browser storage is blocked.
+ * @public
+ */
+export function getMiaixzBrowserStorage(type = "local") {
+    if (typeof window === "undefined")
+        return undefined;
+    try {
+        return type === "local" ? window.localStorage : window.sessionStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parses and optionally validates JSON stored by a key-value adapter.
+ *
+ * @param storage - Optional storage adapter to read.
+ * @param key - Storage key containing JSON.
+ * @param validate - Optional type guard for parsed data.
+ * @returns Parsed and validated value when available.
+ * @public
+ */
+export function readMiaixzJson(storage, key, validate) {
+    const serialized = storage?.getItem(key);
+    if (!serialized)
+        return undefined;
+    try {
+        const value = JSON.parse(serialized);
+        return validate && !validate(value) ? undefined : value;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Serializes a value as JSON, or removes the key for `undefined`.
+ *
+ * @param storage - Optional storage adapter to update.
+ * @param key - Storage key to write or remove.
+ * @param value - Value to serialize, or undefined to remove the key.
+ * @public
+ */
+export function writeMiaixzJson(storage, key, value) {
+    if (!storage)
+        return;
+    if (value === undefined)
+        storage.removeItem(key);
+    else
+        storage.setItem(key, JSON.stringify(value));
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/storage/storage.ts"],"names":[],"mappings":"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","sourcesContent":["import { MiaixzSdkError } from \"../api/errors.js\";\nimport type { MiaixzResponseParser } from \"../api/request.js\";\nimport { translateMiaixzDefaultMessage } from \"../i18n/default-translator.js\";\n\n/**\n * Defines the browser-compatible storage operations required by the SDK.\n *\n * @public\n */\nexport interface MiaixzKeyValueStorage {\n  /**\n   * Reads a serialized value or returns `null` when the key is absent.\n   *\n   * @param key - Storage key to read.\n   * @returns Serialized value or null when the key is absent.\n   */\n  getItem(key: string): string | null;\n  /**\n   * Stores a serialized value under the supplied key.\n   *\n   * @param key - Storage key to write.\n   * @param value - Serialized value to store.\n   */\n  setItem(key: string, value: string): void;\n  /**\n   * Removes the supplied key.\n   *\n   * @param key - Storage key to remove.\n   */\n  removeItem(key: string): void;\n}\n\n/**\n * Wraps persisted data with its schema version.\n *\n * @typeParam T - Persisted application value type.\n * @public\n */\nexport interface MiaixzVersionedValue<T> {\n  /**\n   * Identifies the schema used to serialize the value.\n   */\n  readonly schemaVersion: number;\n\n  /**\n   * Contains the persisted application value.\n   */\n  readonly value: T;\n}\n\n/**\n * Migrates one persisted schema version to its immediate successor.\n *\n * @public\n */\nexport interface MiaixzStorageMigration {\n  /**\n   * Identifies the source schema version.\n   */\n  readonly from: number;\n\n  /**\n   * Identifies the immediate target schema version.\n   */\n  readonly to: number;\n\n  /**\n   * Converts one untrusted persisted value to the next schema.\n   *\n   * @param value - Value produced by storage or the previous migration.\n   * @returns Value represented in the target schema.\n   */\n  migrate(value: unknown): unknown;\n}\n\n/**\n * Identifies the application and optional tenant owning persisted data.\n *\n * @public\n */\nexport interface MiaixzStorageScope {\n  /**\n   * Identifies the consuming frontend application.\n   */\n  readonly appId: string;\n\n  /**\n   * Identifies the optional tenant-specific persistence boundary.\n   */\n  readonly tenantId?: string;\n}\n\n/**\n * Configures validated versioned storage reads.\n *\n * @typeParam T - Parsed application value type.\n * @public\n */\nexport interface MiaixzVersionedStorageOptions<T> {\n  /**\n   * Supplies the optional physical storage adapter.\n   */\n  readonly storage?: MiaixzKeyValueStorage;\n\n  /**\n   * Selects the application and tenant persistence boundary.\n   */\n  readonly scope: Readonly<MiaixzStorageScope>;\n\n  /**\n   * Selects the fixed persisted data category.\n   */\n  readonly kind: \"appearance\" | \"context\" | \"preferences\";\n\n  /**\n   * Identifies the current target schema version.\n   */\n  readonly schemaVersion: number;\n\n  /**\n   * Supplies an optional continuous sequence of one-version migrations.\n   */\n  readonly migrations?: readonly MiaixzStorageMigration[];\n\n  /**\n   * Parses the current-schema value into its normalized application representation.\n   */\n  readonly parse: MiaixzResponseParser<T>;\n}\n\nconst miaixzApplicationIdPattern = /^[a-z][a-z0-9-]{1,63}$/;\nconst miaixzTenantIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;\nconst miaixzStorageKinds = new Set([\"appearance\", \"context\", \"preferences\"]);\n\n/**\n * Creates the fixed localized error for an invalid storage scope or kind.\n *\n * @returns Stable SDK storage-scope error.\n */\nfunction createStorageScopeError(): MiaixzSdkError {\n  return new MiaixzSdkError(translateMiaixzDefaultMessage(\"sdk.error.storage.scopeInvalid\"), {\n    code: \"STORAGE_SCOPE_INVALID\",\n  });\n}\n\n/**\n * Creates the fixed localized error for invalid schema or migration configuration.\n *\n * @returns Stable SDK migration-chain error.\n */\nfunction createMigrationChainError(): MiaixzSdkError {\n  return new MiaixzSdkError(\n    translateMiaixzDefaultMessage(\"sdk.error.storage.migrationChainInvalid\"),\n    { code: \"STORAGE_MIGRATION_CHAIN_INVALID\" },\n  );\n}\n\n/**\n * Reports whether a number is a non-negative safe schema version.\n *\n * @param value - Version candidate to inspect.\n * @returns Whether the value is a supported persisted or migration version.\n */\nfunction isNonNegativeSchemaVersion(value: number): boolean {\n  return Number.isSafeInteger(value) && value >= 0;\n}\n\n/**\n * Validates a current target schema version.\n *\n * @param schemaVersion - Target version to validate.\n * @throws MiaixzSdkError When the target is not a positive safe integer.\n */\nfunction validateTargetSchemaVersion(schemaVersion: number): void {\n  if (!Number.isSafeInteger(schemaVersion) || schemaVersion < 1) {\n    throw createMigrationChainError();\n  }\n}\n\n/**\n * Validates the complete configured migration sequence in caller order.\n *\n * @param migrations - Optional migration chain to validate.\n * @throws MiaixzSdkError When a version is invalid, duplicated, or discontinuous.\n */\nfunction validateMigrationChain(migrations: readonly MiaixzStorageMigration[] = []): void {\n  let previousTarget: number | undefined;\n  for (const migration of migrations) {\n    if (\n      !migration ||\n      typeof migration !== \"object\" ||\n      !isNonNegativeSchemaVersion(migration.from) ||\n      !isNonNegativeSchemaVersion(migration.to) ||\n      migration.to !== migration.from + 1 ||\n      (previousTarget !== undefined && migration.from !== previousTarget) ||\n      typeof migration.migrate !== \"function\"\n    ) {\n      throw createMigrationChainError();\n    }\n    previousTarget = migration.to;\n  }\n}\n\n/**\n * Builds a collision-safe physical key for versioned Miaixz data.\n *\n * @param scope - Application and optional tenant persistence boundary.\n * @param kind - Fixed persisted data category.\n * @returns Physical storage key using the Miaixz version-one namespace.\n * @throws MiaixzSdkError When the application, tenant, or kind is invalid.\n * @public\n */\nexport function createMiaixzStorageKey(\n  scope: Readonly<MiaixzStorageScope>,\n  kind: \"appearance\" | \"context\" | \"preferences\",\n): string {\n  if (\n    !scope ||\n    !miaixzApplicationIdPattern.test(scope.appId) ||\n    (scope.tenantId !== undefined &&\n      (!miaixzTenantIdPattern.test(scope.tenantId) || scope.tenantId === \"global\")) ||\n    !miaixzStorageKinds.has(kind)\n  ) {\n    throw createStorageScopeError();\n  }\n  return `miaixz:v1:${scope.tenantId ?? \"global\"}:${scope.appId}:${kind}`;\n}\n\n/**\n * Reports whether parsed JSON uses the exact versioned-value envelope.\n *\n * @param value - Parsed JSON candidate to inspect.\n * @returns Whether the value contains exactly schemaVersion and value fields.\n */\nfunction isVersionedEnvelope(value: unknown): value is MiaixzVersionedValue<unknown> {\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) return false;\n  const keys = Object.keys(value);\n  return (\n    keys.length === 2 &&\n    keys.includes(\"schemaVersion\") &&\n    keys.includes(\"value\") &&\n    \"schemaVersion\" in value &&\n    \"value\" in value\n  );\n}\n\n/**\n * Removes one physical storage key while swallowing adapter failures.\n *\n * @param storage - Storage adapter to update.\n * @param key - Exact physical key to remove.\n */\nfunction safelyRemoveStorageValue(storage: MiaixzKeyValueStorage, key: string): void {\n  try {\n    storage.removeItem(key);\n  } catch {\n    // Persistence failures never change the caller's in-memory state.\n  }\n}\n\n/**\n * Reads, migrates, validates, and optionally upgrades one versioned value.\n *\n * @typeParam T - Parsed application value type.\n * @param options - Scope, schema, migration, parser, and storage configuration.\n * @returns Parsed normalized value, or undefined when data is absent or unusable.\n * @throws MiaixzSdkError When scope, schema, or migration configuration is invalid.\n * @public\n */\nexport function readMiaixzVersionedValue<T>(\n  options: Readonly<MiaixzVersionedStorageOptions<T>>,\n): T | undefined {\n  const key = createMiaixzStorageKey(options.scope, options.kind);\n  validateTargetSchemaVersion(options.schemaVersion);\n  validateMigrationChain(options.migrations);\n  if (!options.storage) return undefined;\n  let serialized: string | null;\n  try {\n    serialized = options.storage.getItem(key);\n  } catch {\n    return undefined;\n  }\n  if (serialized === null) return undefined;\n  try {\n    const envelope: unknown = JSON.parse(serialized);\n    if (!isVersionedEnvelope(envelope) || !isNonNegativeSchemaVersion(envelope.schemaVersion)) {\n      safelyRemoveStorageValue(options.storage, key);\n      return undefined;\n    }\n    if (envelope.schemaVersion > options.schemaVersion) {\n      safelyRemoveStorageValue(options.storage, key);\n      return undefined;\n    }\n    let currentVersion = envelope.schemaVersion;\n    let migratedValue: unknown = envelope.value;\n    while (currentVersion < options.schemaVersion) {\n      const migration = options.migrations?.find((candidate) => candidate.from === currentVersion);\n      if (!migration) {\n        safelyRemoveStorageValue(options.storage, key);\n        return undefined;\n      }\n      migratedValue = migration.migrate(migratedValue);\n      currentVersion = migration.to;\n    }\n    const parsed = options.parse(migratedValue);\n    if (envelope.schemaVersion < options.schemaVersion) {\n      writeMiaixzVersionedValue(\n        {\n          storage: options.storage,\n          scope: options.scope,\n          kind: options.kind,\n          schemaVersion: options.schemaVersion,\n        },\n        parsed,\n      );\n    }\n    return parsed;\n  } catch {\n    safelyRemoveStorageValue(options.storage, key);\n    return undefined;\n  }\n}\n\n/**\n * Writes or removes one versioned value without affecting caller memory on persistence failure.\n *\n * @typeParam T - Persisted application value type.\n * @param options - Scope, target schema, and optional storage configuration.\n * @param value - Value to persist, or undefined to remove the physical key.\n * @throws MiaixzSdkError When scope, kind, or target schema is invalid.\n * @public\n */\nexport function writeMiaixzVersionedValue<T>(\n  options: Readonly<Omit<MiaixzVersionedStorageOptions<T>, \"migrations\" | \"parse\">>,\n  value: T | undefined,\n): void {\n  const key = createMiaixzStorageKey(options.scope, options.kind);\n  validateTargetSchemaVersion(options.schemaVersion);\n  if (!options.storage) return;\n  if (value === undefined) {\n    safelyRemoveStorageValue(options.storage, key);\n    return;\n  }\n  try {\n    const envelope: MiaixzVersionedValue<T> = {\n      schemaVersion: options.schemaVersion,\n      value,\n    };\n    options.storage.setItem(key, JSON.stringify(envelope));\n  } catch {\n    // Serialization and adapter failures intentionally degrade to non-persistence.\n  }\n}\n\n/**\n * In-memory storage adapter suitable for tests, SSR, and isolated runtimes.\n *\n * @public\n */\nexport class MiaixzMemoryStorage implements MiaixzKeyValueStorage {\n  readonly #values = new Map<string, string>();\n\n  /**\n   * Reads a value from memory.\n   *\n   * @param key - Storage key to read.\n   * @returns Serialized value or null when the key is absent.\n   */\n  getItem(key: string): string | null {\n    return this.#values.get(key) ?? null;\n  }\n\n  /**\n   * Stores a value in memory.\n   *\n   * @param key - Storage key to write.\n   * @param value - Serialized value to store.\n   */\n  setItem(key: string, value: string): void {\n    this.#values.set(key, value);\n  }\n\n  /**\n   * Removes one in-memory value.\n   *\n   * @param key - Storage key to remove.\n   */\n  removeItem(key: string): void {\n    this.#values.delete(key);\n  }\n\n  /**\n   * Removes every in-memory value.\n   */\n  clear(): void {\n    this.#values.clear();\n  }\n}\n\n/**\n * Prefixes storage keys so multiple services can safely share one backend.\n *\n * @public\n */\nexport class MiaixzNamespacedStorage implements MiaixzKeyValueStorage {\n  /**\n   * Underlying storage adapter receiving the namespaced keys.\n   */\n  readonly storage: MiaixzKeyValueStorage;\n\n  /**\n   * Prefix applied to every logical storage key.\n   */\n  readonly namespace: string;\n\n  /**\n   * Creates a namespaced storage adapter.\n   *\n   * @param storage - Underlying adapter.\n   * @param namespace - Key prefix.\n   */\n  constructor(storage: MiaixzKeyValueStorage, namespace: string) {\n    this.storage = storage;\n    this.namespace = namespace;\n  }\n\n  /**\n   * Builds the physical key used by the underlying adapter.\n   *\n   * @param key - Logical storage key.\n   * @returns Namespaced physical storage key.\n   */\n  #key(key: string): string {\n    return `${this.namespace}:${key}`;\n  }\n\n  /**\n   * Reads a namespaced value.\n   *\n   * @param key - Logical storage key to read.\n   * @returns Serialized value or null when the key is absent.\n   */\n  getItem(key: string): string | null {\n    return this.storage.getItem(this.#key(key));\n  }\n\n  /**\n   * Stores a namespaced value.\n   *\n   * @param key - Logical storage key to write.\n   * @param value - Serialized value to store.\n   */\n  setItem(key: string, value: string): void {\n    this.storage.setItem(this.#key(key), value);\n  }\n\n  /**\n   * Removes a namespaced value.\n   *\n   * @param key - Logical storage key to remove.\n   */\n  removeItem(key: string): void {\n    this.storage.removeItem(this.#key(key));\n  }\n}\n\n/**\n * Safely obtains local or session storage when running in a browser.\n *\n * @param type - Browser storage area to obtain.\n * @returns `undefined` during SSR or when browser storage is blocked.\n * @public\n */\nexport function getMiaixzBrowserStorage(\n  type: \"local\" | \"session\" = \"local\",\n): MiaixzKeyValueStorage | undefined {\n  if (typeof window === \"undefined\") return undefined;\n  try {\n    return type === \"local\" ? window.localStorage : window.sessionStorage;\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Parses and optionally validates JSON stored by a key-value adapter.\n *\n * @param storage - Optional storage adapter to read.\n * @param key - Storage key containing JSON.\n * @param validate - Optional type guard for parsed data.\n * @returns Parsed and validated value when available.\n * @public\n */\nexport function readMiaixzJson<T>(\n  storage: MiaixzKeyValueStorage | undefined,\n  key: string,\n  validate?: (value: unknown) => value is T,\n): T | undefined {\n  const serialized = storage?.getItem(key);\n  if (!serialized) return undefined;\n  try {\n    const value: unknown = JSON.parse(serialized);\n    return validate && !validate(value) ? undefined : (value as T);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Serializes a value as JSON, or removes the key for `undefined`.\n *\n * @param storage - Optional storage adapter to update.\n * @param key - Storage key to write or remove.\n * @param value - Value to serialize, or undefined to remove the key.\n * @public\n */\nexport function writeMiaixzJson<T>(\n  storage: MiaixzKeyValueStorage | undefined,\n  key: string,\n  value: T | undefined,\n): void {\n  if (!storage) return;\n  if (value === undefined) storage.removeItem(key);\n  else storage.setItem(key, JSON.stringify(value));\n}\n"]}