@okyrychenko-dev/react-action-guard 0.3.2 → 0.4.0

package/dist/index.d.ts

@@ -1,18 +1,32 @@
 import * as zustand from 'zustand';
+import { StoreApi } from 'zustand';
+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";
@@ -43,6 +57,17 @@ type Middleware = (context: MiddlewareContext) => void | Promise<void>;
 
 declare const createAnalyticsMiddleware: (config: AnalyticsConfig) => Middleware;
 
+/**
+ * Configure middleware for the UI blocking store
+ *
+ * This is a convenience function that registers multiple middleware at once.
+ * Each middleware will be registered with an auto-generated name based on its index.
+ *
+ * @param middlewares - Array of middleware functions to register
+ *
+ */
+declare function configureMiddleware(middlewares: ReadonlyArray<Middleware>): void;
+
 declare const loggerMiddleware: Middleware;
 
 interface PerformanceConfig {
@@ -60,6 +85,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
@@ -69,6 +98,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
@@ -124,6 +159,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)
@@ -131,6 +168,24 @@ declare const uiBlockingStoreApi: zustand.StoreApi<UIBlockingStore>;
  */
 declare const useBlocker: (blockerId: string, config: BlockerConfig, isActive?: boolean) => void;
 
+/**
+ * Hook to get detailed blocking information for a scope
+ *
+ * Returns an array of blocker information objects for the specified scope,
+ * sorted by priority (highest first). Automatically re-renders when blockers change.
+ *
+ * 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
+ *
+ * ```
+ */
+declare const useBlockingInfo: (scope?: string) => ReadonlyArray<BlockerInfo>;
+
 /**
  * Configuration for conditional blocker hook.
  *
@@ -154,6 +209,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
  *
@@ -213,6 +270,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
  *
@@ -255,10 +314,148 @@ 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, createAnalyticsMiddleware, createPerformanceMiddleware, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, 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>;
+}
+/**
+ * Provider component for isolated UI blocking state
+ *
+ * Use this to create an isolated store instance for:
+ * - Server-side rendering (each request gets its own store)
+ * - Testing (no need for beforeEach cleanup)
+ * - Micro-frontends (isolated state per app)
+ *
+ * @example
+ * ```tsx
+ * // SSR - each request gets its own store
+ * function App() {
+ *   return (
+ *     <UIBlockingProvider>
+ *       <MyComponent />
+ *     </UIBlockingProvider>
+ *   );
+ * }
+ *
+ * // Testing - isolated store per test
+ * function renderWithProvider(ui: ReactElement) {
+ *   return render(
+ *     <UIBlockingProvider>{ui}</UIBlockingProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function UIBlockingProvider({ children, enableDevtools, devtoolsName, middlewares, }: UIBlockingProviderProps): ReactNode;
+/**
+ * Hook to access the UIBlocking store from context
+ *
+ * Throws an error if used outside of UIBlockingProvider.
+ * Use useUIBlockingStoreFromContext for safe access with fallback.
+ *
+ * @returns The store API from the nearest UIBlockingProvider
+ * @throws Error if used outside of UIBlockingProvider
+ */
+declare function useUIBlockingContext(): StoreApi<UIBlockingStore>;
+/**
+ * Hook to check if we're inside a UIBlockingProvider
+ *
+ * @returns true if inside UIBlockingProvider, false otherwise
+ */
+declare function useIsInsideUIBlockingProvider(): boolean;
+/**
+ * Hook to use the UIBlocking store from context with a selector
+ *
+ * This is similar to useUIBlockingStore but uses the context store.
+ * Automatically applies shallow comparison to prevent unnecessary re-renders.
+ *
+ * @param selector - Selector function to pick state from the store
+ * @returns Selected state value
+ * @throws Error if used outside of UIBlockingProvider
+ */
+declare function useUIBlockingStoreFromContext<T>(selector: (state: UIBlockingStore) => T): T;
+
+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.js

@@ -1,7 +1,8 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { devtools } from 'zustand/middleware';
+import { createContext, useRef, useMemo, useContext, useCallback, useEffect, useState } from 'react';
 import { createStore, useStore } from 'zustand';
+import { devtools } from 'zustand/middleware';
 import { useShallow } from 'zustand/shallow';
+import { jsx } from 'react/jsx-runtime';
 
 // src/hooks/useAsyncAction/useAsyncAction.ts
 
@@ -65,13 +66,40 @@ var createUIBlockingActions = (set, get) => ({
    *
    */
   addBlocker: (id, config = {}) => {
+    const existingBlocker = get().activeBlockers.get(id);
+    if (existingBlocker?.timeoutId) {
+      clearTimeout(existingBlocker.timeoutId);
+    }
+    let timeoutId;
+    if (config.timeout && config.timeout > 0) {
+      timeoutId = setTimeout(() => {
+        if (get().activeBlockers.has(id)) {
+          config.onTimeout?.(id);
+          void get().runMiddlewares({
+            action: "timeout",
+            blockerId: id,
+            config: {
+              scope: config.scope,
+              reason: config.reason,
+              priority: config.priority,
+              timeout: config.timeout
+            },
+            timestamp: Date.now()
+          });
+          get().removeBlocker(id);
+        }
+      }, config.timeout);
+    }
     set((state) => {
       const newBlockers = new Map(state.activeBlockers);
       const storedBlocker = {
         scope: config.scope ?? DEFAULT_SCOPE,
         reason: config.reason ?? DEFAULT_REASON,
         priority: config.priority ?? DEFAULT_PRIORITY,
-        timestamp: config.timestamp ?? Date.now()
+        timestamp: config.timestamp ?? Date.now(),
+        timeout: config.timeout,
+        timeoutId,
+        onTimeout: config.onTimeout
       };
       newBlockers.set(id, storedBlocker);
       return { activeBlockers: newBlockers };
@@ -82,7 +110,8 @@ var createUIBlockingActions = (set, get) => ({
       config: {
         scope: config.scope,
         reason: config.reason,
-        priority: config.priority
+        priority: config.priority,
+        timeout: config.timeout
       },
       timestamp: Date.now()
     });
@@ -95,6 +124,9 @@ var createUIBlockingActions = (set, get) => ({
    */
   removeBlocker: (id) => {
     const prevBlocker = get().activeBlockers.get(id);
+    if (prevBlocker?.timeoutId) {
+      clearTimeout(prevBlocker.timeoutId);
+    }
     set((state) => {
       const newBlockers = new Map(state.activeBlockers);
       newBlockers.delete(id);
@@ -153,6 +185,12 @@ var createUIBlockingActions = (set, get) => ({
    * Clear all blockers from the store
    */
   clearAllBlockers: () => {
+    const { activeBlockers } = get();
+    for (const [, blocker] of activeBlockers) {
+      if (blocker.timeoutId) {
+        clearTimeout(blocker.timeoutId);
+      }
+    }
     set({ activeBlockers: /* @__PURE__ */ new Map() });
   },
   /**
@@ -162,6 +200,13 @@ var createUIBlockingActions = (set, get) => ({
    *
    */
   clearBlockersForScope: (scope) => {
+    const { activeBlockers } = get();
+    for (const [, blocker] of activeBlockers) {
+      const blockerScopes = normalizeScopeToArray(blocker.scope);
+      if (blockerScopes.includes(scope) && blocker.timeoutId) {
+        clearTimeout(blocker.timeoutId);
+      }
+    }
     set((state) => {
       const newBlockers = /* @__PURE__ */ new Map();
       for (const [id, blocker] of state.activeBlockers) {
@@ -174,6 +219,45 @@ var createUIBlockingActions = (set, get) => ({
     });
   }
 });
+var UIBlockingContext = createContext(null);
+function UIBlockingProvider({
+  children,
+  enableDevtools = process.env.NODE_ENV === "development",
+  devtoolsName = "UIBlocking",
+  middlewares = []
+}) {
+  const middlewaresRef = useRef(middlewares);
+  const store = useMemo(() => {
+    const baseStore = enableDevtools ? createStore(
+      devtools(createUIBlockingActions, {
+        name: devtoolsName,
+        enabled: enableDevtools
+      })
+    ) : createStore(createUIBlockingActions);
+    middlewaresRef.current.forEach((mw, index) => {
+      baseStore.getState().registerMiddleware(`provider-middleware-${index.toString()}`, mw);
+    });
+    return baseStore;
+  }, [enableDevtools, devtoolsName]);
+  return /* @__PURE__ */ jsx(UIBlockingContext.Provider, { value: store, children });
+}
+function useUIBlockingContext() {
+  const store = useContext(UIBlockingContext);
+  if (!store) {
+    throw new Error(
+      "useUIBlockingContext must be used within UIBlockingProvider. Either wrap your app in <UIBlockingProvider> or use the global store via useUIBlockingStore."
+    );
+  }
+  return store;
+}
+function useIsInsideUIBlockingProvider() {
+  const store = useContext(UIBlockingContext);
+  return store !== null;
+}
+function useUIBlockingStoreFromContext(selector) {
+  const store = useUIBlockingContext();
+  return useStore(store, useShallow(selector));
+}
 
 // src/store/uiBlockingStore.config.ts
 var devtoolsConfig = {
@@ -184,9 +268,19 @@ var devtoolsConfig = {
 // src/store/uiBlockingStore.store.ts
 var { useStore: useUIBlockingStore, useStoreApi: uiBlockingStoreApi } = createShallowStore(devtools(createUIBlockingActions, devtoolsConfig));
 
+// src/context/useResolvedStore.ts
+function useResolvedStore() {
+  const contextStore = useContext(UIBlockingContext);
+  return contextStore ?? uiBlockingStoreApi;
+}
+function useResolvedStoreWithSelector(selector) {
+  const store = useResolvedStore();
+  return useStore(store, useShallow(selector));
+}
+
 // src/hooks/useAsyncAction/useAsyncAction.ts
-var useAsyncAction = (actionId, scope) => {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+var useAsyncAction = (actionId, scope, options) => {
+  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -197,19 +291,21 @@ var useAsyncAction = (actionId, scope) => {
         addBlocker(blockerId, {
           scope,
           reason: `Executing ${actionId}`,
-          priority: ASYNC_ACTION_PRIORITY
+          priority: ASYNC_ACTION_PRIORITY,
+          timeout: options?.timeout,
+          onTimeout: options?.onTimeout
         });
         return await asyncFn();
       } finally {
         removeBlocker(blockerId);
       }
     },
-    [actionId, scope, addBlocker, removeBlocker]
+    [actionId, scope, options?.timeout, options?.onTimeout, addBlocker, removeBlocker]
   );
   return executeWithBlocking;
 };
 var useBlocker = (blockerId, config, isActive = true) => {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -232,6 +328,13 @@ function createBlockerConfig(config) {
     priority: config.priority
   };
 }
+var useBlockingInfo = (scope = DEFAULT_SCOPE) => {
+  const store = useResolvedStore();
+  const activeBlockers = useStore(store, (state) => state.activeBlockers);
+  return useMemo(() => {
+    return store.getState().getBlockingInfo(scope);
+  }, [activeBlockers, scope, store]);
+};
 function useConfigRef(config) {
   const configRef = useRef(config);
   useEffect(() => {
@@ -242,7 +345,7 @@ function useConfigRef(config) {
 
 // src/hooks/useConditionalBlocker/useConditionalBlocker.ts
 var useConditionalBlocker = (blockerId, config) => {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -325,7 +428,7 @@ var useConfirmableBlocker = (blockerId, config) => {
 
 // src/hooks/useIsBlocked/useIsBlocked.ts
 var useIsBlocked = (scope) => {
-  return useUIBlockingStore((state) => state.isBlocked(scope));
+  return useResolvedStoreWithSelector((state) => state.isBlocked(scope));
 };
 
 // src/hooks/useScheduledBlocker/useScheduledBlocker.utils.ts
@@ -367,7 +470,7 @@ function isScheduleInPast(startTime, endTime, now) {
 
 // src/hooks/useScheduledBlocker/useScheduledBlocker.ts
 var useScheduledBlocker = (blockerId, config) => {
-  const { addBlocker, removeBlocker } = useUIBlockingStore((state) => ({
+  const { addBlocker, removeBlocker } = useResolvedStoreWithSelector((state) => ({
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
@@ -504,6 +607,15 @@ var createAnalyticsMiddleware = (config) => {
   };
 };
 
+// src/middleware/configureMiddleware.ts
+function configureMiddleware(middlewares) {
+  const store = uiBlockingStoreApi.getState();
+  middlewares.forEach((middleware, index) => {
+    const name = `middleware-${index.toString()}`;
+    store.registerMiddleware(name, middleware);
+  });
+}
+
 // src/middleware/loggerMiddleware.utils.ts
 var getActionEmoji = (action) => {
   switch (action) {
@@ -589,6 +701,22 @@ var createPerformanceMiddleware = (config = {}) => {
   };
 };
 
-export { createAnalyticsMiddleware, createPerformanceMiddleware, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useScheduledBlocker, useUIBlockingStore };
+// src/createTypedHooks.ts
+function createTypedHooks() {
+  return {
+    useBlocker: (blockerId, config, isActive) => {
+      useBlocker(blockerId, config, isActive);
+    },
+    useIsBlocked: (scope) => {
+      return useIsBlocked(scope);
+    },
+    useAsyncAction: (actionId, scope, options) => {
+      return useAsyncAction(actionId, scope, options);
+    },
+    useBlockingInfo: (scope) => useBlockingInfo(scope)
+  };
+}
+
+export { UIBlockingProvider, configureMiddleware, createAnalyticsMiddleware, createPerformanceMiddleware, createTypedHooks, loggerMiddleware, uiBlockingStoreApi, useAsyncAction, useBlocker, useBlockingInfo, useConditionalBlocker, useConfirmableBlocker, useIsBlocked, useIsInsideUIBlockingProvider, useScheduledBlocker, useUIBlockingContext, useUIBlockingStore, useUIBlockingStoreFromContext };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map