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

package/dist/index.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useRef, useCallback, useEffect, useMemo, useState } from 'react';
 import { createStoreProvider, createShallowStore } from '@okyrychenko-dev/react-zustand-toolkit';
 export { createShallowStore } from '@okyrychenko-dev/react-zustand-toolkit';
 import { useStore } from 'zustand';
@@ -23,6 +23,16 @@ function normalizeScopeToArray(scope) {
 }
 
 // src/store/uiBlockingStore.actions.ts
+var normalizePriority = (priority, fallback = DEFAULT_PRIORITY) => {
+  return priority !== void 0 ? Math.max(0, priority) : fallback;
+};
+var createMiddlewareContext = (action, blockerId, config, prevState) => ({
+  action,
+  blockerId,
+  config,
+  timestamp: Date.now(),
+  ...prevState && { prevState }
+});
 var createUIBlockingActions = (set, get) => ({
   // State
   activeBlockers: /* @__PURE__ */ new Map(),
@@ -33,7 +43,6 @@ var createUIBlockingActions = (set, get) => ({
       newMiddlewares.set(name, middleware);
       return { middlewares: newMiddlewares };
     });
-    console.log(`[UIBlocking] Registered middleware: ${name}`);
   },
   unregisterMiddleware: (name) => {
     set((state) => {
@@ -41,7 +50,6 @@ var createUIBlockingActions = (set, get) => ({
       newMiddlewares.delete(name);
       return { middlewares: newMiddlewares };
     });
-    console.log(`[UIBlocking] Unregistered middleware: ${name}`);
   },
   runMiddlewares: async (context) => {
     const { middlewares } = get();
@@ -55,11 +63,38 @@ var createUIBlockingActions = (set, get) => ({
   },
   // Actions
   /**
-   * Add a blocker to the store
-   *
-   * @param id - Unique blocker identifier
-   * @param config - Optional blocker configuration
-   *
+   * Adds a new blocker or overwrites an existing one.
+   * 
+   * If a blocker with the same ID already exists, it will be replaced and any
+   * existing timeout will be cleared. The blocker is active immediately after
+   * being added. Triggers middleware with 'add' action.
+   * 
+   * @param id - Unique identifier for the blocker. Must be unique within the store.
+   * @param config - Blocker configuration. All fields are optional with defaults applied.
+   * 
+   * @example
+   * Basic usage
+   * ```ts
+   * store.getState().addBlocker('save-operation', {
+   *   scope: 'form',
+   *   reason: 'Saving data...',
+   *   priority: 70
+   * });
+   * ```
+   * 
+   * @example
+   * With timeout
+   * ```ts
+   * store.getState().addBlocker('api-call', {
+   *   scope: 'global',
+   *   reason: 'Loading...',
+   *   timeout: 30000, // Auto-remove after 30 seconds
+   *   onTimeout: (id) => console.warn(`${id} timed out`)
+   * });
+   * ```
+   * 
+   * @see {@link removeBlocker} to remove a blocker
+   * @see {@link updateBlocker} to update an existing blocker
    */
   addBlocker: (id, config = {}) => {
     const existingBlocker = get().activeBlockers.get(id);
@@ -71,17 +106,14 @@ var createUIBlockingActions = (set, get) => ({
       timeoutId = setTimeout(() => {
         if (get().activeBlockers.has(id)) {
           config.onTimeout?.(id);
-          void get().runMiddlewares({
-            action: "timeout",
-            blockerId: id,
-            config: {
+          void get().runMiddlewares(
+            createMiddlewareContext("timeout", id, {
               scope: config.scope,
               reason: config.reason,
               priority: config.priority,
               timeout: config.timeout
-            },
-            timestamp: Date.now()
-          });
+            })
+          );
           get().removeBlocker(id);
         }
       }, config.timeout);
@@ -91,7 +123,7 @@ var createUIBlockingActions = (set, get) => ({
       const storedBlocker = {
         scope: config.scope ?? DEFAULT_SCOPE,
         reason: config.reason ?? DEFAULT_REASON,
-        priority: config.priority ?? DEFAULT_PRIORITY,
+        priority: normalizePriority(config.priority),
         timestamp: config.timestamp ?? Date.now(),
         timeout: config.timeout,
         timeoutId,
@@ -100,23 +132,131 @@ var createUIBlockingActions = (set, get) => ({
       newBlockers.set(id, storedBlocker);
       return { activeBlockers: newBlockers };
     });
-    void get().runMiddlewares({
-      action: "add",
-      blockerId: id,
-      config: {
+    void get().runMiddlewares(
+      createMiddlewareContext("add", id, {
         scope: config.scope,
         reason: config.reason,
         priority: config.priority,
         timeout: config.timeout
-      },
-      timestamp: Date.now()
+      })
+    );
+  },
+  /**
+   * Updates an existing blocker or creates it if it doesn't exist.
+   * 
+   * Merges the provided configuration with existing blocker data. If the timeout
+   * is changed, the timeout timer is restarted. Triggers middleware with 'update' action.
+   * 
+   * @param id - Identifier of the blocker to update
+   * @param config - Partial configuration to merge with existing blocker data
+   * 
+   * @example
+   * Update blocker reason
+   * ```ts
+   * store.getState().updateBlocker('save', {
+   *   reason: 'Saving additional data...'
+   * });
+   * ```
+   * 
+   * @example
+   * Extend timeout
+   * ```ts
+   * store.getState().updateBlocker('api-call', {
+   *   timeout: 60000 // Extend to 60 seconds
+   * });
+   * ```
+   * 
+   * @see {@link addBlocker} to create a new blocker
+   */
+  updateBlocker: (id, config = {}) => {
+    const existingBlocker = get().activeBlockers.get(id);
+    if (!existingBlocker) {
+      get().addBlocker(id, config);
+      return;
+    }
+    let timeoutId = existingBlocker.timeoutId;
+    const timeoutChanged = config.timeout !== void 0 && config.timeout !== existingBlocker.timeout;
+    if (timeoutChanged) {
+      if (existingBlocker.timeoutId) {
+        clearTimeout(existingBlocker.timeoutId);
+      }
+      if (config.timeout && config.timeout > 0) {
+        const newTimeout = config.timeout;
+        const newOnTimeout = config.onTimeout ?? existingBlocker.onTimeout;
+        timeoutId = setTimeout(() => {
+          if (get().activeBlockers.has(id)) {
+            newOnTimeout?.(id);
+            void get().runMiddlewares(
+              createMiddlewareContext("timeout", id, {
+                scope: config.scope ?? existingBlocker.scope,
+                reason: config.reason ?? existingBlocker.reason,
+                priority: config.priority ?? existingBlocker.priority,
+                timeout: newTimeout
+              })
+            );
+            get().removeBlocker(id);
+          }
+        }, newTimeout);
+      } else {
+        timeoutId = void 0;
+      }
+    }
+    const updatedBlocker = {
+      ...existingBlocker,
+      scope: config.scope ?? existingBlocker.scope,
+      reason: config.reason ?? existingBlocker.reason,
+      priority: normalizePriority(config.priority, existingBlocker.priority),
+      timestamp: config.timestamp ?? existingBlocker.timestamp,
+      timeout: config.timeout ?? existingBlocker.timeout,
+      timeoutId,
+      onTimeout: config.onTimeout ?? existingBlocker.onTimeout
+    };
+    set((state) => {
+      const newBlockers = new Map(state.activeBlockers);
+      newBlockers.set(id, updatedBlocker);
+      return { activeBlockers: newBlockers };
     });
+    void get().runMiddlewares(
+      createMiddlewareContext(
+        "update",
+        id,
+        {
+          scope: updatedBlocker.scope,
+          reason: updatedBlocker.reason,
+          priority: updatedBlocker.priority,
+          timeout: updatedBlocker.timeout,
+          onTimeout: updatedBlocker.onTimeout,
+          timestamp: updatedBlocker.timestamp
+        },
+        {
+          scope: existingBlocker.scope,
+          reason: existingBlocker.reason,
+          priority: existingBlocker.priority,
+          timeout: existingBlocker.timeout,
+          onTimeout: existingBlocker.onTimeout,
+          timestamp: existingBlocker.timestamp
+        }
+      )
+    );
   },
   /**
-   * Remove a blocker from the store
-   *
-   * @param id - Blocker identifier to remove
-   *
+   * Removes a blocker from the store.
+   * 
+   * Clears any associated timeout and triggers middleware with 'remove' action.
+   * Safe to call even if the blocker doesn't exist (no-op in that case).
+   * 
+   * @param id - Identifier of the blocker to remove
+   * 
+   * @example
+   * ```ts
+   * // Add and remove a blocker
+   * store.getState().addBlocker('temp', { scope: 'form' });
+   * // ... later
+   * store.getState().removeBlocker('temp');
+   * ```
+   * 
+   * @see {@link addBlocker} to add a blocker
+   * @see {@link clearAllBlockers} to remove all blockers at once
    */
   removeBlocker: (id) => {
     const prevBlocker = get().activeBlockers.get(id);
@@ -129,21 +269,34 @@ var createUIBlockingActions = (set, get) => ({
       return { activeBlockers: newBlockers };
     });
     if (prevBlocker) {
-      void get().runMiddlewares({
-        action: "remove",
-        blockerId: id,
-        config: prevBlocker,
-        timestamp: Date.now(),
-        prevState: prevBlocker
-      });
+      void get().runMiddlewares(createMiddlewareContext("remove", id, prevBlocker, prevBlocker));
     }
   },
   /**
-   * Check if a scope is currently blocked
-   *
-   * @param scope - Scope or array of scopes to check (default: "global")
-   * @returns True if any of the scopes are blocked
-   *
+   * Checks if one or more scopes are currently blocked.
+   * 
+   * Returns true if ANY blocker affects the specified scope(s). Global scope
+   * blockers will cause this to return true for any scope check.
+   * 
+   * @param scope - Scope(s) to check. Defaults to "global" if not specified.
+   *                Can be a single scope string or array of scopes.
+   * @returns true if any of the specified scopes are currently blocked
+   * 
+   * @example
+   * Single scope check
+   * ```ts
+   * const isFormBlocked = store.getState().isBlocked('form');
+   * console.log(isFormBlocked); // true or false
+   * ```
+   * 
+   * @example
+   * Multiple scopes check
+   * ```ts
+   * const isBlocked = store.getState().isBlocked(['form', 'navigation']);
+   * // Returns true if either 'form' OR 'navigation' has active blockers
+   * ```
+   * 
+   * @see {@link getBlockingInfo} for detailed blocker information
    */
   isBlocked: (scope = DEFAULT_SCOPE) => {
     const { activeBlockers } = get();
@@ -160,11 +313,37 @@ var createUIBlockingActions = (set, get) => ({
     return false;
   },
   /**
-   * Get detailed blocking information for a specific scope
-   *
+   * Gets detailed information about all blockers affecting a specific scope.
+   * 
+   * Returns an array of blocker objects sorted by priority (highest first).
+   * Includes global blockers and scope-specific blockers. Each blocker object
+   * contains id, reason, priority, scope, timestamp, and timeout information.
+   * 
    * @param scope - Scope to get blocking information for
-   * @returns Array of blockers affecting the scope, sorted by priority (highest first)
-   *
+   * @returns Array of {@link BlockerInfo} objects, sorted by priority descending
+   * 
+   * @example
+   * Display blocker details
+   * ```ts
+   * const blockers = store.getState().getBlockingInfo('form');
+   * blockers.forEach(blocker => {
+   *   console.log(`${blocker.id}: ${blocker.reason}`);
+   *   console.log(`Priority: ${blocker.priority}`);
+   * });
+   * ```
+   * 
+   * @example
+   * Get highest priority blocker
+   * ```ts
+   * const blockers = store.getState().getBlockingInfo('navigation');
+   * const topBlocker = blockers[0]; // Highest priority
+   * if (topBlocker) {
+   *   console.log(`Top blocker: ${topBlocker.reason}`);
+   * }
+   * ```
+   * 
+   * @see {@link isBlocked} for a simple boolean check
+   * @see {@link BlockerInfo} for the structure of returned objects
    */
   getBlockingInfo: (scope) => {
     const { activeBlockers } = get();
@@ -178,29 +357,71 @@ var createUIBlockingActions = (set, get) => ({
     return blockers.sort((a, b) => b.priority - a.priority);
   },
   /**
-   * Clear all blockers from the store
+   * Removes all active blockers from the store.
+   * 
+   * Clears all timeouts and triggers middleware with 'clear' action.
+   * Useful for resetting the blocking state.
+   * 
+   * @example
+   * ```ts
+   * // Clear all blockers on logout
+   * store.getState().clearAllBlockers();
+   * ```
+   * 
+   * @see {@link clearBlockersForScope} to clear blockers for a specific scope
    */
   clearAllBlockers: () => {
     const { activeBlockers } = get();
+    const count = activeBlockers.size;
     for (const [, blocker] of activeBlockers) {
       if (blocker.timeoutId) {
         clearTimeout(blocker.timeoutId);
       }
     }
     set({ activeBlockers: /* @__PURE__ */ new Map() });
+    if (count > 0) {
+      void get().runMiddlewares({
+        action: "clear",
+        blockerId: "*",
+        timestamp: Date.now(),
+        count
+      });
+    }
   },
   /**
-   * Clear all blockers for a specific scope
-   *
+   * Removes all blockers that affect a specific scope.
+   * 
+   * Clears timeouts for removed blockers and triggers middleware with
+   * 'clear_scope' action. Global scope blockers are NOT cleared by this method.
+   * 
    * @param scope - Scope to clear blockers for
-   *
+   * 
+   * @example
+   * Clear form blockers
+   * ```ts
+   * // Clear all blockers affecting 'form' scope
+   * store.getState().clearBlockersForScope('form');
+   * ```
+   * 
+   * @example
+   * Clear on navigation
+   * ```ts
+   * // Clear navigation blockers when user navigates away
+   * store.getState().clearBlockersForScope('navigation');
+   * ```
+   * 
+   * @see {@link clearAllBlockers} to clear all blockers
    */
   clearBlockersForScope: (scope) => {
     const { activeBlockers } = get();
+    let count = 0;
     for (const [, blocker] of activeBlockers) {
       const blockerScopes = normalizeScopeToArray(blocker.scope);
-      if (blockerScopes.includes(scope) && blocker.timeoutId) {
-        clearTimeout(blocker.timeoutId);
+      if (blockerScopes.includes(scope)) {
+        if (blocker.timeoutId) {
+          clearTimeout(blocker.timeoutId);
+        }
+        count++;
       }
     }
     set((state) => {
@@ -213,6 +434,15 @@ var createUIBlockingActions = (set, get) => ({
       }
       return { activeBlockers: newBlockers };
     });
+    if (count > 0) {
+      void get().runMiddlewares({
+        action: "clear_scope",
+        blockerId: "*",
+        timestamp: Date.now(),
+        scope,
+        count
+      });
+    }
   }
 });
 var {
@@ -272,9 +502,11 @@ var useAsyncAction = (actionId, scope, options) => {
     addBlocker: state.addBlocker,
     removeBlocker: state.removeBlocker
   }));
+  const counterRef = useRef(0);
   const executeWithBlocking = useCallback(
     async (asyncFn) => {
-      const blockerId = `${actionId}-${Date.now().toString()}`;
+      counterRef.current += 1;
+      const blockerId = `${actionId}-${String(counterRef.current)}`;
       try {
         addBlocker(blockerId, {
           scope,
@@ -609,14 +841,16 @@ var getActionEmoji = (action) => {
   switch (action) {
     case "add":
       return "\u2795";
-    case "remove":
-      return "\u2796";
     case "update":
       return "\u{1F504}";
-    case "cancel":
-      return "\u274C";
+    case "remove":
+      return "\u2796";
     case "timeout":
       return "\u23F1\uFE0F";
+    case "clear":
+      return "\u{1F9F9}";
+    case "clear_scope":
+      return "\u{1F3AF}";
     default:
       return "\u2753";
   }
@@ -637,13 +871,23 @@ var extractConfigDetails = (config) => {
 };
 var formatLogData = (context) => {
   const configDetails = extractConfigDetails(context.config);
+  const logData = {};
+  if (context.scope !== void 0) {
+    logData.scope = context.scope;
+  }
+  if (context.count !== void 0) {
+    logData.count = context.count;
+  }
+  if (Object.keys(configDetails).length > 0) {
+    logData.config = configDetails;
+  }
   if (context.prevState) {
-    return {
-      config: configDetails,
-      prevState: extractConfigDetails(context.prevState)
-    };
+    logData.prevState = extractConfigDetails(context.prevState);
+  }
+  if (Object.keys(logData).length === 0) {
+    return configDetails;
   }
-  return configDetails;
+  return Object.keys(logData).length === 1 && logData.config ? configDetails : logData;
 };
 
 // src/middleware/loggerMiddleware.ts