@ursalock/zustand 0.2.8 → 0.3.0

package/dist/hooks.d.ts

@@ -0,0 +1,47 @@
+/**
+ * React hooks for vault status
+ */
+import type { SyncStatus } from './sync.js';
+/**
+ * Hook to get sync status from a vault store
+ *
+ * @example
+ * ```tsx
+ * const status = useSyncStatus(useStore)
+ * // 'idle' | 'syncing' | 'synced' | 'error' | 'offline'
+ * ```
+ */
+export declare function useSyncStatus<T extends {
+    vault?: {
+        getSyncStatus?: () => SyncStatus;
+    };
+}>(useStore: () => T): SyncStatus;
+/**
+ * Hook to check if store has been hydrated
+ *
+ * @example
+ * ```tsx
+ * const hydrated = useHydrated(useStore)
+ * if (!hydrated) return <Loading />
+ * ```
+ */
+export declare function useHydrated<T extends {
+    vault?: {
+        hasHydrated?: () => boolean;
+    };
+}>(useStore: () => T): boolean;
+/**
+ * Hook to check if there are pending offline changes
+ *
+ * @example
+ * ```tsx
+ * const hasPending = usePendingChanges(useStore)
+ * if (hasPending) return <PendingBadge />
+ * ```
+ */
+export declare function usePendingChanges<T extends {
+    vault?: {
+        hasPendingChanges?: () => boolean;
+    };
+}>(useStore: () => T): boolean;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AAE3C;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,UAAU,CAAA;KAAE,CAAA;CAAE,EACtF,QAAQ,EAAE,MAAM,CAAC,GAChB,UAAU,CAGZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,OAAO,CAAA;KAAE,CAAA;CAAE,EAC/E,QAAQ,EAAE,MAAM,CAAC,GAChB,OAAO,CAGT;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAA;KAAE,CAAA;CAAE,EAC3F,QAAQ,EAAE,MAAM,CAAC,GAChB,OAAO,CAGT"}

package/dist/hooks.js

@@ -0,0 +1,42 @@
+/**
+ * React hooks for vault status
+ */
+/**
+ * Hook to get sync status from a vault store
+ *
+ * @example
+ * ```tsx
+ * const status = useSyncStatus(useStore)
+ * // 'idle' | 'syncing' | 'synced' | 'error' | 'offline'
+ * ```
+ */
+export function useSyncStatus(useStore) {
+    const store = useStore();
+    return store.vault?.getSyncStatus?.() ?? 'idle';
+}
+/**
+ * Hook to check if store has been hydrated
+ *
+ * @example
+ * ```tsx
+ * const hydrated = useHydrated(useStore)
+ * if (!hydrated) return <Loading />
+ * ```
+ */
+export function useHydrated(useStore) {
+    const store = useStore();
+    return store.vault?.hasHydrated?.() ?? false;
+}
+/**
+ * Hook to check if there are pending offline changes
+ *
+ * @example
+ * ```tsx
+ * const hasPending = usePendingChanges(useStore)
+ * if (hasPending) return <PendingBadge />
+ * ```
+ */
+export function usePendingChanges(useStore) {
+    const store = useStore();
+    return store.vault?.hasPendingChanges?.() ?? false;
+}

package/dist/index.d.ts

@@ -1,353 +1,18 @@
-import { StoreMutatorIdentifier, StateCreator } from 'zustand';
-import { CipherJWK } from '@ursalock/crypto';
-
 /**
- * Storage interfaces for vault middleware
- * Follows Dependency Inversion Principle - depend on abstractions not concretions
- */
-/**
- * Base storage provider interface
- * Abstracts away the underlying storage mechanism (localStorage, AsyncStorage, etc.)
- */
-interface IStorageProvider {
-    /** Get item from storage */
-    getItem(key: string): Promise<string | null>;
-    /** Set item in storage */
-    setItem(key: string, value: string): Promise<void>;
-    /** Remove item from storage */
-    removeItem(key: string): Promise<void>;
-}
-/**
- * Encrypted vault storage interface
- * Higher-level abstraction that handles encryption/decryption
- */
-interface IVaultStorage {
-    /** Get decrypted state from storage */
-    getItem(name: string): Promise<string | null>;
-    /** Set encrypted state in storage */
-    setItem(name: string, value: string): Promise<void>;
-    /** Remove state from storage */
-    removeItem(name: string): Promise<void>;
-}
-
-/**
- * Encrypted storage layer for vault middleware
- * Supports both legacy recovery key and new CipherJWK encryption
- *
- * Refactored to follow SOLID principles:
- * - Uses IStorageProvider interface (Dependency Inversion)
- * - Separates encryption concerns from storage access (Single Responsibility)
- * - Injectable storage provider for testing
- */
-
-interface VaultStorage extends IVaultStorage {
-}
-
-/** Legacy options using recovery key string */
-interface LegacyEncryptedStorageOptions {
-    /** Recovery key for encryption (legacy mode) */
-    recoveryKey: string;
-    /** Underlying storage provider (default: LocalStorageProvider) */
-    storageProvider?: IStorageProvider;
-    /** Key prefix in storage */
-    prefix?: string;
-    /** @deprecated Use storageProvider instead. For backward compatibility with VaultStorage */
-    storage?: VaultStorage;
-}
-/** New options using CipherJWK directly */
-interface JwkEncryptedStorageOptions {
-    /** CipherJWK for encryption (from ZKCredentials) */
-    cipherJwk: CipherJWK;
-    /** Underlying storage provider (default: LocalStorageProvider) */
-    storageProvider?: IStorageProvider;
-    /** Key prefix in storage */
-    prefix?: string;
-    /** @deprecated Use storageProvider instead. For backward compatibility with VaultStorage */
-    storage?: VaultStorage;
-}
-type EncryptedStorageOptions = LegacyEncryptedStorageOptions | JwkEncryptedStorageOptions;
-/**
- * Create an encrypted storage wrapper
- * Supports both legacy recovery key and new CipherJWK modes
- *
- * Uses dependency injection for storage provider (Dependency Inversion Principle)
- */
-declare function createVaultStorage(options: EncryptedStorageOptions): VaultStorage;
-
-/**
- * HTTP client interface for sync engine
- * Follows Dependency Inversion Principle - allows mocking and alternative implementations
- */
-/** HTTP request options */
-interface IHttpRequest {
-    url: string;
-    method: "GET" | "POST" | "PUT" | "DELETE";
-    headers?: Record<string, string>;
-    body?: string;
-}
-/** HTTP response */
-interface IHttpResponse {
-    ok: boolean;
-    status: number;
-    json<T = unknown>(): Promise<T>;
-    text(): Promise<string>;
-}
-/** HTTP client interface */
-interface IHttpClient {
-    /**
-     * Make an HTTP request
-     * @param request Request options
-     * @returns Response
-     */
-    request(request: IHttpRequest): Promise<IHttpResponse>;
-}
-
-/**
- * Sync engine for vault middleware
- * Handles bidirectional sync with server + offline queue
+ * @ursalock/zustand
+ * Encrypted persistence middleware for Zustand
  *
  * Refactored to follow SOLID principles:
- * - IHttpClient interface (Dependency Inversion)
- * - Separated offline queue logic (Single Responsibility)
- * - Injectable HTTP client for testing
- */
-
-type SyncStatus = "idle" | "syncing" | "synced" | "error" | "offline";
-interface SyncState {
-    /** Last successful sync timestamp */
-    lastSyncAt: number | null;
-    /** Current sync status */
-    status: SyncStatus;
-    /** Pending changes waiting to be synced */
-    pendingChanges: boolean;
-    /** Last error message */
-    error: string | null;
-}
-interface SyncOptions {
-    /** Server base URL */
-    serverUrl: string;
-    /** Vault name */
-    name: string;
-    /** Auth token getter */
-    getToken: () => string | null;
-    /** Called when server has newer data */
-    onServerData: (data: string, salt: string, updatedAt: number) => void;
-    /** Get current local data */
-    getLocalData: () => {
-        data: string;
-        salt: string;
-        updatedAt: number;
-    };
-    /** Called on sync status change */
-    onStatusChange?: (status: SyncStatus) => void;
-    /** HTTP client for making requests (default: FetchHttpClient) */
-    httpClient?: IHttpClient;
-}
-/**
- * Create a sync engine instance
- * Uses dependency injection for HTTP client (Dependency Inversion Principle)
- */
-declare function createSyncEngine(options: SyncOptions): {
-    sync: () => Promise<void>;
-    push: () => Promise<void>;
-    pull: () => Promise<boolean>;
-    getState: () => SyncState;
-    clearQueue: () => void;
-};
-type SyncEngine = ReturnType<typeof createSyncEngine>;
-
-/**
- * vault() middleware - Drop-in replacement for persist()
- * Adds E2EE encryption and cloud sync to Zustand stores
- *
- * Supports two encryption modes:
- * - Legacy: recoveryKey string (Argon2id key derivation)
- * - New: cipherJwk from ZKCredentials (PRF-derived)
- *
- * Type pattern follows zustand's persist middleware:
- * - Simple internal implementation type (VaultImpl)
- * - Complex public API type (Vault)
- * - Cast at export: `vaultImpl as unknown as Vault`
- */
-
-/** Base vault middleware options */
-interface VaultOptionsBase<S, PersistedState = S> {
-    /** Unique name for this vault (used as storage key) */
-    name: string;
-    /**
-     * Server URL for sync (optional)
-     * If not provided, only local encrypted storage is used
-     */
-    server?: string;
-    /**
-     * Auth token getter for server sync
-     * Required if server is provided
-     */
-    getToken?: () => string | null;
-    /** Custom storage implementation */
-    storage?: VaultStorage;
-    /** Storage key prefix (default: 'ursalock:') */
-    prefix?: string;
-    /**
-     * Partial state to persist
-     * @default (state) => state (persist everything)
-     */
-    partialize?: (state: S) => PersistedState;
-    /**
-     * Merge function for rehydration
-     * @default Object.assign
-     */
-    merge?: (persistedState: unknown, currentState: S) => S;
-    /**
-     * Called when state is loaded from storage
-     */
-    onRehydrateStorage?: (state: S) => ((state?: S, error?: unknown) => void) | void;
-    /**
-     * Skip hydration on init (useful for SSR)
-     * Call rehydrate() manually when ready
-     */
-    skipHydration?: boolean;
-    /**
-     * Sync interval in ms (default: 30000 = 30s)
-     * Set to 0 to disable auto-sync
-     */
-    syncInterval?: number;
-}
-/** Legacy options using recovery key string */
-interface VaultOptionsLegacy<S, PersistedState = S> extends VaultOptionsBase<S, PersistedState> {
-    /** Recovery key for E2EE encryption (legacy mode) */
-    recoveryKey: string;
-}
-/** New options using CipherJWK from ZKCredentials */
-interface VaultOptionsJwk<S, PersistedState = S> extends VaultOptionsBase<S, PersistedState> {
-    /** CipherJWK for E2EE encryption (from ZKCredentials) */
-    cipherJwk: CipherJWK;
-}
-type VaultOptions<S, PersistedState = S> = VaultOptionsLegacy<S, PersistedState> | VaultOptionsJwk<S, PersistedState>;
-
-type VaultListener<S> = (state: S) => void;
-
-/** Store shape extended with vault API */
-type StoreVault<S, Ps> = S extends {
-    getState: () => infer T;
-    setState: {
-        (...args: infer Sa1): infer Sr1;
-        (...args: infer Sa2): infer Sr2;
-    };
-} ? {
-    setState(...args: Sa1): Sr1 | Promise<void>;
-    setState(...args: Sa2): Sr2 | Promise<void>;
-    vault: {
-        /** Full bidirectional sync with server */
-        sync: () => Promise<void>;
-        /** Push local changes to server */
-        push: () => Promise<void>;
-        /** Pull latest from server */
-        pull: () => Promise<boolean>;
-        /** Rehydrate from local storage */
-        rehydrate: () => Promise<void>;
-        /** Check if store has been hydrated */
-        hasHydrated: () => boolean;
-        /** Get current sync status */
-        getSyncStatus: () => SyncStatus;
-        /** Check if there are pending offline changes */
-        hasPendingChanges: () => boolean;
-        /** Clear all stored data (local + server) */
-        clearStorage: () => Promise<void>;
-        /** Subscribe to hydration start */
-        onHydrate: (fn: VaultListener<T>) => () => void;
-        /** Subscribe to hydration complete */
-        onFinishHydration: (fn: VaultListener<T>) => () => void;
-    };
-} : never;
-type Write<T, U> = Omit<T, keyof U> & U;
-type WithVault<S, A> = Write<S, StoreVault<S, A>>;
-/** Public API type with complex mutator support */
-type Vault = <T, Mps extends [StoreMutatorIdentifier, unknown][] = [], Mcs extends [StoreMutatorIdentifier, unknown][] = [], U = T>(initializer: StateCreator<T, [...Mps, ["vault", unknown]], Mcs>, options: VaultOptions<T, U>) => StateCreator<T, Mps, [["vault", U], ...Mcs]>;
-declare module "zustand" {
-    interface StoreMutators<S, A> {
-        vault: WithVault<S, A>;
-    }
-}
-/**
- * vault() middleware - Add E2EE encrypted persistence to Zustand
- *
- * @example Using CipherJWK from ZKCredentials (recommended)
- * ```ts
- * const useStore = create(
- *   vault(
- *     (set) => ({
- *       count: 0,
- *       increment: () => set((s) => ({ count: s.count + 1 })),
- *     }),
- *     {
- *       name: 'my-store',
- *       cipherJwk: credential.cipherJwk, // From ZKCredentials
- *       server: 'https://vault.example.com', // optional
- *     }
- *   )
- * )
- * ```
- *
- * @example Using recovery key (legacy)
- * ```ts
- * const useStore = create(
- *   vault(
- *     (set) => ({ ... }),
- *     {
- *       name: 'my-store',
- *       recoveryKey: 'ABCD-EFGH-...',
- *     }
- *   )
- * )
- * ```
- */
-declare const vault: Vault;
-
-/**
- * LocalStorage implementation of IStorageProvider
- * Concrete implementation following Dependency Inversion Principle
- */
-
-/**
- * LocalStorage provider with async interface
- * Wraps synchronous localStorage with async API for consistency
- */
-declare class LocalStorageProvider implements IStorageProvider {
-    getItem(key: string): Promise<string | null>;
-    setItem(key: string, value: string): Promise<void>;
-    removeItem(key: string): Promise<void>;
-}
-
-/**
- * Fetch-based HTTP client implementation
- * Concrete implementation of IHttpClient using browser fetch API
- */
-
-/**
- * HTTP client using native fetch API
- */
-declare class FetchHttpClient implements IHttpClient {
-    request(request: IHttpRequest): Promise<IHttpResponse>;
-}
-
-/**
- * React hooks for vault status
- */
-
-/**
- * Hook to get sync status from a vault store
- *
- * @example
- * ```tsx
- * const status = useSyncStatus(useStore)
- * // 'idle' | 'syncing' | 'synced' | 'error' | 'offline'
- * ```
- */
-declare function useSyncStatus<T extends {
-    vault?: {
-        getSyncStatus?: () => SyncStatus;
-    };
-}>(useStore: () => T): SyncStatus;
-
-export { type EncryptedStorageOptions, FetchHttpClient, type IHttpClient, type IHttpRequest, type IHttpResponse, type IStorageProvider, type IVaultStorage, type JwkEncryptedStorageOptions, type LegacyEncryptedStorageOptions, LocalStorageProvider, type SyncEngine, type SyncState, type SyncStatus, type VaultOptions, type VaultOptionsJwk, type VaultOptionsLegacy, type VaultStorage, createSyncEngine, createVaultStorage, useSyncStatus, vault };
+ * - Interface-based design (Dependency Inversion)
+ * - Injectable dependencies for testing
+ * - Separated concerns (Single Responsibility)
+ */
+export { vault, type VaultOptions, type VaultOptionsLegacy, type VaultOptionsJwk, } from "./vault.js";
+export { createVaultStorage, type VaultStorage, type IStorageProvider, type EncryptedStorageOptions, type LegacyEncryptedStorageOptions, type JwkEncryptedStorageOptions, } from "./storage.js";
+export type { IVaultStorage } from "./interfaces/storage.js";
+export { LocalStorageProvider } from "./providers/local-storage.js";
+export type { IHttpClient, IHttpRequest, IHttpResponse } from "./interfaces/http.js";
+export { FetchHttpClient } from "./providers/fetch-http.js";
+export { type SyncStatus, type SyncState, createSyncEngine, type SyncEngine } from "./sync.js";
+export { useSyncStatus, useHydrated, usePendingChanges } from "./hooks.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EACL,KAAK,EACL,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,GAChC,MAAM,cAAc,CAAC;AAGtB,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAGpE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrF,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAG5D,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AAG/F,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}