react-native-permission-handler 0.1.0

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

@@ -0,0 +1,167 @@
+import { createElement } from "react";
+import { type ReactTestRenderer, act, create } from "react-test-renderer";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { MultiplePermissionsConfig, MultiplePermissionsResult } from "../types";
+
+vi.mock("react-native", () => ({
+  AppState: {
+    currentState: "active",
+    addEventListener: vi.fn(() => ({ remove: vi.fn() })),
+  },
+}));
+
+vi.mock("react-native-permissions", () => ({
+  check: vi.fn(),
+  request: vi.fn(),
+  openSettings: vi.fn(),
+  checkNotifications: vi.fn(),
+  requestNotifications: vi.fn(),
+}));
+
+import { check, request } from "react-native-permissions";
+import { useMultiplePermissions } from "./use-multiple-permissions";
+
+function renderHook(hookFn: () => MultiplePermissionsResult) {
+  const results: { current: MultiplePermissionsResult } = {} as {
+    current: MultiplePermissionsResult;
+  };
+  function TestComponent() {
+    results.current = hookFn();
+    return null;
+  }
+  let renderer: ReactTestRenderer;
+  act(() => {
+    renderer = create(createElement(TestComponent));
+  });
+  return {
+    result: results,
+    unmount: () => act(() => renderer.unmount()),
+  };
+}
+
+const baseConfig: MultiplePermissionsConfig = {
+  permissions: [
+    {
+      permission:
+        "ios.permission.CAMERA" as MultiplePermissionsConfig["permissions"][0]["permission"],
+      prePrompt: { title: "Camera", message: "Need camera" },
+      blockedPrompt: { title: "Blocked", message: "Camera blocked" },
+    },
+    {
+      permission:
+        "ios.permission.MICROPHONE" as MultiplePermissionsConfig["permissions"][0]["permission"],
+      prePrompt: { title: "Mic", message: "Need mic" },
+      blockedPrompt: { title: "Blocked", message: "Mic blocked" },
+    },
+  ],
+  strategy: "sequential",
+};
+
+describe("useMultiplePermissions", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("initializes all permissions as idle", () => {
+    const { result } = renderHook(() => useMultiplePermissions(baseConfig));
+
+    expect(result.current.allGranted).toBe(false);
+    expect(Object.values(result.current.statuses)).toEqual(["idle", "idle"]);
+  });
+
+  it("grants all permissions sequentially when already granted", async () => {
+    vi.mocked(check).mockResolvedValue("granted");
+    const onAllGranted = vi.fn();
+
+    const { result } = renderHook(() => useMultiplePermissions({ ...baseConfig, onAllGranted }));
+
+    await act(async () => {
+      await result.current.request();
+    });
+
+    expect(result.current.allGranted).toBe(true);
+    expect(onAllGranted).toHaveBeenCalledOnce();
+  });
+
+  it("requests denied permissions sequentially", async () => {
+    // Initial checks return denied, final re-checks return granted
+    vi.mocked(check)
+      .mockResolvedValueOnce("denied") // camera initial check
+      .mockResolvedValueOnce("denied") // mic initial check
+      .mockResolvedValue("granted"); // final re-checks
+    vi.mocked(request).mockResolvedValue("granted");
+    const onAllGranted = vi.fn();
+
+    const { result } = renderHook(() => useMultiplePermissions({ ...baseConfig, onAllGranted }));
+
+    await act(async () => {
+      await result.current.request();
+    });
+
+    expect(result.current.allGranted).toBe(true);
+    expect(request).toHaveBeenCalledTimes(2);
+    expect(onAllGranted).toHaveBeenCalledOnce();
+  });
+
+  it("stops sequential flow when permission is denied", async () => {
+    vi.mocked(check).mockResolvedValue("denied");
+    vi.mocked(request).mockResolvedValueOnce("denied");
+
+    const { result } = renderHook(() => useMultiplePermissions(baseConfig));
+
+    await act(async () => {
+      await result.current.request();
+    });
+
+    expect(result.current.allGranted).toBe(false);
+    expect(request).toHaveBeenCalledTimes(1);
+  });
+
+  it("fires per-permission callbacks", async () => {
+    vi.mocked(check).mockResolvedValue("denied");
+    vi.mocked(request).mockResolvedValueOnce("granted").mockResolvedValueOnce("denied");
+    const onGrant = vi.fn();
+    const onDeny = vi.fn();
+
+    const config: MultiplePermissionsConfig = {
+      ...baseConfig,
+      permissions: [
+        { ...baseConfig.permissions[0], onGrant },
+        { ...baseConfig.permissions[1], onDeny },
+      ],
+    };
+
+    const { result } = renderHook(() => useMultiplePermissions(config));
+
+    await act(async () => {
+      await result.current.request();
+    });
+
+    expect(onGrant).toHaveBeenCalledOnce();
+    expect(onDeny).toHaveBeenCalledOnce();
+  });
+
+  it("handles parallel strategy — checks all, then requests denied", async () => {
+    vi.mocked(check)
+      .mockResolvedValueOnce("granted") // camera already granted
+      .mockResolvedValueOnce("denied") // mic needs request
+      .mockResolvedValue("granted"); // final re-checks
+    vi.mocked(request).mockResolvedValue("granted");
+    const onAllGranted = vi.fn();
+
+    const config: MultiplePermissionsConfig = {
+      ...baseConfig,
+      strategy: "parallel",
+      onAllGranted,
+    };
+
+    const { result } = renderHook(() => useMultiplePermissions(config));
+
+    await act(async () => {
+      await result.current.request();
+    });
+
+    expect(request).toHaveBeenCalledTimes(1); // only mic was requested
+    expect(onAllGranted).toHaveBeenCalledOnce();
+  });
+});

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

@@ -0,0 +1,196 @@
+import { useCallback, useRef, useState } from "react";
+import {
+  type PermissionStatus,
+  check,
+  checkNotifications,
+  request,
+  requestNotifications,
+} from "react-native-permissions";
+import type {
+  MultiPermissionEntry,
+  MultiplePermissionsConfig,
+  MultiplePermissionsResult,
+  PermissionFlowState,
+} from "../types";
+
+function isNotifications(
+  permission: MultiPermissionEntry["permission"],
+): permission is "notifications" {
+  return permission === "notifications";
+}
+
+async function checkOne(entry: MultiPermissionEntry): Promise<PermissionStatus> {
+  if (isNotifications(entry.permission)) {
+    const result = await checkNotifications();
+    return result.status;
+  }
+  return check(entry.permission);
+}
+
+async function requestOne(entry: MultiPermissionEntry): Promise<PermissionStatus> {
+  if (isNotifications(entry.permission)) {
+    const result = await requestNotifications(["alert", "badge", "sound"]);
+    return result.status;
+  }
+  return request(entry.permission);
+}
+
+function permissionKey(entry: MultiPermissionEntry): string {
+  return String(entry.permission);
+}
+
+function isGrantedStatus(status: PermissionStatus): boolean {
+  return status === "granted" || status === "limited";
+}
+
+export function useMultiplePermissions(
+  config: MultiplePermissionsConfig,
+): MultiplePermissionsResult {
+  const { permissions, strategy, onAllGranted } = config;
+  const [statuses, setStatuses] = useState<Record<string, PermissionFlowState>>(() => {
+    const initial: Record<string, PermissionFlowState> = {};
+    for (const entry of permissions) {
+      initial[permissionKey(entry)] = "idle";
+    }
+    return initial;
+  });
+  const isRunning = useRef(false);
+
+  const allGranted = permissions.every((entry) => statuses[permissionKey(entry)] === "granted");
+
+  const requestAll = useCallback(async () => {
+    if (isRunning.current) return;
+    isRunning.current = true;
+
+    const update = (key: string, state: PermissionFlowState) => {
+      setStatuses((prev) => ({ ...prev, [key]: state }));
+    };
+
+    try {
+      if (strategy === "sequential") {
+        await runSequential(permissions, update);
+      } else {
+        await runParallel(permissions, update);
+      }
+
+      // Final check: are all granted?
+      let allDone = true;
+      for (const entry of permissions) {
+        const finalStatus = await checkOne(entry);
+        if (!isGrantedStatus(finalStatus)) {
+          allDone = false;
+          break;
+        }
+      }
+      if (allDone) {
+        onAllGranted?.();
+      }
+    } finally {
+      isRunning.current = false;
+    }
+  }, [permissions, strategy, onAllGranted]);
+
+  return {
+    statuses,
+    allGranted,
+    request: requestAll,
+  };
+}
+
+async function runSequential(
+  permissions: MultiPermissionEntry[],
+  updateStatus: (key: string, state: PermissionFlowState) => void,
+): Promise<void> {
+  for (const entry of permissions) {
+    const key = permissionKey(entry);
+
+    updateStatus(key, "checking");
+    const checkStatus = await checkOne(entry);
+
+    if (isGrantedStatus(checkStatus)) {
+      updateStatus(key, "granted");
+      entry.onGrant?.();
+      continue;
+    }
+
+    if (checkStatus === "unavailable") {
+      updateStatus(key, "unavailable");
+      continue;
+    }
+
+    if (checkStatus === "blocked") {
+      updateStatus(key, "blockedPrompt");
+      entry.onBlock?.();
+      break;
+    }
+
+    // Denied — request it
+    updateStatus(key, "requesting");
+    const requestStatus = await requestOne(entry);
+
+    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;
+    }
+  }
+}
+
+async function runParallel(
+  permissions: MultiPermissionEntry[],
+  updateStatus: (key: string, state: PermissionFlowState) => void,
+): Promise<void> {
+  // Check all in parallel
+  const checkResults = await Promise.all(
+    permissions.map(async (entry) => {
+      const key = permissionKey(entry);
+      updateStatus(key, "checking");
+      const status = await checkOne(entry);
+      return { entry, key, status };
+    }),
+  );
+
+  // Update granted/unavailable immediately
+  for (const { entry, key, status } of checkResults) {
+    if (isGrantedStatus(status)) {
+      updateStatus(key, "granted");
+      entry.onGrant?.();
+    } else if (status === "unavailable") {
+      updateStatus(key, "unavailable");
+    }
+  }
+
+  // Request denied/blocked ones sequentially (system dialogs are sequential)
+  const needsAction = checkResults.filter(
+    ({ status }) => status === "denied" || status === "blocked",
+  );
+
+  for (const { entry, key, status } of needsAction) {
+    if (status === "blocked") {
+      updateStatus(key, "blockedPrompt");
+      entry.onBlock?.();
+      continue;
+    }
+
+    updateStatus(key, "requesting");
+    const requestStatus = await requestOne(entry);
+
+    if (isGrantedStatus(requestStatus)) {
+      updateStatus(key, "granted");
+      entry.onGrant?.();
+    } else if (requestStatus === "blocked") {
+      updateStatus(key, "blockedPrompt");
+      entry.onBlock?.();
+    } else {
+      updateStatus(key, "denied");
+      entry.onDeny?.();
+    }
+  }
+}

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

@@ -0,0 +1,210 @@
+import { createElement } from "react";
+import { type ReactTestRenderer, act, create } from "react-test-renderer";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { PermissionHandlerConfig, PermissionHandlerResult } from "../types";
+
+// Mocks must be before imports that use them
+vi.mock("react-native", () => ({
+  AppState: {
+    currentState: "active",
+    addEventListener: vi.fn(() => ({ remove: vi.fn() })),
+  },
+}));
+
+vi.mock("react-native-permissions", () => ({
+  check: vi.fn(),
+  request: vi.fn(),
+  openSettings: vi.fn(),
+  checkNotifications: vi.fn(),
+  requestNotifications: vi.fn(),
+}));
+
+import { check, checkNotifications, request, requestNotifications } from "react-native-permissions";
+import { usePermissionHandler } from "./use-permission-handler";
+
+// Minimal renderHook using react-test-renderer
+function renderHook(hookFn: () => PermissionHandlerResult) {
+  const results: { current: PermissionHandlerResult } = {} as {
+    current: PermissionHandlerResult;
+  };
+  function TestComponent() {
+    results.current = hookFn();
+    return null;
+  }
+  let renderer: ReactTestRenderer;
+  act(() => {
+    renderer = create(createElement(TestComponent));
+  });
+  return {
+    result: results,
+    unmount: () => act(() => renderer.unmount()),
+  };
+}
+
+const baseConfig: PermissionHandlerConfig = {
+  permission: "ios.permission.CAMERA" as PermissionHandlerConfig["permission"],
+  prePrompt: { title: "Camera", message: "We need camera access" },
+  blockedPrompt: { title: "Blocked", message: "Camera is blocked" },
+};
+
+describe("usePermissionHandler", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("auto-checks on mount and transitions to granted", async () => {
+    vi.mocked(check).mockResolvedValue("granted");
+    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+
+    // After mount, should be checking
+    await act(async () => {});
+
+    expect(result.current.isGranted).toBe(true);
+    expect(result.current.state).toBe("granted");
+    expect(check).toHaveBeenCalledWith(baseConfig.permission);
+  });
+
+  it("transitions to prePrompt when permission is denied", async () => {
+    vi.mocked(check).mockResolvedValue("denied");
+    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+
+    await act(async () => {});
+
+    expect(result.current.state).toBe("prePrompt");
+  });
+
+  it("transitions to blockedPrompt when permission is blocked", async () => {
+    vi.mocked(check).mockResolvedValue("blocked");
+    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+
+    await act(async () => {});
+
+    expect(result.current.state).toBe("blockedPrompt");
+    expect(result.current.isBlocked).toBe(true);
+  });
+
+  it("transitions to unavailable", async () => {
+    vi.mocked(check).mockResolvedValue("unavailable");
+    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+
+    await act(async () => {});
+
+    expect(result.current.isUnavailable).toBe(true);
+    expect(result.current.state).toBe("unavailable");
+  });
+
+  it("skips auto-check when autoCheck is false", async () => {
+    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, autoCheck: false }));
+
+    await act(async () => {});
+
+    expect(result.current.state).toBe("idle");
+    expect(check).not.toHaveBeenCalled();
+  });
+
+  it("requests permission and fires onGrant", async () => {
+    vi.mocked(check).mockResolvedValue("denied");
+    vi.mocked(request).mockResolvedValue("granted");
+    const onGrant = vi.fn();
+
+    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, onGrant }));
+
+    await act(async () => {});
+    expect(result.current.state).toBe("prePrompt");
+
+    await act(async () => {
+      result.current.request();
+    });
+
+    expect(result.current.isGranted).toBe(true);
+    expect(onGrant).toHaveBeenCalled();
+  });
+
+  it("fires onDeny when request is denied", async () => {
+    vi.mocked(check).mockResolvedValue("denied");
+    vi.mocked(request).mockResolvedValue("denied");
+    const onDeny = vi.fn();
+
+    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, onDeny }));
+
+    await act(async () => {});
+    await act(async () => {
+      result.current.request();
+    });
+
+    expect(result.current.isDenied).toBe(true);
+    expect(onDeny).toHaveBeenCalled();
+  });
+
+  it("fires onBlock when request results in blocked", async () => {
+    vi.mocked(check).mockResolvedValue("denied");
+    vi.mocked(request).mockResolvedValue("blocked");
+    const onBlock = vi.fn();
+
+    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, onBlock }));
+
+    await act(async () => {});
+    await act(async () => {
+      result.current.request();
+    });
+
+    expect(result.current.state).toBe("blockedPrompt");
+    expect(onBlock).toHaveBeenCalled();
+  });
+
+  it("uses notification API when permission is 'notifications'", async () => {
+    vi.mocked(checkNotifications).mockResolvedValue({ status: "denied", settings: {} });
+    vi.mocked(requestNotifications).mockResolvedValue({ status: "granted", settings: {} });
+
+    const { result } = renderHook(() =>
+      usePermissionHandler({ ...baseConfig, permission: "notifications" }),
+    );
+
+    await act(async () => {});
+    expect(checkNotifications).toHaveBeenCalled();
+    expect(check).not.toHaveBeenCalled();
+
+    await act(async () => {
+      result.current.request();
+    });
+
+    expect(requestNotifications).toHaveBeenCalledWith(["alert", "badge", "sound"]);
+    expect(result.current.isGranted).toBe(true);
+  });
+
+  it("guards against double-tap race condition", async () => {
+    vi.mocked(check).mockResolvedValue("denied");
+    vi.mocked(request).mockImplementation(
+      () => new Promise((resolve) => setTimeout(() => resolve("granted"), 50)),
+    );
+
+    const { result } = renderHook(() => usePermissionHandler(baseConfig));
+
+    await act(async () => {});
+    expect(result.current.state).toBe("prePrompt");
+
+    await act(async () => {
+      result.current.request();
+      result.current.request(); // double-tap
+    });
+
+    expect(request).toHaveBeenCalledTimes(1);
+  });
+
+  it("dismiss fires onDeny and transitions to denied", async () => {
+    vi.mocked(check).mockResolvedValue("denied");
+    const onDeny = vi.fn();
+
+    const { result } = renderHook(() => usePermissionHandler({ ...baseConfig, onDeny }));
+
+    await act(async () => {});
+    expect(result.current.state).toBe("prePrompt");
+
+    act(() => {
+      result.current.dismiss();
+    });
+
+    expect(result.current.isDenied).toBe(true);
+    expect(onDeny).toHaveBeenCalled();
+  });
+});