@oxog/state 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1061 @@
+/**
+ * Deep partial type for nested optional properties.
+ *
+ * @typeParam T - The type to make partially deep
+ *
+ * @example
+ * ```typescript
+ * type User = {
+ *   name: string;
+ *   profile: { age: number; city: string; };
+ * };
+ *
+ * const partial: DeepPartial<User> = {
+ *   name: 'John',
+ *   profile: { age: 30 } // city is optional
+ * };
+ * ```
+ */
+type DeepPartial<T> = T extends object ? {
+    [P in keyof T]?: DeepPartial<T[P]>;
+} : T;
+/**
+ * Action function that receives state and optional arguments, returning a partial state update.
+ *
+ * @typeParam TState - The store state type
+ * @typeParam TArgs - The action argument types tuple
+ *
+ * @example
+ * ```typescript
+ * type CounterAction = Action<{ count: number }, [number: number]>;
+ *
+ * const incrementBy: CounterAction = (state, amount) => ({
+ *   count: state.count + amount
+ * });
+ * ```
+ */
+type Action<TState, TArgs extends unknown[] = []> = (state: TState, ...args: TArgs) => Partial<TState> | Promise<Partial<TState>>;
+/**
+ * Collection of actions indexed by name.
+ *
+ * @typeParam TState - The store state type
+ *
+ * @example
+ * ```typescript
+ * const actions: Actions<{ count: number }> = {
+ *   increment: (state) => ({ count: state.count + 1 }),
+ *   decrement: (state) => ({ count: state.count - 1 })
+ * };
+ * ```
+ */
+type Actions<TState> = Record<string, Action<TState>>;
+/**
+ * Selector function to extract a slice of state.
+ *
+ * @typeParam TState - The store state type
+ * @typeParam TSelected - The selected value type
+ *
+ * @example
+ * ```typescript
+ * const selectCount: Selector<{ count: number; name: string }, number> =
+ *   (state) => state.count;
+ * ```
+ */
+type Selector<TState, TSelected> = (state: TState) => TSelected;
+/**
+ * Equality function for comparing two values.
+ *
+ * @typeParam T - The type to compare
+ *
+ * @example
+ * ```typescript
+ * const shallowEquality: EqualityFn<{ a: number }> = (a, b) =>
+ *   a.a === b.a;
+ * ```
+ */
+type EqualityFn<T> = (a: T, b: T) => boolean;
+/**
+ * Listener function called when state changes.
+ *
+ * @typeParam TState - The store state type
+ *
+ * @example
+ * ```typescript
+ * const listener: Listener<{ count: number }> = (state, prevState) => {
+ *   console.log(`Count changed from ${prevState.count} to ${state.count}`);
+ * };
+ * ```
+ */
+type Listener<TState> = (state: TState, prevState: TState) => void;
+/**
+ * Storage interface for persisting state.
+ *
+ * @example
+ * ```typescript
+ * const sessionStorage: StorageLike = {
+ *   getItem: (key) => sessionStorage.getItem(key),
+ *   setItem: (key, value) => sessionStorage.setItem(key, value),
+ *   removeItem: (key) => sessionStorage.removeItem(key)
+ * };
+ * ```
+ */
+interface StorageLike$1 {
+    /** Get an item from storage */
+    getItem(key: string): string | null;
+    /** Set an item in storage */
+    setItem(key: string, value: string): void;
+    /** Remove an item from storage */
+    removeItem(key: string): void;
+}
+/**
+ * Store configuration options.
+ *
+ * @typeParam TState - The store state type
+ *
+ * @example
+ * ```typescript
+ * const options: StoreOptions<{ count: number }> = {
+ *   name: 'Counter',
+ *   devtools: true
+ * };
+ * ```
+ */
+interface StoreOptions<TState> {
+    /** Initial state */
+    initialState: TState;
+    /** Store name for debugging */
+    name?: string;
+    /** Enable/disable devtools (default: true in development) */
+    devtools?: boolean;
+}
+/**
+ * Plugin interface for extending store functionality.
+ *
+ * @typeParam TState - The store state type
+ *
+ * @example
+ * ```typescript
+ * const loggerPlugin: Plugin<{ count: number }> = {
+ *   name: 'logger',
+ *   version: '1.0.0',
+ *   install(store) {
+ *     store.subscribe((state) => console.log('State:', state));
+ *   }
+ * };
+ * ```
+ */
+interface Plugin<TState = unknown> {
+    /** Unique plugin identifier (kebab-case) */
+    name: string;
+    /** Semantic version (e.g., "1.0.0") */
+    version: string;
+    /** Other plugins this plugin depends on */
+    dependencies?: string[];
+    /**
+     * Called when plugin is registered.
+     *
+     * @param store - The store instance
+     * @param options - Plugin-specific options
+     */
+    install: (store: Store<TState>, options?: unknown) => void;
+    /**
+     * Called after all plugins are installed.
+     *
+     * @param store - The store instance
+     */
+    onInit?: (store: Store<TState>) => void | Promise<void>;
+    /**
+     * Called when plugin is unregistered.
+     */
+    onDestroy?: () => void | Promise<void>;
+    /**
+     * Called on state change.
+     *
+     * @param state - New state
+     * @param prevState - Previous state
+     */
+    onStateChange?: (state: TState, prevState: TState) => void;
+    /**
+     * Called on error in store.
+     *
+     * @param error - The error that occurred
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Store instance with state management methods.
+ *
+ * @typeParam TState - The store state type
+ *
+ * @example
+ * ```typescript
+ * const store: Store<{ count: number }> = createStore({ count: 0 });
+ * const state = store.getState(); // { count: 0 }
+ * store.setState({ count: 1 });
+ * ```
+ */
+interface Store<TState> {
+    /** Get current state snapshot */
+    getState(): TState;
+    /**
+     * Update state with partial object or function.
+     *
+     * @param partial - Partial state or updater function
+     *
+     * @example
+     * ```typescript
+     * store.setState({ count: 10 });
+     * store.setState((state) => ({ count: state.count + 1 }));
+     * ```
+     */
+    setState(partial: Partial<TState> | ((state: TState) => Partial<TState>)): void;
+    /**
+     * Deep merge state.
+     *
+     * @param partial - Partial state to merge
+     *
+     * @example
+     * ```typescript
+     * store.merge({ user: { name: 'John' } });
+     * ```
+     */
+    merge(partial: DeepPartial<TState>): void;
+    /** Reset to initial state */
+    reset(): void;
+    /**
+     * Subscribe to state changes.
+     *
+     * @param listener - Function called on state changes
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = store.subscribe((state) => console.log(state));
+     * unsubscribe();
+     * ```
+     */
+    subscribe(listener: Listener<TState>): () => void;
+    /**
+     * Subscribe to state changes with selector.
+     *
+     * @param selector - Function to extract state slice
+     * @param listener - Function called when selected value changes
+     * @param equalityFn - Optional custom equality function
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = store.subscribe(
+     *   (state) => state.count,
+     *   (count) => console.log('Count:', count)
+     * );
+     * ```
+     */
+    subscribe<TSelected>(selector: Selector<TState, TSelected>, listener: Listener<TSelected>, equalityFn?: EqualityFn<TSelected>): () => void;
+    /**
+     * Register a plugin.
+     *
+     * @param plugin - The plugin to register
+     * @param options - Plugin-specific options
+     * @returns The store instance for chaining
+     *
+     * @example
+     * ```typescript
+     * store.use(persist({ key: 'app' }));
+     * ```
+     */
+    use<TPlugin extends Plugin<TState>>(plugin: TPlugin, options?: unknown): this;
+    /** Destroy store and cleanup all resources */
+    destroy(): void;
+}
+/**
+ * Store builder interface for fluent API.
+ *
+ * @typeParam TState - The store state type
+ *
+ * @example
+ * ```typescript
+ * createStore({ count: 0 })
+ *   .action('increment', (s) => ({ count: s.count + 1 }))
+ *   .action('decrement', (s) => ({ count: s.count - 1 }));
+ * ```
+ */
+interface StoreBuilder<TState> extends Store<TState> {
+    /**
+     * Add an action to the store.
+     *
+     * @param name - Action name
+     * @param fn - Action function
+     * @returns The builder for chaining
+     */
+    action<K extends string>(name: K, fn: Action<TState & Record<K, Action<TState>>>): this;
+}
+/**
+ * Error codes for store errors.
+ */
+declare enum StoreErrorCode {
+    /** Store was destroyed and cannot be used */
+    STORE_DESTROYED = "STORE_DESTROYED",
+    /** Plugin with same name already registered */
+    PLUGIN_EXISTS = "PLUGIN_EXISTS",
+    /** Required plugin dependency not found */
+    PLUGIN_DEPENDENCY_MISSING = "PLUGIN_DEPENDENCY_MISSING",
+    /** Invalid state update argument */
+    INVALID_STATE_UPDATE = "INVALID_STATE_UPDATE",
+    /** Action threw an error */
+    ACTION_ERROR = "ACTION_ERROR"
+}
+/**
+ * Store error class.
+ */
+declare class StoreError extends Error {
+    code: StoreErrorCode;
+    constructor(code: StoreErrorCode, message: string);
+}
+
+/**
+ * Create a new reactive store.
+ *
+ * Supports three action definition styles:
+ * - **Inline**: Actions defined within state object (functions starting with $)
+ * - **Separate**: Actions passed as second argument
+ * - **Fluent**: Actions added via `.action()` method
+ *
+ * @typeParam TState - The type of the store state
+ * @param initialState - Initial state object, may include inline actions
+ * @param actions - Optional separate actions object
+ * @returns A new Store instance
+ *
+ * @example
+ * ```typescript
+ * // Style A: Inline actions (prefix with $)
+ * const store = createStore({
+ *   count: 0,
+ *   $increment: (state) => ({ count: state.count + 1 }),
+ * });
+ *
+ * // Style B: Separate actions
+ * const store = createStore(
+ *   { count: 0 },
+ *   { increment: (state) => ({ count: state.count + 1 }) }
+ * );
+ *
+ * // Style C: Fluent builder
+ * const store = createStore({ count: 0 })
+ *   .action('increment', (state) => ({ count: state.count + 1 }));
+ * ```
+ */
+declare function createStore<TState>(initialState: TState, actions?: Actions<TState>): Store<TState>;
+/**
+ * Batch multiple state updates into a single notification.
+ *
+ * @param fn - Function containing state updates
+ * @returns The return value of fn
+ *
+ * @example
+ * ```typescript
+ * import { batch } from '@oxog/state';
+ *
+ * // Without batch - 3 re-renders
+ * store.setState({ a: 1 });
+ * store.setState({ b: 2 });
+ * store.setState({ c: 3 });
+ *
+ * // With batch - 1 re-render
+ * batch(() => {
+ *   store.setState({ a: 1 });
+ *   store.setState({ b: 2 });
+ *   store.setState({ c: 3 });
+ * });
+ * ```
+ */
+declare function batch<T>(fn: () => T): T;
+
+/**
+ * React hook for subscribing to store state changes.
+ *
+ * Uses useSyncExternalStore for optimal performance and SSR compatibility.
+ *
+ * @typeParam TState - The store state type
+ * @typeParam TSelected - The selected state type
+ * @param store - The store instance
+ * @param selector - Optional selector to extract a slice of state
+ * @param equalityFn - Optional custom equality function
+ * @returns The selected state slice
+ *
+ * @example
+ * ```typescript
+ * import { createStore, useStore } from '@oxog/state';
+ *
+ * const store = createStore({
+ *   count: 0,
+ *   name: 'John',
+ *   increment: (state) => ({ count: state.count + 1 }),
+ * });
+ *
+ * function Counter() {
+ *   // Select entire state
+ *   const state = useStore(store);
+ *
+ *   // Select with selector
+ *   const count = useStore(store, (state) => state.count);
+ *
+ *   // Select with custom equality check
+ *   const user = useStore(
+ *     store,
+ *     (state) => state.user,
+ *     (a, b) => a?.id === b?.id
+ *   );
+ *
+ *   // Select action
+ *   const increment = useStore(store, (state) => state.increment);
+ *
+ *   return (
+ *     <button onClick={increment}>
+ *       Count: {count}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useStore<TState, TSelected = TState>(store: Store<TState>, selector?: Selector<TState, TSelected>, equalityFn?: EqualityFn<TSelected>): TSelected;
+/**
+ * React hook for creating and using a store.
+ *
+ * Creates a store on first render and destroys it on unmount.
+ *
+ * @typeParam TState - The store state type
+ * @param initialState - The initial state
+ * @returns The store instance
+ *
+ * @example
+ * ```typescript
+ * import { useCreateStore } from '@oxog/state';
+ *
+ * function Component() {
+ *   const store = useCreateStore({ count: 0 });
+ *   const count = useStore(store, (s) => s.count);
+ *
+ *   return <div>{count}</div>;
+ * }
+ * ```
+ */
+declare function useCreateStore<TState>(initialState: TState): Store<TState>;
+/**
+ * React hook for getting a store action.
+ *
+ * Convenience hook for selecting action functions from a store.
+ *
+ * @typeParam TState - The store state type
+ * @typeParam TAction - The action type
+ * @param store - The store instance
+ * @param actionName - The name of the action
+ * @returns The action function
+ *
+ * @example
+ * ```typescript
+ * import { createStore, useAction } from '@oxog/state';
+ *
+ * const store = createStore({
+ *   count: 0,
+ *   increment: (state) => ({ count: state.count + 1 }),
+ *   decrement: (state) => ({ count: state.count - 1 }),
+ * });
+ *
+ * function Counter() {
+ *   const increment = useAction(store, 'increment');
+ *   const decrement = useAction(store, 'decrement');
+ *   const count = useStore(store, (s) => s.count);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={decrement}>-</button>
+ *       <span>{count}</span>
+ *       <button onClick={increment}>+</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useAction<TState, TAction extends (...args: any[]) => any>(store: Store<TState>, actionName: string): TAction;
+
+/**
+ * Plugin-specific types and interfaces.
+ */
+
+/**
+ * Persist plugin options.
+ */
+interface PersistOptions<TState> {
+    /** Storage key */
+    key: string;
+    /** Storage implementation (defaults to localStorage) */
+    storage?: StorageLike;
+    /** List of state keys to persist (whitelist) */
+    whitelist?: Array<keyof TState>;
+    /** List of state keys to exclude (blacklist) */
+    blacklist?: Array<keyof TState>;
+}
+/**
+ * Storage interface for persistence.
+ */
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Devtools plugin options.
+ */
+interface DevtoolsOptions {
+    /** Store name for DevTools */
+    name?: string;
+    /** Enable/disable DevTools */
+    enabled?: boolean;
+    /** Maximum number of states to keep in history */
+    maxAge?: number;
+}
+/**
+ * History plugin options.
+ */
+interface HistoryOptions<TState> {
+    /** Maximum number of past states to keep */
+    limit?: number;
+    /** Keys to track for history (empty array tracks all) */
+    keys?: Array<keyof TState>;
+}
+/**
+ * Sync plugin options.
+ */
+interface SyncOptions {
+    /** Channel name for BroadcastChannel */
+    channel?: string;
+}
+/**
+ * Selector plugin options.
+ */
+interface SelectorOptions<TState> {
+    /** Map of computed selectors */
+    selectors: {
+        [K in keyof TState]?: (state: TState) => TState[K];
+    };
+}
+/**
+ * History-enabled store interface.
+ */
+interface HistoryStore<TState> extends Store<TState> {
+    undo(): void;
+    redo(): void;
+    clearHistory(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+}
+
+/**
+ * Persist plugin - Save and restore state from storage.
+ *
+ * Automatically persists state to localStorage, sessionStorage, or any
+ * storage implementation. State is restored on store creation.
+ *
+ * @example
+ * ```typescript
+ * import { createStore, persist } from '@oxog/state';
+ *
+ * const store = createStore({ count: 0, user: null })
+ *   .use(persist({
+ *     key: 'my-app',
+ *     storage: localStorage,
+ *     whitelist: ['count'] // Only persist count
+ *   }));
+ * ```
+ */
+
+/**
+ * SessionStorage implementation.
+ */
+declare const sessionStorage: StorageLike;
+/**
+ * Create a persist plugin.
+ *
+ * @param options - Plugin options
+ * @returns A persist plugin
+ *
+ * @example
+ * ```typescript
+ * import { persist, sessionStorage } from '@oxog/state';
+ *
+ * // Using localStorage (default)
+ * const store = createStore({ count: 0 })
+ *   .use(persist({ key: 'counter' }));
+ *
+ * // Using sessionStorage
+ * const store = createStore({ count: 0 })
+ *   .use(persist({ key: 'counter', storage: sessionStorage }));
+ *
+ * // With whitelist
+ * 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'] }));
+ * ```
+ */
+declare function persist<TState>(options: PersistOptions<TState>): Plugin<TState>;
+/**
+ * Create a custom storage from a storage object.
+ *
+ * @param storage - Any object with getItem, setItem, removeItem
+ * @returns A StorageLike interface
+ *
+ * @example
+ * ```typescript
+ * import { createStorage } from '@oxog/state';
+ *
+ * const AsyncStorage = createStorage({
+ *   getItem: async (key) => await AsyncStorage.getItem(key),
+ *   setItem: async (key, value) => await AsyncStorage.setItem(key, value),
+ *   removeItem: async (key) => await AsyncStorage.removeItem(key),
+ * });
+ * ```
+ */
+declare function createStorage(storage: StorageLike): StorageLike;
+
+/**
+ * Devtools plugin - Redux DevTools integration.
+ *
+ * Connects to Redux DevTools extension for debugging state changes.
+ *
+ * @example
+ * ```typescript
+ * import { createStore, devtools } from '@oxog/state';
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(devtools({ name: 'Counter' }));
+ * ```
+ */
+
+/**
+ * Create a DevTools plugin.
+ *
+ * @param options - Plugin options
+ * @returns A DevTools plugin
+ *
+ * @example
+ * ```typescript
+ * import { devtools } from '@oxog/state';
+ *
+ * // Basic usage
+ * const store = createStore({ count: 0 })
+ *   .use(devtools({ name: 'My Store' }));
+ *
+ * // Disabled in production
+ * const store = createStore({ count: 0 })
+ *   .use(devtools({
+ *     name: 'My Store',
+ *     enabled: process.env.NODE_ENV === 'development'
+ *   }));
+ * ```
+ */
+declare function devtools<TState>(options?: DevtoolsOptions): Plugin<TState>;
+
+/**
+ * History plugin - Undo/redo functionality.
+ *
+ * Tracks state changes and provides undo/redo methods.
+ *
+ * @example
+ * ```typescript
+ * import { createStore, history } from '@oxog/state';
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(history({ limit: 100 }));
+ *
+ * // Now store has undo() and redo() methods
+ * store.setState({ count: 1 });
+ * store.setState({ count: 2 });
+ * store.undo(); // { count: 1 }
+ * store.redo(); // { count: 2 }
+ * ```
+ */
+
+/**
+ * Create a history plugin.
+ *
+ * @param options - Plugin options
+ * @returns A history plugin
+ *
+ * @example
+ * ```typescript
+ * import { history } from '@oxog/state';
+ *
+ * // Default options
+ * const store = createStore({ count: 0 })
+ *   .use(history());
+ *
+ * // Custom limit
+ * const store = createStore({ count: 0 })
+ *   .use(history({ limit: 50 }));
+ *
+ * // Track specific keys only
+ * const store = createStore({ count: 0, temp: '' })
+ *   .use(history({ keys: ['count'] }));
+ * ```
+ */
+declare function history<TState>(options?: HistoryOptions<TState>): Plugin<TState>;
+/**
+ * Check if a store has history capabilities.
+ *
+ * @param store - The store to check
+ * @returns true if store supports undo/redo
+ *
+ * @example
+ * ```typescript
+ * import { hasHistory } from '@oxog/state';
+ *
+ * if (hasHistory(store)) {
+ *   store.undo();
+ *   store.redo();
+ * }
+ * ```
+ */
+declare function hasHistory<TState>(store: Store<TState>): store is HistoryStore<TState>;
+
+/**
+ * Sync plugin - Cross-tab state synchronization.
+ *
+ * Synchronizes state across browser tabs using BroadcastChannel API.
+ *
+ * @example
+ * ```typescript
+ * import { createStore, sync } from '@oxog/state';
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(sync({ channel: 'my-app-state' }));
+ *
+ * // State changes will sync across all tabs
+ * ```
+ */
+
+/**
+ * Create a sync plugin.
+ *
+ * @param options - Plugin options
+ * @returns A sync plugin
+ *
+ * @example
+ * ```typescript
+ * import { sync } from '@oxog/state';
+ *
+ * // Default channel name
+ * const store = createStore({ count: 0 })
+ *   .use(sync());
+ *
+ * // Custom channel name
+ * const store = createStore({ count: 0 })
+ *   .use(sync({ channel: 'my-app' }));
+ * ```
+ */
+declare function sync<TState>(options?: SyncOptions): Plugin<TState>;
+/**
+ * Manually trigger a sync broadcast.
+ *
+ * @param store - The store to sync
+ * @param channel - The channel to broadcast on
+ *
+ * @example
+ * ```typescript
+ * import { createStore, sync, triggerSync } from '@oxog/state';
+ *
+ * const store = createStore({ count: 0 })
+ *   .use(sync({ channel: 'my-app' }));
+ *
+ * // Manually trigger sync
+ * triggerSync(store, 'my-app');
+ * ```
+ */
+declare function triggerSync<TState>(store: Store<TState>, channel?: string): void;
+
+/**
+ * Immer plugin - Immutable updates with mutable syntax.
+ *
+ * Uses Proxy to enable writing immutable state updates with mutable syntax.
+ *
+ * @example
+ * ```typescript
+ * import { createStore, immer } from '@oxog/state';
+ *
+ * const store = createStore({
+ *   users: [{ name: 'John', age: 30 }]
+ * }).use(immer());
+ *
+ * // Now you can write mutable-style updates
+ * store.setState((draft) => {
+ *   draft.users[0].age = 31; // Mutate draft directly
+ * });
+ * ```
+ */
+
+/**
+ * Produce a new state by applying mutations to a draft.
+ *
+ * @param base - The base state
+ * @param recipe - The mutation function
+ * @returns The new state
+ *
+ * @example
+ * ```typescript
+ * import { produce } from '@oxog/state';
+ *
+ * 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>;
+
+/**
+ * Deep clone a value, creating copies of nested objects and arrays.
+ *
+ * Handles:
+ * - Primitives (returned as-is)
+ * - null and undefined (returned as-is)
+ * - Date objects
+ * - Arrays
+ * - Plain objects
+ * - Circular references
+ * - Other objects (returned as-is, not cloned)
+ *
+ * @typeParam T - The type to clone
+ * @param value - The value to clone
+ * @param seen - Internal map for tracking circular references
+ * @returns A deep clone of the value
+ *
+ * @example
+ * ```typescript
+ * const original = { a: 1, b: { c: 2 } };
+ * const cloned = deepClone(original);
+ * cloned.b.c = 3;
+ * console.log(original.b.c); // 2 (unchanged)
+ * ```
+ */
+declare function deepClone<T>(value: T, seen?: WeakMap<object, unknown>): T;
+
+/**
+ * Deep equality check for two values.
+ *
+ * Recursively compares objects and arrays.
+ * Uses Object.is for primitive comparison.
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @returns true if values are deeply equal
+ *
+ * @example
+ * ```typescript
+ * deepEqual(1, 1); // true
+ * deepEqual({ a: { b: 1 } }, { a: { b: 1 } }); // true
+ * deepEqual({ a: { b: 1 } }, { a: { b: 2 } }); // false
+ * deepEqual([1, 2], [1, 2]); // true
+ * deepEqual([1, 2], [1, 2, 3]); // false
+ * ```
+ */
+declare function deepEqual(a: unknown, b: unknown): boolean;
+
+/**
+ * Shallow equality check for two values.
+ *
+ * Uses Object.is for comparison, which handles NaN correctly
+ * and distinguishes between +0 and -0.
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @returns true if values are shallowly equal
+ *
+ * @example
+ * ```typescript
+ * shallowEqual(1, 1); // true
+ * shallowEqual({ a: 1 }, { a: 1 }); // true
+ * shallowEqual({ a: 1 }, { a: 2 }); // false
+ * shallowEqual(NaN, NaN); // true
+ * ```
+ */
+declare function shallowEqual(a: unknown, b: unknown): boolean;
+
+/**
+ * Deep merge a partial object into a target object.
+ *
+ * Creates a new object with nested objects merged recursively.
+ * Arrays are replaced, not merged.
+ *
+ * @typeParam T - The target type
+ * @param target - The target object
+ * @param source - The partial source to merge
+ * @returns A new merged object
+ *
+ * @example
+ * ```typescript
+ * const target = { a: 1, b: { c: 2, d: 3 } };
+ * const source = { b: { c: 10 }, e: 4 };
+ * const merged = deepMerge(target, source);
+ * // { a: 1, b: { c: 10, d: 3 }, e: 4 }
+ * ```
+ */
+
+declare function deepMerge<T>(target: T, source: Partial<T> | DeepPartial<T>): T;
+
+/**
+ * Type guard to check if a value is a function.
+ *
+ * @param value - The value to check
+ * @returns true if the value is a function
+ *
+ * @example
+ * ```typescript
+ * const value: unknown = () => {};
+ * if (isFunction(value)) {
+ *   value(); // TypeScript knows this is a function
+ * }
+ * ```
+ */
+declare function isFunction(value: unknown): value is (...args: any[]) => any;
+
+/**
+ * Pick specified properties from an object.
+ *
+ * Creates a new object with only the specified keys.
+ *
+ * @typeParam T - The object type
+ * @typeParam K - The keys to pick
+ * @param obj - The source object
+ * @param keys - The keys to pick
+ * @returns A new object with only the picked keys
+ *
+ * @example
+ * ```typescript
+ * const user = { name: 'John', age: 30, city: 'NYC' };
+ * const picked = pick(user, ['name', 'age']);
+ * // { name: 'John', age: 30 }
+ * ```
+ */
+declare function pick<T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Pick<T, K>;
+
+/**
+ * Omit specified properties from an object.
+ *
+ * Creates a new object without the specified keys.
+ *
+ * @typeParam T - The object type
+ * @typeParam K - The keys to omit
+ * @param obj - The source object
+ * @param keys - The keys to omit
+ * @returns A new object without the omitted keys
+ *
+ * @example
+ * ```typescript
+ * const user = { name: 'John', age: 30, city: 'NYC' };
+ * const omitted = omit(user, ['age', 'city']);
+ * // { name: 'John' }
+ * ```
+ */
+declare function omit<T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K>;
+
+/**
+ * Identity function that returns its input.
+ *
+ * Useful as a default selector when no transformation is needed.
+ *
+ * @typeParam T - The value type
+ * @param value - The value to return
+ * @returns The same value
+ *
+ * @example
+ * ```typescript
+ * const selector = identity;
+ * selector(42); // 42
+ * selector('hello'); // 'hello'
+ * ```
+ */
+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 };