@okyrychenko-dev/react-action-guard 0.3.3 → 0.5.0

package/dist/index.d.cts

@@ -1,18 +1,33 @@
 import * as zustand from 'zustand';
+import { StoreApi } from 'zustand';
+export { ShallowStoreBindings, createShallowStore } from '@okyrychenko-dev/react-zustand-toolkit';
+import { ReactNode } from 'react';
 
+/**
+ * Options for useAsyncAction hook
+ */
+interface UseAsyncActionOptions {
+    /** Timeout in milliseconds after which the blocker will be automatically removed */
+    timeout?: number;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
+}
 /**
  * Hook to wrap async functions with automatic blocking/unblocking
  *
  * Creates a wrapper function that automatically adds a blocker before executing
  * the async function and removes it after completion (success or failure).
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @template T - The return type of the async function
  * @param actionId - Unique identifier for the action (used in blocker ID and reason)
  * @param scope - Scope(s) to block during execution (default: "global")
+ * @param options - Optional configuration including timeout
  * @returns Function that wraps async functions with blocking behavior
  *
  */
-declare const useAsyncAction: <T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>) => ((asyncFn: () => Promise<T>) => Promise<T>);
+declare const useAsyncAction: <T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>, options?: UseAsyncActionOptions) => ((asyncFn: () => Promise<T>) => Promise<T>);
 
 type AnalyticsEventData = Record<string, string | number | ReadonlyArray<string> | undefined>;
 type AnalyticsProvider = "ga" | "mixpanel" | "amplitude";
@@ -71,6 +86,10 @@ interface BlockerConfig {
     reason?: string;
     priority?: number;
     timestamp?: number;
+    /** Automatically remove the blocker after N milliseconds */
+    timeout?: number;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
 }
 /**
  * Stored blocker with all required fields
@@ -80,6 +99,12 @@ interface StoredBlocker {
     reason: string;
     priority: number;
     timestamp: number;
+    /** Timeout duration in milliseconds (if set) */
+    timeout?: number;
+    /** Internal timeout ID for cleanup */
+    timeoutId?: ReturnType<typeof setTimeout>;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
 }
 /**
  * Blocker information including its ID
@@ -126,7 +151,10 @@ type UIBlockingStore = UIBlockingStoreState & UIBlockingStoreActions;
  * - Automatic shallow comparison for selectors
  *
  */
-declare const useUIBlockingStore: <T>(selector: (state: UIBlockingStore) => T) => T;
+declare const useUIBlockingStore: {
+    (): UIBlockingStore;
+    <T>(selector: (state: UIBlockingStore) => T): T;
+};
 declare const uiBlockingStoreApi: zustand.StoreApi<UIBlockingStore>;
 
 /**
@@ -135,6 +163,8 @@ declare const uiBlockingStoreApi: zustand.StoreApi<UIBlockingStore>;
  * Automatically adds a blocker when the component mounts (or when activated)
  * and removes it when the component unmounts (or when deactivated).
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param blockerId - Unique identifier for the blocker
  * @param config - Blocker configuration (scope, reason, priority)
  * @param isActive - Whether the blocker is currently active (default: true)
@@ -151,6 +181,8 @@ declare const useBlocker: (blockerId: string, config: BlockerConfig, isActive?:
  * Uses a stable reference - only re-renders when the actual blocker list changes,
  * not on every store update.
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param scope - Scope to get blocking information for (default: "global")
  * @returns Array of blocker information objects, sorted by priority
  *
@@ -181,6 +213,8 @@ interface ConditionalBlockerConfig<TState = unknown> extends Omit<BlockerConfig,
  * Periodically checks a condition and blocks/unblocks based on the result.
  * The condition is evaluated at the specified interval (default 1000ms).
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param blockerId - Unique identifier for this blocker
  * @param config - Configuration including condition function and check interval
  *
@@ -240,6 +274,8 @@ declare const useConfirmableBlocker: (blockerId: string, config: ConfirmableBloc
  * Returns a boolean indicating whether the specified scope(s) are blocked.
  * Automatically re-renders when the blocking state changes.
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param scope - Scope or array of scopes to check (default: "global")
  * @returns True if any of the specified scopes are blocked
  *
@@ -282,10 +318,110 @@ interface ScheduledBlockerConfig extends BlockerConfig {
  * Supports start/end times as Date objects, ISO strings, or timestamps.
  * If both duration and end are provided, duration takes precedence.
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param blockerId - Unique identifier for this blocker
  * @param config - Configuration including schedule and callbacks
  *
  */
 declare const useScheduledBlocker: (blockerId: string, config: ScheduledBlockerConfig) => void;
 
-export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type StoredBlocker, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseConfirmableBlockerReturn, configureMiddleware, createAnalyticsMiddleware, createPerformanceMiddleware, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useScheduledBlocker, useUIBlockingStore };
+/**
+ * Default scope type
+ */
+type DefaultScopes = "global";
+/**
+ * Utility type for scope values - can be a single scope or array of scopes
+ */
+type ScopeValue<TScope extends string = string> = TScope | ReadonlyArray<TScope>;
+/**
+ * Type-safe blocker configuration with generic scope type
+ */
+interface BlockerConfigTyped<TScope extends string> {
+    /** Scope(s) to block */
+    scope?: ScopeValue<TScope>;
+    /** Human-readable reason for blocking */
+    reason?: string;
+    /** Priority level (higher priority blockers take precedence) */
+    priority?: number;
+    /** Timestamp when the blocker was created */
+    timestamp?: number;
+    /** Timeout in milliseconds after which the blocker will be automatically removed */
+    timeout?: number;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
+}
+
+/**
+ * Return type for createTypedHooks factory
+ */
+interface TypedHooks<TScope extends string> {
+    /**
+     * Type-safe version of useBlocker hook
+     */
+    useBlocker: (blockerId: string, config: BlockerConfigTyped<TScope>, isActive?: boolean) => void;
+    /**
+     * Type-safe version of useIsBlocked hook
+     */
+    useIsBlocked: (scope?: ScopeValue<TScope>) => boolean;
+    /**
+     * Type-safe version of useAsyncAction hook
+     */
+    useAsyncAction: <T = unknown>(actionId: string, scope?: ScopeValue<TScope>, options?: UseAsyncActionOptions) => (asyncFn: () => Promise<T>) => Promise<T>;
+    /**
+     * Type-safe version of useBlockingInfo hook
+     */
+    useBlockingInfo: (scope: TScope) => ReturnType<typeof useBlockingInfo>;
+}
+/**
+ * Creates type-safe versions of all blocking hooks with your custom scope types
+ *
+ * @template TScope - Union type of allowed scope strings
+ * @returns Object with type-safe hook functions
+ *
+ * @example
+ * ```typescript
+ * // Define your app's scopes
+ * type AppScopes = "global" | "form" | "navigation" | "checkout";
+ *
+ * // Create typed hooks
+ * const { useBlocker, useIsBlocked, useAsyncAction } = createTypedHooks<AppScopes>();
+ *
+ * // Now TypeScript will catch typos
+ * useBlocker("id", { scope: "form" }); // ✓ OK
+ * useBlocker("id", { scope: "typo" }); // ✗ Type error!
+ * ```
+ */
+declare function createTypedHooks<TScope extends string>(): TypedHooks<TScope>;
+
+/**
+ * Props for UIBlockingProvider component
+ */
+interface UIBlockingProviderProps {
+    children: ReactNode;
+    /** Enable Redux DevTools integration (default: true in development) */
+    enableDevtools?: boolean;
+    /** Name for Redux DevTools (default: "UIBlocking") */
+    devtoolsName?: string;
+    /** Initial middlewares to register */
+    middlewares?: ReadonlyArray<Middleware>;
+}
+/**
+ * Base provider created using toolkit's createStoreProvider
+ * This creates isolated store instances for SSR, testing, and micro-frontends
+ */
+declare const useUIBlockingContext: () => StoreApi<UIBlockingStore>;
+declare const useUIBlockingStoreFromContext: {
+    (): UIBlockingStore;
+    <T>(selector: (state: UIBlockingStore) => T): T;
+};
+declare const useIsInsideUIBlockingProvider: () => boolean;
+/**
+ * Provider component for isolated UI blocking state
+ *
+ * Uses toolkit's createStoreProvider with built-in DevTools support
+ * and onStoreCreate callback for middleware registration.
+ */
+declare function UIBlockingProvider({ children, enableDevtools, devtoolsName, middlewares, }: UIBlockingProviderProps): ReactNode;
+
+export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerConfigTyped, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type DefaultScopes, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type ScopeValue, type StoredBlocker, type TypedHooks, UIBlockingProvider, type UIBlockingProviderProps, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseAsyncActionOptions, type UseConfirmableBlockerReturn, configureMiddleware, createAnalyticsMiddleware, createPerformanceMiddleware, createTypedHooks, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useIsInsideUIBlockingProvider, useScheduledBlocker, useUIBlockingContext, useUIBlockingStore, useUIBlockingStoreFromContext };

package/dist/index.d.ts

@@ -1,18 +1,33 @@
 import * as zustand from 'zustand';
+import { StoreApi } from 'zustand';
+export { ShallowStoreBindings, createShallowStore } from '@okyrychenko-dev/react-zustand-toolkit';
+import { ReactNode } from 'react';
 
+/**
+ * Options for useAsyncAction hook
+ */
+interface UseAsyncActionOptions {
+    /** Timeout in milliseconds after which the blocker will be automatically removed */
+    timeout?: number;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
+}
 /**
  * Hook to wrap async functions with automatic blocking/unblocking
  *
  * Creates a wrapper function that automatically adds a blocker before executing
  * the async function and removes it after completion (success or failure).
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @template T - The return type of the async function
  * @param actionId - Unique identifier for the action (used in blocker ID and reason)
  * @param scope - Scope(s) to block during execution (default: "global")
+ * @param options - Optional configuration including timeout
  * @returns Function that wraps async functions with blocking behavior
  *
  */
-declare const useAsyncAction: <T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>) => ((asyncFn: () => Promise<T>) => Promise<T>);
+declare const useAsyncAction: <T = unknown>(actionId: string, scope?: string | ReadonlyArray<string>, options?: UseAsyncActionOptions) => ((asyncFn: () => Promise<T>) => Promise<T>);
 
 type AnalyticsEventData = Record<string, string | number | ReadonlyArray<string> | undefined>;
 type AnalyticsProvider = "ga" | "mixpanel" | "amplitude";
@@ -71,6 +86,10 @@ interface BlockerConfig {
     reason?: string;
     priority?: number;
     timestamp?: number;
+    /** Automatically remove the blocker after N milliseconds */
+    timeout?: number;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
 }
 /**
  * Stored blocker with all required fields
@@ -80,6 +99,12 @@ interface StoredBlocker {
     reason: string;
     priority: number;
     timestamp: number;
+    /** Timeout duration in milliseconds (if set) */
+    timeout?: number;
+    /** Internal timeout ID for cleanup */
+    timeoutId?: ReturnType<typeof setTimeout>;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
 }
 /**
  * Blocker information including its ID
@@ -126,7 +151,10 @@ type UIBlockingStore = UIBlockingStoreState & UIBlockingStoreActions;
  * - Automatic shallow comparison for selectors
  *
  */
-declare const useUIBlockingStore: <T>(selector: (state: UIBlockingStore) => T) => T;
+declare const useUIBlockingStore: {
+    (): UIBlockingStore;
+    <T>(selector: (state: UIBlockingStore) => T): T;
+};
 declare const uiBlockingStoreApi: zustand.StoreApi<UIBlockingStore>;
 
 /**
@@ -135,6 +163,8 @@ declare const uiBlockingStoreApi: zustand.StoreApi<UIBlockingStore>;
  * Automatically adds a blocker when the component mounts (or when activated)
  * and removes it when the component unmounts (or when deactivated).
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param blockerId - Unique identifier for the blocker
  * @param config - Blocker configuration (scope, reason, priority)
  * @param isActive - Whether the blocker is currently active (default: true)
@@ -151,6 +181,8 @@ declare const useBlocker: (blockerId: string, config: BlockerConfig, isActive?:
  * Uses a stable reference - only re-renders when the actual blocker list changes,
  * not on every store update.
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param scope - Scope to get blocking information for (default: "global")
  * @returns Array of blocker information objects, sorted by priority
  *
@@ -181,6 +213,8 @@ interface ConditionalBlockerConfig<TState = unknown> extends Omit<BlockerConfig,
  * Periodically checks a condition and blocks/unblocks based on the result.
  * The condition is evaluated at the specified interval (default 1000ms).
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param blockerId - Unique identifier for this blocker
  * @param config - Configuration including condition function and check interval
  *
@@ -240,6 +274,8 @@ declare const useConfirmableBlocker: (blockerId: string, config: ConfirmableBloc
  * Returns a boolean indicating whether the specified scope(s) are blocked.
  * Automatically re-renders when the blocking state changes.
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param scope - Scope or array of scopes to check (default: "global")
  * @returns True if any of the specified scopes are blocked
  *
@@ -282,10 +318,110 @@ interface ScheduledBlockerConfig extends BlockerConfig {
  * Supports start/end times as Date objects, ISO strings, or timestamps.
  * If both duration and end are provided, duration takes precedence.
  *
+ * Supports both global store and context store (via UIBlockingProvider).
+ *
  * @param blockerId - Unique identifier for this blocker
  * @param config - Configuration including schedule and callbacks
  *
  */
 declare const useScheduledBlocker: (blockerId: string, config: ScheduledBlockerConfig) => void;
 
-export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type StoredBlocker, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseConfirmableBlockerReturn, configureMiddleware, createAnalyticsMiddleware, createPerformanceMiddleware, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useScheduledBlocker, useUIBlockingStore };
+/**
+ * Default scope type
+ */
+type DefaultScopes = "global";
+/**
+ * Utility type for scope values - can be a single scope or array of scopes
+ */
+type ScopeValue<TScope extends string = string> = TScope | ReadonlyArray<TScope>;
+/**
+ * Type-safe blocker configuration with generic scope type
+ */
+interface BlockerConfigTyped<TScope extends string> {
+    /** Scope(s) to block */
+    scope?: ScopeValue<TScope>;
+    /** Human-readable reason for blocking */
+    reason?: string;
+    /** Priority level (higher priority blockers take precedence) */
+    priority?: number;
+    /** Timestamp when the blocker was created */
+    timestamp?: number;
+    /** Timeout in milliseconds after which the blocker will be automatically removed */
+    timeout?: number;
+    /** Callback invoked when the blocker is automatically removed due to timeout */
+    onTimeout?: (blockerId: string) => void;
+}
+
+/**
+ * Return type for createTypedHooks factory
+ */
+interface TypedHooks<TScope extends string> {
+    /**
+     * Type-safe version of useBlocker hook
+     */
+    useBlocker: (blockerId: string, config: BlockerConfigTyped<TScope>, isActive?: boolean) => void;
+    /**
+     * Type-safe version of useIsBlocked hook
+     */
+    useIsBlocked: (scope?: ScopeValue<TScope>) => boolean;
+    /**
+     * Type-safe version of useAsyncAction hook
+     */
+    useAsyncAction: <T = unknown>(actionId: string, scope?: ScopeValue<TScope>, options?: UseAsyncActionOptions) => (asyncFn: () => Promise<T>) => Promise<T>;
+    /**
+     * Type-safe version of useBlockingInfo hook
+     */
+    useBlockingInfo: (scope: TScope) => ReturnType<typeof useBlockingInfo>;
+}
+/**
+ * Creates type-safe versions of all blocking hooks with your custom scope types
+ *
+ * @template TScope - Union type of allowed scope strings
+ * @returns Object with type-safe hook functions
+ *
+ * @example
+ * ```typescript
+ * // Define your app's scopes
+ * type AppScopes = "global" | "form" | "navigation" | "checkout";
+ *
+ * // Create typed hooks
+ * const { useBlocker, useIsBlocked, useAsyncAction } = createTypedHooks<AppScopes>();
+ *
+ * // Now TypeScript will catch typos
+ * useBlocker("id", { scope: "form" }); // ✓ OK
+ * useBlocker("id", { scope: "typo" }); // ✗ Type error!
+ * ```
+ */
+declare function createTypedHooks<TScope extends string>(): TypedHooks<TScope>;
+
+/**
+ * Props for UIBlockingProvider component
+ */
+interface UIBlockingProviderProps {
+    children: ReactNode;
+    /** Enable Redux DevTools integration (default: true in development) */
+    enableDevtools?: boolean;
+    /** Name for Redux DevTools (default: "UIBlocking") */
+    devtoolsName?: string;
+    /** Initial middlewares to register */
+    middlewares?: ReadonlyArray<Middleware>;
+}
+/**
+ * Base provider created using toolkit's createStoreProvider
+ * This creates isolated store instances for SSR, testing, and micro-frontends
+ */
+declare const useUIBlockingContext: () => StoreApi<UIBlockingStore>;
+declare const useUIBlockingStoreFromContext: {
+    (): UIBlockingStore;
+    <T>(selector: (state: UIBlockingStore) => T): T;
+};
+declare const useIsInsideUIBlockingProvider: () => boolean;
+/**
+ * Provider component for isolated UI blocking state
+ *
+ * Uses toolkit's createStoreProvider with built-in DevTools support
+ * and onStoreCreate callback for middleware registration.
+ */
+declare function UIBlockingProvider({ children, enableDevtools, devtoolsName, middlewares, }: UIBlockingProviderProps): ReactNode;
+
+export { type AmplitudeConfig, type AnalyticsConfig, type AnalyticsEventData, type AnalyticsProvider, type BlockerConfig, type BlockerConfigTyped, type BlockerInfo, type BlockingAction, type BlockingSchedule, type ConditionalBlockerConfig, type ConfirmDialogConfig, type ConfirmableBlockerConfig, type CustomAnalyticsConfig, type DefaultScopes, type GoogleAnalyticsConfig, type Middleware, type MiddlewareContext, type MixpanelConfig, type PerformanceConfig, type ScheduledBlockerConfig, type ScopeValue, type StoredBlocker, type TypedHooks, UIBlockingProvider, type UIBlockingProviderProps, type UIBlockingStore, type UIBlockingStoreActions, type UIBlockingStoreState, type UseAsyncActionOptions, type UseConfirmableBlockerReturn, configureMiddleware, createAnalyticsMiddleware, createPerformanceMiddleware, createTypedHooks, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useIsInsideUIBlockingProvider, useScheduledBlocker, useUIBlockingContext, useUIBlockingStore, useUIBlockingStoreFromContext };