react-native-permission-handler 0.2.1 → 0.3.0

package/src/core/with-timeout.test.ts

@@ -0,0 +1,82 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PermissionTimeoutError, withTimeout } from "./with-timeout";
+
+describe("withTimeout", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("resolves when the promise resolves before timeout", async () => {
+    const promise = Promise.resolve("granted");
+    const result = await withTimeout(promise, 5000, "camera");
+    expect(result).toBe("granted");
+  });
+
+  it("rejects with PermissionTimeoutError when promise hangs", async () => {
+    const promise = new Promise(() => {}); // never resolves
+    const wrapped = withTimeout(promise, 1000, "camera");
+
+    vi.advanceTimersByTime(1000);
+
+    await expect(wrapped).rejects.toThrow(PermissionTimeoutError);
+    await expect(wrapped).rejects.toThrow("timed out after 1000ms");
+  });
+
+  it("includes permission name in error", async () => {
+    const promise = new Promise(() => {});
+    const wrapped = withTimeout(promise, 500, "microphone");
+
+    vi.advanceTimersByTime(500);
+
+    try {
+      await wrapped;
+    } catch (err) {
+      expect(err).toBeInstanceOf(PermissionTimeoutError);
+      expect((err as PermissionTimeoutError).permission).toBe("microphone");
+      expect((err as PermissionTimeoutError).timeoutMs).toBe(500);
+    }
+  });
+
+  it("clears the timer when promise resolves", async () => {
+    const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout");
+    const promise = Promise.resolve("denied");
+
+    await withTimeout(promise, 5000, "camera");
+
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+    clearTimeoutSpy.mockRestore();
+  });
+
+  it("clears the timer when promise rejects", async () => {
+    const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout");
+    const promise = Promise.reject(new Error("network error"));
+
+    await expect(withTimeout(promise, 5000, "camera")).rejects.toThrow("network error");
+
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+    clearTimeoutSpy.mockRestore();
+  });
+
+  it("propagates original rejection when promise rejects before timeout", async () => {
+    const error = new Error("engine error");
+    const promise = Promise.reject(error);
+
+    await expect(withTimeout(promise, 5000, "camera")).rejects.toBe(error);
+  });
+});
+
+describe("PermissionTimeoutError", () => {
+  it("has the correct name", () => {
+    const error = new PermissionTimeoutError("camera", 1000);
+    expect(error.name).toBe("PermissionTimeoutError");
+  });
+
+  it("is an instance of Error", () => {
+    const error = new PermissionTimeoutError("camera", 1000);
+    expect(error).toBeInstanceOf(Error);
+  });
+});

package/src/core/with-timeout.ts

@@ -0,0 +1,34 @@
+export class PermissionTimeoutError extends Error {
+  readonly permission: string;
+  readonly timeoutMs: number;
+
+  constructor(permission: string, timeoutMs: number) {
+    super(`Permission request for "${permission}" timed out after ${timeoutMs}ms`);
+    this.name = "PermissionTimeoutError";
+    this.permission = permission;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+export function withTimeout<T>(
+  promise: Promise<T>,
+  timeoutMs: number,
+  permission: string,
+): Promise<T> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new PermissionTimeoutError(permission, timeoutMs)),
+      timeoutMs,
+    );
+    promise.then(
+      (val) => {
+        clearTimeout(timer);
+        resolve(val);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}

package/src/hooks/use-multiple-permissions.ts

@@ -1,4 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from "react";
+import { createDebugLogger } from "../core/debug-logger";
+import { PermissionTimeoutError, withTimeout } from "../core/with-timeout";
 import { resolveEngine } from "../engines/use-engine";
 import type {
   MultiPermissionEntry,
@@ -37,7 +39,16 @@ export function useMultiplePermissions(
   config: MultiplePermissionsConfig,
 ): MultiplePermissionsResult {
   const engine = resolveEngine(config.engine);
-  const { permissions, strategy, autoCheck = true, onAllGranted } = config;
+  const {
+    permissions,
+    strategy,
+    autoCheck = true,
+    requestTimeout,
+    onTimeout,
+    debug,
+    onAllGranted,
+  } = config;
+  const logger = createDebugLogger(debug, "multi");
   const [statuses, setStatuses] = useState<Record<string, PermissionFlowState>>(() => {
     const initial: Record<string, PermissionFlowState> = {};
     for (const entry of permissions) {
@@ -54,14 +65,17 @@ export function useMultiplePermissions(
     isRunning.current = true;
 
     const update = (key: string, state: PermissionFlowState) => {
-      setStatuses((prev) => ({ ...prev, [key]: state }));
+      setStatuses((prev) => {
+        logger.transition(prev[key] ?? "idle", state, key);
+        return { ...prev, [key]: state };
+      });
     };
 
     try {
       if (strategy === "sequential") {
-        await runSequential(permissions, engine, update);
+        await runSequential(permissions, engine, update, requestTimeout, onTimeout);
       } else {
-        await runParallel(permissions, engine, update);
+        await runParallel(permissions, engine, update, requestTimeout, onTimeout);
       }
 
       // Final check: are all granted?
@@ -79,7 +93,7 @@ export function useMultiplePermissions(
     } finally {
       isRunning.current = false;
     }
-  }, [permissions, strategy, engine, onAllGranted]);
+  }, [permissions, strategy, engine, requestTimeout, onTimeout, logger, onAllGranted]);
 
   // Auto-check on mount
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentional mount-only effect
@@ -112,6 +126,8 @@ async function runSequential(
   permissions: MultiPermissionEntry[],
   engine: PermissionEngine,
   updateStatus: (key: string, state: PermissionFlowState) => void,
+  requestTimeout?: number,
+  onTimeout?: () => void,
 ): Promise<void> {
   for (const entry of permissions) {
     const key = permissionKey(entry);
@@ -138,19 +154,31 @@ async function runSequential(
 
     // Denied — request it
     updateStatus(key, "requesting");
-    const requestStatus = await engine.request(entry.permission);
-
-    if (isGrantedStatus(requestStatus)) {
-      updateStatus(key, "granted");
-      entry.onGrant?.();
-    } else if (requestStatus === "blocked") {
-      updateStatus(key, "blockedPrompt");
-      entry.onBlock?.();
-      break;
-    } else {
-      updateStatus(key, "denied");
-      entry.onDeny?.();
-      break;
+    try {
+      const requestPromise = engine.request(entry.permission);
+      const requestStatus = requestTimeout
+        ? await withTimeout(requestPromise, requestTimeout, entry.permission)
+        : await requestPromise;
+
+      if (isGrantedStatus(requestStatus)) {
+        updateStatus(key, "granted");
+        entry.onGrant?.();
+      } else if (requestStatus === "blocked") {
+        updateStatus(key, "blockedPrompt");
+        entry.onBlock?.();
+        break;
+      } else {
+        updateStatus(key, "denied");
+        entry.onDeny?.();
+        break;
+      }
+    } catch (err) {
+      if (err instanceof PermissionTimeoutError) {
+        onTimeout?.();
+        updateStatus(key, "blockedPrompt");
+        break;
+      }
+      throw err;
     }
   }
 }
@@ -159,6 +187,8 @@ async function runParallel(
   permissions: MultiPermissionEntry[],
   engine: PermissionEngine,
   updateStatus: (key: string, state: PermissionFlowState) => void,
+  requestTimeout?: number,
+  onTimeout?: () => void,
 ): Promise<void> {
   // Check all in parallel
   const checkResults = await Promise.all(
@@ -193,17 +223,29 @@ async function runParallel(
     }
 
     updateStatus(key, "requesting");
-    const requestStatus = await engine.request(entry.permission);
-
-    if (isGrantedStatus(requestStatus)) {
-      updateStatus(key, "granted");
-      entry.onGrant?.();
-    } else if (requestStatus === "blocked") {
-      updateStatus(key, "blockedPrompt");
-      entry.onBlock?.();
-    } else {
-      updateStatus(key, "denied");
-      entry.onDeny?.();
+    try {
+      const requestPromise = engine.request(entry.permission);
+      const requestStatus = requestTimeout
+        ? await withTimeout(requestPromise, requestTimeout, entry.permission)
+        : await requestPromise;
+
+      if (isGrantedStatus(requestStatus)) {
+        updateStatus(key, "granted");
+        entry.onGrant?.();
+      } else if (requestStatus === "blocked") {
+        updateStatus(key, "blockedPrompt");
+        entry.onBlock?.();
+      } else {
+        updateStatus(key, "denied");
+        entry.onDeny?.();
+      }
+    } catch (err) {
+      if (err instanceof PermissionTimeoutError) {
+        onTimeout?.();
+        updateStatus(key, "blockedPrompt");
+      } else {
+        throw err;
+      }
     }
   }
 }

package/src/hooks/use-permission-handler.ts

@@ -1,6 +1,8 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { AppState } from "react-native";
+import { createDebugLogger } from "../core/debug-logger";
 import { transition } from "../core/state-machine";
+import { PermissionTimeoutError, withTimeout } from "../core/with-timeout";
 import { resolveEngine } from "../engines/use-engine";
 import type {
   PermissionFlowState,
@@ -17,52 +19,91 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
   const waitingForSettings = useRef(false);
   const appStateRef = useRef(AppState.currentState);
 
-  const { permission, autoCheck = true, onGrant, onDeny, onBlock, onSettingsReturn } = config;
+  const {
+    permission,
+    autoCheck = true,
+    requestTimeout,
+    onTimeout,
+    debug,
+    onGrant,
+    onDeny,
+    onBlock,
+    onSettingsReturn,
+  } = config;
+
+  const logger = createDebugLogger(debug, permission);
 
   const checkPermission = useCallback(async () => {
-    setFlowState((s) => transition(s, { type: "CHECK" }));
+    setFlowState((s) => {
+      const next = transition(s, { type: "CHECK" });
+      logger.transition(s, next, "CHECK");
+      return next;
+    });
     try {
       const status = await engine.check(permission);
       setNativeStatus(status);
       setFlowState((s) => {
         const next = transition(s, { type: "CHECK_RESULT", status });
+        logger.transition(s, next, `CHECK_RESULT:${status}`);
         if (next === "granted" && s !== "granted") onGrant?.();
         return next;
       });
     } catch {
       setFlowState("idle");
     }
-  }, [engine, permission, onGrant]);
+  }, [engine, permission, logger, onGrant]);
 
   const requestPermission = useCallback(async () => {
     if (isRequesting.current) return;
     isRequesting.current = true;
 
-    setFlowState((s) => transition(s, { type: "PRE_PROMPT_CONFIRM" }));
+    setFlowState((s) => {
+      const next = transition(s, { type: "PRE_PROMPT_CONFIRM" });
+      logger.transition(s, next, "PRE_PROMPT_CONFIRM");
+      return next;
+    });
     try {
-      const status = await engine.request(permission);
+      const requestPromise = engine.request(permission);
+      const status = requestTimeout
+        ? await withTimeout(requestPromise, requestTimeout, permission)
+        : await requestPromise;
       setNativeStatus(status);
       setFlowState((s) => {
         const next = transition(s, { type: "REQUEST_RESULT", status });
+        logger.transition(s, next, `REQUEST_RESULT:${status}`);
         if (next === "granted") onGrant?.();
         if (next === "denied") onDeny?.();
         if (next === "blockedPrompt") onBlock?.();
         return next;
       });
-    } catch {
-      setFlowState("denied");
+    } catch (err) {
+      if (err instanceof PermissionTimeoutError) {
+        logger.info(`request timed out after ${requestTimeout}ms`);
+        onTimeout?.();
+        setFlowState("blockedPrompt");
+      } else {
+        setFlowState("denied");
+      }
     } finally {
       isRequesting.current = false;
     }
-  }, [engine, permission, onGrant, onDeny, onBlock]);
+  }, [engine, permission, requestTimeout, onTimeout, logger, onGrant, onDeny, onBlock]);
 
   const dismiss = useCallback(() => {
-    setFlowState((s) => transition(s, { type: "PRE_PROMPT_DISMISS" }));
+    setFlowState((s) => {
+      const next = transition(s, { type: "PRE_PROMPT_DISMISS" });
+      logger.transition(s, next, "PRE_PROMPT_DISMISS");
+      return next;
+    });
     onDeny?.();
-  }, [onDeny]);
+  }, [logger, onDeny]);
 
   const goToSettings = useCallback(async () => {
-    setFlowState((s) => transition(s, { type: "OPEN_SETTINGS" }));
+    setFlowState((s) => {
+      const next = transition(s, { type: "OPEN_SETTINGS" });
+      logger.transition(s, next, "OPEN_SETTINGS");
+      return next;
+    });
     waitingForSettings.current = true;
     try {
       await engine.openSettings();
@@ -70,15 +111,20 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
       waitingForSettings.current = false;
       setFlowState("blockedPrompt");
     }
-  }, [engine]);
+  }, [engine, logger]);
 
   const recheckAfterSettings = useCallback(async () => {
-    setFlowState((s) => transition(s, { type: "SETTINGS_RETURN" }));
+    setFlowState((s) => {
+      const next = transition(s, { type: "SETTINGS_RETURN" });
+      logger.transition(s, next, "SETTINGS_RETURN");
+      return next;
+    });
     try {
       const status = await engine.check(permission);
       setNativeStatus(status);
       setFlowState((s) => {
         const next = transition(s, { type: "RECHECK_RESULT", status });
+        logger.transition(s, next, `RECHECK_RESULT:${status}`);
         if (next === "granted") onGrant?.();
         onSettingsReturn?.(next === "granted");
         return next;
@@ -86,7 +132,7 @@ export function usePermissionHandler(config: PermissionHandlerConfig): Permissio
     } catch {
       setFlowState("blockedPrompt");
     }
-  }, [engine, permission, onGrant, onSettingsReturn]);
+  }, [engine, permission, logger, onGrant, onSettingsReturn]);
 
   // Auto-check on mount
   // biome-ignore lint/correctness/useExhaustiveDependencies: intentional mount-only effect

package/src/types.ts

@@ -82,6 +82,9 @@ export interface PermissionHandlerConfig extends PermissionCallbacks {
   blockedPrompt: BlockedPromptConfig;
   autoCheck?: boolean;
   recheckOnForeground?: boolean;
+  requestTimeout?: number;
+  onTimeout?: () => void;
+  debug?: boolean | ((msg: string) => void);
 }
 
 /**
@@ -118,6 +121,9 @@ export interface MultiplePermissionsConfig {
   strategy: "sequential" | "parallel";
   engine?: PermissionEngine;
   autoCheck?: boolean;
+  requestTimeout?: number;
+  onTimeout?: () => void;
+  debug?: boolean | ((msg: string) => void);
   onAllGranted?: () => void;
 }