@webview-bridge/react-native 1.7.0-rc.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webview-bridge/react-native",
-  "version": "1.7.0-rc.0",
+  "version": "1.7.0",
   "type": "module",
   "description": "Fully Type-Safe Integration for React Native WebView and Web",
   "main": "dist/index.js",
@@ -24,6 +24,7 @@
   "license": "MIT",
   "files": [
     "dist",
+    "src",
     "package.json"
   ],
   "devDependencies": {
@@ -38,8 +39,8 @@
     "react-native-webview": "*"
   },
   "dependencies": {
-    "@webview-bridge/utils": "1.7.0-rc.0",
-    "@webview-bridge/types": "1.7.0-rc.0",
+    "@webview-bridge/utils": "1.7.0",
+    "@webview-bridge/types": "1.7.0",
     "use-sync-external-store": "^1.2.0"
   },
   "scripts": {

package/src/createWebView.tsx

@@ -0,0 +1,346 @@
+import type {
+  Bridge,
+  BridgeStore,
+  KeyOfOrString,
+  Parser,
+  ParserSchema,
+  Primitive,
+} from "@webview-bridge/types";
+import { createEvents } from "@webview-bridge/utils";
+import React, {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from "react";
+import type { WebViewMessageEvent, WebViewProps } from "react-native-webview";
+import WebView from "react-native-webview";
+
+import {
+  handleBridge,
+  INJECT_BRIDGE_METHODS,
+  INJECT_BRIDGE_STATE,
+  SAFE_NATIVE_EMITTER_EMIT,
+} from "./integrations/bridge";
+import { handleLog, INJECT_DEBUG, LogType } from "./integrations/console";
+import { handleRegisterWebMethod } from "./integrations/handleRegisterWebMethod";
+import type { BridgeWebView } from "./types/webview";
+
+export type CreateWebViewArgs<
+  BridgeObject extends Bridge,
+  PostMessageSchema extends ParserSchema<any>,
+> = {
+  /**
+   * The bridge object to be used in the WebView.
+  * @example
+    import { createWebView, bridge } from "@webview-bridge/react-native";
+    import InAppBrowser from "react-native-inappbrowser-reborn";
+
+    // Register functions in the bridge object in your React Native code
+    export const appBridge = bridge({
+      async getMessage() {
+        return "Hello, I'm native";
+      },
+      async sum(a: number, b: number) {
+        return a + b;
+      },
+      async openInAppBrowser(url: string) {
+        if (await InAppBrowser.isAvailable()) {
+          await InAppBrowser.open(url);
+        }
+      },
+      // ... Add more functions as needed
+    });
+
+    export const { WebView } = createWebView({
+      bridge: appBridge,
+      debug: true, // Enable console.log visibility in the native WebView
+    });
+    */
+  bridge: BridgeStore<BridgeObject>;
+  /**
+   * If `true`, the console.log visibility in the WebView is enabled.
+   * @default false
+   */
+  debug?: boolean;
+  /**
+   * Set the timeout in milliseconds for the response from the web method.
+   * @default 2000
+   */
+  responseTimeout?: number;
+  /**
+   * The schema for the postMessage method.
+   * @link https://gronxb.github.io/webview-bridge/using-a-post-message.html
+   */
+  postMessageSchema?: PostMessageSchema;
+  /**
+   * Callback function when a method that is not defined in the bridge is called.
+   * @link https://gronxb.github.io/webview-bridge/backward-compatibility/new-method.html#react-native-part
+   */
+  fallback?: (method: keyof BridgeObject) => void;
+};
+
+export type WebMethod<T> = T & {
+  isReady: boolean;
+};
+
+/**
+ * Create a WebView component that can communicate with the bridge.
+ * @link https://gronxb.github.io/webview-bridge/getting-started.html
+ * @example
+    import { createWebView, bridge } from "@webview-bridge/react-native";
+    import InAppBrowser from "react-native-inappbrowser-reborn";
+
+    // Register functions in the bridge object in your React Native code
+    export const appBridge = bridge({
+      async getMessage() {
+        return "Hello, I'm native";
+      },
+      async sum(a: number, b: number) {
+        return a + b;
+      },
+      async openInAppBrowser(url: string) {
+        if (await InAppBrowser.isAvailable()) {
+          await InAppBrowser.open(url);
+        }
+      },
+      // ... Add more functions as needed
+    });
+
+    export const { WebView } = createWebView({
+      bridge: appBridge,
+      debug: true, // Enable console.log visibility in the native WebView
+    });
+ */
+export const createWebView = <
+  BridgeObject extends Bridge,
+  PostMessageSchema extends ParserSchema<any>,
+>({
+  bridge,
+  debug,
+  responseTimeout = 2000,
+  postMessageSchema,
+  fallback,
+}: CreateWebViewArgs<BridgeObject, PostMessageSchema>) => {
+  const WebMethod = {
+    current: {
+      isReady: false,
+    },
+  };
+
+  const webviewRefList: React.RefObject<BridgeWebView>[] = [];
+  const emitter = createEvents();
+
+  bridge.subscribe((state) => {
+    for (const ref of webviewRefList) {
+      ref?.current?.injectJavaScript(
+        SAFE_NATIVE_EMITTER_EMIT("bridgeStateChange", state),
+      );
+    }
+  });
+
+  return {
+    /**
+     * Sends an event from React Native to the Web.
+     * @link https://gronxb.github.io/webview-bridge/using-a-post-message.html
+     */
+    postMessage: <
+      EventName extends KeyOfOrString<PostMessageSchema>,
+      Args extends Parser<PostMessageSchema, EventName>,
+    >(
+      eventName: EventName,
+      args: Args,
+    ) => {
+      let _args: any = args;
+      if (postMessageSchema) {
+        _args = postMessageSchema[eventName].validate(args);
+      }
+
+      for (const ref of webviewRefList) {
+        ref?.current?.injectJavaScript(
+          SAFE_NATIVE_EMITTER_EMIT(`postMessage/${String(eventName)}`, _args),
+        );
+      }
+    },
+    WebView: forwardRef<BridgeWebView, WebViewProps>((props, ref) => {
+      const webviewRef = useRef<WebView>(null);
+
+      useLayoutEffect(() => {
+        webviewRefList.push(webviewRef);
+        return () => {
+          webviewRefList.pop();
+        };
+      }, []);
+
+      const initData = useMemo(() => {
+        const bridgeMethods = Object.entries(bridge.getState() ?? {})
+          .filter(([_, bridge]) => typeof bridge === "function")
+          .map(([name]) => name);
+        const initialState = Object.fromEntries(
+          Object.entries(bridge.getState() ?? {}).filter(
+            ([_, value]) => typeof value !== "function",
+          ),
+        ) as Record<string, Primitive>;
+        return { bridgeMethods, initialState };
+      }, []);
+
+      useEffect(() => {
+        webviewRef.current?.injectJavaScript(
+          SAFE_NATIVE_EMITTER_EMIT("hydrate", initData),
+        );
+      }, [initData]);
+
+      useImperativeHandle(ref, () => webviewRef.current as BridgeWebView, []);
+
+      const handleMessage = async (event: WebViewMessageEvent) => {
+        props.onMessage?.(event);
+
+        if (!webviewRef.current) {
+          return;
+        }
+        const { type, body } = JSON.parse(event.nativeEvent.data);
+
+        switch (type) {
+          case "log": {
+            const { method, args } = body as {
+              method: LogType;
+              args: string;
+            };
+            debug && handleLog(method, args);
+            return;
+          }
+          case "bridge": {
+            const { method, args, eventId } = body as {
+              method: string;
+              args: unknown[];
+              eventId: string;
+            };
+
+            handleBridge({
+              bridge,
+              method,
+              args,
+              eventId,
+              webview: webviewRef.current,
+            });
+            return;
+          }
+          case "getBridgeState": {
+            for (const ref of webviewRefList) {
+              ref?.current?.injectJavaScript(
+                SAFE_NATIVE_EMITTER_EMIT(
+                  "bridgeStateChange",
+                  bridge.getState(),
+                ),
+              );
+            }
+            return;
+          }
+          case "registerWebMethod": {
+            const { bridgeNames } = body as {
+              bridgeNames: string[];
+            };
+            Object.assign(
+              WebMethod.current,
+              handleRegisterWebMethod(
+                emitter,
+                webviewRef.current,
+                bridgeNames,
+                responseTimeout,
+              ),
+            );
+            WebMethod.current.isReady = true;
+            return;
+          }
+          case "webMethodResponse": {
+            const { eventId, funcName, value } = body as {
+              eventId: string;
+              funcName: string;
+              value: unknown;
+            };
+
+            emitter.emit(`${funcName}-${eventId}`, value);
+            return;
+          }
+          case "webMethodError": {
+            const { eventId, funcName } = body as {
+              eventId: string;
+              funcName: string;
+              value: unknown;
+            };
+
+            emitter.emit(`${funcName}-${eventId}`, {}, true);
+            return;
+          }
+          case "fallback": {
+            const { method } = body as {
+              method: keyof BridgeObject;
+            };
+            fallback?.(method);
+            return;
+          }
+        }
+      };
+
+      return (
+        <WebView
+          {...props}
+          ref={webviewRef}
+          onMessage={handleMessage}
+          injectedJavaScriptBeforeContentLoaded={[
+            INJECT_BRIDGE_METHODS(initData.bridgeMethods),
+            INJECT_BRIDGE_STATE(initData.initialState),
+            props.injectedJavaScriptBeforeContentLoaded,
+            "true;",
+          ]
+            .filter(Boolean)
+            .join("\n")}
+          injectedJavaScript={[
+            debug && INJECT_DEBUG,
+            props.injectedJavaScript,
+            "true;",
+          ]
+            .filter(Boolean)
+            .join("\n")}
+        />
+      );
+    }),
+    /**
+     * @deprecated Use `postMessage` instead.  And complete the type through the `postMessageSchema` option.
+     * @see https://gronxb.github.io/webview-bridge/using-a-post-message.html
+     * @example 
+      import { createWebView, postMessageSchema } from "@webview-bridge/react-native";
+      import { z } from "zod";
+
+      const appPostMessageSchema = postMessageSchema({
+        eventName1: z.object({
+          message: z.string(),
+        }),
+        eventName2: z.string(),
+      });
+
+
+      // Export the event schema to be used in the web application
+      export type AppPostMessageSchema = typeof appPostMessageSchema;
+
+      // When you bridge a webview, a postMessage is extracted.
+      export const { postMessage } = createWebView({
+        postMessageSchema: appPostMessageSchema, // Pass in the your schema. This is optional, so if the type doesn't matter to you, you don't need to include it.
+        // ..
+      });
+
+      // usage
+      postMessage("eventName1", {
+        message: "test",
+      });
+      postMessage("eventName2", "test");
+    */
+    linkWebMethod<T>() {
+      return WebMethod as {
+        current: WebMethod<T>;
+      };
+    },
+  };
+};

package/src/error.ts

@@ -0,0 +1,6 @@
+export class WebMethodError extends Error {
+  constructor(methodName: string) {
+    super(`An error occurred in the WebMethod.current.${methodName}`);
+    this.name = "WebMethodError";
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./createWebView";
+export * from "./integrations/bridge";
+export * from "./integrations/postMessageSchema";
+export * from "./types/webview";
+export * from "./useBridge";
+export type * from "@webview-bridge/types";

package/src/integrations/bridge.ts

@@ -0,0 +1,138 @@
+import type {
+  Bridge,
+  BridgeStore,
+  OnlyJSON,
+  Primitive,
+} from "@webview-bridge/types";
+import { equals, removeUndefinedKeys } from "@webview-bridge/utils";
+import WebView from "react-native-webview";
+
+export type StoreCallback<T> = ({
+  get,
+  set,
+}: {
+  get: () => T;
+  set: (newState: Partial<OnlyJSON<T>>) => void;
+}) => T;
+
+export const bridge = <T extends Bridge>(
+  procedures: T | StoreCallback<T>,
+): BridgeStore<T> => {
+  const getState = () => state;
+
+  const setState = (newState: Partial<OnlyJSON<T>>) => {
+    const _newState = {
+      ...state,
+      ...removeUndefinedKeys(newState),
+    };
+
+    if (equals(state, _newState)) {
+      return;
+    }
+
+    const prevState = state;
+    state = _newState;
+    emitChange(state, prevState);
+  };
+
+  let state: T =
+    typeof procedures === "function"
+      ? procedures({
+          get: getState,
+          set: setState,
+        })
+      : procedures;
+
+  const listeners = new Set<(newState: T, prevState: T) => void>();
+
+  const emitChange = (newState: T, prevState: T) => {
+    for (const listener of listeners) {
+      listener(newState, prevState);
+    }
+  };
+
+  const subscribe = (listener: (newState: T, prevState: T) => void) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+
+  return {
+    getState,
+    setState,
+    subscribe,
+  } as BridgeStore<T>;
+};
+
+type HandleBridgeArgs<ArgType = unknown> = {
+  bridge: BridgeStore<Bridge>;
+  method: string;
+  args?: ArgType[];
+  webview: WebView;
+  eventId: string;
+};
+
+export const handleBridge = async ({
+  bridge,
+  method,
+  args,
+  webview,
+  eventId,
+}: HandleBridgeArgs) => {
+  const _bridge = bridge.getState();
+
+  const _method = _bridge[method];
+  const handleThrow = () => {
+    webview.injectJavaScript(SAFE_NATIVE_EMITTER_THROW(`${method}-${eventId}`));
+  };
+  if (!(method in _bridge)) {
+    handleThrow();
+    return;
+  }
+  if (typeof _method !== "function") {
+    return;
+  }
+
+  try {
+    const response = await _method?.(...(args ?? []));
+
+    webview.injectJavaScript(
+      SAFE_NATIVE_EMITTER_EMIT(`${method}-${eventId}`, response),
+    );
+  } catch (error) {
+    handleThrow();
+    console.error(error);
+  }
+};
+
+export const INJECT_BRIDGE_METHODS = (bridgeNames: string[]) => `
+    window.__bridgeMethods__ = ${JSON.stringify(bridgeNames)};
+`;
+
+export const INJECT_BRIDGE_STATE = (
+  initialState: Record<string, Primitive>,
+) => `
+    window.__bridgeInitialState__ = ${JSON.stringify(initialState)};
+`;
+
+export const SAFE_NATIVE_EMITTER_EMIT = (eventName: string, data: unknown) => {
+  const dataString = JSON.stringify(data);
+  return `
+if (window.nativeEmitter) {
+  window.nativeEmitter.emit('${eventName}', ${dataString});
+} else {
+  window.nativeBatchedEvents = window.nativeBatchedEvents || [];
+  window.nativeBatchedEvents.push(['${eventName}', ${dataString}]);
+}
+true;
+`;
+};
+
+export const SAFE_NATIVE_EMITTER_THROW = (eventName: string) => `
+if (window.nativeEmitter) {
+  window.nativeEmitter.emit('${eventName}', {}, true);
+} else {
+  window.nativeBatchedEvents = window.nativeBatchedEvents || [];
+  window.nativeBatchedEvents.push(['${eventName}', {}, true]);
+}
+true;
+`;

package/src/integrations/console.ts

@@ -0,0 +1,57 @@
+export const INJECT_DEBUG = `
+{
+  const originalConsoleLog = console.log;
+  const originalConsoleError = console.error;
+  const originalConsoleWarn = console.warn;
+
+  console.log = function() {
+    var message = JSON.stringify(Array.from(arguments));
+    window.ReactNativeWebView?.postMessage(
+      JSON.stringify({ type: "log", body: { method: "log", args: message } }),
+    );
+    originalConsoleLog.apply(console, arguments);
+  };
+
+  console.error = function() {
+    var message = JSON.stringify(Array.from(arguments));
+    window.ReactNativeWebView?.postMessage(
+      JSON.stringify({ type: "log", body: { method: "error", args: message } }),
+    );
+    originalConsoleError.apply(console, arguments);
+  };
+
+  console.warn = function() {
+    var message = JSON.stringify(Array.from(arguments));
+    window.ReactNativeWebView?.postMessage(
+      JSON.stringify({ type: "log", body: { method: "warn", args: message } }),
+    );
+    originalConsoleWarn.apply(console, arguments);
+  };
+};
+`;
+
+export type LogType = "log" | "error" | "warn";
+
+export const handleLog = (type: LogType, message: string) => {
+  const [formatMessage, ...parsedMessage] = JSON.parse(message);
+  const webviewMark = "(WebView) ";
+
+  const webviewMarkedMessage =
+    typeof formatMessage === "string"
+      ? [webviewMark + formatMessage, ...parsedMessage]
+      : [webviewMark, formatMessage, ...parsedMessage];
+  switch (type) {
+    case "log": {
+      console.log(...webviewMarkedMessage);
+      break;
+    }
+    case "error": {
+      console.error(...webviewMarkedMessage);
+      break;
+    }
+    case "warn": {
+      console.warn(...webviewMarkedMessage);
+      break;
+    }
+  }
+};

package/src/integrations/handleRegisterWebMethod.ts

@@ -0,0 +1,46 @@
+import type { Bridge } from "@webview-bridge/types";
+import {
+  createRandomId,
+  createResolver,
+  type EventEmitter,
+  timeout,
+} from "@webview-bridge/utils";
+import WebView from "react-native-webview";
+
+import { WebMethodError } from "../error";
+
+export const handleRegisterWebMethod = (
+  emitter: EventEmitter,
+  webview: WebView,
+  bridgeNames: string[],
+  responseTimeout: number,
+) => {
+  return bridgeNames.reduce((acc, methodName) => {
+    acc[methodName] = async (...args: unknown[]) => {
+      const eventId = createRandomId();
+
+      return Promise.race([
+        createResolver({
+          emitter,
+          methodName,
+          eventId,
+          evaluate: () => {
+            webview.injectJavaScript(
+              `
+              window.webEmitter.emit('${methodName}', '${eventId}', ${JSON.stringify(
+                args,
+              )});
+            
+              true;
+              `,
+            );
+          },
+          failHandler: new WebMethodError(methodName),
+        }),
+        timeout(responseTimeout),
+      ]);
+    };
+
+    return acc;
+  }, {} as Bridge);
+};

package/src/integrations/postMessageSchema.ts

@@ -0,0 +1,8 @@
+import type { PostMessageSchemaObject } from "@webview-bridge/types";
+
+export const postMessageSchema = <T extends PostMessageSchemaObject>(
+  schema: T,
+) => {
+  // Returning immediately to infer the correct type.
+  return schema;
+};

package/src/types/webview.ts

@@ -0,0 +1,7 @@
+import { Component } from "react";
+import WebView, { WebViewProps } from "react-native-webview";
+
+export type BridgeWebView = Pick<
+  WebView,
+  Exclude<keyof WebView, keyof Component<WebViewProps>>
+>;

package/src/useBridge.ts

@@ -0,0 +1,26 @@
+import type { Bridge, BridgeStore, ExtractStore } from "@webview-bridge/types";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/with-selector.js";
+
+export function useBridge<T extends Bridge>(
+  store: BridgeStore<T>,
+): ExtractStore<BridgeStore<T>>;
+
+export function useBridge<
+  T extends Bridge,
+  U extends ExtractStore<BridgeStore<T>>,
+  V,
+>(store: BridgeStore<T>, selector?: (state: U) => V): V;
+
+export function useBridge<T extends Bridge, U>(
+  store: BridgeStore<T>,
+  selector?: (state: T) => U,
+): U {
+  const $selector = selector ?? ((state: T) => state as unknown as U);
+
+  return useSyncExternalStoreWithSelector(
+    store.subscribe,
+    store.getState,
+    store.getState,
+    $selector,
+  );
+}