@applicaster/zapp-react-native-utils 15.0.0-alpha.9102699023 → 15.0.0-alpha.9102777840

package/refreshUtils/RefreshCoordinator/index.ts

@@ -0,0 +1,216 @@
+import { noop } from "@applicaster/zapp-react-native-utils/functionUtils";
+import { interval, Subject, Subscription } from "rxjs";
+import { map, filter, throttleTime } from "rxjs/operators";
+
+import { getDataRefreshConfig } from "./utils";
+
+export { getDataRefreshConfig, type RefreshConfig } from "./utils";
+
+const THROTTLE_TIMEOUT = 500; // ms
+
+type ComponentToRefresh = {
+  component: ZappUIComponent;
+  screenId: string;
+};
+
+/**
+ * Public contract for refresh coordination.
+ *
+ * register() → starts refresh timer for a component with screen context
+ * subscribeTo() → listen to refresh events for a specific component and screen
+ * subscribeToAny() → listen to all refresh events with throttling
+ */
+interface IRefreshCoordinator {
+  register(component: ZappUIComponent, screenId: string): () => void;
+  subscribeTo(
+    component: ZappUIComponent,
+    screenId: string,
+    listener: () => void
+  ): Subscription;
+  subscribeToAny(
+    listener: (componentToRefresh: ComponentToRefresh) => void
+  ): Subscription;
+}
+
+/**
+ * Singleton implementation of RefreshCoordinator.
+ *
+ * Design goals:
+ * - One shared coordinator across the app
+ * - Multiple components can register refresh timers with screen context
+ * - Multiple listeners can subscribe to refresh events
+ * - Safe cleanup of timers and subscriptions
+ */
+class RefreshCoordinator implements IRefreshCoordinator {
+  private static instance: RefreshCoordinator;
+
+  /**
+   * Active timers per component/screen pair ((componentId, screenId) → RxJS Subscription).
+   * Each entry is keyed by a composite of componentId and screenId (via getKey),
+   * and gets its own interval stream for periodic refresh.
+   */
+  private timers: Map<string, Subscription> = new Map();
+
+  /**
+   * Central event stream emitting components that need refresh.
+   * All component interval streams push into this Subject.
+   * Multiple listeners can subscribe to receive refresh events for specific components.
+   * This is the core stream that coordinates all refresh operations.
+   */
+  private refresh$ = new Subject<ComponentToRefresh>();
+
+  // Store the current single subscriber for subscribeToAny
+  private anyListenerSubscription?: Subscription;
+
+  private constructor() {}
+
+  public static getInstance(): RefreshCoordinator {
+    if (!RefreshCoordinator.instance) {
+      RefreshCoordinator.instance = new RefreshCoordinator();
+    }
+
+    return RefreshCoordinator.instance;
+  }
+
+  /**
+   * Registers a component for periodic refresh.
+   *
+   * Behavior:
+   * - If the component was previously registered, its timer is replaced.
+   * - If refreshing is disabled, nothing is scheduled.
+   * - Returns an unregister function for manual cleanup.
+   * - Each component gets its own interval stream for periodic refresh.
+   */
+  public register(component: ZappUIComponent, screenId: string): () => void {
+    const componentId: ZappUIComponent["id"] = component.id;
+
+    // Ensure no duplicate timer exists for this component
+    this.unregister(componentId, screenId);
+
+    const refreshConfig = getDataRefreshConfig(component);
+
+    // If refreshing disabled → do nothing
+    if (!refreshConfig.isRefreshingEnabled) {
+      return noop;
+    }
+
+    /**
+     * Create interval stream:
+     * - Emits every refreshIntervalMs
+     * - Maps emission to the ComponentToRefresh object
+     * - Pushes component into central refresh$ stream
+     */
+    const subscription: Subscription = interval(refreshConfig.refreshIntervalMs)
+      .pipe(
+        map(() => ({
+          component,
+          screenId,
+        }))
+      )
+      .subscribe(this.refresh$);
+
+    this.timers.set(this.getKey(componentId, screenId), subscription);
+
+    return (): void => this.unregister(componentId, screenId);
+  }
+
+  /**
+   * Stops and removes timer for a specific component.
+   * Cleans up the RxJS subscription for that component's interval stream.
+   */
+  private unregister(
+    componentId: ZappUIComponent["id"],
+    screenId: string
+  ): void {
+    const key = this.getKey(componentId, screenId);
+    const subscription: Subscription | undefined = this.timers.get(key);
+
+    if (subscription) {
+      subscription.unsubscribe();
+      this.timers.delete(key);
+    }
+  }
+
+  private getKey(componentId: ZappUIComponent["id"], screenId: string): string {
+    return `componentId:${componentId}___screenId:${screenId}`;
+  }
+
+  /**
+   * Subscribes to refresh events for a specific component.
+   *
+   * Each subscription is independent - multiple listeners can subscribe
+   * to the same component's refresh events.
+   */
+  public subscribeTo(
+    component: ZappUIComponent,
+    screenId: string,
+    listener: () => void
+  ): Subscription {
+    return this.refresh$
+      .pipe(
+        filter(
+          (componentToRefresh: ComponentToRefresh) =>
+            componentToRefresh.component.id === component.id &&
+            componentToRefresh.screenId === screenId
+        )
+      )
+      .subscribe(listener);
+  }
+
+  /**
+   * Subscribes a single global listener to all refresh events.
+   *
+   * Behavior:
+   * - Only one active listener exists at a time.
+   *   - If a previous listener was already subscribed, it is automatically unsubscribed.
+   * - Throttles refresh events to emit at most once per THROTTLE_TIMEOUT interval.
+   * - Useful for scenarios where you want a single handler to react
+   *   to any component refresh without having multiple active callbacks.
+   *
+   * @param listener - Callback to invoke whenever any component triggers a refresh
+   * @returns The RxJS Subscription object for this listener
+   */
+  public subscribeToAny(
+    listener: (componentToRefresh: ComponentToRefresh) => void
+  ): Subscription {
+    // Unsubscribe previous listener if present to enforce "single active listener" policy
+    if (this.anyListenerSubscription) {
+      this.anyListenerSubscription.unsubscribe();
+    }
+
+    // Create a new throttled subscription
+    this.anyListenerSubscription = this.refresh$
+      .pipe(throttleTime(THROTTLE_TIMEOUT))
+      .subscribe(listener);
+
+    return this.anyListenerSubscription;
+  }
+
+  /**
+   * Fully resets coordinator state.
+   *
+   * Clears:
+   * - All component timers
+   * - Any active "subscribeToAny" listener
+   * - Recreates internal Subject to allow fresh subscriptions
+   */
+  public clear(): void {
+    // Stop and remove all active timers
+    this.timers.forEach((sub: Subscription) => sub.unsubscribe());
+    this.timers.clear();
+
+    // Stop any active "subscribeToAny" subscription
+    if (this.anyListenerSubscription) {
+      this.anyListenerSubscription.unsubscribe();
+      this.anyListenerSubscription = undefined;
+    }
+
+    // Complete old Subject to release subscribers
+    this.refresh$.complete();
+
+    // Recreate Subject so coordinator can be reused
+    this.refresh$ = new Subject<ComponentToRefresh>();
+  }
+}
+
+export const refreshCoordinator = RefreshCoordinator.getInstance();

package/refreshUtils/RefreshCoordinator/utils/__tests__/getDataRefreshConfig.test.ts

@@ -0,0 +1,104 @@
+import {
+  getDataRefreshConfig,
+  MINIMUM_REFRESHING_INTERVAL_IN_SECONDS,
+  DEFAULT_REFRESHING_INTERVAL_IN_SECONDS,
+} from "..";
+
+describe("getDataRefreshConfig", () => {
+  it("returns correct values when rules are defined", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: true,
+        refreshing_interval: 30,
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: true,
+      refreshIntervalMs: 30 * 1000,
+    });
+  });
+
+  it("returns false for isRefreshingEnabled if rules flag is false", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: false,
+        refreshing_interval: 45,
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: false,
+      refreshIntervalMs: 45 * 1000,
+    });
+  });
+
+  it("applies minimum interval if given interval is too low", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: true,
+        refreshing_interval: 2,
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result.refreshIntervalMs).toBe(
+      MINIMUM_REFRESHING_INTERVAL_IN_SECONDS * 1000
+    );
+  });
+
+  it("uses default interval when rules.refreshing_interval is undefined", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: true,
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result.refreshIntervalMs).toBe(
+      DEFAULT_REFRESHING_INTERVAL_IN_SECONDS * 1000
+    );
+  });
+
+  it("handles missing rules gracefully", () => {
+    const component = {} as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: false,
+      refreshIntervalMs: DEFAULT_REFRESHING_INTERVAL_IN_SECONDS * 1000,
+    });
+  });
+
+  it("handles null component gracefully", () => {
+    const result = getDataRefreshConfig(null as any);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: false,
+      refreshIntervalMs: DEFAULT_REFRESHING_INTERVAL_IN_SECONDS * 1000,
+    });
+  });
+
+  it("handles string values for rules correctly", () => {
+    const component = {
+      rules: {
+        enable_data_refreshing: "true",
+        refreshing_interval: "25",
+      },
+    } as any;
+
+    const result = getDataRefreshConfig(component);
+
+    expect(result).toEqual({
+      isRefreshingEnabled: true,
+      refreshIntervalMs: 25 * 1000,
+    });
+  });
+});

package/refreshUtils/RefreshCoordinator/utils/index.ts

@@ -0,0 +1,29 @@
+import { isTrue } from "@applicaster/zapp-react-native-utils/booleanUtils";
+import { toNumberWithDefault } from "@applicaster/zapp-react-native-utils/numberUtils";
+
+export const MINIMUM_REFRESHING_INTERVAL_IN_SECONDS = 5; // 5 seconds
+
+export const DEFAULT_REFRESHING_INTERVAL_IN_SECONDS = 60; // 1 minute
+
+export type RefreshConfig = {
+  isRefreshingEnabled: boolean;
+  refreshIntervalMs: number;
+};
+
+export const getDataRefreshConfig = (
+  component: ZappUIComponent
+): RefreshConfig => {
+  const isRefreshingEnabled = isTrue(component?.rules?.enable_data_refreshing);
+
+  const refreshing_interval = toNumberWithDefault(
+    DEFAULT_REFRESHING_INTERVAL_IN_SECONDS,
+    component?.rules?.refreshing_interval
+  );
+
+  return {
+    isRefreshingEnabled,
+    refreshIntervalMs:
+      Math.max(refreshing_interval, MINIMUM_REFRESHING_INTERVAL_IN_SECONDS) *
+      1000,
+  };
+};

package/screenPickerUtils/index.ts

@@ -1,3 +1,5 @@
+import { endsWith } from "@applicaster/zapp-react-native-utils/utils";
+
 export const getFocusableId = (id) => `PickerItem.${id}`;
 
 export const getPickerSelectorId = (id) => `PickerSelector.${id}`;
@@ -11,3 +13,6 @@ export const getScreenPickerSelectorContainerId = (id) =>
 
 export const getScreenPickerContentContainerId = (id) =>
   `${getScreenPickerId(id)}-screen-container`;
+
+export const isTabsScreenContentContainerId = (id) =>
+  endsWith("-screen-container", id);

package/screenUtils/index.ts

@@ -0,0 +1,3 @@
+export const TV_SCREEN_HEIGHT = 1080;
+
+export const TV_SCREEN_WIDTH = 1920;

package/utils/__tests__/clone.test.ts

@@ -0,0 +1,158 @@
+import { clone } from "../clone";
+
+describe("clone", () => {
+  const originalStructuredClone = global.structuredClone;
+
+  afterEach(() => {
+    // Restore the original structuredClone after each test
+    global.structuredClone = originalStructuredClone;
+  });
+
+  describe("when structuredClone is available", () => {
+    beforeEach(() => {
+      // Mock structuredClone if it's not available
+      if (typeof global.structuredClone === "undefined") {
+        global.structuredClone = jest.fn((value) =>
+          JSON.parse(JSON.stringify(value))
+        );
+      }
+    });
+
+    test("clones primitive values", () => {
+      expect(clone(42)).toBe(42);
+      expect(clone("test")).toBe("test");
+      expect(clone(true)).toBe(true);
+      expect(clone(null)).toBe(null);
+    });
+
+    test("clones simple objects", () => {
+      const original = { a: 1, b: 2 };
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+    });
+
+    test("clones nested objects", () => {
+      const original = { a: { b: { c: 1 } } };
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned.a).not.toBe(original.a);
+      expect(cloned.a.b).not.toBe(original.a.b);
+    });
+
+    test("clones arrays", () => {
+      const original = [1, 2, 3];
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+    });
+
+    test("clones arrays with nested objects", () => {
+      const original = [{ a: 1 }, { b: 2 }];
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned[0]).not.toBe(original[0]);
+      expect(cloned[1]).not.toBe(original[1]);
+    });
+
+    test("does not mutate the original value", () => {
+      const original = { a: 1, b: { c: 2 } };
+      const cloned = clone(original);
+
+      cloned.a = 99;
+      cloned.b.c = 99;
+
+      expect(original.a).toBe(1);
+      expect(original.b.c).toBe(2);
+    });
+  });
+
+  describe("when structuredClone is not available (fallback to cloneDeep)", () => {
+    beforeEach(() => {
+      // Delete structuredClone to force fallback to cloneDeep
+      delete (global as any).structuredClone;
+    });
+
+    test("clones primitive values using cloneDeep", () => {
+      expect(clone(42)).toBe(42);
+      expect(clone("test")).toBe("test");
+      expect(clone(true)).toBe(true);
+      expect(clone(null)).toBe(null);
+    });
+
+    test("clones simple objects using cloneDeep", () => {
+      const original = { a: 1, b: 2 };
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+    });
+
+    test("clones nested objects using cloneDeep", () => {
+      const original = { a: { b: { c: 1 } } };
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned.a).not.toBe(original.a);
+      expect(cloned.a.b).not.toBe(original.a.b);
+    });
+
+    test("clones arrays using cloneDeep", () => {
+      const original = [1, 2, 3];
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+    });
+
+    test("clones arrays with nested objects using cloneDeep", () => {
+      const original = [{ a: 1 }, { b: 2 }];
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned[0]).not.toBe(original[0]);
+      expect(cloned[1]).not.toBe(original[1]);
+    });
+
+    test("does not mutate the original value when using cloneDeep", () => {
+      const original = { a: 1, b: { c: 2 } };
+      const cloned = clone(original);
+
+      cloned.a = 99;
+      cloned.b.c = 99;
+
+      expect(original.a).toBe(1);
+      expect(original.b.c).toBe(2);
+    });
+
+    test("handles complex objects with multiple levels", () => {
+      const original = {
+        name: "test",
+        data: {
+          items: [
+            { id: 1, value: "a" },
+            { id: 2, value: "b" },
+          ],
+          meta: { count: 2 },
+        },
+      };
+
+      const cloned = clone(original);
+
+      expect(cloned).toEqual(original);
+      expect(cloned).not.toBe(original);
+      expect(cloned.data).not.toBe(original.data);
+      expect(cloned.data.items).not.toBe(original.data.items);
+      expect(cloned.data.items[0]).not.toBe(original.data.items[0]);
+      expect(cloned.data.meta).not.toBe(original.data.meta);
+    });
+  });
+});

package/utils/__tests__/path.test.ts

@@ -31,3 +31,10 @@ test("example 4", () => {
 
   expect(path(route, xs)).toBeUndefined();
 });
+
+test("example 5", () => {
+  const route = ["a", "b", 0];
+  const xs = { a: { b: [1, 2, 3] } };
+
+  expect(path(route, xs)).toBe(1);
+});

package/utils/clone.ts

@@ -0,0 +1,7 @@
+import { cloneDeep } from "lodash";
+
+export const clone = (value) => {
+  return typeof structuredClone !== "undefined"
+    ? structuredClone(value) // no support for hermes, fallback to cloneDeep
+    : cloneDeep(value);
+};

package/utils/index.ts

@@ -20,8 +20,9 @@ export { mapAccum } from "./mapAccum";
 
 export { mergeRight } from "./mergeRight";
 
+export { clone } from "./clone";
+
 export {
-  cloneDeep as clone,
   flatten,
   drop,
   size,

package/reactHooks/feed/__tests__/useFeedRefresh.test.tsx

@@ -1,75 +0,0 @@
-import { renderHook } from "@testing-library/react-native";
-
-jest.useFakeTimers();
-
-jest.mock("@applicaster/zapp-react-native-utils/reactHooks/navigation", () => ({
-  useIsScreenActive: () => true,
-}));
-
-const { useFeedRefresh, feedRefreshLogger } = require("..");
-
-describe("useFeedRefresh", () => {
-  const reloadData = jest.fn();
-
-  const component = {
-    id: "foo",
-    rules: { enable_data_refreshing: true, refreshing_interval: 61 },
-  };
-
-  it("Calls reloadData after passed time lapses", () => {
-    renderHook(() => useFeedRefresh({ reloadData, component }));
-
-    expect(reloadData).not.toBeCalled();
-    jest.runOnlyPendingTimers();
-    expect(reloadData).toBeCalled();
-  });
-
-  it("Logs warning message if refresh time set below minimum value", () => {
-    const loggerSpy = jest.spyOn(feedRefreshLogger, "warning");
-
-    renderHook(() =>
-      useFeedRefresh({
-        reloadData,
-        component: {
-          ...component,
-          rules: { enable_data_refreshing: true, refreshing_interval: 2 },
-        },
-      })
-    );
-
-    expect(loggerSpy).toBeCalled();
-  });
-
-  it("Calls reloadData on a Component that had a timer setup and was re-mounted", () => {
-    reloadData.mockReset();
-
-    // it is not called before rendering hook"
-    expect(reloadData).not.toBeCalled();
-
-    // it is not called when rendering new component (Not previously rendered)
-    renderHook(() =>
-      useFeedRefresh({ reloadData, component: { ...component, id: "bar" } })
-    );
-
-    expect(reloadData).not.toBeCalled();
-
-    // it is called when rendering previously rendered component",
-    renderHook(() => useFeedRefresh({ reloadData, component }));
-    expect(reloadData).toBeCalled();
-  });
-
-  it("Doesn't refresh data when enable_data_refreshing if false", () => {
-    reloadData.mockReset();
-
-    renderHook(() =>
-      useFeedRefresh({
-        reloadData,
-        component: { ...component, rules: { enable_data_refreshing: false } },
-      })
-    );
-
-    jest.runOnlyPendingTimers();
-
-    expect(reloadData).not.toBeCalled();
-  });
-});

package/reactHooks/feed/useFeedRefresh.tsx

@@ -1,65 +0,0 @@
-import * as React from "react";
-import { path, max } from "ramda";
-import { isTrue } from "@applicaster/zapp-react-native-utils/booleanUtils";
-import { toNumberWithDefault } from "@applicaster/zapp-react-native-utils/numberUtils";
-import { useIsScreenActive } from "@applicaster/zapp-react-native-utils/reactHooks/navigation";
-
-import { reactHooksLogger } from "../logger";
-import { ReloadDataFunction } from "./useFeedLoader";
-
-export const feedRefreshLogger = reactHooksLogger.addSubsystem("feed-refresh");
-
-type Props = {
-  reloadData?: ReloadDataFunction;
-  component: ZappUIComponent;
-};
-
-const previousTimersMap = {};
-const minimumRefreshingInterval = 5;
-const defaultRefreshInterval = 60;
-
-export const useFeedRefresh = ({ reloadData, component }: Props): void => {
-  const isDataRefreshingEnabled = isTrue(
-    path(["rules", "enable_data_refreshing"], component)
-  );
-
-  const refreshing_interval = toNumberWithDefault(
-    defaultRefreshInterval,
-    component?.rules?.refreshing_interval
-  );
-
-  const refreshingIntervalInMilliseconds =
-    max(refreshing_interval, minimumRefreshingInterval) * 1000;
-
-  const isScreenActive = useIsScreenActive();
-
-  React.useEffect(() => {
-    if (isDataRefreshingEnabled && refreshing_interval && isScreenActive) {
-      if (refreshing_interval < minimumRefreshingInterval) {
-        feedRefreshLogger.warning({
-          message: `You set your feed refresh interval to ${refreshing_interval} when minimum value is ${minimumRefreshingInterval}seconds.Your feed will refresh after ${minimumRefreshingInterval}seconds.`,
-        });
-      }
-
-      if (!reloadData || typeof reloadData !== "function") {
-        feedRefreshLogger.warning({
-          message:
-            "reloadData function is undefined, feed refresh feature won't work properly",
-        });
-      }
-
-      if (previousTimersMap[component?.id]) {
-        reloadData?.();
-      }
-
-      const refreshInterval = setInterval(() => {
-        reloadData?.();
-      }, refreshingIntervalInMilliseconds);
-
-      return () => {
-        previousTimersMap[component?.id] = true;
-        clearInterval(refreshInterval);
-      };
-    }
-  }, [reloadData, isScreenActive]);
-};