@oxog/state 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -478,6 +478,741 @@ declare function useCreateStore<TState>(initialState: TState): Store<TState>;
  * ```
  */
 declare function useAction<TState, TAction extends (...args: any[]) => any>(store: Store<TState>, actionName: string): TAction;
+/**
+ * Create a shallow equality wrapper for selectors.
+ *
+ * Use this hook to wrap selectors that return objects or arrays
+ * and you want to avoid re-renders when the content hasn't changed.
+ *
+ * @param selector - The selector function to wrap
+ * @returns A wrapped selector with shallow equality
+ *
+ * @example
+ * ```typescript
+ * import { useStore, useShallow } from '@oxog/state';
+ *
+ * function UserInfo() {
+ *   // Without useShallow - re-renders on every state change
+ *   const { name, email } = useStore(store, s => ({ name: s.name, email: s.email }));
+ *
+ *   // With useShallow - only re-renders when name or email actually changes
+ *   const { name, email } = useStore(
+ *     store,
+ *     useShallow(s => ({ name: s.name, email: s.email }))
+ *   );
+ * }
+ * ```
+ */
+declare function useShallow<TState, TSelected extends object>(selector: Selector<TState, TSelected>): Selector<TState, TSelected>;
+/**
+ * Hook for selecting multiple actions from a store.
+ *
+ * Returns stable references to actions that don't change between renders.
+ *
+ * @param store - The store instance
+ * @param actionNames - Names of actions to select
+ * @returns An object with the selected actions
+ *
+ * @example
+ * ```typescript
+ * import { useStoreActions } from '@oxog/state';
+ *
+ * function Counter() {
+ *   const { increment, decrement, reset } = useStoreActions(
+ *     store,
+ *     'increment',
+ *     'decrement',
+ *     'reset'
+ *   );
+ *
+ *   return (
+ *     <>
+ *       <button onClick={decrement}>-</button>
+ *       <button onClick={increment}>+</button>
+ *       <button onClick={reset}>Reset</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useStoreActions<TState, TKeys extends string[]>(store: Store<TState>, ...actionNames: TKeys): {
+    [K in TKeys[number]]: (...args: any[]) => any;
+};
+/**
+ * Hook for selecting multiple values with independent selectors.
+ *
+ * Each selector is tracked independently, so the component only
+ * re-renders when a selector's output actually changes.
+ *
+ * @param store - The store instance
+ * @param selectors - Object of named selectors
+ * @returns An object with selected values
+ *
+ * @example
+ * ```typescript
+ * import { useStoreSelector } from '@oxog/state';
+ *
+ * function Dashboard() {
+ *   const { userCount, activeUsers, totalRevenue } = useStoreSelector(store, {
+ *     userCount: s => s.users.length,
+ *     activeUsers: s => s.users.filter(u => u.active).length,
+ *     totalRevenue: s => s.orders.reduce((sum, o) => sum + o.total, 0),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <p>Users: {userCount} ({activeUsers} active)</p>
+ *       <p>Revenue: ${totalRevenue}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useStoreSelector<TState, TSelectors extends Record<string, Selector<TState, any>>>(store: Store<TState>, selectors: TSelectors): {
+    [K in keyof TSelectors]: ReturnType<TSelectors[K]>;
+};
+/**
+ * Hook for transient updates - subscribe without causing re-renders.
+ *
+ * Use this for side effects that don't need to update the UI.
+ *
+ * @param store - The store instance
+ * @param selector - Selector function
+ * @param callback - Callback to run on changes
+ *
+ * @example
+ * ```typescript
+ * import { useTransientSubscribe } from '@oxog/state';
+ *
+ * function Analytics() {
+ *   // Track page views without re-rendering
+ *   useTransientSubscribe(
+ *     store,
+ *     s => s.currentPage,
+ *     (page) => analytics.track('pageview', { page })
+ *   );
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useTransientSubscribe<TState, TSelected>(store: Store<TState>, selector: Selector<TState, TSelected>, callback: (value: TSelected, prevValue: TSelected) => void, equalityFn?: EqualityFn<TSelected>): void;
+/**
+ * Hook that returns the store's setState function with stable reference.
+ *
+ * @param store - The store instance
+ * @returns The setState function
+ *
+ * @example
+ * ```typescript
+ * function Form() {
+ *   const setState = useSetState(store);
+ *
+ *   const handleChange = (e) => {
+ *     setState({ [e.target.name]: e.target.value });
+ *   };
+ *
+ *   return <input onChange={handleChange} />;
+ * }
+ * ```
+ */
+declare function useSetState<TState>(store: Store<TState>): (partial: Partial<TState> | ((state: TState) => Partial<TState>)) => void;
+
+/**
+ * Enhanced subscription system with advanced options.
+ *
+ * @module subscribe
+ */
+
+/**
+ * Options for enhanced subscriptions.
+ *
+ * @typeParam T - The store state type
+ * @typeParam U - The selected value type
+ *
+ * @example
+ * ```typescript
+ * const options: SubscribeOptions<State, number> = {
+ *   debounce: 100,
+ *   fireImmediately: true,
+ *   when: (state) => state.isReady
+ * };
+ * ```
+ */
+interface SubscribeOptions<T, U = T> {
+    /** Custom equality function for comparing selected values */
+    equalityFn?: EqualityFn<U>;
+    /** Fire callback immediately with current state */
+    fireImmediately?: boolean;
+    /** Debounce notifications (ms) */
+    debounce?: number;
+    /** Throttle notifications (ms) */
+    throttle?: number;
+    /** Only fire when condition is met */
+    when?: (state: T, prevState: T) => boolean;
+}
+/**
+ * Enhanced subscribe function with advanced options.
+ *
+ * @param store - The store to subscribe to
+ * @param selectorOrListener - Selector function or direct listener
+ * @param listenerOrOptions - Listener function or options (if no selector)
+ * @param options - Subscription options
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * // With debounce
+ * const unsubscribe = subscribeWithOptions(
+ *   store,
+ *   (state) => state.searchQuery,
+ *   (query) => performSearch(query),
+ *   { debounce: 300 }
+ * );
+ *
+ * // With throttle and condition
+ * const unsubscribe = subscribeWithOptions(
+ *   store,
+ *   (state) => state.scrollPosition,
+ *   (pos) => updateUI(pos),
+ *   { throttle: 16, when: (state) => state.isVisible }
+ * );
+ *
+ * // Fire immediately
+ * const unsubscribe = subscribeWithOptions(
+ *   store,
+ *   (state) => state.user,
+ *   (user) => console.log('User:', user),
+ *   { fireImmediately: true }
+ * );
+ * ```
+ */
+declare function subscribeWithOptions<TState, TSelected>(store: Store<TState>, selector: Selector<TState, TSelected>, listener: Listener<TSelected>, options?: SubscribeOptions<TState, TSelected>): () => void;
+/**
+ * Create a subscription factory with preset options.
+ *
+ * @param defaultOptions - Default options for all subscriptions
+ * @returns A subscribe function with preset options
+ *
+ * @example
+ * ```typescript
+ * const debouncedSubscribe = createSubscriber({ debounce: 100 });
+ *
+ * const unsubscribe = debouncedSubscribe(
+ *   store,
+ *   (state) => state.input,
+ *   (input) => validate(input)
+ * );
+ * ```
+ */
+declare function createSubscriber<TState>(defaultOptions?: SubscribeOptions<TState, any>): <TSelected>(store: Store<TState>, selector: Selector<TState, TSelected>, listener: Listener<TSelected>, options?: SubscribeOptions<TState, TSelected>) => () => void;
+/**
+ * Subscribe to multiple selectors with a single listener.
+ *
+ * @param store - The store to subscribe to
+ * @param selectors - Object of named selectors
+ * @param listener - Listener called when any selector value changes
+ * @param options - Subscription options
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * const unsubscribe = subscribeToMany(
+ *   store,
+ *   {
+ *     count: (s) => s.count,
+ *     name: (s) => s.name,
+ *   },
+ *   ({ count, name }) => console.log(`${name}: ${count}`)
+ * );
+ * ```
+ */
+declare function subscribeToMany<TState, TSelectors extends Record<string, Selector<TState, any>>>(store: Store<TState>, selectors: TSelectors, listener: (values: {
+    [K in keyof TSelectors]: ReturnType<TSelectors[K]>;
+}) => void, options?: Omit<SubscribeOptions<TState, any>, 'equalityFn'>): () => void;
+/**
+ * Subscribe only once - automatically unsubscribes after first call.
+ *
+ * @param store - The store to subscribe to
+ * @param selector - Selector function
+ * @param listener - Listener called once when value changes
+ * @param options - Subscription options
+ * @returns Unsubscribe function (can be called to cancel before trigger)
+ *
+ * @example
+ * ```typescript
+ * // Wait for user to be loaded
+ * subscribeOnce(
+ *   store,
+ *   (state) => state.user,
+ *   (user) => console.log('User loaded:', user),
+ *   { when: (state) => state.user !== null }
+ * );
+ * ```
+ */
+declare function subscribeOnce<TState, TSelected>(store: Store<TState>, selector: Selector<TState, TSelected>, listener: Listener<TSelected>, options?: SubscribeOptions<TState, TSelected>): () => void;
+
+/**
+ * Computed values (derived state) with memoization.
+ *
+ * @module computed
+ */
+
+/**
+ * Options for computed values.
+ *
+ * @typeParam T - The store state type
+ * @typeParam U - The computed value type
+ */
+interface ComputedOptions<T, U> {
+    /** Custom equality for caching */
+    equals?: EqualityFn<U>;
+    /** Lazy evaluation (only compute when accessed) */
+    lazy?: boolean;
+    /** Keep last N values in cache for time-travel debugging */
+    cacheSize?: number;
+}
+/**
+ * Computed value interface with getter and utilities.
+ */
+interface Computed<U> {
+    /** Get the computed value */
+    (): U;
+    /** Get value (alias) */
+    get(): U;
+    /** Force recomputation */
+    invalidate(): void;
+    /** Subscribe to value changes */
+    subscribe(listener: (value: U, prevValue: U) => void): () => void;
+    /** Get cache history (if cacheSize > 1) */
+    getHistory(): U[];
+    /** Destroy and cleanup */
+    destroy(): void;
+}
+/**
+ * Create a computed (derived) value from store state.
+ *
+ * Computed values are memoized and only recompute when dependencies change.
+ *
+ * @param store - The store to derive from
+ * @param selector - Function to compute the derived value
+ * @param options - Computed options
+ * @returns A computed value accessor
+ *
+ * @example
+ * ```typescript
+ * const store = createStore({ items: [], filter: 'all' });
+ *
+ * // Simple computed
+ * const filteredItems = computed(store, (state) => {
+ *   if (state.filter === 'all') return state.items;
+ *   return state.items.filter(item => item.status === state.filter);
+ * });
+ *
+ * console.log(filteredItems()); // Get computed value
+ *
+ * // With caching for debugging
+ * const total = computed(
+ *   store,
+ *   (state) => state.items.reduce((sum, item) => sum + item.price, 0),
+ *   { cacheSize: 10 }
+ * );
+ *
+ * console.log(total.getHistory()); // See past values
+ * ```
+ */
+declare function computed<TState, TComputed>(store: Store<TState>, selector: Selector<TState, TComputed>, options?: ComputedOptions<TState, TComputed>): Computed<TComputed>;
+/**
+ * Create a computed value that depends on other computed values.
+ *
+ * @param computeds - Array of computed values to depend on
+ * @param combiner - Function to combine the computed values
+ * @param options - Computed options
+ * @returns A combined computed value
+ *
+ * @example
+ * ```typescript
+ * const subtotal = computed(store, (s) => s.items.reduce((sum, i) => sum + i.price, 0));
+ * const tax = computed(store, (s) => s.taxRate);
+ *
+ * const total = combineComputed(
+ *   [subtotal, tax],
+ *   ([subtotalVal, taxVal]) => subtotalVal * (1 + taxVal)
+ * );
+ *
+ * console.log(total()); // Subtotal + tax
+ * ```
+ */
+declare function combineComputed<TInputs extends Computed<any>[], TOutput>(computeds: [...TInputs], combiner: (values: {
+    [K in keyof TInputs]: TInputs[K] extends Computed<infer U> ? U : never;
+}) => TOutput, options?: Omit<ComputedOptions<any, TOutput>, 'lazy'>): Computed<TOutput>;
+/**
+ * Create a memoized selector for use with store.subscribe.
+ *
+ * @param selector - The selector function to memoize
+ * @param equals - Custom equality function
+ * @returns A memoized selector
+ *
+ * @example
+ * ```typescript
+ * const selectExpensiveComputation = memoizeSelector(
+ *   (state: State) => expensiveOperation(state.data)
+ * );
+ *
+ * store.subscribe(selectExpensiveComputation, (result) => {
+ *   console.log('Result:', result);
+ * });
+ * ```
+ */
+declare function memoizeSelector<TState, TSelected>(selector: Selector<TState, TSelected>, equals?: EqualityFn<TSelected>): Selector<TState, TSelected>;
+
+/**
+ * Slices pattern for modular store composition.
+ *
+ * @module slices
+ */
+
+/**
+ * SetSlice function type for updating slice state.
+ */
+type SetSlice<TState> = {
+    (partial: Partial<TState>): void;
+    (updater: (state: TState) => Partial<TState>): void;
+};
+/**
+ * GetSlice function type for getting current state.
+ */
+type GetSlice<TState> = () => TState;
+/**
+ * Slice creator function signature.
+ *
+ * @typeParam TState - The full store state type
+ * @typeParam TSlice - The slice state type
+ */
+type SliceCreator<TState, TSlice extends Partial<TState>> = (set: SetSlice<TState>, get: GetSlice<TState>, store: Store<TState>) => TSlice;
+/**
+ * Slice definition with state and actions.
+ */
+interface SliceDefinition<TState, TSlice extends Partial<TState>> {
+    /** Slice name for debugging */
+    name: string;
+    /** Slice creator function */
+    creator: SliceCreator<TState, TSlice>;
+}
+/**
+ * Create a slice definition for use with combineSlices.
+ *
+ * Slices are modular pieces of state and actions that can be combined
+ * to create a complete store.
+ *
+ * @param name - Slice name for debugging
+ * @param creator - Slice creator function
+ * @returns A slice definition
+ *
+ * @example
+ * ```typescript
+ * // Define a counter slice
+ * const counterSlice = createSlice('counter', (set, get) => ({
+ *   count: 0,
+ *   increment: () => set((s) => ({ count: s.count + 1 })),
+ *   decrement: () => set((s) => ({ count: s.count - 1 })),
+ *   reset: () => set({ count: 0 }),
+ * }));
+ *
+ * // Define a user slice
+ * const userSlice = createSlice('user', (set, get) => ({
+ *   user: null as User | null,
+ *   setUser: (user: User) => set({ user }),
+ *   logout: () => set({ user: null }),
+ * }));
+ *
+ * // Combine slices into a store
+ * const store = combineSlices(counterSlice, userSlice);
+ *
+ * // Use the store
+ * store.increment();
+ * store.setUser({ name: 'John' });
+ * ```
+ */
+declare function createSlice<TState, TSlice extends Partial<TState>>(name: string, creator: SliceCreator<TState, TSlice>): SliceDefinition<TState, TSlice>;
+/**
+ * Internal slice creator type for type inference.
+ */
+type InferSlice<T> = T extends SliceDefinition<any, infer S> ? S : never;
+/**
+ * Combined state type from multiple slices.
+ */
+type CombinedState<TSlices extends SliceDefinition<any, any>[]> = {
+    [K in keyof TSlices]: InferSlice<TSlices[K]>;
+}[number] extends infer U ? U extends object ? {
+    [K in keyof U as U extends Record<K, any> ? K : never]: U[K];
+} : never : never;
+/**
+ * Combine multiple slices into a single store.
+ *
+ * @param slices - Slice definitions to combine
+ * @returns A store with combined state and actions
+ *
+ * @example
+ * ```typescript
+ * const counterSlice = createSlice('counter', (set) => ({
+ *   count: 0,
+ *   increment: () => set((s) => ({ count: s.count + 1 })),
+ * }));
+ *
+ * const userSlice = createSlice('user', (set) => ({
+ *   user: null,
+ *   setUser: (user) => set({ user }),
+ * }));
+ *
+ * const store = combineSlices(counterSlice, userSlice);
+ *
+ * // Type-safe access to all slice methods
+ * store.increment();
+ * store.setUser({ name: 'John' });
+ * ```
+ */
+declare function combineSlices<TSlices extends SliceDefinition<any, any>[]>(...slices: TSlices): Store<CombinedState<TSlices>> & CombinedState<TSlices>;
+/**
+ * Create a namespaced slice that prefixes all state keys.
+ *
+ * @param namespace - The namespace prefix
+ * @param creator - Slice creator function
+ * @returns A namespaced slice definition
+ *
+ * @example
+ * ```typescript
+ * const settingsSlice = createNamespacedSlice('settings', (set) => ({
+ *   theme: 'dark',
+ *   language: 'en',
+ *   setTheme: (theme) => set({ theme }),
+ * }));
+ *
+ * // State will be: { settings: { theme: 'dark', language: 'en' } }
+ * // Actions will be: setTheme
+ * ```
+ */
+declare function createNamespacedSlice<TSlice extends Record<string, any>>(namespace: string, creator: (set: (partial: Partial<TSlice>) => void, get: () => TSlice) => TSlice): SliceDefinition<Record<string, any>, Record<string, any>>;
+/**
+ * Extend an existing store with additional slices.
+ *
+ * @param store - The existing store
+ * @param slices - Additional slices to add
+ * @returns The extended store
+ *
+ * @example
+ * ```typescript
+ * const baseStore = createStore({ count: 0 });
+ *
+ * const extendedStore = extendStore(
+ *   baseStore,
+ *   createSlice('user', (set) => ({
+ *     user: null,
+ *     setUser: (user) => set({ user }),
+ *   }))
+ * );
+ * ```
+ */
+declare function extendStore<TState, TSlices extends SliceDefinition<TState & any, any>[]>(store: Store<TState>, ...slices: TSlices): Store<TState & CombinedState<TSlices>> & CombinedState<TSlices>;
+/**
+ * Reset specific slices to their initial state.
+ *
+ * @param store - The store
+ * @param sliceNames - Names of slices to reset
+ *
+ * @example
+ * ```typescript
+ * // Reset only the user slice
+ * resetSlices(store, 'user');
+ *
+ * // Reset multiple slices
+ * resetSlices(store, 'user', 'cart');
+ * ```
+ */
+declare function resetSlices<TState>(store: Store<TState>, ...sliceNames: string[]): void;
+
+/**
+ * Store Federation - Multi-store coordination and communication.
+ *
+ * Enables coordinated updates across multiple stores with
+ * atomic transactions and unified state access.
+ *
+ * @module federation
+ */
+
+/**
+ * Extract state type from a Store.
+ */
+type StoreState<S> = S extends Store<infer T> ? T : never;
+/**
+ * Map of store names to their state types.
+ */
+type FederatedState<Stores extends Record<string, Store<any>>> = {
+    [K in keyof Stores]: StoreState<Stores[K]>;
+};
+/**
+ * Federation listener callback.
+ */
+type FederationListener<Stores extends Record<string, Store<any>>> = (state: FederatedState<Stores>, prevState: FederatedState<Stores>, changedStore: keyof Stores) => void;
+/**
+ * Federation transaction function.
+ */
+type TransactionFn<Stores extends Record<string, Store<any>>> = (stores: Stores) => void | Promise<void>;
+/**
+ * Federation options.
+ */
+interface FederationOptions {
+    /** Name for debugging */
+    name?: string;
+    /** Enable transaction logging */
+    debug?: boolean;
+}
+/**
+ * Federation interface for coordinating multiple stores.
+ */
+interface Federation<Stores extends Record<string, Store<any>>> {
+    /** Access to individual stores */
+    readonly stores: Stores;
+    /** Get combined state from all stores */
+    getState(): FederatedState<Stores>;
+    /** Subscribe to any store change */
+    subscribe(listener: FederationListener<Stores>): () => void;
+    /** Atomic multi-store update (synchronous) */
+    transaction(fn: TransactionFn<Stores>): void;
+    /** Async transaction with rollback on error */
+    transactionAsync(fn: TransactionFn<Stores>): Promise<void>;
+    /** Get a specific store */
+    getStore<K extends keyof Stores>(name: K): Stores[K];
+    /** Destroy federation and unsubscribe from all stores */
+    destroy(): void;
+}
+/**
+ * Create a federation of multiple stores.
+ *
+ * @param stores - Object containing named stores
+ * @param options - Federation options
+ * @returns A federation instance
+ *
+ * @example
+ * ```typescript
+ * import { createStore, createFederation } from '@oxog/state';
+ *
+ * // Create individual stores
+ * const userStore = createStore({
+ *   user: null,
+ *   setUser: (state, user) => ({ user }),
+ * });
+ *
+ * const cartStore = createStore({
+ *   items: [],
+ *   addItem: (state, item) => ({ items: [...state.items, item] }),
+ *   clear: () => ({ items: [] }),
+ * });
+ *
+ * const settingsStore = createStore({
+ *   theme: 'light',
+ *   setTheme: (state, theme) => ({ theme }),
+ * });
+ *
+ * // Create federation
+ * const federation = createFederation({
+ *   user: userStore,
+ *   cart: cartStore,
+ *   settings: settingsStore,
+ * });
+ *
+ * // Get combined state
+ * const state = federation.getState();
+ * // { user: { user: null, ... }, cart: { items: [], ... }, settings: { theme: 'light', ... } }
+ *
+ * // Subscribe to any store change
+ * federation.subscribe((state, prevState, changedStore) => {
+ *   console.log(`${changedStore} changed:`, state[changedStore]);
+ * });
+ *
+ * // Atomic cross-store transaction
+ * federation.transaction(({ user, cart }) => {
+ *   cart.setState({ items: [] });
+ *   user.setState({ user: null });
+ * });
+ * ```
+ */
+declare function createFederation<Stores extends Record<string, Store<any>>>(stores: Stores, options?: FederationOptions): Federation<Stores>;
+/**
+ * Create a selector that combines state from multiple stores.
+ *
+ * @param federation - The federation instance
+ * @param selector - Selector function
+ * @returns A function that returns the selected value
+ *
+ * @example
+ * ```typescript
+ * const getCartTotal = createFederatedSelector(
+ *   federation,
+ *   (state) => {
+ *     const items = state.cart.items;
+ *     const discount = state.user.user?.discount || 0;
+ *     const total = items.reduce((sum, item) => sum + item.price, 0);
+ *     return total * (1 - discount);
+ *   }
+ * );
+ *
+ * const total = getCartTotal();
+ * ```
+ */
+declare function createFederatedSelector<Stores extends Record<string, Store<any>>, R>(federation: Federation<Stores>, selector: (state: FederatedState<Stores>) => R): () => R;
+/**
+ * Create a computed value from federated state.
+ *
+ * @param federation - The federation instance
+ * @param selector - Selector function
+ * @param equalityFn - Optional equality function for caching
+ * @returns Object with get() and subscribe() methods
+ *
+ * @example
+ * ```typescript
+ * const isLoggedIn = createFederatedComputed(
+ *   federation,
+ *   (state) => state.user.user !== null
+ * );
+ *
+ * // Get current value
+ * if (isLoggedIn.get()) {
+ *   showDashboard();
+ * }
+ *
+ * // Subscribe to changes
+ * isLoggedIn.subscribe((value) => {
+ *   console.log('Login status:', value);
+ * });
+ * ```
+ */
+declare function createFederatedComputed<Stores extends Record<string, Store<any>>, R>(federation: Federation<Stores>, selector: (state: FederatedState<Stores>) => R, equalityFn?: (a: R, b: R) => boolean): {
+    get(): R;
+    subscribe(listener: (value: R, prevValue: R) => void): () => void;
+};
+/**
+ * Wait for a condition across federated stores.
+ *
+ * @param federation - The federation instance
+ * @param predicate - Condition to wait for
+ * @param timeout - Optional timeout in ms
+ * @returns Promise that resolves when condition is met
+ *
+ * @example
+ * ```typescript
+ * // Wait for user to be logged in and cart to have items
+ * await waitForFederated(
+ *   federation,
+ *   (state) => state.user.user !== null && state.cart.items.length > 0,
+ *   5000 // 5 second timeout
+ * );
+ *
+ * // Now proceed with checkout
+ * checkout();
+ * ```
+ */
+declare function waitForFederated<Stores extends Record<string, Store<any>>>(federation: Federation<Stores>, predicate: (state: FederatedState<Stores>) => boolean, timeout?: number): Promise<FederatedState<Stores>>;
 
 /**
  * Plugin-specific types and interfaces.
@@ -495,6 +1230,30 @@ interface PersistOptions<TState> {
     whitelist?: Array<keyof TState>;
     /** List of state keys to exclude (blacklist) */
     blacklist?: Array<keyof TState>;
+    /** Custom function to select which parts of state to persist */
+    partialize?: (state: TState) => Partial<TState>;
+    /** Custom merge strategy for hydration */
+    merge?: (persistedState: Partial<TState>, currentState: TState) => TState;
+    /** Version for migration support */
+    version?: number;
+    /** Migration function between versions */
+    migrate?: (persistedState: unknown, version: number) => TState;
+    /** Custom serialization */
+    serialize?: (state: Partial<TState>) => string;
+    /** Custom deserialization */
+    deserialize?: (str: string) => Partial<TState>;
+    /** Encryption function */
+    encrypt?: (data: string) => string;
+    /** Decryption function */
+    decrypt?: (data: string) => string;
+    /** Debounce writes to storage (ms) */
+    writeDebounce?: number;
+    /** Called when hydration starts */
+    onRehydrateStorage?: (state: TState | undefined) => void;
+    /** Called when hydration completes */
+    onHydrationComplete?: (state: TState) => void;
+    /** Called on persistence error */
+    onPersistError?: (error: Error) => void;
 }
 /**
  * Storage interface for persistence.
@@ -596,9 +1355,25 @@ declare const sessionStorage: StorageLike;
  * const store = createStore({ count: 0, temp: '' })
  *   .use(persist({ key: 'app', whitelist: ['count'] }));
  *
- * // With blacklist
- * const store = createStore({ count: 0, temp: '' })
- *   .use(persist({ key: 'app', blacklist: ['temp'] }));
+ * // With encryption
+ * const store = createStore({ secret: 'data' })
+ *   .use(persist({
+ *     key: 'secure',
+ *     encrypt: (data) => btoa(data),
+ *     decrypt: (data) => atob(data),
+ *   }));
+ *
+ * // With debounce and migration
+ * const store = createStore({ count: 0 })
+ *   .use(persist({
+ *     key: 'app',
+ *     writeDebounce: 1000,
+ *     version: 2,
+ *     migrate: (state, version) => {
+ *       if (version < 2) return { ...state, newField: 'default' };
+ *       return state;
+ *     },
+ *   }));
  * ```
  */
 declare function persist<TState>(options: PersistOptions<TState>): Plugin<TState>;
@@ -807,92 +1582,611 @@ declare function triggerSync<TState>(store: Store<TState>, channel?: string): vo
  * ```typescript
  * import { produce } from '@oxog/state';
  *
- * const state = { users: [{ name: 'John', age: 30 }] };
- * const newState = produce(state, (draft) => {
- *   draft.users[0].age = 31;
- * });
+ * const state = { users: [{ name: 'John', age: 30 }] };
+ * const newState = produce(state, (draft) => {
+ *   draft.users[0].age = 31;
+ * });
+ * ```
+ */
+declare function produce<T>(base: T, recipe: (draft: T) => void): T;
+/**
+ * Create an immer plugin.
+ *
+ * @returns An immer plugin
+ *
+ * @example
+ * ```typescript
+ * import { createStore, immer } from '@oxog/state';
+ *
+ * const store = createStore({
+ *   items: [{ id: 1, name: 'Item 1' }]
+ * }).use(immer());
+ *
+ * // Now setState can accept a mutable recipe function
+ * store.setState((draft) => {
+ *   draft.items[0].name = 'Updated Item';
+ *   draft.items.push({ id: 2, name: 'Item 2' });
+ * });
+ * ```
+ */
+declare function immer<TState>(): Plugin<TState>;
+
+/**
+ * Selector plugin - Computed/derived values.
+ *
+ * Define computed values that automatically update when dependencies change.
+ *
+ * @example
+ * ```typescript
+ * import { createStore, selector } from '@oxog/state';
+ *
+ * const store = createStore({
+ *   items: [],
+ *   filter: 'all',
+ * })
+ * .use(selector({
+ *   // Computed: filtered items
+ *   filteredItems: (state) => {
+ *     if (state.filter === 'all') return state.items;
+ *     return state.items.filter((item: any) => item.status === state.filter);
+ *   },
+ *   // Computed: item count
+ *   itemCount: (state) => state.items.length,
+ * }));
+ *
+ * // Access computed values
+ * const state = store.getState();
+ * console.log(state.filteredItems); // Computed value
+ * ```
+ */
+
+/**
+ * Create a selector plugin for computed values.
+ *
+ * @param options - Plugin options with selectors
+ * @returns A selector plugin
+ *
+ * @example
+ * ```typescript
+ * import { selector } from '@oxog/state';
+ *
+ * const store = createStore({
+ *   items: [{ price: 10 }, { price: 20 }],
+ *   taxRate: 0.1,
+ * })
+ * .use(selector({
+ *   // Computed total
+ *   total: (state) =>
+ *     state.items.reduce((sum: number, item: any) => sum + item.price, 0),
+ *
+ *   // Computed total with tax
+ *   totalWithTax: (state) => {
+ *     const total = state.items.reduce((sum: number, item: any) => sum + item.price, 0);
+ *     return total * (1 + state.taxRate);
+ *   },
+ * }));
+ * ```
+ */
+declare function selector<TState>(options: SelectorOptions<TState>): Plugin<TState>;
+
+/**
+ * Logger plugin for console logging state changes.
+ *
+ * @module plugins/logger
+ */
+
+/**
+ * Log level for filtering messages.
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Logger options.
+ */
+interface LoggerOptions<TState = unknown> {
+    /** Log level filter (default: 'debug') */
+    level?: LogLevel;
+    /** Custom logger (default: console) */
+    logger?: Console;
+    /** Use collapsed console groups (default: true) */
+    collapsed?: boolean;
+    /** Show state diff (default: true) */
+    diff?: boolean;
+    /** Colorize output (default: true in browsers) */
+    colors?: boolean;
+    /** Show timestamp (default: true) */
+    timestamp?: boolean;
+    /** Filter function to skip certain changes */
+    filter?: (state: TState, prevState: TState) => boolean;
+    /** Transform state before logging */
+    stateTransformer?: (state: TState) => unknown;
+    /** Custom action name (default: 'STATE_CHANGE') */
+    actionName?: string | ((state: TState, prevState: TState) => string);
+    /** Name for this logger instance */
+    name?: string;
+    /** Enabled flag (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Create a logger plugin.
+ *
+ * @param options - Logger options
+ * @returns A logger plugin
+ *
+ * @example
+ * ```typescript
+ * import { createStore, logger } from '@oxog/state';
+ *
+ * // Basic usage
+ * const store = createStore({ count: 0 })
+ *   .use(logger());
+ *
+ * // With options
+ * const store = createStore({ count: 0 })
+ *   .use(logger({
+ *     level: 'info',
+ *     collapsed: false,
+ *     diff: true,
+ *     name: 'CounterStore',
+ *   }));
+ *
+ * // Disabled in production
+ * const store = createStore({ count: 0 })
+ *   .use(logger({
+ *     enabled: process.env.NODE_ENV !== 'production',
+ *   }));
+ * ```
+ */
+declare function logger<TState = unknown>(options?: LoggerOptions<TState>): Plugin<TState>;
+/**
+ * Create a logger with preset options.
+ *
+ * @param defaultOptions - Default options
+ * @returns A logger factory function
+ *
+ * @example
+ * ```typescript
+ * const devLogger = createLogger({
+ *   enabled: process.env.NODE_ENV === 'development',
+ *   collapsed: true,
+ * });
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(devLogger({ name: 'Counter' }));
+ * ```
+ */
+declare function createLogger<TState = unknown>(defaultOptions?: LoggerOptions<TState>): (options?: LoggerOptions<TState>) => Plugin<TState>;
+
+/**
+ * Effects plugin for managing side effects.
+ *
+ * Provides a declarative way to handle async operations,
+ * API calls, and other side effects in response to state changes.
+ *
+ * @module plugins/effects
+ */
+
+/**
+ * Effect cleanup function.
+ */
+type EffectCleanup = () => void;
+/**
+ * Effect function that runs when dependencies change.
+ */
+type EffectFn<T> = (value: T, prevValue: T, utils: EffectUtils) => void | EffectCleanup | Promise<void | EffectCleanup>;
+/**
+ * Utilities available to effects.
+ */
+interface EffectUtils {
+    /** Get current store state */
+    getState: () => unknown;
+    /** Set store state */
+    setState: (partial: any) => void;
+    /** Check if effect is still active (not cancelled) */
+    isActive: () => boolean;
+    /** Cancel this effect */
+    cancel: () => void;
+    /** Run a callback only if effect is active */
+    onlyIfActive: <T>(fn: () => T) => T | undefined;
+}
+/**
+ * Effect definition for the effects plugin.
+ */
+interface EffectDefinition<TState, TSelected = TState> {
+    /** Selector to watch */
+    selector: Selector<TState, TSelected>;
+    /** Effect function */
+    effect: EffectFn<TSelected>;
+    /** Custom equality function */
+    equalityFn?: EqualityFn<TSelected>;
+    /** Fire effect immediately with current value */
+    fireImmediately?: boolean;
+    /** Debounce effect (ms) */
+    debounce?: number;
+    /** Effect name for debugging */
+    name?: string;
+}
+/**
+ * Options for the effects plugin.
+ */
+interface EffectsOptions<TState> {
+    /** Array of effect definitions */
+    effects: EffectDefinition<TState, any>[];
+    /** Error handler for effect errors */
+    onError?: (error: Error, effectName?: string) => void;
+}
+/**
+ * Create an effects plugin.
+ *
+ * @param options - Effects configuration
+ * @returns An effects plugin
+ *
+ * @example
+ * ```typescript
+ * import { createStore, effects } from '@oxog/state';
+ *
+ * const store = createStore({
+ *   userId: null,
+ *   user: null,
+ *   loading: false,
+ * }).use(effects({
+ *   effects: [
+ *     {
+ *       name: 'fetchUser',
+ *       selector: (s) => s.userId,
+ *       effect: async (userId, _prev, { setState, isActive }) => {
+ *         if (!userId) return;
+ *
+ *         setState({ loading: true });
+ *         try {
+ *           const user = await fetchUser(userId);
+ *           if (isActive()) {
+ *             setState({ user, loading: false });
+ *           }
+ *         } catch (error) {
+ *           if (isActive()) {
+ *             setState({ user: null, loading: false });
+ *           }
+ *         }
+ *       },
+ *     },
+ *   ],
+ * }));
+ * ```
+ */
+declare function effects<TState>(options: EffectsOptions<TState>): Plugin<TState>;
+/**
+ * Create an effect definition helper.
+ *
+ * @param name - Effect name
+ * @param selector - Selector to watch
+ * @param effect - Effect function
+ * @param options - Additional options
+ * @returns Effect definition
+ *
+ * @example
+ * ```typescript
+ * const fetchUserEffect = createEffect(
+ *   'fetchUser',
+ *   (s) => s.userId,
+ *   async (userId, _prev, { setState }) => {
+ *     const user = await api.getUser(userId);
+ *     setState({ user });
+ *   },
+ *   { fireImmediately: true }
+ * );
+ *
+ * const store = createStore({ userId: null, user: null })
+ *   .use(effects({ effects: [fetchUserEffect] }));
+ * ```
+ */
+declare function createEffect<TState, TSelected>(name: string, selector: Selector<TState, TSelected>, effect: EffectFn<TSelected>, options?: Omit<EffectDefinition<TState, TSelected>, 'name' | 'selector' | 'effect'>): EffectDefinition<TState, TSelected>;
+/**
+ * Create a simple effect that runs on any state change.
+ *
+ * @param effect - Effect function
+ * @param options - Effect options
+ * @returns Effect definition
+ *
+ * @example
+ * ```typescript
+ * const logEffect = createSimpleEffect(
+ *   (state, prevState) => {
+ *     console.log('State changed:', state);
+ *   }
+ * );
+ * ```
+ */
+declare function createSimpleEffect<TState>(effect: (state: TState, prevState: TState, utils: EffectUtils) => void | EffectCleanup, options?: Omit<EffectDefinition<TState, TState>, 'selector' | 'effect'>): EffectDefinition<TState, TState>;
+/**
+ * Combine multiple effect definitions.
+ *
+ * @param effectDefs - Effect definitions to combine
+ * @returns Combined effects options
+ *
+ * @example
+ * ```typescript
+ * const store = createStore({ ... })
+ *   .use(effects(combineEffects(
+ *     fetchUserEffect,
+ *     saveToStorageEffect,
+ *     analyticsEffect,
+ *   )));
+ * ```
+ */
+declare function combineEffects<TState>(...effectDefs: EffectDefinition<TState, any>[]): EffectsOptions<TState>;
+/**
+ * Create a debounced effect that only fires after a delay.
+ *
+ * @param delay - Debounce delay in ms
+ * @param selector - Selector to watch
+ * @param effect - Effect function
+ * @returns Effect definition
+ *
+ * @example
+ * ```typescript
+ * const searchEffect = createDebouncedEffect(
+ *   300,
+ *   (s) => s.searchQuery,
+ *   async (query, _prev, { setState }) => {
+ *     const results = await api.search(query);
+ *     setState({ searchResults: results });
+ *   }
+ * );
+ * ```
+ */
+declare function createDebouncedEffect<TState, TSelected>(delay: number, selector: Selector<TState, TSelected>, effect: EffectFn<TSelected>, options?: Omit<EffectDefinition<TState, TSelected>, 'selector' | 'effect' | 'debounce'>): EffectDefinition<TState, TSelected>;
+
+/**
+ * Validation plugin for state schema validation.
+ *
+ * Provides schema-agnostic validation with support for Zod, Yup,
+ * or custom validation functions.
+ *
+ * @module plugins/validate
+ */
+
+/**
+ * Validation error type.
+ */
+interface ValidationError {
+    /** Path to the invalid field */
+    path: string[];
+    /** Error message */
+    message: string;
+    /** Validation rule that failed */
+    rule?: string;
+    /** The invalid value */
+    value?: unknown;
+}
+/**
+ * Validation result.
+ */
+interface ValidationResult {
+    /** Whether validation passed */
+    valid: boolean;
+    /** List of validation errors */
+    errors: ValidationError[];
+}
+/**
+ * Custom validator function type.
+ */
+type ValidatorFn<T> = (state: T) => boolean | ValidationResult | ValidationError[];
+/**
+ * Zod-like schema interface.
+ */
+interface ZodLikeSchema<T> {
+    safeParse(data: unknown): {
+        success: boolean;
+        error?: {
+            issues: Array<{
+                path: (string | number)[];
+                message: string;
+                code?: string;
+            }>;
+        };
+        data?: T;
+    };
+}
+/**
+ * Yup-like schema interface.
+ */
+interface YupLikeSchema<T> {
+    validateSync(data: unknown, options?: {
+        abortEarly?: boolean;
+    }): T;
+    validate(data: unknown, options?: {
+        abortEarly?: boolean;
+    }): Promise<T>;
+}
+/**
+ * Schema type - supports Zod, Yup, or custom validators.
+ */
+type Schema<T> = ZodLikeSchema<T> | YupLikeSchema<T> | ValidatorFn<T>;
+/**
+ * Validation timing options.
+ */
+type ValidationTiming = 'change' | 'commit' | 'manual';
+/**
+ * Validation plugin options.
+ */
+interface ValidateOptions<T> {
+    /** Schema to validate against (Zod, Yup, or custom function) */
+    schema: Schema<T>;
+    /** When to validate: 'change' (every setState), 'commit' (on batch commit), 'manual' (only when validate() called) */
+    on?: ValidationTiming;
+    /** Callback when validation fails */
+    onError?: (errors: ValidationError[]) => void;
+    /** Throw error on validation failure */
+    throwOnError?: boolean;
+    /** Only validate these paths (keys of state) */
+    paths?: Array<keyof T>;
+    /** Name for debugging */
+    name?: string;
+}
+/**
+ * Validation API added to store.
+ */
+interface ValidationAPI {
+    /** Manually trigger validation */
+    validate(): ValidationResult;
+    /** Check if current state is valid */
+    isValid(): boolean;
+    /** Get current validation errors */
+    getErrors(): ValidationError[];
+    /** Clear validation errors */
+    clearErrors(): void;
+}
+/**
+ * Create a validation plugin.
+ *
+ * @param options - Validation options
+ * @returns A validation plugin
+ *
+ * @example
+ * ```typescript
+ * import { createStore, validate } from '@oxog/state';
+ * import { z } from 'zod';
+ *
+ * // With Zod schema
+ * const userSchema = z.object({
+ *   name: z.string().min(1),
+ *   age: z.number().min(0),
+ *   email: z.string().email(),
+ * });
+ *
+ * const store = createStore({ name: '', age: 0, email: '' })
+ *   .use(validate({
+ *     schema: userSchema,
+ *     on: 'change',
+ *     onError: (errors) => console.log('Validation errors:', errors),
+ *   }));
+ *
+ * // Manual validation
+ * const result = store.validate();
+ * if (!result.valid) {
+ *   console.log(result.errors);
+ * }
+ *
+ * // Check if valid
+ * if (store.isValid()) {
+ *   submitForm();
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom validator function
+ * const store = createStore({ password: '', confirmPassword: '' })
+ *   .use(validate({
+ *     schema: (state) => {
+ *       const errors = [];
+ *       if (state.password.length < 8) {
+ *         errors.push({
+ *           path: ['password'],
+ *           message: 'Password must be at least 8 characters',
+ *         });
+ *       }
+ *       if (state.password !== state.confirmPassword) {
+ *         errors.push({
+ *           path: ['confirmPassword'],
+ *           message: 'Passwords must match',
+ *         });
+ *       }
+ *       return errors;
+ *     },
+ *     on: 'change',
+ *   }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With partial validation
+ * const store = createStore({ name: '', age: 0, temp: '' })
+ *   .use(validate({
+ *     schema: userSchema,
+ *     paths: ['name', 'age'], // Only validate these fields
+ *   }));
+ * ```
+ */
+declare function validate<TState>(options: ValidateOptions<TState>): Plugin<TState>;
+/**
+ * Create a simple boolean validator.
+ *
+ * @param predicate - Validation predicate function
+ * @param message - Error message when validation fails
+ * @returns A validator function
+ *
+ * @example
+ * ```typescript
+ * const isPositive = createValidator(
+ *   (state) => state.count >= 0,
+ *   'Count must be positive'
+ * );
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(validate({ schema: isPositive }));
  * ```
  */
-declare function produce<T>(base: T, recipe: (draft: T) => void): T;
+declare function createValidator<T>(predicate: (state: T) => boolean, message: string): ValidatorFn<T>;
 /**
- * Create an immer plugin.
+ * Combine multiple validators into one.
  *
- * @returns An immer plugin
+ * @param validators - Array of validator functions
+ * @returns Combined validator function
  *
  * @example
  * ```typescript
- * import { createStore, immer } from '@oxog/state';
- *
- * const store = createStore({
- *   items: [{ id: 1, name: 'Item 1' }]
- * }).use(immer());
+ * const combinedValidator = combineValidators(
+ *   createValidator((s) => s.name.length > 0, 'Name required'),
+ *   createValidator((s) => s.age >= 18, 'Must be 18+'),
+ * );
  *
- * // Now setState can accept a mutable recipe function
- * store.setState((draft) => {
- *   draft.items[0].name = 'Updated Item';
- *   draft.items.push({ id: 2, name: 'Item 2' });
- * });
+ * const store = createStore({ name: '', age: 0 })
+ *   .use(validate({ schema: combinedValidator }));
  * ```
  */
-declare function immer<TState>(): Plugin<TState>;
-
+declare function combineValidators<T>(...validators: ValidatorFn<T>[]): ValidatorFn<T>;
 /**
- * Selector plugin - Computed/derived values.
+ * Create a field-level validator.
  *
- * Define computed values that automatically update when dependencies change.
+ * @param field - Field name to validate
+ * @param predicate - Validation predicate for field value
+ * @param message - Error message when validation fails
+ * @returns A validator function
  *
  * @example
  * ```typescript
- * import { createStore, selector } from '@oxog/state';
- *
- * const store = createStore({
- *   items: [],
- *   filter: 'all',
- * })
- * .use(selector({
- *   // Computed: filtered items
- *   filteredItems: (state) => {
- *     if (state.filter === 'all') return state.items;
- *     return state.items.filter((item: any) => item.status === state.filter);
- *   },
- *   // Computed: item count
- *   itemCount: (state) => state.items.length,
- * }));
+ * const emailValidator = createFieldValidator(
+ *   'email',
+ *   (email) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email),
+ *   'Invalid email format'
+ * );
  *
- * // Access computed values
- * const state = store.getState();
- * console.log(state.filteredItems); // Computed value
+ * const store = createStore({ email: '' })
+ *   .use(validate({ schema: emailValidator }));
  * ```
  */
-
+declare function createFieldValidator<T, K extends keyof T>(field: K, predicate: (value: T[K], state: T) => boolean, message: string): ValidatorFn<T>;
 /**
- * Create a selector plugin for computed values.
+ * Create an async validator (for server-side validation).
  *
- * @param options - Plugin options with selectors
- * @returns A selector plugin
+ * @param validator - Async validation function
+ * @returns A promise that resolves to validation result
  *
  * @example
  * ```typescript
- * import { selector } from '@oxog/state';
- *
- * const store = createStore({
- *   items: [{ price: 10 }, { price: 20 }],
- *   taxRate: 0.1,
- * })
- * .use(selector({
- *   // Computed total
- *   total: (state) =>
- *     state.items.reduce((sum: number, item: any) => sum + item.price, 0),
+ * const checkUsername = createAsyncValidator(async (state) => {
+ *   const exists = await api.checkUsername(state.username);
+ *   return exists
+ *     ? [{ path: ['username'], message: 'Username already taken' }]
+ *     : [];
+ * });
  *
- *   // Computed total with tax
- *   totalWithTax: (state) => {
- *     const total = state.items.reduce((sum: number, item: any) => sum + item.price, 0);
- *     return total * (1 + state.taxRate);
- *   },
- * }));
+ * // Manual validation
+ * const result = await checkUsername(store.getState());
  * ```
  */
-declare function selector<TState>(options: SelectorOptions<TState>): Plugin<TState>;
+declare function createAsyncValidator<T>(validator: (state: T) => Promise<ValidationError[]>): (state: T) => Promise<ValidationResult>;
 
 /**
  * Deep clone a value, creating copies of nested objects and arrays.
@@ -1058,4 +2352,430 @@ declare function omit<T extends object, K extends keyof T>(obj: T, keys: readonl
  */
 declare function identity<T>(value: T): T;
 
-export { type Action, type Actions, type DeepPartial, type DevtoolsOptions, type EqualityFn, type HistoryOptions, type HistoryStore, type Listener, type PersistOptions, type Plugin, type Selector, type SelectorOptions, type StorageLike$1 as StorageLike, type Store, type StoreBuilder, StoreError, StoreError as StoreErrorClass, StoreErrorCode, type StoreOptions, type SyncOptions, batch, createStorage, createStore, deepClone, deepEqual, deepMerge, devtools, hasHistory, history, identity, immer, isFunction, omit, persist, pick, produce, selector, sessionStorage, shallowEqual, sync, triggerSync, useAction, useCreateStore, useStore };
+/**
+ * Testing utilities for @oxog/state.
+ *
+ * Provides helpers for testing stores, state changes,
+ * and async effects in unit tests.
+ *
+ * @module testing
+ */
+
+/**
+ * Mock storage for testing persist plugin.
+ */
+interface MockStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    getAll(): Record<string, string>;
+}
+/**
+ * Create a mock storage for testing.
+ *
+ * @returns A mock storage implementation
+ *
+ * @example
+ * ```typescript
+ * import { createMockStorage, persist } from '@oxog/state';
+ *
+ * const mockStorage = createMockStorage();
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(persist({ key: 'test', storage: mockStorage }));
+ *
+ * store.setState({ count: 5 });
+ * expect(mockStorage.getItem('test')).toBe('{"count":5}');
+ * ```
+ */
+declare function createMockStorage(): MockStorage;
+/**
+ * State change record for tracking.
+ */
+interface StateChange<TState> {
+    state: TState;
+    prevState: TState;
+    timestamp: number;
+}
+/**
+ * Store spy for testing state changes.
+ */
+interface StoreSpy<TState> {
+    /** All recorded state changes */
+    changes: StateChange<TState>[];
+    /** Get the last state change */
+    lastChange: () => StateChange<TState> | undefined;
+    /** Get the last state */
+    lastState: () => TState | undefined;
+    /** Reset recorded changes */
+    reset: () => void;
+    /** Unsubscribe from store */
+    unsubscribe: () => void;
+    /** Wait for a specific state condition */
+    waitFor: (predicate: (state: TState) => boolean, timeout?: number) => Promise<TState>;
+    /** Wait for a specific number of changes */
+    waitForChanges: (count: number, timeout?: number) => Promise<StateChange<TState>[]>;
+}
+/**
+ * Create a spy to track store state changes.
+ *
+ * @param store - The store to spy on
+ * @returns A store spy object
+ *
+ * @example
+ * ```typescript
+ * import { createStore, spyOnStore } from '@oxog/state';
+ *
+ * const store = createStore({ count: 0 });
+ * const spy = spyOnStore(store);
+ *
+ * store.setState({ count: 1 });
+ * store.setState({ count: 2 });
+ *
+ * expect(spy.changes).toHaveLength(2);
+ * expect(spy.lastState()?.count).toBe(2);
+ * ```
+ */
+declare function spyOnStore<TState>(store: Store<TState>): StoreSpy<TState>;
+/**
+ * Test helper for asserting state values.
+ */
+interface StateAssertion<TState> {
+    /** Assert the current state equals expected */
+    toEqual: (expected: Partial<TState>) => void;
+    /** Assert a selector value equals expected */
+    toHaveSelected: <T>(selector: Selector<TState, T>, expected: T) => void;
+    /** Assert state matches a predicate */
+    toMatch: (predicate: (state: TState) => boolean) => void;
+}
+/**
+ * Create assertions for a store's state.
+ *
+ * @param store - The store to assert on
+ * @returns State assertion helpers
+ *
+ * @example
+ * ```typescript
+ * import { createStore, assertState } from '@oxog/state';
+ *
+ * const store = createStore({ count: 0, name: 'test' });
+ * const assert = assertState(store);
+ *
+ * assert.toEqual({ count: 0 });
+ * assert.toHaveSelected(s => s.name, 'test');
+ * assert.toMatch(s => s.count >= 0);
+ * ```
+ */
+declare function assertState<TState>(store: Store<TState>): StateAssertion<TState>;
+/**
+ * Options for test store creation.
+ */
+interface TestStoreOptions<TState> {
+    /** Initial state */
+    initialState: TState;
+    /** Whether to enable spy automatically */
+    spy?: boolean;
+}
+/**
+ * Test store wrapper with built-in utilities.
+ */
+interface TestStore<TState> {
+    /** The underlying store */
+    store: Store<TState>;
+    /** State spy (if enabled) */
+    spy?: StoreSpy<TState>;
+    /** State assertions */
+    assert: StateAssertion<TState>;
+    /** Reset store to initial state */
+    reset: () => void;
+    /** Destroy store and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a test store with built-in utilities.
+ *
+ * @param options - Test store options
+ * @returns A test store wrapper
+ *
+ * @example
+ * ```typescript
+ * import { createTestStore } from '@oxog/state';
+ *
+ * describe('Counter', () => {
+ *   let testStore: TestStore<{ count: number }>;
+ *
+ *   beforeEach(() => {
+ *     testStore = createTestStore({ initialState: { count: 0 }, spy: true });
+ *   });
+ *
+ *   afterEach(() => {
+ *     testStore.destroy();
+ *   });
+ *
+ *   it('should increment count', () => {
+ *     testStore.store.setState({ count: 1 });
+ *     testStore.assert.toEqual({ count: 1 });
+ *     expect(testStore.spy?.changes).toHaveLength(1);
+ *   });
+ * });
+ * ```
+ */
+declare function createTestStore<TState>(options: TestStoreOptions<TState>): TestStore<TState>;
+/**
+ * Wait for a specified amount of time.
+ *
+ * @param ms - Milliseconds to wait
+ * @returns A promise that resolves after the delay
+ *
+ * @example
+ * ```typescript
+ * await delay(100);
+ * ```
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * Run a function and wait for all pending microtasks.
+ *
+ * @param fn - Function to run
+ * @returns A promise that resolves after microtasks complete
+ *
+ * @example
+ * ```typescript
+ * await flushMicrotasks(() => {
+ *   store.setState({ count: 1 });
+ * });
+ * ```
+ */
+declare function flushMicrotasks(fn?: () => void): Promise<void>;
+/**
+ * Wrap a store action for testing with call tracking.
+ */
+interface MockedAction<TArgs extends any[], TReturn> {
+    /** Call the action */
+    (...args: TArgs): TReturn;
+    /** Number of times called */
+    callCount: number;
+    /** Arguments from each call */
+    calls: TArgs[];
+    /** Reset call tracking */
+    reset: () => void;
+}
+/**
+ * Create a mocked action for testing.
+ *
+ * @param fn - The original function
+ * @returns A mocked action with call tracking
+ *
+ * @example
+ * ```typescript
+ * const mockIncrement = mockAction((amount: number) => {
+ *   store.setState(s => ({ count: s.count + amount }));
+ * });
+ *
+ * mockIncrement(5);
+ * mockIncrement(3);
+ *
+ * expect(mockIncrement.callCount).toBe(2);
+ * expect(mockIncrement.calls).toEqual([[5], [3]]);
+ * ```
+ */
+declare function mockAction<TArgs extends any[], TReturn>(fn: (...args: TArgs) => TReturn): MockedAction<TArgs, TReturn>;
+/**
+ * Create a snapshot of the current store state.
+ *
+ * @param store - The store to snapshot
+ * @returns A deep clone of the current state
+ *
+ * @example
+ * ```typescript
+ * const before = snapshot(store);
+ * store.setState({ count: 5 });
+ * const after = snapshot(store);
+ *
+ * expect(before.count).toBe(0);
+ * expect(after.count).toBe(5);
+ * ```
+ */
+declare function snapshot<TState>(store: Store<TState>): TState;
+/**
+ * Compare two state snapshots and return differences.
+ *
+ * @param before - State before changes
+ * @param after - State after changes
+ * @returns Object containing changed keys and their values
+ *
+ * @example
+ * ```typescript
+ * const before = { count: 0, name: 'test' };
+ * const after = { count: 5, name: 'test' };
+ *
+ * const diff = stateDiff(before, after);
+ * // { count: { before: 0, after: 5 } }
+ * ```
+ */
+declare function stateDiff<TState extends Record<string, any>>(before: TState, after: TState): Record<string, {
+    before: any;
+    after: any;
+}>;
+
+/**
+ * Middleware Compatibility Layer
+ *
+ * Provides a generic middleware pattern for state management,
+ * enabling compatibility with various middleware ecosystems.
+ *
+ * @module compat/middleware
+ */
+
+/**
+ * Middleware-style SetState function.
+ */
+type MiddlewareSetState<T> = {
+    (partial: Partial<T> | ((state: T) => Partial<T>), replace?: boolean): void;
+};
+/**
+ * Middleware-style GetState function.
+ */
+type MiddlewareGetState<T> = () => T;
+/**
+ * Middleware-style Subscribe function.
+ */
+type MiddlewareSubscribe<T> = (listener: (state: T, prevState: T) => void) => () => void;
+/**
+ * Generic StoreApi for middleware compatibility.
+ */
+interface MiddlewareStoreApi<T> {
+    setState: MiddlewareSetState<T>;
+    getState: MiddlewareGetState<T>;
+    subscribe: MiddlewareSubscribe<T>;
+    destroy?: () => void;
+}
+/**
+ * State creator function for middleware pattern.
+ */
+type StateCreatorFn<T, Mps extends unknown[] = [], Mcs extends unknown[] = []> = (set: MiddlewareSetState<T>, get: MiddlewareGetState<T>, api: MiddlewareStoreApi<T>) => T;
+/**
+ * Generic Middleware type.
+ */
+type MiddlewareFn<T, Mps extends unknown[] = [], Mcs extends unknown[] = []> = (creator: StateCreatorFn<T, Mps, Mcs>) => StateCreatorFn<T, Mps, Mcs>;
+/**
+ * Convert an @oxog/state store to middleware-compatible API.
+ *
+ * @param store - An @oxog/state store
+ * @returns A middleware-compatible store API
+ *
+ * @example
+ * ```typescript
+ * import { createStore, toMiddlewareApi } from '@oxog/state';
+ *
+ * const store = createStore({ count: 0 });
+ * const api = toMiddlewareApi(store);
+ *
+ * // Use middleware-style API
+ * api.setState({ count: 1 });
+ * api.setState((state) => ({ count: state.count + 1 }));
+ * console.log(api.getState()); // { count: 2 }
+ * ```
+ */
+declare function toMiddlewareApi<T>(store: Store<T>): MiddlewareStoreApi<T>;
+/**
+ * Wrap a middleware to work as an @oxog/state plugin.
+ *
+ * @param middleware - A middleware function
+ * @param options - Optional middleware options
+ * @returns An @oxog/state plugin
+ *
+ * @example
+ * ```typescript
+ * import { createStore, middlewareCompat } from '@oxog/state';
+ *
+ * // Use external middleware with @oxog/state
+ * const store = createStore({ count: 0 })
+ *   .use(middlewareCompat(someMiddleware, { name: 'MyStore' }));
+ * ```
+ */
+declare function middlewareCompat<T>(middleware: MiddlewareFn<T>, options?: Record<string, unknown>): Plugin<T>;
+/**
+ * Create a store using middleware-style state creator.
+ *
+ * @param creator - Middleware-style state creator function
+ * @returns A store API
+ *
+ * @example
+ * ```typescript
+ * import { createWithMiddleware } from '@oxog/state';
+ *
+ * const store = createWithMiddleware((set, get) => ({
+ *   count: 0,
+ *   increment: () => set((state) => ({ count: state.count + 1 })),
+ *   decrement: () => set((state) => ({ count: state.count - 1 })),
+ *   reset: () => set({ count: 0 }),
+ *   getDoubled: () => get().count * 2,
+ * }));
+ *
+ * store.getState().increment();
+ * console.log(store.getState().count); // 1
+ * ```
+ */
+declare function createWithMiddleware<T extends object>(creator: StateCreatorFn<T>): MiddlewareStoreApi<T> & {
+    use: <U>(plugin: Plugin<T>) => MiddlewareStoreApi<T>;
+};
+/**
+ * Create a simple middleware.
+ *
+ * @param name - Middleware name
+ * @param enhancer - Function that enhances the state creator
+ * @returns A middleware function
+ *
+ * @example
+ * ```typescript
+ * const loggerMiddleware = createSimpleMiddleware('logger', (creator) => (set, get, api) => {
+ *   const loggedSet: typeof set = (partial, replace) => {
+ *     console.log('Before:', get());
+ *     set(partial, replace);
+ *     console.log('After:', get());
+ *   };
+ *   return creator(loggedSet, get, api);
+ * });
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(middlewareCompat(loggerMiddleware));
+ * ```
+ */
+declare function createSimpleMiddleware<T>(name: string, enhancer: (creator: StateCreatorFn<T>) => StateCreatorFn<T>): MiddlewareFn<T>;
+/**
+ * Compose multiple middlewares.
+ *
+ * @param middlewares - Array of middlewares
+ * @returns A single composed middleware
+ *
+ * @example
+ * ```typescript
+ * import { compose, middlewareCompat } from '@oxog/state';
+ *
+ * const composedMiddleware = compose(
+ *   loggerMiddleware,
+ *   devtoolsMiddleware,
+ *   persistMiddleware,
+ * );
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(middlewareCompat(composedMiddleware));
+ * ```
+ */
+declare function compose<T>(...middlewares: MiddlewareFn<T>[]): MiddlewareFn<T>;
+/**
+ * Type helper for extracting state type from a store API.
+ */
+type ExtractStateType<S> = S extends MiddlewareStoreApi<infer T> ? T : never;
+/**
+ * Type helper for selector function.
+ */
+type SelectorFn<T, U> = (state: T) => U;
+/**
+ * Type helper for equality function.
+ */
+type EqualityCheck<T> = (a: T, b: T) => boolean;
+
+export { type Action, type Actions, type Computed, type ComputedOptions, type DeepPartial, type DevtoolsOptions, type EffectCleanup, type EffectDefinition, type EffectFn, type EffectUtils, type EffectsOptions, type EqualityCheck, type EqualityFn, type ExtractStateType, type FederatedState, type Federation, type FederationListener, type FederationOptions, type GetSlice, type HistoryOptions, type HistoryStore, type Listener, type LogLevel, type LoggerOptions, type MiddlewareFn, type MiddlewareGetState, type MiddlewareSetState, type MiddlewareStoreApi, type MiddlewareSubscribe, type MockStorage, type MockedAction, type PersistOptions, type Plugin, type Selector, type SelectorFn, type SelectorOptions, type SetSlice, type SliceCreator, type SliceDefinition, type StateAssertion, type StateChange, type StateCreatorFn, type StorageLike$1 as StorageLike, type Store, type StoreBuilder, StoreError, StoreError as StoreErrorClass, StoreErrorCode, type StoreOptions, type StoreSpy, type StoreState, type SubscribeOptions, type SyncOptions, type TestStore, type TestStoreOptions, type TransactionFn, type ValidateOptions, type ValidationAPI, type ValidationError, type ValidationResult, type ValidationTiming, type ValidatorFn, assertState, batch, combineComputed, combineEffects, combineSlices, combineValidators, compose, computed, createAsyncValidator, createDebouncedEffect, createEffect, createFederatedComputed, createFederatedSelector, createFederation, createFieldValidator, createLogger, createMockStorage, createNamespacedSlice, createSimpleEffect, createSimpleMiddleware, createSlice, createStorage, createStore, createSubscriber, createTestStore, createValidator, createWithMiddleware, deepClone, deepEqual, deepMerge, delay, devtools, effects, extendStore, flushMicrotasks, hasHistory, history, identity, immer, isFunction, logger, memoizeSelector, middlewareCompat, mockAction, omit, persist, pick, produce, resetSlices, selector, sessionStorage, shallowEqual, snapshot, spyOnStore, stateDiff, subscribeOnce, subscribeToMany, subscribeWithOptions, sync, toMiddlewareApi, triggerSync, useAction, useCreateStore, useSetState, useShallow, useStore, useStoreActions, useStoreSelector, useTransientSubscribe, validate, waitForFederated };