@onekeyfe/react-native-perf-stats 3.0.35 → 3.0.37

package/src/index.tsx

@@ -1,5 +1,8 @@
 import { NitroModules } from 'react-native-nitro-modules';
-import type { ReactNativePerfStats as ReactNativePerfStatsType } from './ReactNativePerfStats.nitro';
+import type {
+  MemoryWarningEvent,
+  ReactNativePerfStats as ReactNativePerfStatsType,
+} from './ReactNativePerfStats.nitro';
 
 const nativeImpl =
   NitroModules.createHybridObject<ReactNativePerfStatsType>('ReactNativePerfStats');
@@ -28,6 +31,11 @@ let jsFpsIntervalId: ReturnType<typeof setInterval> | null = null;
 let jsFpsFrameCount = 0;
 let jsFpsCurrentInterval: number | null = null;
 
+// Module-level latch so forceGarbageCollection's "no GC binding" branch
+// warns exactly once per JS realm. Avoids spamming the console when a
+// memory-warning handler calls forceGarbageCollection on every event.
+let forceGcMissingWarned = false;
+
 /**
  * Start the JS-side FPS ticker. Normally invoked automatically by
  * `ReactNativePerfStats.start` and stopped by `.stop`; exported as
@@ -39,9 +47,17 @@ let jsFpsCurrentInterval: number | null = null;
  * interval is a no-op.
  */
 export function startJsFpsTracker(reportIntervalMs: number = 1000): void {
-  if (jsFpsCurrentInterval === reportIntervalMs) return;
+  // Clamp before use: `setInterval(_, 0)` fires every event-loop tick and
+  // the per-second divide below would race away to Infinity; NaN/negative
+  // values are equally meaningless here. 100 ms is below one rAF frame
+  // on a 60 Hz display, so it's already finer than the data warrants;
+  // 60 s is an arbitrary upper sanity bound.
+  const safeInterval = Number.isFinite(reportIntervalMs)
+    ? Math.max(100, Math.min(60_000, Math.trunc(reportIntervalMs)))
+    : 1000;
+  if (jsFpsCurrentInterval === safeInterval) return;
   stopJsFpsTracker();
-  jsFpsCurrentInterval = reportIntervalMs;
+  jsFpsCurrentInterval = safeInterval;
 
   const tick = () => {
     jsFpsFrameCount += 1;
@@ -50,10 +66,10 @@ export function startJsFpsTracker(reportIntervalMs: number = 1000): void {
   jsFpsRafId = requestAnimationFrame(tick);
 
   jsFpsIntervalId = setInterval(() => {
-    const fps = (jsFpsFrameCount * 1000) / reportIntervalMs;
+    const fps = (jsFpsFrameCount * 1000) / safeInterval;
     jsFpsFrameCount = 0;
     nativeImpl.setJsFpsHint(fps);
-  }, reportIntervalMs);
+  }, safeInterval);
 }
 
 /** Stop the JS-side FPS ticker. Idempotent. */
@@ -89,4 +105,73 @@ export const ReactNativePerfStats = {
   hideOverlay: (): void => nativeImpl.hideOverlay(),
   sample: () => nativeImpl.sample(),
   setJsFpsHint: (fps: number): void => nativeImpl.setJsFpsHint(fps),
+  // Memory pressure is independent of the sampler — these stay active
+  // even after `stop()`. iOS only emits `level: 'critical'`.
+  addMemoryWarningListener: (
+    callback: (event: MemoryWarningEvent) => void,
+  ): number => nativeImpl.addMemoryWarningListener(callback),
+  removeMemoryWarningListener: (id: number): void =>
+    nativeImpl.removeMemoryWarningListener(id),
+  /**
+   * Run the same native reclaim path the OS memory-warning observer
+   * triggers, on demand. Returns immediately (heavy work runs async
+   * on iOS). See the spec doc for what gets dropped on each platform.
+   */
+  cleanupNativeCaches: (): void => nativeImpl.cleanupNativeCaches(),
+
+  /**
+   * Best-effort hint to the JS engine that now is a good time to GC.
+   *
+   * Hermes does not expose a public `collectGarbage` binding in production
+   * builds; the only stable JS-level entry point is the (undocumented)
+   * `HermesInternal.gc` property, which is present in some builds and
+   * absent in others. We feature-detect it and fall back to a no-op so
+   * callers never have to branch.
+   *
+   * Returns `true` only if a GC binding was both found AND invoked
+   * without throwing. A `false` return therefore covers three cases —
+   * binding missing (production Hermes is the common case), binding
+   * present but threw, and any unexpected failure. The first miss is
+   * logged once via `console.warn` so the caller knows it landed in the
+   * "no binding" branch; throws are logged on every occurrence because
+   * those are real errors.
+   *
+   * Cost: when honoured, Hermes does a stop-the-world collection that
+   * can take 100–500 ms — never call this on the hot path. Memory-warning
+   * handlers are the intended use case.
+   */
+  forceGarbageCollection(): boolean {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const g = globalThis as any;
+    const hi = g?.HermesInternal;
+    if (hi && typeof hi.gc === 'function') {
+      try {
+        hi.gc();
+        return true;
+      } catch (e) {
+        console.warn('[PerfStats] HermesInternal.gc threw:', e);
+        return false;
+      }
+    }
+    if (typeof g?.gc === 'function') {
+      // V8-style binding (only present with --expose-gc; never in
+      // production Hermes, but harmless to try).
+      try {
+        g.gc();
+        return true;
+      } catch (e) {
+        console.warn('[PerfStats] globalThis.gc threw:', e);
+        return false;
+      }
+    }
+    if (!forceGcMissingWarned) {
+      forceGcMissingWarned = true;
+      console.warn(
+        '[PerfStats] forceGarbageCollection: no GC binding found ' +
+          '(HermesInternal.gc / globalThis.gc absent). Production Hermes ' +
+          'strips these; this warning fires once per JS realm.',
+      );
+    }
+    return false;
+  },
 };