react-native-permission-handler 0.1.0 → 0.2.0

package/src/engines/resolve.test.ts

@@ -0,0 +1,85 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { PermissionEngine } from "../types";
+
+// Mock the RNP fallback
+const mockFallbackEngine: PermissionEngine = {
+  check: vi.fn().mockResolvedValue("granted"),
+  request: vi.fn().mockResolvedValue("granted"),
+  openSettings: vi.fn().mockResolvedValue(undefined),
+};
+
+vi.mock("./rnp-fallback", () => ({
+  getRNPFallbackEngine: vi.fn(() => mockFallbackEngine),
+}));
+
+import { getDefaultEngine, setDefaultEngine } from "./resolve";
+import { resolveEngine } from "./use-engine";
+
+describe("resolveEngine", () => {
+  afterEach(() => {
+    // Reset global default by setting it to a known state
+    // We can't truly reset since there's no clearDefaultEngine, but tests
+    // run in order so we test the cascade explicitly
+  });
+
+  it("uses config engine when provided", () => {
+    const configEngine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+
+    expect(resolveEngine(configEngine)).toBe(configEngine);
+  });
+
+  it("falls back to RNP fallback when no config or global engine", () => {
+    // getDefaultEngine() returns null by default (no setDefaultEngine called yet in fresh module)
+    // But since we can't guarantee module state across tests, we test the cascade
+    const result = resolveEngine(undefined);
+    // Should either be the global default or the fallback
+    expect(result).toBeDefined();
+    expect(result.check).toBeDefined();
+    expect(result.request).toBeDefined();
+    expect(result.openSettings).toBeDefined();
+  });
+});
+
+describe("setDefaultEngine / getDefaultEngine", () => {
+  it("stores and retrieves a default engine", () => {
+    const engine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+
+    setDefaultEngine(engine);
+    expect(getDefaultEngine()).toBe(engine);
+  });
+
+  it("resolveEngine uses global default over fallback", () => {
+    const globalEngine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+
+    setDefaultEngine(globalEngine);
+    expect(resolveEngine(undefined)).toBe(globalEngine);
+  });
+
+  it("config engine takes priority over global default", () => {
+    const globalEngine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+    const configEngine: PermissionEngine = {
+      check: vi.fn(),
+      request: vi.fn(),
+      openSettings: vi.fn(),
+    };
+
+    setDefaultEngine(globalEngine);
+    expect(resolveEngine(configEngine)).toBe(configEngine);
+  });
+});

package/src/engines/resolve.ts

@@ -0,0 +1,11 @@
+import type { PermissionEngine } from "../types";
+
+let defaultEngine: PermissionEngine | null = null;
+
+export function setDefaultEngine(engine: PermissionEngine): void {
+  defaultEngine = engine;
+}
+
+export function getDefaultEngine(): PermissionEngine | null {
+  return defaultEngine;
+}

package/src/engines/rnp-fallback.ts

@@ -0,0 +1,23 @@
+import type { PermissionEngine } from "../types";
+
+let cachedFallback: PermissionEngine | null = null;
+
+export function getRNPFallbackEngine(): PermissionEngine {
+  if (cachedFallback) return cachedFallback;
+
+  try {
+    // Dynamic require to avoid hard dependency — only resolves if
+    // react-native-permissions is installed by the consumer.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require("./rnp") as { createRNPEngine: () => PermissionEngine };
+    const { createRNPEngine } = mod;
+    cachedFallback = createRNPEngine();
+    return cachedFallback;
+  } catch {
+    throw new Error(
+      "react-native-permission-handler: No permission engine configured. " +
+        "Either pass an `engine` in your hook config, call setDefaultEngine(), " +
+        "or install react-native-permissions as a peer dependency.",
+    );
+  }
+}

package/src/engines/rnp.test.ts

@@ -0,0 +1,96 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("react-native-permissions", () => ({
+  check: vi.fn(),
+  request: vi.fn(),
+  openSettings: vi.fn(),
+  checkNotifications: vi.fn(),
+  requestNotifications: vi.fn(),
+}));
+
+import {
+  check,
+  checkNotifications,
+  openSettings,
+  request,
+  requestNotifications,
+} from "react-native-permissions";
+import { createRNPEngine } from "./rnp";
+
+describe("createRNPEngine", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("check", () => {
+    it("delegates to check() for regular permissions", async () => {
+      vi.mocked(check).mockResolvedValue("granted");
+      const engine = createRNPEngine();
+
+      const result = await engine.check("ios.permission.CAMERA");
+
+      expect(check).toHaveBeenCalledWith("ios.permission.CAMERA");
+      expect(result).toBe("granted");
+    });
+
+    it("delegates to checkNotifications() for 'notifications'", async () => {
+      vi.mocked(checkNotifications).mockResolvedValue({
+        status: "denied",
+        settings: {},
+      });
+      const engine = createRNPEngine();
+
+      const result = await engine.check("notifications");
+
+      expect(checkNotifications).toHaveBeenCalled();
+      expect(check).not.toHaveBeenCalled();
+      expect(result).toBe("denied");
+    });
+
+    it("returns all status values correctly", async () => {
+      const engine = createRNPEngine();
+
+      for (const status of ["granted", "denied", "blocked", "limited", "unavailable"] as const) {
+        vi.mocked(check).mockResolvedValue(status);
+        expect(await engine.check("some.permission")).toBe(status);
+      }
+    });
+  });
+
+  describe("request", () => {
+    it("delegates to request() for regular permissions", async () => {
+      vi.mocked(request).mockResolvedValue("granted");
+      const engine = createRNPEngine();
+
+      const result = await engine.request("ios.permission.CAMERA");
+
+      expect(request).toHaveBeenCalledWith("ios.permission.CAMERA");
+      expect(result).toBe("granted");
+    });
+
+    it("delegates to requestNotifications() for 'notifications'", async () => {
+      vi.mocked(requestNotifications).mockResolvedValue({
+        status: "granted",
+        settings: {},
+      });
+      const engine = createRNPEngine();
+
+      const result = await engine.request("notifications");
+
+      expect(requestNotifications).toHaveBeenCalledWith(["alert", "badge", "sound"]);
+      expect(request).not.toHaveBeenCalled();
+      expect(result).toBe("granted");
+    });
+  });
+
+  describe("openSettings", () => {
+    it("delegates to openSettings()", async () => {
+      vi.mocked(openSettings).mockResolvedValue(undefined as never);
+      const engine = createRNPEngine();
+
+      await engine.openSettings();
+
+      expect(openSettings).toHaveBeenCalled();
+    });
+  });
+});

package/src/engines/rnp.ts

@@ -0,0 +1,33 @@
+import {
+  type Permission,
+  check,
+  checkNotifications,
+  openSettings,
+  request,
+  requestNotifications,
+} from "react-native-permissions";
+import type { PermissionEngine, PermissionStatus } from "../types";
+
+export function createRNPEngine(): PermissionEngine {
+  return {
+    async check(permission: string): Promise<PermissionStatus> {
+      if (permission === "notifications") {
+        const result = await checkNotifications();
+        return result.status as PermissionStatus;
+      }
+      return (await check(permission as Permission)) as PermissionStatus;
+    },
+
+    async request(permission: string): Promise<PermissionStatus> {
+      if (permission === "notifications") {
+        const result = await requestNotifications(["alert", "badge", "sound"]);
+        return result.status as PermissionStatus;
+      }
+      return (await request(permission as Permission)) as PermissionStatus;
+    },
+
+    async openSettings(): Promise<void> {
+      await openSettings();
+    },
+  };
+}

package/src/engines/use-engine.ts

@@ -0,0 +1,10 @@
+import type { PermissionEngine } from "../types";
+import { getDefaultEngine } from "./resolve";
+import { getRNPFallbackEngine } from "./rnp-fallback";
+
+export function resolveEngine(configEngine?: PermissionEngine): PermissionEngine {
+  if (configEngine) return configEngine;
+  const global = getDefaultEngine();
+  if (global) return global;
+  return getRNPFallbackEngine();
+}

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

@@ -1,7 +1,11 @@
 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";
+import type {
+  MultiplePermissionsConfig,
+  MultiplePermissionsResult,
+  PermissionEngine,
+} from "../types";
 
 vi.mock("react-native", () => ({
   AppState: {
@@ -10,17 +14,24 @@ vi.mock("react-native", () => ({
   },
 }));
 
-vi.mock("react-native-permissions", () => ({
-  check: vi.fn(),
-  request: vi.fn(),
-  openSettings: vi.fn(),
-  checkNotifications: vi.fn(),
-  requestNotifications: vi.fn(),
+// Mock the RNP fallback so hooks don't try to require react-native-permissions
+vi.mock("../engines/rnp-fallback", () => ({
+  getRNPFallbackEngine: vi.fn(() => {
+    throw new Error("No engine configured");
+  }),
 }));
 
-import { check, request } from "react-native-permissions";
 import { useMultiplePermissions } from "./use-multiple-permissions";
 
+function createMockEngine(overrides?: Partial<PermissionEngine>): PermissionEngine {
+  return {
+    check: vi.fn().mockResolvedValue("granted"),
+    request: vi.fn().mockResolvedValue("granted"),
+    openSettings: vi.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
 function renderHook(hookFn: () => MultiplePermissionsResult) {
   const results: { current: MultiplePermissionsResult } = {} as {
     current: MultiplePermissionsResult;
@@ -39,41 +50,58 @@ function renderHook(hookFn: () => MultiplePermissionsResult) {
   };
 }
 
-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", () => {
+  let engine: PermissionEngine;
+
+  const baseConfig = (
+    overrides?: Partial<MultiplePermissionsConfig>,
+  ): MultiplePermissionsConfig => ({
+    permissions: [
+      {
+        permission: "camera",
+        prePrompt: { title: "Camera", message: "Need camera" },
+        blockedPrompt: { title: "Blocked", message: "Camera blocked" },
+      },
+      {
+        permission: "microphone",
+        prePrompt: { title: "Mic", message: "Need mic" },
+        blockedPrompt: { title: "Blocked", message: "Mic blocked" },
+      },
+    ],
+    strategy: "sequential",
+    engine,
+    ...overrides,
+  });
+
   beforeEach(() => {
     vi.clearAllMocks();
+    engine = createMockEngine();
   });
 
-  it("initializes all permissions as idle", () => {
-    const { result } = renderHook(() => useMultiplePermissions(baseConfig));
+  it("initializes all permissions as idle when autoCheck is false", () => {
+    const { result } = renderHook(() => useMultiplePermissions(baseConfig({ autoCheck: false })));
 
     expect(result.current.allGranted).toBe(false);
     expect(Object.values(result.current.statuses)).toEqual(["idle", "idle"]);
   });
 
+  it("auto-checks all permissions on mount", async () => {
+    vi.mocked(engine.check).mockResolvedValueOnce("granted").mockResolvedValueOnce("denied");
+
+    const { result } = renderHook(() => useMultiplePermissions(baseConfig()));
+
+    await act(async () => {});
+
+    expect(engine.check).toHaveBeenCalledTimes(2);
+    expect(result.current.statuses.camera).toBe("granted");
+    expect(result.current.statuses.microphone).toBe("prePrompt");
+  });
+
   it("grants all permissions sequentially when already granted", async () => {
-    vi.mocked(check).mockResolvedValue("granted");
+    vi.mocked(engine.check).mockResolvedValue("granted");
     const onAllGranted = vi.fn();
 
-    const { result } = renderHook(() => useMultiplePermissions({ ...baseConfig, onAllGranted }));
+    const { result } = renderHook(() => useMultiplePermissions(baseConfig({ onAllGranted })));
 
     await act(async () => {
       await result.current.request();
@@ -84,52 +112,65 @@ describe("useMultiplePermissions", () => {
   });
 
   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
+    // Auto-check on mount returns denied for both, then requestAll flow
+    // checks again (denied), requests (granted), and final re-checks (granted)
+    vi.mocked(engine.check)
+      .mockResolvedValueOnce("denied") // auto-check: camera
+      .mockResolvedValueOnce("denied") // auto-check: mic
+      .mockResolvedValueOnce("denied") // requestAll: camera check
+      .mockResolvedValueOnce("denied") // requestAll: mic check
       .mockResolvedValue("granted"); // final re-checks
-    vi.mocked(request).mockResolvedValue("granted");
+    vi.mocked(engine.request).mockResolvedValue("granted");
     const onAllGranted = vi.fn();
 
-    const { result } = renderHook(() => useMultiplePermissions({ ...baseConfig, onAllGranted }));
+    const { result } = renderHook(() => useMultiplePermissions(baseConfig({ onAllGranted })));
 
+    await act(async () => {});
     await act(async () => {
       await result.current.request();
     });
 
     expect(result.current.allGranted).toBe(true);
-    expect(request).toHaveBeenCalledTimes(2);
+    expect(engine.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");
+    vi.mocked(engine.check).mockResolvedValue("denied");
+    vi.mocked(engine.request).mockResolvedValueOnce("denied");
 
-    const { result } = renderHook(() => useMultiplePermissions(baseConfig));
+    const { result } = renderHook(() => useMultiplePermissions(baseConfig()));
 
     await act(async () => {
       await result.current.request();
     });
 
     expect(result.current.allGranted).toBe(false);
-    expect(request).toHaveBeenCalledTimes(1);
+    expect(engine.request).toHaveBeenCalledTimes(1);
   });
 
   it("fires per-permission callbacks", async () => {
-    vi.mocked(check).mockResolvedValue("denied");
-    vi.mocked(request).mockResolvedValueOnce("granted").mockResolvedValueOnce("denied");
+    vi.mocked(engine.check).mockResolvedValue("denied");
+    vi.mocked(engine.request).mockResolvedValueOnce("granted").mockResolvedValueOnce("denied");
     const onGrant = vi.fn();
     const onDeny = vi.fn();
 
-    const config: MultiplePermissionsConfig = {
-      ...baseConfig,
+    const config = baseConfig({
       permissions: [
-        { ...baseConfig.permissions[0], onGrant },
-        { ...baseConfig.permissions[1], onDeny },
+        {
+          permission: "camera",
+          prePrompt: { title: "Camera", message: "Need camera" },
+          blockedPrompt: { title: "Blocked", message: "Camera blocked" },
+          onGrant,
+        },
+        {
+          permission: "microphone",
+          prePrompt: { title: "Mic", message: "Need mic" },
+          blockedPrompt: { title: "Blocked", message: "Mic blocked" },
+          onDeny,
+        },
       ],
-    };
+    });
 
     const { result } = renderHook(() => useMultiplePermissions(config));
 
@@ -142,18 +183,17 @@ describe("useMultiplePermissions", () => {
   });
 
   it("handles parallel strategy — checks all, then requests denied", async () => {
-    vi.mocked(check)
+    vi.mocked(engine.check)
       .mockResolvedValueOnce("granted") // camera already granted
       .mockResolvedValueOnce("denied") // mic needs request
       .mockResolvedValue("granted"); // final re-checks
-    vi.mocked(request).mockResolvedValue("granted");
+    vi.mocked(engine.request).mockResolvedValue("granted");
     const onAllGranted = vi.fn();
 
-    const config: MultiplePermissionsConfig = {
-      ...baseConfig,
+    const config = baseConfig({
       strategy: "parallel",
       onAllGranted,
-    };
+    });
 
     const { result } = renderHook(() => useMultiplePermissions(config));
 
@@ -161,7 +201,7 @@ describe("useMultiplePermissions", () => {
       await result.current.request();
     });
 
-    expect(request).toHaveBeenCalledTimes(1); // only mic was requested
+    expect(engine.request).toHaveBeenCalledTimes(1); // only mic was requested
     expect(onAllGranted).toHaveBeenCalledOnce();
   });
 });

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

@@ -1,40 +1,14 @@
-import { useCallback, useRef, useState } from "react";
-import {
-  type PermissionStatus,
-  check,
-  checkNotifications,
-  request,
-  requestNotifications,
-} from "react-native-permissions";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { resolveEngine } from "../engines/use-engine";
 import type {
   MultiPermissionEntry,
   MultiplePermissionsConfig,
   MultiplePermissionsResult,
+  PermissionEngine,
   PermissionFlowState,
+  PermissionStatus,
 } 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);
 }
@@ -43,10 +17,27 @@ function isGrantedStatus(status: PermissionStatus): boolean {
   return status === "granted" || status === "limited";
 }
 
+function statusToFlowState(status: PermissionStatus): PermissionFlowState {
+  switch (status) {
+    case "granted":
+    case "limited":
+      return "granted";
+    case "blocked":
+      return "blockedPrompt";
+    case "unavailable":
+      return "unavailable";
+    case "denied":
+      return "prePrompt";
+    default:
+      return "idle";
+  }
+}
+
 export function useMultiplePermissions(
   config: MultiplePermissionsConfig,
 ): MultiplePermissionsResult {
-  const { permissions, strategy, onAllGranted } = config;
+  const engine = resolveEngine(config.engine);
+  const { permissions, strategy, autoCheck = true, onAllGranted } = config;
   const [statuses, setStatuses] = useState<Record<string, PermissionFlowState>>(() => {
     const initial: Record<string, PermissionFlowState> = {};
     for (const entry of permissions) {
@@ -68,15 +59,15 @@ export function useMultiplePermissions(
 
     try {
       if (strategy === "sequential") {
-        await runSequential(permissions, update);
+        await runSequential(permissions, engine, update);
       } else {
-        await runParallel(permissions, update);
+        await runParallel(permissions, engine, update);
       }
 
       // Final check: are all granted?
       let allDone = true;
       for (const entry of permissions) {
-        const finalStatus = await checkOne(entry);
+        const finalStatus = await engine.check(entry.permission);
         if (!isGrantedStatus(finalStatus)) {
           allDone = false;
           break;
@@ -88,7 +79,27 @@ export function useMultiplePermissions(
     } finally {
       isRunning.current = false;
     }
-  }, [permissions, strategy, onAllGranted]);
+  }, [permissions, strategy, engine, onAllGranted]);
+
+  // Auto-check on mount
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional mount-only effect
+  useEffect(() => {
+    if (!autoCheck) return;
+
+    let cancelled = false;
+    async function checkAll() {
+      for (const entry of permissions) {
+        const key = permissionKey(entry);
+        const status = await engine.check(entry.permission);
+        if (cancelled) return;
+        setStatuses((prev) => ({ ...prev, [key]: statusToFlowState(status) }));
+      }
+    }
+    checkAll();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
 
   return {
     statuses,
@@ -99,13 +110,14 @@ export function useMultiplePermissions(
 
 async function runSequential(
   permissions: MultiPermissionEntry[],
+  engine: PermissionEngine,
   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);
+    const checkStatus = await engine.check(entry.permission);
 
     if (isGrantedStatus(checkStatus)) {
       updateStatus(key, "granted");
@@ -126,7 +138,7 @@ async function runSequential(
 
     // Denied — request it
     updateStatus(key, "requesting");
-    const requestStatus = await requestOne(entry);
+    const requestStatus = await engine.request(entry.permission);
 
     if (isGrantedStatus(requestStatus)) {
       updateStatus(key, "granted");
@@ -145,6 +157,7 @@ async function runSequential(
 
 async function runParallel(
   permissions: MultiPermissionEntry[],
+  engine: PermissionEngine,
   updateStatus: (key: string, state: PermissionFlowState) => void,
 ): Promise<void> {
   // Check all in parallel
@@ -152,7 +165,7 @@ async function runParallel(
     permissions.map(async (entry) => {
       const key = permissionKey(entry);
       updateStatus(key, "checking");
-      const status = await checkOne(entry);
+      const status = await engine.check(entry.permission);
       return { entry, key, status };
     }),
   );
@@ -180,7 +193,7 @@ async function runParallel(
     }
 
     updateStatus(key, "requesting");
-    const requestStatus = await requestOne(entry);
+    const requestStatus = await engine.request(entry.permission);
 
     if (isGrantedStatus(requestStatus)) {
       updateStatus(key, "granted");