@symbiote-native/app-metrics 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,150 @@
 {
   "name": "@symbiote-native/app-metrics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "expo-app-metrics wrapped for SymbioteNative — one framework-agnostic core plus a React adapter, reachable from every framework's core surface and React's additional AppMetricsRoot/AppMetricsErrorBoundary/useNetworkRequestObserver. App startup, frame rate, memory, crash reporting, and session metrics.",
+  "license": "MIT",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "expo-app-metrics",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "angular",
+    "metrics",
+    "crash-reporting"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/app-metrics"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/app-metrics#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./svelte": {
+      "types": "./build/svelte/index.d.ts",
+      "default": "./build/svelte/index.js"
+    },
+    "./solid": {
+      "types": "./build/solid/index.d.ts",
+      "default": "./build/solid/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.detox.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-app-metrics": "57.0.21",
+    "expo-modules-core": "57.0.20"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "solid-js": ">=1.9.0",
+    "svelte": ">=5.56.0",
+    "vue": ">=3.5.0",
+    "@symbiote-native/angular": "^3.1.3",
+    "@symbiote-native/engine": "^1.4.0",
+    "@symbiote-native/solid": "^3.0.5",
+    "@symbiote-native/svelte": "^3.0.5",
+    "@symbiote-native/vue": "^3.1.0",
+    "@symbiote-native/react": "^3.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/solid": {
+      "optional": true
+    },
+    "@symbiote-native/svelte": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "~22.0.8",
+    "@angular/compiler-cli": "~22.0.8",
+    "@angular/core": "~22.0.8",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "solid-js": "^1.9.14",
+    "svelte": "^5.56.0",
+    "typescript": "~6.0.0",
+    "@symbiote-native/angular": "3.1.3",
+    "@symbiote-native/react": "3.1.0",
+    "@symbiote-native/engine": "1.4.0",
+    "@symbiote-native/test-utils": "0.4.5",
+    "@symbiote-native/svelte": "3.0.5",
+    "@symbiote-native/solid": "3.0.5",
+    "@symbiote-native/vue": "3.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
 }

package/src/angular/app-metrics-root.ts

@@ -0,0 +1,14 @@
+import { Component, type OnInit } from '@angular/core';
+import { markFirstRender } from '../core';
+
+/** Marks the first render, so time-to-first-render is measured without a manual call */
+@Component({
+  selector: 'app-metrics-root',
+  standalone: true,
+  template: '<ng-content />',
+})
+export class AppMetricsRoot implements OnInit {
+  ngOnInit(): void {
+    markFirstRender();
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,8 @@
+// No `AppMetricsErrorBoundary` here - blocked on `@angular/core` >=22.2
+// (this package's README "Scope decision")
+export * from '../core';
+export { AppMetricsRoot } from './app-metrics-root';
+export {
+  injectNetworkRequestObserver,
+  type IUseNetworkRequestObserverOptions,
+} from './inject-network-request-observer';

package/src/angular/inject-network-request-observer.ts

@@ -0,0 +1,18 @@
+import { DestroyRef, effect, inject } from '@angular/core';
+import { createNetworkRequestObserverLifecycle } from '../core/network-request-observer-lifecycle';
+import type { NetworkRequestObserver } from '../core';
+import type { IUseNetworkRequestObserverOptions } from '../core/network-request-observer-lifecycle';
+
+export type { IUseNetworkRequestObserverOptions } from '../core/network-request-observer-lifecycle';
+
+/** Angular twin of `expo-app-metrics`'s `useNetworkRequestObserver` */
+export function injectNetworkRequestObserver(
+  getOptions: () => IUseNetworkRequestObserverOptions = () => ({}),
+): NetworkRequestObserver {
+  const destroyRef = inject(DestroyRef);
+  return createNetworkRequestObserverLifecycle(
+    getOptions,
+    filterEffect => effect(filterEffect),
+    cleanup => destroyRef.onDestroy(cleanup),
+  );
+}

package/src/core/app-metrics.ts

@@ -0,0 +1,74 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import { expoAppMetrics } from './native-module';
+import type {
+  ICrashReport,
+  IDebugSession,
+  ILogAttributeValue,
+  ILogEventOptions,
+  IMetricAttributes,
+  IReportErrorInput,
+} from './types';
+
+const NATIVE_MODULE_NAME = 'expo-app-metrics';
+
+/** Marks the moment the app is ready to measure time to first render */
+export function markFirstRender(): void {
+  expoAppMetrics.markFirstRender();
+}
+
+export function markInteractive(attributes?: IMetricAttributes): void {
+  expoAppMetrics.markInteractive(attributes);
+}
+
+/** Persisted locally, dispatched on the next flush as an OpenTelemetry log record */
+export function logEvent(name: string, options?: ILogEventOptions): void {
+  expoAppMetrics.logEvent(name, options);
+}
+
+/** Merged into every subsequent metric and log event, per-record keys win on collision */
+export function setGlobalAttributes(
+  attributes?: Record<string, ILogAttributeValue> | null,
+): void {
+  expoAppMetrics.setGlobalAttributes(attributes);
+}
+
+export async function clearStoredEntries(): Promise<void> {
+  return expoAppMetrics.clearStoredEntries();
+}
+
+/** Debug-only, ordered most-recent-first, each session eagerly includes metrics/logs/crash */
+export async function getInactiveSessions(): Promise<IDebugSession[]> {
+  return expoAppMetrics.getInactiveSessions();
+}
+
+/** Debug-only, includes orphan crashes with `sessionId: null`. @platform android */
+export async function getAllCrashReports(): Promise<ICrashReport[]> {
+  if (Platform.OS !== 'android' || !expoAppMetrics.getAllCrashReports) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getAllCrashReports');
+  }
+  return expoAppMetrics.getAllCrashReports();
+}
+
+/** Called by `installErrorHandler`'s global handler and `AppMetricsErrorBoundary` */
+export function reportError(error: IReportErrorInput): void {
+  expoAppMetrics.reportError(error);
+}
+
+/** The per-launch session, a static reference: repeated calls return the same object */
+export function getMainSession() {
+  return expoAppMetrics.getMainSession();
+}
+
+/** Created when the app becomes active, ended when backgrounded, `null` when none is active */
+export async function getForegroundSession() {
+  return expoAppMetrics.getForegroundSession();
+}
+
+export const NetworkRequestObserver = expoAppMetrics.NetworkRequestObserver;
+export type NetworkRequestObserver = InstanceType<
+  typeof NetworkRequestObserver
+>;
+
+/** Not intended to be constructed from user code, see `getMainSession`/`getForegroundSession` */
+export const Session = expoAppMetrics.Session;
+export type Session = InstanceType<typeof Session>;

package/src/core/index.ts

@@ -0,0 +1,52 @@
+import { installErrorHandler } from './install-error-handler';
+
+export {
+  clearStoredEntries,
+  getAllCrashReports,
+  getForegroundSession,
+  getInactiveSessions,
+  getMainSession,
+  logEvent,
+  markFirstRender,
+  markInteractive,
+  NetworkRequestObserver,
+  reportError,
+  Session,
+  setGlobalAttributes,
+} from './app-metrics';
+export {
+  filterKeyOf,
+  subscribeNetworkRequestObserverEvents,
+} from './network-request-observer-subscription';
+export type {
+  INetworkRequestObserverCallbacks,
+  ISubscribableNetworkRequestObserver,
+} from './network-request-observer-subscription';
+export type {
+  IAppStartupTimes,
+  ICallStack,
+  ICallStackFrame,
+  ICallStackTree,
+  ICrashReport,
+  IDebugSession,
+  IFrameRateMetrics,
+  ILogAttributeValue,
+  ILogEventOptions,
+  ILogRecord,
+  ILogSeverity,
+  IMemoryUsageSnapshot,
+  IMetric,
+  IMetricAttributes,
+  IMetricInput,
+  INetworkRequestCompletedEvent,
+  INetworkRequestFilter,
+  INetworkRequestObserverEvents,
+  INetworkRequestRedirect,
+  INetworkRequestStartedEvent,
+  IReportErrorInput,
+  ISessionType,
+} from './types';
+export { installErrorHandler } from './install-error-handler';
+
+// Live as early as the app pulls this module in, matching upstream's own side effect
+installErrorHandler();

package/src/core/install-error-handler.ts

@@ -0,0 +1,55 @@
+import { reportError } from './app-metrics';
+
+type IErrorHandlerCallback = (error: unknown, isFatal?: boolean) => void;
+
+type IGlobalErrorUtils = {
+  getGlobalHandler(): IErrorHandlerCallback | undefined;
+  setGlobalHandler(handler: IErrorHandlerCallback): void;
+};
+
+let installed = false;
+
+// react-native ships its own ambient `ErrorUtils` global, so a package whose tsconfig pulls
+// that in conflicts with a local `declare global` here (core/engine/src/report-error.ts hit
+// this, TS2451) - reading it off `globalThis` through Reflect sidesteps the whole ambient type
+function globalErrorUtils(): IGlobalErrorUtils | null {
+  const utils: unknown = Reflect.get(globalThis, 'ErrorUtils');
+  if (typeof utils !== 'object' || utils === null) return null;
+  const getGlobalHandler: unknown = Reflect.get(utils, 'getGlobalHandler');
+  const setGlobalHandler: unknown = Reflect.get(utils, 'setGlobalHandler');
+  if (
+    typeof getGlobalHandler !== 'function' ||
+    typeof setGlobalHandler !== 'function'
+  ) {
+    return null;
+  }
+  return {
+    getGlobalHandler: () => Reflect.apply(getGlobalHandler, utils, []),
+    setGlobalHandler: handler =>
+      Reflect.apply(setGlobalHandler, utils, [handler]),
+  };
+}
+
+/** Wraps React Native's global `ErrorUtils` handler, chaining to whatever ran before it */
+export function installErrorHandler(): void {
+  if (installed) return;
+  const errorUtils = globalErrorUtils();
+  if (!errorUtils) return;
+  installed = true;
+
+  const previousHandler = errorUtils.getGlobalHandler();
+  errorUtils.setGlobalHandler((error, isFatal) => {
+    try {
+      const asError = error instanceof Error ? error : undefined;
+      reportError({
+        source: 'global',
+        type: asError?.name,
+        message: asError?.message ?? String(error),
+        stacktrace: asError?.stack,
+        isFatal: isFatal ?? false,
+      });
+    } finally {
+      previousHandler?.(error, isFatal);
+    }
+  });
+}

package/src/core/native-module.ts

@@ -0,0 +1,36 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { NetworkRequestObserver } from './network-request-observer';
+import type { Session } from './session';
+import type {
+  ICrashReport,
+  IDebugSession,
+  ILogAttributeValue,
+  ILogEventOptions,
+  IMetricAttributes,
+  IReportErrorInput,
+} from './types';
+
+const EXPO_APP_METRICS_MODULE_NAME = 'ExpoAppMetrics';
+
+export type INativeAppMetricsModule = {
+  markFirstRender(): void;
+  markInteractive(attributes?: IMetricAttributes): void;
+  logEvent(name: string, options?: ILogEventOptions): void;
+  setGlobalAttributes(
+    attributes?: Record<string, ILogAttributeValue> | null,
+  ): void;
+  clearStoredEntries(): Promise<void>;
+  getInactiveSessions(): Promise<IDebugSession[]>;
+  /** Android's native module only, app-metrics.ts gates it on Platform.OS */
+  getAllCrashReports?(): Promise<ICrashReport[]>;
+  reportError(error: IReportErrorInput): void;
+  getMainSession(): Session;
+  // Typed `@platform ios` upstream, but AppMetricsModule.swift and .kt both implement it
+  getForegroundSession(): Promise<Session | null>;
+  NetworkRequestObserver: typeof NetworkRequestObserver;
+  Session: typeof Session;
+};
+
+export const expoAppMetrics = requireNativeModule<INativeAppMetricsModule>(
+  EXPO_APP_METRICS_MODULE_NAME,
+);

package/src/core/network-request-observer-lifecycle.ts

@@ -0,0 +1,37 @@
+import { NetworkRequestObserver } from './app-metrics';
+import {
+  filterKeyOf,
+  subscribeNetworkRequestObserverEvents,
+} from './network-request-observer-subscription';
+import type { INetworkRequestObserverCallbacks } from './network-request-observer-subscription';
+import type { INetworkRequestFilter } from './types';
+
+export type IUseNetworkRequestObserverOptions =
+  INetworkRequestObserverCallbacks & {
+    /** Applied natively. Omit or pass `null` to observe every request */
+    filter?: INetworkRequestFilter | null;
+  };
+
+// Shared by adapters whose reactivity auto-tracks reads inside a plain effect (Vue's
+// `watchEffect`, Solid's `createEffect`); React's render model doesn't, so it keeps its own wiring
+export function createNetworkRequestObserverLifecycle(
+  getOptions: () => IUseNetworkRequestObserverOptions,
+  runFilterEffect: (effect: () => void) => void,
+  registerCleanup: (cleanup: () => void) => void,
+): NetworkRequestObserver {
+  const initialFilter = getOptions().filter;
+  const observer = new NetworkRequestObserver(initialFilter);
+
+  let appliedFilterKey = filterKeyOf(initialFilter);
+  runFilterEffect(() => {
+    const nextKey = filterKeyOf(getOptions().filter);
+    if (appliedFilterKey === nextKey) return;
+    appliedFilterKey = nextKey;
+    observer.setFilter(getOptions().filter ?? null);
+  });
+
+  registerCleanup(subscribeNetworkRequestObserverEvents(observer, getOptions));
+  registerCleanup(() => observer.release());
+
+  return observer;
+}

package/src/core/network-request-observer-subscription.ts

@@ -0,0 +1,53 @@
+import type {
+  INetworkRequestCompletedEvent,
+  INetworkRequestFilter,
+  INetworkRequestStartedEvent,
+} from './types';
+
+// Field-listed rather than a bare JSON.stringify(filter) so `{ hosts, methods }` and
+// `{ methods, hosts }` (the same filter) don't produce different keys
+export function filterKeyOf(
+  filter: INetworkRequestFilter | null | undefined,
+): string {
+  return JSON.stringify({
+    hosts: filter?.hosts ?? null,
+    methods: filter?.methods ?? null,
+  });
+}
+
+export type INetworkRequestObserverCallbacks = {
+  onStarted?: (event: INetworkRequestStartedEvent) => void;
+  onCompleted?: (event: INetworkRequestCompletedEvent) => void;
+};
+
+export type ISubscribableNetworkRequestObserver = {
+  addListener(
+    event: 'requestStarted',
+    listener: (event: INetworkRequestStartedEvent) => void,
+  ): { remove: () => void };
+  addListener(
+    event: 'requestCompleted',
+    listener: (event: INetworkRequestCompletedEvent) => void,
+  ): { remove: () => void };
+};
+
+// `getCallbacks` is read fresh on every event, so a caller never needs to resubscribe just
+// because its own callbacks changed identity between renders
+export function subscribeNetworkRequestObserverEvents(
+  observer: ISubscribableNetworkRequestObserver,
+  getCallbacks: () => INetworkRequestObserverCallbacks,
+): () => void {
+  const startedSubscription = observer.addListener('requestStarted', event => {
+    getCallbacks().onStarted?.(event);
+  });
+  const completedSubscription = observer.addListener(
+    'requestCompleted',
+    event => {
+      getCallbacks().onCompleted?.(event);
+    },
+  );
+  return () => {
+    startedSubscription.remove();
+    completedSubscription.remove();
+  };
+}

package/src/core/network-request-observer.ts

@@ -0,0 +1,15 @@
+import type { SharedObject } from 'expo-modules-core';
+import type {
+  INetworkRequestFilter,
+  INetworkRequestObserverEvents,
+} from './types';
+
+// Ambient shape only, matching upstream's own declaration - the real class is a native
+// SharedObject subclass exposed as `NetworkRequestObserver` on the native module, constructed
+// from JS with `new NetworkRequestObserver(filter)` and released like any other SharedObject
+export declare class NetworkRequestObserver extends SharedObject<INetworkRequestObserverEvents> {
+  constructor(filter?: INetworkRequestFilter | null);
+
+  /** Applies atomically, in-flight events are emitted under either the old or new filter */
+  setFilter(filter: INetworkRequestFilter | null): void;
+}

package/src/core/report-caught-error.ts

@@ -0,0 +1,26 @@
+import { reportError } from './app-metrics';
+
+/** Shared by every adapter's error-boundary equivalent, builds and reports a caught render error */
+export function reportCaughtError(
+  error: unknown,
+  componentStack?: string,
+): void {
+  const caught = error instanceof Error ? error : undefined;
+  try {
+    reportError({
+      source: 'errorBoundary',
+      type: caught?.name,
+      message: caught?.message ?? String(error),
+      stacktrace: caught?.stack,
+      componentStack,
+      isFatal: false,
+    });
+  } catch (reportingError) {
+    if (__DEV__) {
+      console.warn(
+        '[app-metrics] Failed to report a caught error:',
+        reportingError,
+      );
+    }
+  }
+}

package/src/core/session.ts

@@ -0,0 +1,17 @@
+import type { SharedObject } from 'expo-modules-core';
+import type { ILogRecord, IMetric, IMetricInput, ISessionType } from './types';
+
+// Ambient shape only, matching upstream's own Session.ts - the real class is a native
+// SharedObject subclass exposed as `Session` on the native module (§10b of
+// symbiote-expo-native-module), never constructed from JS
+export declare class Session extends SharedObject {
+  readonly id: string;
+  readonly type: ISessionType;
+  readonly startDate: string;
+
+  isActive(): Promise<boolean>;
+  getEndDate(): Promise<string | null>;
+  getMetrics(): Promise<IMetric[]>;
+  getLogs(): Promise<ILogRecord[]>;
+  addMetric(metric: IMetricInput): Promise<void>;
+}