@applicaster/zapp-react-native-utils 15.0.0-rc.14 → 15.0.0-rc.140

package/refreshUtils/RefreshCoordinator/__tests__/refreshCoordinator.test.ts

@@ -0,0 +1,206 @@
+import { refreshCoordinator } from "..";
+import { getDataRefreshConfig } from "../utils";
+import { Subscription } from "rxjs";
+
+jest.mock("../utils", () => ({
+  getDataRefreshConfig: jest.fn(),
+}));
+
+describe("RefreshCoordinator", () => {
+  const component = { id: "c1" } as ZappUIComponent;
+  const screenId = "screen-1";
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    refreshCoordinator.clear();
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
+  });
+
+  // ----------------------------------------
+  // Singleton
+  // ----------------------------------------
+  it("returns the same instance via getInstance", () => {
+    const instance1 = refreshCoordinator;
+    const instance2 = (refreshCoordinator as any).constructor.getInstance();
+    expect(instance1).toBe(instance2);
+  });
+
+  // ----------------------------------------
+  // register & unregister
+  // ----------------------------------------
+  it("register starts a timer and returns an unregister function", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const unregister = refreshCoordinator.register(component, screenId);
+
+    expect(typeof unregister).toBe("function");
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+
+    // Calling unregister should remove timer
+    unregister();
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+  });
+
+  it("does not register if refreshing is disabled", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: false,
+    });
+
+    const unregister = refreshCoordinator.register(component, screenId);
+
+    expect(unregister).toBeInstanceOf(Function);
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+  });
+
+  it("replaces existing timer if component is re-registered", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const unregister1 = refreshCoordinator.register(component, screenId);
+    const unregister2 = refreshCoordinator.register(component, screenId);
+
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+    expect(unregister1).toBeInstanceOf(Function);
+    expect(unregister2).toBeInstanceOf(Function);
+  });
+
+  // ----------------------------------------
+  // subscribeTo
+  // ----------------------------------------
+  it("subscribeTo only triggers listener for matching component & screen", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const listener = jest.fn();
+    refreshCoordinator.register(component, screenId);
+    const sub = refreshCoordinator.subscribeTo(component, screenId, listener);
+
+    // Emit a refresh manually via private Subject
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    // Non-matching component should not call listener
+    (refreshCoordinator as any).refresh$.next({
+      component: { id: "other" } as ZappUIComponent,
+      screenId,
+    });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    sub.unsubscribe();
+  });
+
+  // ----------------------------------------
+  // subscribeToAny
+  // ----------------------------------------
+  it("subscribeToAny triggers listener with throttling and replaces previous listener", () => {
+    const listener1 = jest.fn();
+    const listener2 = jest.fn();
+
+    // First subscription
+    const sub1: Subscription = refreshCoordinator.subscribeToAny(listener1);
+    expect(sub1).toBeInstanceOf(Subscription);
+
+    // Second subscription replaces first
+    const sub2: Subscription = refreshCoordinator.subscribeToAny(listener2);
+    expect(sub2).toBeInstanceOf(Subscription);
+
+    // Emit multiple events quickly
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+
+    // Because of throttleTime(500ms), fast events are ignored
+    jest.advanceTimersByTime(500);
+    expect(listener1).not.toHaveBeenCalled();
+    expect(listener2).toHaveBeenCalledTimes(1);
+
+    sub2.unsubscribe();
+  });
+
+  // ----------------------------------------
+  // triggerRefresh
+  // ----------------------------------------
+  it("triggerRefresh emits refresh events for each component", () => {
+    const component1 = { id: "c1" } as ZappUIComponent;
+    const component2 = { id: "c2" } as ZappUIComponent;
+    const listener = jest.fn();
+
+    // Subscribe to all events
+    (refreshCoordinator as any).refresh$.subscribe(listener);
+
+    refreshCoordinator.triggerRefresh([component1, component2], screenId);
+
+    expect(listener).toHaveBeenCalledTimes(2);
+
+    expect(listener).toHaveBeenCalledWith({
+      component: component1,
+      screenId,
+    });
+
+    expect(listener).toHaveBeenCalledWith({
+      component: component2,
+      screenId,
+    });
+  });
+
+  it("triggerRefresh with empty components does nothing", () => {
+    const listener = jest.fn();
+
+    (refreshCoordinator as any).refresh$.subscribe(listener);
+
+    refreshCoordinator.triggerRefresh([], screenId);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("triggerRefresh events are picked up by subscribeTo", () => {
+    const listener = jest.fn();
+
+    refreshCoordinator.subscribeTo(component, screenId, listener);
+    refreshCoordinator.triggerRefresh([component], screenId);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+  });
+
+  // ----------------------------------------
+  // clear
+  // ----------------------------------------
+  it("clear stops all timers, anyListener, and recreates subject", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const listener = jest.fn();
+    refreshCoordinator.register(component, screenId);
+    refreshCoordinator.subscribeToAny(listener);
+
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+    expect((refreshCoordinator as any).anyListenerSubscription).toBeDefined();
+
+    refreshCoordinator.clear();
+
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+    expect((refreshCoordinator as any).anyListenerSubscription).toBeUndefined();
+
+    // New events on new Subject still work
+    const newListener = jest.fn();
+    refreshCoordinator.subscribeToAny(newListener);
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    jest.advanceTimersByTime(500);
+    expect(newListener).toHaveBeenCalled();
+  });
+});

package/refreshUtils/RefreshCoordinator/index.ts

@@ -0,0 +1,245 @@
+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.
+ *
+ * The coordinator serves as an event bus for component refresh events.
+ * It supports two types of producers and any number of consumers:
+ *
+ * Producers (push events into refresh$):
+ *   register()        → starts a periodic timer that emits refresh events
+ *   triggerRefresh()   → imperatively emits refresh events (e.g. pull-to-refresh)
+ *
+ * Consumers (react to refresh events):
+ *   subscribeTo()     → listen to refresh events for a specific component/screen
+ *   subscribeToAny()  → listen to all refresh events with throttling
+ *
+ * Note: subscribeTo() works independently of register(). A component can
+ * subscribe to refresh events without having auto-refresh enabled.
+ * This is how pull-to-refresh works — triggerRefresh() pushes events that
+ * are picked up by existing subscribeTo() listeners in UrlFeedResolver,
+ * even for components that don't have periodic auto-refresh timers.
+ */
+interface IRefreshCoordinator {
+  register(component: ZappUIComponent, screenId: string): () => void;
+  triggerRefresh(components: 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
+ * - Central refresh$ event bus for all refresh events
+ * - Multiple producers: periodic timers (register) and imperative triggers (triggerRefresh)
+ * - Multiple consumers: per-component (subscribeTo) and global (subscribeToAny)
+ * - Producers and consumers are independent — subscribeTo works without register
+ * - 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);
+  }
+
+  /**
+   * Imperatively triggers refresh for the given components on a screen.
+   *
+   * Pushes each component into the central refresh$ stream so that
+   * existing subscribers (e.g. UrlFeedResolver's reloadData) react
+   * to the event. Used by pull-to-refresh and programmatic refresh.
+   */
+  public triggerRefresh(components: ZappUIComponent[], screenId: string): void {
+    components.forEach((component) => {
+      this.refresh$.next({ component, 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,
+  };
+};