@minip2p/react-native 0.1.1 → 0.3.1

package/src/hook-lifecycle.ts

@@ -0,0 +1,152 @@
+/* oxlint-disable promise/prefer-await-to-callbacks -- This module coordinates synchronous lifecycle callbacks. */
+
+import { ClosedError } from "@minip2p/core";
+import type { CloseReason, Unsubscribe } from "@minip2p/core";
+
+export interface HookEndpoint {
+  close: () => void;
+  listenAddrs: () => readonly string[];
+  onClose: (handler: (reason: CloseReason) => void) => Unsubscribe;
+  peerId: () => string;
+  setActive: (active: boolean) => void;
+}
+
+export interface AppStateSource {
+  readonly currentState: string | null | undefined;
+  addEventListener: (
+    type: "change",
+    handler: (state: string) => void
+  ) => { remove: () => void };
+}
+
+/** @internal */
+export const bindAppStateSource = (
+  endpoint: Pick<HookEndpoint, "setActive">,
+  source: AppStateSource
+): Unsubscribe => {
+  let active = true;
+  try {
+    endpoint.setActive(source.currentState === "active");
+  } catch (error) {
+    if (error instanceof ClosedError) {
+      return () => {
+        active = false;
+      };
+    }
+    throw error;
+  }
+  const subscription = source.addEventListener("change", (state) => {
+    if (!active) {
+      return;
+    }
+    try {
+      endpoint.setActive(state === "active");
+    } catch (error) {
+      if (!(error instanceof ClosedError)) {
+        throw error;
+      }
+      active = false;
+      subscription.remove();
+    }
+  });
+  return () => {
+    active = false;
+    subscription.remove();
+  };
+};
+
+export type LifecycleState<Endpoint extends HookEndpoint> =
+  | {
+      readonly status: "running";
+      readonly endpoint: Endpoint;
+      readonly peerId: string;
+      readonly listenAddrs: readonly string[];
+    }
+  | { readonly status: "closed" }
+  | { readonly status: "failed"; readonly error: unknown };
+
+/** @internal */
+export const mountEndpointLifecycle = <Endpoint extends HookEndpoint>(options: {
+  readonly bindAppState: (endpoint: Endpoint) => Unsubscribe;
+  readonly create: () => Endpoint;
+  readonly notify: (state: LifecycleState<Endpoint>) => void;
+  readonly schedule?: (callback: () => void) => void;
+}): { readonly close: () => void; readonly cleanup: () => void } => {
+  const schedule = options.schedule ?? ((callback) => setTimeout(callback, 0));
+  let active = true;
+  let generation = 0;
+  let endpoint: Endpoint | undefined;
+  let removeClose: Unsubscribe | undefined;
+  let removeAppState: Unsubscribe | undefined;
+
+  try {
+    const created = options.create();
+    endpoint = created;
+    removeClose = created.onClose((reason) => {
+      if (!active) {
+        return;
+      }
+      generation += 1;
+      removeAppState?.();
+      removeAppState = undefined;
+      endpoint = undefined;
+      options.notify(
+        reason.reason === "driverFailed"
+          ? { error: reason.error, status: "failed" }
+          : { status: "closed" }
+      );
+    });
+    const unbindAppState = options.bindAppState(created);
+    if (endpoint === created) {
+      removeAppState = unbindAppState;
+    } else {
+      unbindAppState();
+    }
+    const running = {
+      endpoint: created,
+      listenAddrs: created.listenAddrs(),
+      peerId: created.peerId(),
+      status: "running" as const,
+    };
+    const scheduledGeneration = generation;
+    schedule(() => {
+      if (
+        active &&
+        generation === scheduledGeneration &&
+        endpoint === created
+      ) {
+        options.notify(running);
+      }
+    });
+  } catch (error) {
+    removeClose?.();
+    removeClose = undefined;
+    removeAppState?.();
+    removeAppState = undefined;
+    endpoint?.close();
+    endpoint = undefined;
+    const scheduledGeneration = generation;
+    schedule(() => {
+      if (active && generation === scheduledGeneration) {
+        options.notify({ error, status: "failed" });
+      }
+    });
+  }
+
+  return {
+    cleanup: () => {
+      active = false;
+      generation += 1;
+      removeClose?.();
+      removeClose = undefined;
+      removeAppState?.();
+      removeAppState = undefined;
+      const current = endpoint;
+      endpoint = undefined;
+      current?.close();
+    },
+    close: () => {
+      endpoint?.close();
+    },
+  };
+};

package/src/hooks.ts

@@ -0,0 +1,102 @@
+import type {
+  DriverFailedError,
+  Minip2pConfig,
+  Unsubscribe,
+} from "@minip2p/core";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { AppState } from "react-native";
+
+import { Minip2p } from "./adapter";
+import { bindAppStateSource, mountEndpointLifecycle } from "./hook-lifecycle";
+
+/** Lifecycle state returned by {@link useMinip2p}. */
+export type Minip2pHookState =
+  | {
+      readonly status: "starting";
+      readonly endpoint?: undefined;
+      readonly peerId?: undefined;
+      readonly listenAddrs?: undefined;
+      readonly error?: undefined;
+    }
+  | {
+      readonly status: "running";
+      readonly endpoint: Minip2p;
+      readonly peerId: string;
+      readonly listenAddrs: readonly string[];
+      readonly error?: undefined;
+    }
+  | {
+      readonly status: "closed";
+      readonly endpoint?: undefined;
+      readonly peerId?: undefined;
+      readonly listenAddrs?: undefined;
+      readonly error?: undefined;
+    }
+  | {
+      readonly status: "failed";
+      readonly endpoint?: undefined;
+      readonly peerId?: undefined;
+      readonly listenAddrs?: undefined;
+      readonly error: unknown;
+    };
+
+/** Hook lifecycle state plus an idempotent endpoint shutdown callback. */
+export type UseMinip2pResult = Minip2pHookState & {
+  /** Closes the currently owned endpoint, if one exists. */
+  readonly close: () => void;
+};
+
+/** Mirrors the current and future React Native AppState into an endpoint. */
+export const bindAppState = (
+  endpoint: Pick<Minip2p, "setActive">
+): Unsubscribe => bindAppStateSource(endpoint, AppState);
+
+/**
+ * Owns a native endpoint for a committed component lifetime.
+ *
+ * Keep `createConfig` pure and stable for the component lifetime. Endpoint
+ * construction happens only in the committed effect.
+ */
+export const useMinip2p = (
+  createConfig: () => Minip2pConfig
+): UseMinip2pResult => {
+  const endpointRef = useRef<Minip2p | null>(null);
+  const configFactory = useRef(createConfig);
+  const [state, setState] = useState<Minip2pHookState>({
+    status: "starting",
+  });
+  const close = useCallback(() => {
+    endpointRef.current?.close();
+  }, []);
+
+  useEffect(() => {
+    const lifecycle = mountEndpointLifecycle({
+      bindAppState,
+      create: () => {
+        const endpoint = Minip2p.create(configFactory.current());
+        endpointRef.current = endpoint;
+        return endpoint;
+      },
+      notify: (next) => {
+        endpointRef.current = next.status === "running" ? next.endpoint : null;
+        setState(next);
+      },
+    });
+    return () => {
+      endpointRef.current = null;
+      lifecycle.cleanup();
+    };
+  }, []);
+
+  return { ...state, close };
+};
+
+/** Narrows the failed hook state for consumers that want a native failure. */
+export const isDriverFailure = (
+  state: Minip2pHookState
+): state is Extract<Minip2pHookState, { status: "failed" }> & {
+  error: DriverFailedError;
+} =>
+  state.status === "failed" &&
+  state.error instanceof Error &&
+  state.error.name === "DriverFailedError";

package/src/index.ts

@@ -1,7 +1,14 @@
 export * from "@minip2p/core";
 export {
-  MiniP2p,
+  Minip2p,
   circuitAddress,
   generateSecretKey,
   peerIdFromSecretKey,
 } from "./adapter";
+export {
+  bindAppState,
+  isDriverFailure,
+  useMinip2p,
+  type Minip2pHookState,
+  type UseMinip2pResult,
+} from "./hooks";