@hot-updater/react-native 0.30.7 → 0.30.9

package/src/index.spec.ts

@@ -0,0 +1,170 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  addListener: vi.fn(() => () => {}),
+  checkForUpdate: vi.fn(),
+  clearCrashHistory: vi.fn(() => true),
+  createDefaultResolver: vi.fn(),
+  getAppVersion: vi.fn(() => "1.0.0"),
+  getBaseURL: vi.fn(() => null),
+  getBundleId: vi.fn(() => "bundle-id"),
+  getChannel: vi.fn(() => "production"),
+  getCohort: vi.fn(() => "123"),
+  getCrashHistory: vi.fn(() => []),
+  getDefaultChannel: vi.fn(() => "production"),
+  getFingerprintHash: vi.fn(() => null),
+  getManifest: vi.fn(() => null),
+  getMinBundleId: vi.fn(() => "min-bundle-id"),
+  init: vi.fn(),
+  isChannelSwitched: vi.fn(() => false),
+  reload: vi.fn(),
+  resetChannel: vi.fn(),
+  setCohort: vi.fn(),
+  setReloadBehavior: vi.fn(),
+  updateBundle: vi.fn(),
+  wrap: vi.fn(),
+}));
+
+vi.mock("./DefaultResolver", () => ({
+  createDefaultResolver: mocks.createDefaultResolver,
+}));
+
+vi.mock("./checkForUpdate", () => ({
+  checkForUpdate: mocks.checkForUpdate,
+}));
+
+vi.mock("./native", () => ({
+  addListener: mocks.addListener,
+  clearCrashHistory: mocks.clearCrashHistory,
+  getAppVersion: mocks.getAppVersion,
+  getBaseURL: mocks.getBaseURL,
+  getBundleId: mocks.getBundleId,
+  getChannel: mocks.getChannel,
+  getCohort: mocks.getCohort,
+  getCrashHistory: mocks.getCrashHistory,
+  getDefaultChannel: mocks.getDefaultChannel,
+  getFingerprintHash: mocks.getFingerprintHash,
+  getManifest: mocks.getManifest,
+  getMinBundleId: mocks.getMinBundleId,
+  isChannelSwitched: mocks.isChannelSwitched,
+  reload: mocks.reload,
+  resetChannel: mocks.resetChannel,
+  setCohort: mocks.setCohort,
+  setReloadBehavior: mocks.setReloadBehavior,
+  updateBundle: mocks.updateBundle,
+}));
+
+vi.mock("./wrap", () => ({
+  init: mocks.init,
+  wrap: mocks.wrap,
+}));
+
+const importHotUpdater = async () => {
+  const { HotUpdater } = await import("./index");
+  return HotUpdater;
+};
+
+describe("HotUpdater client initialization", () => {
+  beforeEach(() => {
+    vi.resetModules();
+
+    for (const mock of Object.values(mocks)) {
+      mock.mockReset();
+    }
+
+    mocks.addListener.mockReturnValue(() => {});
+    mocks.checkForUpdate.mockResolvedValue(null);
+    mocks.createDefaultResolver.mockImplementation((baseURL: string) => ({
+      baseURL,
+      checkUpdate: vi.fn(),
+      notifyAppReady: vi.fn(),
+    }));
+    mocks.getBaseURL.mockReturnValue(null);
+    mocks.init.mockReturnValue(undefined);
+    mocks.wrap.mockReturnValue((Component: unknown) => Component);
+  });
+
+  it("initializes manual update flows without wrapping a component", async () => {
+    const resolver = {
+      checkUpdate: vi.fn(),
+      notifyAppReady: vi.fn(),
+    };
+    mocks.createDefaultResolver.mockReturnValue(resolver);
+
+    const HotUpdater = await importHotUpdater();
+
+    const result = HotUpdater.init({
+      baseURL: "https://updates.example.com",
+      requestHeaders: {
+        Authorization: "Bearer token",
+      },
+      requestTimeout: 1000,
+    });
+
+    expect(result).toBeUndefined();
+    expect(mocks.createDefaultResolver).toHaveBeenCalledWith(
+      "https://updates.example.com",
+    );
+    expect(mocks.init).toHaveBeenCalledWith({
+      requestHeaders: {
+        Authorization: "Bearer token",
+      },
+      requestTimeout: 1000,
+      resolver,
+    });
+  });
+
+  it("uses init configuration for later manual update checks", async () => {
+    const resolver = {
+      checkUpdate: vi.fn(),
+      notifyAppReady: vi.fn(),
+    };
+    mocks.createDefaultResolver.mockReturnValue(resolver);
+
+    const HotUpdater = await importHotUpdater();
+
+    HotUpdater.init({
+      baseURL: "https://updates.example.com",
+      requestHeaders: {
+        Authorization: "Bearer token",
+      },
+      requestTimeout: 1000,
+    });
+
+    await HotUpdater.checkForUpdate({
+      requestHeaders: {
+        "X-Runtime": "secondary",
+      },
+      updateStrategy: "appVersion",
+    });
+
+    expect(mocks.checkForUpdate).toHaveBeenCalledWith({
+      requestHeaders: {
+        Authorization: "Bearer token",
+        "X-Runtime": "secondary",
+      },
+      requestTimeout: 1000,
+      resolver,
+      updateStrategy: "appVersion",
+    });
+  });
+
+  it("points users to wrap or init when methods are called too early", async () => {
+    const HotUpdater = await importHotUpdater();
+
+    expect(() =>
+      HotUpdater.checkForUpdate({
+        updateStrategy: "appVersion",
+      }),
+    ).toThrow("requires HotUpdater.wrap() or HotUpdater.init() to be used");
+  });
+
+  it("requires baseURL for init", async () => {
+    const HotUpdater = await importHotUpdater();
+
+    expect(() => HotUpdater.init({} as never)).toThrow(
+      "baseURL must be provided",
+    );
+    expect(mocks.init).not.toHaveBeenCalled();
+  });
+});

package/src/index.ts

@@ -27,7 +27,14 @@ import {
 } from "./native";
 import { hotUpdaterStore } from "./store";
 import type { HotUpdaterResolver } from "./types";
-import { type HotUpdaterOptions, type InternalWrapOptions, wrap } from "./wrap";
+import {
+  type HotUpdaterInitOptions,
+  type HotUpdaterOptions,
+  init,
+  type InternalInitOptions,
+  type InternalWrapOptions,
+  wrap,
+} from "./wrap";
 
 export type {
   CustomReloadHandler,
@@ -47,7 +54,11 @@ export {
   type ResolverNotifyAppReadyParams,
   type SignatureVerificationFailure,
 } from "./types";
-export type { HotUpdaterOptions, RunUpdateProcessResponse } from "./wrap";
+export type {
+  HotUpdaterInitOptions,
+  HotUpdaterOptions,
+  RunUpdateProcessResponse,
+} from "./wrap";
 
 /**
  * Register getBaseURL to global objects for use without imports.
@@ -81,23 +92,109 @@ function createHotUpdaterClient() {
     resolver: null,
   };
 
+  const createMissingNetworkConfigError = (apiName: "init" | "wrap") => {
+    if (apiName === "init") {
+      return new Error(
+        `[HotUpdater] baseURL must be provided.\n\n` +
+          `Configure HotUpdater before calling update APIs:\n\n` +
+          `  HotUpdater.init({\n` +
+          `    baseURL: "<your-update-server-url>",\n` +
+          `  });\n\n` +
+          `For more information, visit: https://hot-updater.dev/docs/react-native-api/init`,
+      );
+    }
+
+    const baseURLExample =
+      `  export default HotUpdater.wrap({\n` +
+      `    baseURL: "<your-update-server-url>",\n` +
+      `    updateStrategy: "appVersion",\n` +
+      `    updateMode: "auto"\n` +
+      `  })(App);\n\n`;
+
+    const resolverExample =
+      `  export default HotUpdater.wrap({\n` +
+      `    resolver: {\n` +
+      `      checkUpdate: async (params) => { /* custom logic */ },\n` +
+      `      notifyAppReady: async (params) => { /* custom logic */ }\n` +
+      `    },\n` +
+      `    updateMode: "manual"\n` +
+      `  })(App);\n\n`;
+
+    return new Error(
+      `[HotUpdater] Either baseURL or resolver must be provided.\n\n` +
+        `Option 1: Using baseURL (recommended for most cases)\n` +
+        baseURLExample +
+        `Option 2: Using custom resolver (advanced)\n` +
+        resolverExample +
+        `For more information, visit: https://hot-updater.dev/docs/react-native-api/${apiName}`,
+    );
+  };
+
+  const normalizeOptions = (
+    options: HotUpdaterOptions,
+  ): InternalWrapOptions => {
+    if ("baseURL" in options && options.baseURL) {
+      const { baseURL, ...rest } = options;
+      return {
+        ...rest,
+        resolver: createDefaultResolver(baseURL),
+      };
+    }
+
+    if ("resolver" in options && options.resolver) {
+      return options;
+    }
+
+    throw createMissingNetworkConfigError("wrap");
+  };
+
+  const normalizeInitOptions = (
+    options: HotUpdaterInitOptions,
+  ): InternalInitOptions => {
+    const {
+      baseURL,
+      updateMode: _updateMode,
+      ...rest
+    } = options as HotUpdaterInitOptions & {
+      updateMode?: unknown;
+    };
+
+    if (baseURL) {
+      return {
+        ...rest,
+        resolver: createDefaultResolver(baseURL),
+      };
+    }
+
+    throw createMissingNetworkConfigError("init");
+  };
+
+  const configureGlobal = (
+    normalizedOptions: InternalInitOptions | InternalWrapOptions,
+    options: HotUpdaterOptions | HotUpdaterInitOptions,
+  ) => {
+    globalConfig.resolver = normalizedOptions.resolver;
+    globalConfig.requestHeaders = options.requestHeaders;
+    globalConfig.requestTimeout = options.requestTimeout;
+  };
+
   const ensureGlobalResolver = (methodName: string) => {
     if (!globalConfig.resolver) {
       throw new Error(
-        `[HotUpdater] ${methodName} requires HotUpdater.wrap() to be used.\n\n` +
-          `To fix this issue, wrap your root component with HotUpdater.wrap():\n\n` +
-          `Option 1: With automatic updates\n` +
+        `[HotUpdater] ${methodName} requires HotUpdater.wrap() or HotUpdater.init() to be used.\n\n` +
+          `To fix this issue, configure HotUpdater before calling ${methodName}:\n\n` +
+          `Option 1: With HotUpdater.wrap()\n` +
           `  export default HotUpdater.wrap({\n` +
           `    baseURL: "<your-update-server-url>",\n` +
           `    updateStrategy: "appVersion",\n` +
           `    updateMode: "auto"\n` +
           `  })(App);\n\n` +
-          `Option 2: Manual updates only (custom flow)\n` +
-          `  export default HotUpdater.wrap({\n` +
+          `Option 2: With HotUpdater.init() for custom runtimes\n` +
+          `  HotUpdater.init({\n` +
           `    baseURL: "<your-update-server-url>",\n` +
-          `    updateMode: "manual"\n` +
-          `  })(App);\n\n` +
-          `For more information, visit: https://hot-updater.dev/docs/react-native-api/wrap`,
+          `  });\n\n` +
+          `For more information, visit: https://hot-updater.dev/docs/react-native-api/wrap ` +
+          `or https://hot-updater.dev/docs/react-native-api/init`,
       );
     }
     return globalConfig.resolver;
@@ -129,44 +226,36 @@ function createHotUpdaterClient() {
      * ```
      */
     wrap: (options: HotUpdaterOptions) => {
-      let normalizedOptions: InternalWrapOptions;
-
-      if ("baseURL" in options && options.baseURL) {
-        const { baseURL, ...rest } = options;
-        normalizedOptions = {
-          ...rest,
-          resolver: createDefaultResolver(baseURL),
-        };
-      } else if ("resolver" in options && options.resolver) {
-        normalizedOptions = options;
-      } else {
-        throw new Error(
-          `[HotUpdater] Either baseURL or resolver must be provided.\n\n` +
-            `Option 1: Using baseURL (recommended for most cases)\n` +
-            `  export default HotUpdater.wrap({\n` +
-            `    baseURL: "<your-update-server-url>",\n` +
-            `    updateStrategy: "appVersion",\n` +
-            `    updateMode: "auto"\n` +
-            `  })(App);\n\n` +
-            `Option 2: Using custom resolver (advanced)\n` +
-            `  export default HotUpdater.wrap({\n` +
-            `    resolver: {\n` +
-            `      checkUpdate: async (params) => { /* custom logic */ },\n` +
-            `      notifyAppReady: async (params) => { /* custom logic */ }\n` +
-            `    },\n` +
-            `    updateMode: "manual"\n` +
-            `  })(App);\n\n` +
-            `For more information, visit: https://hot-updater.dev/docs/react-native-api/wrap`,
-        );
-      }
-
-      globalConfig.resolver = normalizedOptions.resolver;
-      globalConfig.requestHeaders = options.requestHeaders;
-      globalConfig.requestTimeout = options.requestTimeout;
+      const normalizedOptions = normalizeOptions(options);
+      configureGlobal(normalizedOptions, options);
 
       return wrap(normalizedOptions);
     },
 
+    /**
+     * Initializes HotUpdater without wrapping a React component.
+     *
+     * Use this for manual update flows in runtimes where a root component HOC
+     * is not convenient. It has the same initialization effect as
+     * `HotUpdater.wrap({ updateMode: "manual" })(App)`.
+     *
+     * @example
+     * ```tsx
+     * HotUpdater.init({
+     *   baseURL: "<your-update-server-url>",
+     * });
+     *
+     * export default App;
+     * ```
+     */
+    init: (options: HotUpdaterInitOptions): void => {
+      const normalizedOptions = normalizeInitOptions(options);
+
+      configureGlobal(normalizedOptions, options);
+
+      init(normalizedOptions);
+    },
+
     /**
      * Reloads the app.
      */

package/src/wrap.spec.ts

@@ -0,0 +1,81 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  addListener: vi.fn(() => () => {}),
+  checkForUpdate: vi.fn(),
+  getBundleId: vi.fn(() => "bundle-id"),
+  notifyAppReady: vi.fn(() => ({ status: "STABLE" })),
+  reload: vi.fn(),
+}));
+
+vi.mock("./checkForUpdate", () => ({
+  checkForUpdate: mocks.checkForUpdate,
+}));
+
+vi.mock("./native", () => ({
+  addListener: mocks.addListener,
+  getBundleId: mocks.getBundleId,
+  notifyAppReady: mocks.notifyAppReady,
+  reload: mocks.reload,
+}));
+
+describe("HotUpdater wrap initialization", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.unstubAllGlobals();
+    vi.useRealTimers();
+
+    for (const mock of Object.values(mocks)) {
+      mock.mockReset();
+    }
+
+    mocks.checkForUpdate.mockResolvedValue(null);
+    mocks.addListener.mockReturnValue(() => {});
+    mocks.getBundleId.mockReturnValue("bundle-id");
+    mocks.notifyAppReady.mockReturnValue({ status: "STABLE" });
+  });
+
+  it("returns void from init and defers notifyAppReady to the next frame", async () => {
+    vi.useFakeTimers();
+
+    const requestAnimationFrame = vi.fn(
+      (callback: (timestamp: number) => void) => {
+        setTimeout(() => callback(0), 0);
+        return 1;
+      },
+    );
+    vi.stubGlobal("requestAnimationFrame", requestAnimationFrame);
+
+    const resolver = {
+      checkUpdate: vi.fn(),
+      notifyAppReady: vi.fn().mockResolvedValue(undefined),
+    };
+    const { init } = await import("./wrap");
+
+    const result = init({
+      resolver,
+      requestHeaders: {
+        Authorization: "Bearer token",
+      },
+      requestTimeout: 1000,
+    });
+
+    expect(result).toBeUndefined();
+    expect(mocks.notifyAppReady).not.toHaveBeenCalled();
+    expect(resolver.notifyAppReady).not.toHaveBeenCalled();
+
+    expect(requestAnimationFrame).toHaveBeenCalled();
+
+    await vi.runOnlyPendingTimersAsync();
+
+    expect(mocks.notifyAppReady).toHaveBeenCalledWith();
+    expect(resolver.notifyAppReady).toHaveBeenCalledWith({
+      status: "STABLE",
+      crashedBundleId: undefined,
+      requestHeaders: {
+        Authorization: "Bearer token",
+      },
+      requestTimeout: 1000,
+    });
+  });
+});

package/src/wrap.tsx

@@ -173,6 +173,16 @@ export type ManualUpdateOptions = CommonHotUpdaterOptions &
     updateMode: "manual";
   };
 
+type ManualBaseURLUpdateOptions = CommonHotUpdaterOptions &
+  BaseURLConfig & {
+    updateMode: "manual";
+  };
+
+export type HotUpdaterInitOptions = Omit<
+  ManualBaseURLUpdateOptions,
+  "updateMode"
+>;
+
 export type HotUpdaterOptions = AutoUpdateOptions | ManualUpdateOptions;
 
 /**
@@ -204,10 +214,30 @@ type InternalManualUpdateOptions = InternalCommonOptions & {
   updateMode: "manual";
 };
 
+export type InternalInitOptions = InternalCommonOptions;
+
 export type InternalWrapOptions =
   | InternalAutoUpdateOptions
   | InternalManualUpdateOptions;
 
+type RequestAnimationFrame = (callback: (timestamp: number) => void) => number;
+
+const waitForNextFrame = () =>
+  new Promise<void>((resolve) => {
+    const requestAnimationFrame = (
+      globalThis as typeof globalThis & {
+        requestAnimationFrame?: RequestAnimationFrame;
+      }
+    )?.requestAnimationFrame;
+
+    if (requestAnimationFrame) {
+      requestAnimationFrame(() => resolve());
+      return;
+    }
+
+    void Promise.resolve().then(resolve);
+  });
+
 /**
  * Helper function to handle notifyAppReady flow
  */
@@ -217,6 +247,8 @@ const handleNotifyAppReady = async (options: {
   requestTimeout?: number;
   onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
 }): Promise<void> => {
+  await waitForNextFrame();
+
   try {
     const nativeResult = nativeNotifyAppReady();
 
@@ -240,6 +272,10 @@ const handleNotifyAppReady = async (options: {
   }
 };
 
+export function init(options: InternalInitOptions): void {
+  void handleNotifyAppReady(options);
+}
+
 export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
   options: InternalWrapOptions,
 ): (WrappedComponent: React.ComponentType<P>) => React.ComponentType<P> {