@hot-updater/react-native 0.30.11 → 0.31.0

package/src/store.ts

@@ -1,18 +1,88 @@
 import useSyncExternalStoreExports from "use-sync-external-store/shim/with-selector";
 
+import type {
+  HotUpdaterDiffFileSnapshot,
+  HotUpdaterDiffProgressDetails,
+  HotUpdaterProgressEvent,
+} from "./native";
 import { addListener } from "./native";
 
 export type HotUpdaterState = {
   progress: number;
+  downloadedBytes: number | undefined;
+  totalBytes: number | undefined;
   isUpdateDownloaded: boolean;
+  artifactType: "archive" | "diff" | null;
+  details: HotUpdaterDiffProgressDetails | null;
 };
 
 const { useSyncExternalStoreWithSelector } = useSyncExternalStoreExports;
 
+const areDiffDetailsEqual = (
+  left: HotUpdaterDiffProgressDetails | null,
+  right: HotUpdaterDiffProgressDetails | null,
+) => {
+  if (left === right) {
+    return true;
+  }
+
+  if (left === null || right === null) {
+    return false;
+  }
+
+  if (
+    left.totalFilesCount !== right.totalFilesCount ||
+    left.completedFilesCount !== right.completedFilesCount ||
+    left.files.length !== right.files.length
+  ) {
+    return false;
+  }
+
+  return left.files.every((leftFile, index) => {
+    const rightFile = right.files[index];
+    return (
+      rightFile !== undefined &&
+      leftFile.order === rightFile.order &&
+      leftFile.path === rightFile.path &&
+      leftFile.downloadPath === rightFile.downloadPath &&
+      leftFile.downloadedBytes === rightFile.downloadedBytes &&
+      leftFile.progress === rightFile.progress &&
+      leftFile.status === rightFile.status &&
+      leftFile.totalBytes === rightFile.totalBytes
+    );
+  });
+};
+
+const areStatesEqual = (left: HotUpdaterState, right: HotUpdaterState) => {
+  return (
+    left.progress === right.progress &&
+    left.downloadedBytes === right.downloadedBytes &&
+    left.totalBytes === right.totalBytes &&
+    left.isUpdateDownloaded === right.isUpdateDownloaded &&
+    left.artifactType === right.artifactType &&
+    areDiffDetailsEqual(left.details, right.details)
+  );
+};
+
+const normalizeByteCount = (value: number | undefined) => {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return undefined;
+  }
+  return Math.round(value);
+};
+
+const normalizeDownloadPath = (value: string | undefined) => {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+
 const createHotUpdaterStore = () => {
   let state: HotUpdaterState = {
     progress: 0,
+    downloadedBytes: undefined,
+    totalBytes: undefined,
     isUpdateDownloaded: false,
+    artifactType: null,
+    details: null,
   };
 
   const getSnapshot = () => {
@@ -27,8 +97,39 @@ const createHotUpdaterStore = () => {
     }
   };
 
+  const normalizeDiffDetails = (
+    details: HotUpdaterDiffProgressDetails,
+  ): HotUpdaterDiffProgressDetails => {
+    const totalFilesCount = Math.max(0, details.totalFilesCount);
+    const normalizedFiles: HotUpdaterDiffFileSnapshot[] = details.files
+      .map((file) => {
+        const downloadPath =
+          normalizeDownloadPath(file.downloadPath) ?? file.path;
+
+        return {
+          downloadPath,
+          downloadedBytes: normalizeByteCount(file.downloadedBytes),
+          order: Math.max(0, file.order),
+          path: file.path,
+          progress: Math.max(0, Math.min(file.progress, 1)),
+          status: file.status,
+          totalBytes: normalizeByteCount(file.totalBytes),
+        };
+      })
+      .sort((left, right) => left.order - right.order);
+
+    return {
+      completedFilesCount: Math.max(
+        0,
+        Math.min(details.completedFilesCount, totalFilesCount),
+      ),
+      files: normalizedFiles,
+      totalFilesCount,
+    };
+  };
+
   const setState = (newState: Partial<HotUpdaterState>) => {
-    // Merge first, then normalize derived fields
+    // Merge first, then normalize derived fields.
     const nextState: HotUpdaterState = {
       ...state,
       ...newState,
@@ -38,7 +139,8 @@ const createHotUpdaterStore = () => {
     // If `progress` is not provided but `isUpdateDownloaded` is,
     // honor the explicit value.
     if ("progress" in newState && typeof newState.progress === "number") {
-      nextState.isUpdateDownloaded = newState.progress >= 1;
+      nextState.progress = Math.max(0, Math.min(newState.progress, 1));
+      nextState.isUpdateDownloaded = nextState.progress >= 1;
     } else if (
       "isUpdateDownloaded" in newState &&
       typeof newState.isUpdateDownloaded === "boolean"
@@ -46,10 +148,15 @@ const createHotUpdaterStore = () => {
       nextState.isUpdateDownloaded = newState.isUpdateDownloaded;
     }
 
-    if (
-      state.progress === nextState.progress &&
-      state.isUpdateDownloaded === nextState.isUpdateDownloaded
-    ) {
+    if (newState.details === undefined) {
+      nextState.details = state.details;
+    }
+
+    if (nextState.artifactType !== "diff") {
+      nextState.details = null;
+    }
+
+    if (areStatesEqual(state, nextState)) {
       return;
     }
 
@@ -57,6 +164,25 @@ const createHotUpdaterStore = () => {
     emitChange();
   };
 
+  const applyProgressEvent = (event: HotUpdaterProgressEvent) => {
+    setState({
+      artifactType: event.artifactType,
+      details:
+        event.artifactType === "diff"
+          ? normalizeDiffDetails(event.details)
+          : null,
+      downloadedBytes:
+        event.artifactType === "archive"
+          ? normalizeByteCount(event.downloadedBytes)
+          : undefined,
+      progress: event.progress,
+      totalBytes:
+        event.artifactType === "archive"
+          ? normalizeByteCount(event.totalBytes)
+          : undefined,
+    });
+  };
+
   const subscribe = (listener: () => void) => {
     listeners.add(listener);
     return () => listeners.delete(listener);
@@ -64,7 +190,7 @@ const createHotUpdaterStore = () => {
 
   // Subscribe to native onProgress events
   // This listener is registered once when the store is created
-  addListener("onProgress", setState);
+  addListener("onProgress", applyProgressEvent);
 
   return { getSnapshot, setState, subscribe };
 };

package/src/types.ts

@@ -2,6 +2,8 @@ import type { AppUpdateInfo } from "@hot-updater/core";
 
 import type { NotifyAppReadyResult } from "./native";
 
+export type HotUpdaterBaseURL = string | (() => string | Promise<string>);
+
 /**
  * Parameters passed to resolver.checkUpdate method
  */

package/src/wrap.spec.ts

@@ -1,5 +1,8 @@
+import type React from "react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
+import type { HotUpdaterOptions } from "./wrap";
+
 const mocks = vi.hoisted(() => ({
   addListener: vi.fn(() => () => {}),
   checkForUpdate: vi.fn(),
@@ -78,4 +81,92 @@ describe("HotUpdater wrap initialization", () => {
       requestTimeout: 1000,
     });
   });
+
+  it("calls init onError when app-ready notification fails", async () => {
+    vi.useFakeTimers();
+
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const error = new Error("notify failed");
+    const onError = vi.fn();
+    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().mockRejectedValue(error),
+    };
+    const { init } = await import("./wrap");
+
+    init({
+      resolver,
+      onError,
+    });
+
+    await vi.runOnlyPendingTimersAsync();
+
+    expect(onError).toHaveBeenCalledWith(error);
+    warn.mockRestore();
+  });
+
+  it("warns when the deprecated manual wrap HOC is used", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const { wrap } = await import("./wrap");
+
+    wrap({
+      resolver: {
+        checkUpdate: vi.fn(),
+        notifyAppReady: vi.fn(),
+      },
+      updateMode: "manual",
+    });
+
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'HotUpdater.wrap({ updateMode: "manual" }) is deprecated',
+      ),
+    );
+    warn.mockRestore();
+  });
+
+  it("preserves wrapped component prop inference", async () => {
+    const { wrap } = await import("./wrap");
+    const Component: React.ComponentType<{ title: string }> = () => null;
+
+    const WrappedComponent = wrap({
+      resolver: {
+        checkUpdate: vi.fn(),
+        notifyAppReady: vi.fn(),
+      },
+      updateMode: "auto",
+      updateStrategy: "appVersion",
+    })(Component);
+
+    const acceptsTitleProps: React.ComponentType<{ title: string }> =
+      WrappedComponent;
+    expect(acceptsTitleProps).toBe(WrappedComponent);
+  });
+
+  it("types public wrap options as automatic mode by default", () => {
+    const autoOptions = {
+      baseURL: "https://updates.example.com",
+      updateStrategy: "appVersion",
+    } satisfies HotUpdaterOptions;
+    const explicitAutoOptions = {
+      baseURL: "https://updates.example.com",
+      updateMode: "auto",
+      updateStrategy: "appVersion",
+    } satisfies HotUpdaterOptions;
+    const manualOptions = {
+      baseURL: "https://updates.example.com",
+      updateMode: "manual",
+    } satisfies HotUpdaterOptions;
+
+    expect(autoOptions.updateStrategy).toBe("appVersion");
+    expect(explicitAutoOptions.updateMode).toBe("auto");
+    expect(manualOptions.updateMode).toBe("manual");
+  });
 });

package/src/wrap.tsx

@@ -9,8 +9,8 @@ import {
   notifyAppReady as nativeNotifyAppReady,
   reload,
 } from "./native";
-import { useHotUpdaterStore } from "./store";
-import type { HotUpdaterResolver } from "./types";
+import { type HotUpdaterState, useHotUpdaterStore } from "./store";
+import type { HotUpdaterBaseURL, HotUpdaterResolver } from "./types";
 
 export interface RunUpdateProcessResponse {
   status: "ROLLBACK" | "UPDATE" | "UP_TO_DATE";
@@ -24,8 +24,18 @@ type UpdateStatus =
   | "UPDATING"
   | "UPDATE_PROCESS_COMPLETED";
 
+export type HotUpdaterFallbackComponentProps = {
+  status: Exclude<UpdateStatus, "UPDATE_PROCESS_COMPLETED">;
+  progress: number;
+  downloadedBytes: HotUpdaterState["downloadedBytes"];
+  totalBytes: HotUpdaterState["totalBytes"];
+  message: string | null;
+  artifactType: HotUpdaterState["artifactType"];
+  details: HotUpdaterState["details"];
+};
+
 /**
- * Common options shared between auto and manual update modes
+ * Common options shared by HotUpdater initialization APIs.
  */
 interface CommonHotUpdaterOptions {
   /**
@@ -51,18 +61,24 @@ interface CommonHotUpdaterOptions {
    *
    * @example
    * ```tsx
-   * HotUpdater.wrap({
+   * HotUpdater.init({
    *   baseURL: "https://api.example.com",
-   *   updateMode: "manual",
    *   onNotifyAppReady: ({ status, crashedBundleId }) => {
    *     if (status === "RECOVERED") {
    *       analytics.track("bundle_rollback", { crashedBundleId });
    *     }
-   *   }
-   * })(App);
+   *   },
+   * });
    * ```
    */
   onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+
+  /**
+   * Default callback invoked when Hot Updater initialization or update checks
+   * fail. Per-call `HotUpdater.checkForUpdate({ onError })` handlers override
+   * this callback for that check.
+   */
+  onError?: (error: HotUpdaterError | Error | unknown) => void;
 }
 
 /**
@@ -70,10 +86,12 @@ interface CommonHotUpdaterOptions {
  */
 interface BaseURLConfig {
   /**
-   * Base URL for update server
+   * Base URL for update server. Use a function to resolve it dynamically
+   * before each update check.
    * @example "https://update.example.com"
+   * @example () => getUpdateServerURL()
    */
-  baseURL: string;
+  baseURL: HotUpdaterBaseURL;
 
   /**
    * Resolver is not allowed when using baseURL
@@ -103,6 +121,11 @@ type NetworkConfig = BaseURLConfig | ResolverConfig;
 
 export type AutoUpdateOptions = CommonHotUpdaterOptions &
   NetworkConfig & {
+    /**
+     * Automatic update mode. This is the default and can be omitted.
+     */
+    updateMode?: "auto";
+
     /**
      * Update strategy
      * - "fingerprint": Use fingerprint hash to check for updates
@@ -110,14 +133,6 @@ export type AutoUpdateOptions = CommonHotUpdaterOptions &
      */
     updateStrategy: "fingerprint" | "appVersion";
 
-    /**
-     * Update mode
-     * - "auto": Automatically check and download updates
-     */
-    updateMode: "auto";
-
-    onError?: (error: HotUpdaterError | Error | unknown) => void;
-
     /**
      * Component to show while downloading a new bundle update.
      *
@@ -140,11 +155,7 @@ export type AutoUpdateOptions = CommonHotUpdaterOptions &
      *
      * If not defined, the bundle will download in the background without blocking the screen.
      */
-    fallbackComponent?: React.FC<{
-      status: Exclude<UpdateStatus, "UPDATE_PROCESS_COMPLETED">;
-      progress: number;
-      message: string | null;
-    }>;
+    fallbackComponent?: React.FC<HotUpdaterFallbackComponentProps>;
 
     onProgress?: (progress: number) => void;
 
@@ -167,21 +178,25 @@ export type AutoUpdateOptions = CommonHotUpdaterOptions &
 export type ManualUpdateOptions = CommonHotUpdaterOptions &
   NetworkConfig & {
     /**
-     * Update mode
-     * - "manual": Only notify app ready, user manually calls checkForUpdate()
+     * @deprecated Replace manual `HotUpdater.wrap` with `HotUpdater.init`.
+     *
+     * ```tsx
+     * import { HotUpdater } from "@hot-updater/react-native";
+     *
+     * HotUpdater.init({
+     *   baseURL: "<your-update-server-url>",
+     * });
+     *
+     * export default App;
+     * ```
+     *
+     * Then call `HotUpdater.checkForUpdate(...)` from your manual update flow.
+     * See https://hot-updater.dev/docs/guides/custom-update
      */
     updateMode: "manual";
   };
 
-type ManualBaseURLUpdateOptions = CommonHotUpdaterOptions &
-  BaseURLConfig & {
-    updateMode: "manual";
-  };
-
-export type HotUpdaterInitOptions = Omit<
-  ManualBaseURLUpdateOptions,
-  "updateMode"
->;
+export type HotUpdaterInitOptions = CommonHotUpdaterOptions & NetworkConfig;
 
 export type HotUpdaterOptions = AutoUpdateOptions | ManualUpdateOptions;
 
@@ -194,17 +209,13 @@ type InternalCommonOptions = {
   requestHeaders?: Record<string, string>;
   requestTimeout?: number;
   onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+  onError?: (error: HotUpdaterError | Error | unknown) => void;
 };
 
 type InternalAutoUpdateOptions = InternalCommonOptions & {
   updateStrategy: "fingerprint" | "appVersion";
   updateMode: "auto";
-  onError?: (error: HotUpdaterError | Error | unknown) => void;
-  fallbackComponent?: React.FC<{
-    status: Exclude<UpdateStatus, "UPDATE_PROCESS_COMPLETED">;
-    progress: number;
-    message: string | null;
-  }>;
+  fallbackComponent?: React.FC<HotUpdaterFallbackComponentProps>;
   onProgress?: (progress: number) => void;
   reloadOnForceUpdate?: boolean;
   onUpdateProcessCompleted?: (response: RunUpdateProcessResponse) => void;
@@ -222,6 +233,23 @@ export type InternalWrapOptions =
 
 type RequestAnimationFrame = (callback: (timestamp: number) => void) => number;
 
+let didWarnManualWrapDeprecation = false;
+
+const warnManualWrapDeprecation = () => {
+  if (didWarnManualWrapDeprecation) {
+    return;
+  }
+
+  didWarnManualWrapDeprecation = true;
+  console.warn(
+    '[HotUpdater] HotUpdater.wrap({ updateMode: "manual" }) is deprecated. ' +
+      "Move the same baseURL/resolver options to HotUpdater.init({ ... }), " +
+      "export your root component directly, and call " +
+      "HotUpdater.checkForUpdate(...) from your manual update flow. " +
+      "See https://hot-updater.dev/docs/guides/custom-update",
+  );
+};
+
 const waitForNextFrame = () =>
   new Promise<void>((resolve) => {
     const requestAnimationFrame = (
@@ -246,6 +274,7 @@ const handleNotifyAppReady = async (options: {
   requestHeaders?: Record<string, string>;
   requestTimeout?: number;
   onNotifyAppReady?: (result: NotifyAppReadyResult) => void;
+  onError?: (error: HotUpdaterError | Error | unknown) => void;
 }): Promise<void> => {
   await waitForNextFrame();
 
@@ -262,12 +291,14 @@ const handleNotifyAppReady = async (options: {
           requestTimeout: options.requestTimeout,
         })
         .catch((e: unknown) => {
+          options.onError?.(e);
           console.warn("[HotUpdater] Resolver notifyAppReady failed:", e);
         });
     }
 
     options.onNotifyAppReady?.(nativeResult);
   } catch (e) {
+    options.onError?.(e);
     console.warn("[HotUpdater] Failed to notify app ready:", e);
   }
 };
@@ -276,11 +307,15 @@ export function init(options: InternalInitOptions): void {
   void handleNotifyAppReady(options);
 }
 
-export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
+export function wrap(
   options: InternalWrapOptions,
-): (WrappedComponent: React.ComponentType<P>) => React.ComponentType<P> {
+): <P extends object>(
+  WrappedComponent: React.ComponentType<P>,
+) => React.ComponentType<P> {
   if (options.updateMode === "manual") {
-    return (WrappedComponent: React.ComponentType<P>) => {
+    warnManualWrapDeprecation();
+
+    return <P extends object>(WrappedComponent: React.ComponentType<P>) => {
       const ManualHOC: React.FC<P> = (props: P) => {
         useEffect(() => {
           void handleNotifyAppReady(options);
@@ -293,12 +328,12 @@ export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
     };
   }
 
-  // updateMode: "auto"
   const { reloadOnForceUpdate = true, ...restOptions } = options;
 
-  return (WrappedComponent: React.ComponentType<P>) => {
+  return <P extends object>(WrappedComponent: React.ComponentType<P>) => {
     const HotUpdaterHOC: React.FC<P> = (props: P) => {
-      const progress = useHotUpdaterStore((state) => state.progress);
+      const progressState = useHotUpdaterStore((state) => state);
+      const progress = progressState.progress;
 
       const [message, setMessage] = useState<string | null>(null);
       const [updateStatus, setUpdateStatus] =
@@ -392,9 +427,13 @@ export function wrap<P extends React.JSX.IntrinsicAttributes = object>(
         const Fallback = restOptions.fallbackComponent;
         return (
           <Fallback
+            artifactType={progressState.artifactType}
+            details={progressState.details}
+            downloadedBytes={progressState.downloadedBytes}
             progress={progress}
             status={updateStatus}
             message={message}
+            totalBytes={progressState.totalBytes}
           />
         );
       }