@react-native-firebase/perf 24.1.1 → 25.0.0

package/lib/{MetricWithAttributes.js → MetricWithAttributes.ts}

@@ -17,23 +17,33 @@
 
 import { hasOwnProperty, isString } from '@react-native-firebase/app/dist/module/common';
 
+import type { RNFBPerfNativeModule } from './types/internal';
+
 let id = 0;
 
 export default class MetricWithAttributes {
-  constructor(native) {
+  protected readonly native: RNFBPerfNativeModule;
+  protected readonly _id: number;
+  protected _attributes: Record<string, string>;
+
+  constructor(native: RNFBPerfNativeModule) {
     this._id = id++;
     this.native = native;
     this._attributes = {};
   }
 
-  getAttribute(attribute) {
+  getAttribute(attribute: string): string | null {
     if (!isString(attribute)) {
       throw new Error("firebase.perf.*.getAttribute(*) 'attribute' must be a string.");
     }
-    return this._attributes[attribute] || null;
+    return hasOwnProperty(this._attributes, attribute) ? this._attributes[attribute]! : null;
+  }
+
+  getAttributes(): Record<string, string> {
+    return Object.assign({}, this._attributes);
   }
 
-  putAttribute(attribute, value) {
+  putAttribute(attribute: string, value: string): void {
     // TODO(VALIDATION): attribute: no leading or trailing whitespace, no leading underscore '_'
     if (!isString(attribute) || attribute.length > 40) {
       throw new Error(

package/lib/ScreenTrace.ts

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { isIOS } from '@react-native-firebase/app/dist/module/common';
+
+import type { RNFBPerfNativeModule } from './types/internal';
+
+let id = 0;
+
+export default class ScreenTrace {
+  readonly native: RNFBPerfNativeModule;
+  private readonly _identifier: string;
+  private readonly _id: number;
+  private _started: boolean;
+  private _stopped: boolean;
+
+  constructor(native: RNFBPerfNativeModule, identifier: string) {
+    this.native = native;
+    this._identifier = identifier;
+    this._id = id++;
+    this._started = false;
+    this._stopped = false;
+  }
+
+  start(): Promise<null> {
+    if (isIOS) {
+      return Promise.reject(new Error('Custom screentraces are currently not supported on iOS.'));
+    }
+    if (this._started) {
+      return Promise.resolve(null);
+    }
+    this._started = true;
+
+    return this.native.startScreenTrace(this._id, this._identifier);
+  }
+
+  stop(): Promise<null> {
+    if (!this._started || this._stopped) {
+      return Promise.resolve(null);
+    }
+    this._stopped = true;
+
+    return this.native.stopScreenTrace(this._id);
+  }
+}

package/lib/Trace.ts

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { hasOwnProperty, isNumber, isString } from '@react-native-firebase/app/dist/module/common';
+
+import MetricWithAttributes from './MetricWithAttributes';
+
+import type { RNFBPerfNativeModule } from './types/internal';
+
+export default class Trace extends MetricWithAttributes {
+  private readonly _identifier: string;
+  private readonly _metrics: Record<string, number>;
+  private _started: boolean;
+  private _stopped: boolean;
+
+  constructor(native: RNFBPerfNativeModule, identifier: string) {
+    super(native);
+    this._identifier = identifier;
+
+    this._metrics = {};
+
+    this._started = false;
+    this._stopped = false;
+  }
+
+  getMetric(metricName: string): number {
+    if (!isString(metricName)) {
+      throw new Error("firebase.perf.Trace.getMetric(*) 'metricName' must be a string.");
+    }
+
+    return hasOwnProperty(this._metrics, metricName) ? this._metrics[metricName]! : 0;
+  }
+
+  getMetrics(): Record<string, number> {
+    return Object.assign({}, this._metrics);
+  }
+
+  putMetric(metricName: string, value: number): void {
+    // TODO(VALIDATION): metricName: no leading or trailing whitespace, no leading underscore '_' character, max length is 32 characters
+    // TODO(VALIDATION): value: >= 0
+    if (!isString(metricName)) {
+      throw new Error("firebase.perf.Trace.putMetric(*, _) 'metricName' must be a string.");
+    }
+
+    if (!isNumber(value)) {
+      throw new Error("firebase.perf.Trace.putMetric(_, *) 'value' must be a number.");
+    }
+
+    this._metrics[metricName] = value;
+  }
+
+  incrementMetric(metricName: string, num?: number): void {
+    // TODO(VALIDATION): metricName: no leading or trailing whitespace, no leading underscore '_' character, max length is 32 characters
+    // TODO(VALIDATION): value: >= 0
+    if (!isString(metricName)) {
+      throw new Error("firebase.perf.Trace.incrementMetric(*, _) 'metricName' must be a string.");
+    }
+
+    const incrementBy = num ?? 1;
+
+    if (!isNumber(incrementBy)) {
+      throw new Error("firebase.perf.Trace.incrementMetric(_, *) 'num' must be a number.");
+    }
+
+    this._metrics[metricName] = this.getMetric(metricName) + incrementBy;
+  }
+
+  removeMetric(metric: string): void {
+    if (!isString(metric)) {
+      throw new Error("firebase.perf.Trace.removeMetric(*) 'metric' must be a string.");
+    }
+
+    delete this._metrics[metric];
+  }
+
+  start(): Promise<null> {
+    if (this._started) {
+      return Promise.resolve(null);
+    }
+    this._started = true;
+
+    return this.native.startTrace(this._id, this._identifier);
+  }
+
+  stop(): Promise<null> {
+    if (this._stopped) {
+      return Promise.resolve(null);
+    }
+    this._stopped = true;
+
+    const traceData = {
+      metrics: Object.assign({}, this._metrics),
+      attributes: Object.assign({}, this._attributes),
+    };
+
+    return this.native.stopTrace(this._id, traceData);
+  }
+}

package/lib/index.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+export type * from './types/perf';
+
+export * from './modular';
+
+export type { FirebasePerformanceTypes } from './types/namespaced';
+
+export * from './namespaced';
+export { default } from './namespaced';

package/lib/modular.ts

@@ -0,0 +1,116 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { getApp } from '@react-native-firebase/app';
+import { MODULAR_DEPRECATION_ARG } from '@react-native-firebase/app/dist/module/common';
+
+import type { FirebaseApp } from '@react-native-firebase/app';
+import type {
+  FirebasePerformance,
+  HttpMetric,
+  HttpMethod,
+  PerformanceSettings,
+  PerformanceTrace,
+  ScreenTrace,
+} from './types/perf';
+
+import type { PerfInternal } from './types/internal';
+
+function perfInternal(performance: FirebasePerformance): PerfInternal {
+  return performance as PerfInternal;
+}
+
+/**
+ * Returns a {@link FirebasePerformance} instance for the given app.
+ * @param app - The FirebaseApp to use. Optional; defaults to the default app.
+ */
+export function getPerformance(app?: FirebaseApp): FirebasePerformance {
+  if (app) {
+    return getApp(app.name).perf() as FirebasePerformance;
+  }
+
+  return getApp().perf() as FirebasePerformance;
+}
+
+/**
+ * Returns a {@link FirebasePerformance} instance for the given app (aligned with the Firebase JS SDK).
+ * Can only be called once per app during initialization in typical usage.
+ *
+ * @param app - The FirebaseApp to use.
+ * @param settings - Optional {@link PerformanceSettings}.
+ */
+export function initializePerformance(
+  app: FirebaseApp,
+  settings?: PerformanceSettings,
+): FirebasePerformance {
+  const perf = getPerformance(app);
+
+  if (settings?.dataCollectionEnabled !== undefined) {
+    perf.dataCollectionEnabled = settings.dataCollectionEnabled;
+  }
+  if (settings?.instrumentationEnabled !== undefined) {
+    perf.instrumentationEnabled = settings.instrumentationEnabled;
+  }
+
+  return perf;
+}
+
+/**
+ * Returns a new {@link PerformanceTrace} instance.
+ * @param performance - The {@link FirebasePerformance} instance to use.
+ * @param name - The name of the trace.
+ */
+export function trace(performance: FirebasePerformance, name: string): PerformanceTrace {
+  return perfInternal(performance).newTrace(name, MODULAR_DEPRECATION_ARG);
+}
+
+/**
+ * Creates an {@link HttpMetric} for a URL and HTTP method (React Native).
+ * @param performance - The {@link FirebasePerformance} instance to use.
+ * @param url - Request URL.
+ * @param httpMethod - HTTP method.
+ */
+export function httpMetric(
+  performance: FirebasePerformance,
+  url: string,
+  httpMethod: HttpMethod,
+): HttpMetric {
+  return perfInternal(performance).newHttpMetric(url, httpMethod, MODULAR_DEPRECATION_ARG);
+}
+
+/**
+ * Creates a {@link ScreenTrace} with the given screen name.
+ * Android only; throws if hardware acceleration is disabled or if Android is 9.0 or 9.1.
+ * @param performance - The {@link FirebasePerformance} instance to use.
+ * @param screenName - Screen name; no leading/trailing whitespace, no leading `_`, max length 100.
+ */
+export function newScreenTrace(performance: FirebasePerformance, screenName: string): ScreenTrace {
+  return perfInternal(performance).newScreenTrace(screenName, MODULAR_DEPRECATION_ARG);
+}
+
+/**
+ * Creates a {@link ScreenTrace} and starts it immediately.
+ * Android only; throws if hardware acceleration is disabled or if Android is 9.0 or 9.1.
+ * @param performance - The {@link FirebasePerformance} instance to use.
+ * @param screenName - Name of the screen.
+ */
+export function startScreenTrace(
+  performance: FirebasePerformance,
+  screenName: string,
+): Promise<ScreenTrace> {
+  return perfInternal(performance).startScreenTrace(screenName, MODULAR_DEPRECATION_ARG);
+}

package/lib/namespaced.ts

@@ -0,0 +1,200 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { isBoolean, isOneOf, isString } from '@react-native-firebase/app/dist/module/common';
+import {
+  createModuleNamespace,
+  FirebaseModule,
+  getFirebaseRoot,
+  type ModuleConfig,
+} from '@react-native-firebase/app/dist/module/internal';
+import { Platform } from 'react-native';
+
+import HttpMetric from './HttpMetric';
+import ScreenTrace from './ScreenTrace';
+import Trace from './Trace';
+import { version } from './version';
+
+import type { ReactNativeFirebase } from '@react-native-firebase/app';
+import type { FirebasePerformanceTypes } from './types/namespaced';
+
+const statics: FirebasePerformanceTypes.Statics = {
+  SDK_VERSION: version,
+};
+
+const namespace = 'perf';
+
+const nativeModuleName = 'RNFBPerfModule' as const;
+
+const VALID_HTTP_METHODS: FirebasePerformanceTypes.HttpMethod[] = [
+  'CONNECT',
+  'DELETE',
+  'GET',
+  'HEAD',
+  'OPTIONS',
+  'PATCH',
+  'POST',
+  'PUT',
+  'TRACE',
+];
+
+class FirebasePerfModule extends FirebaseModule<typeof nativeModuleName> {
+  private _isPerformanceCollectionEnabled: boolean;
+  private _instrumentationEnabled: boolean;
+
+  constructor(
+    app: ReactNativeFirebase.FirebaseAppBase,
+    config: ModuleConfig,
+    customUrlOrRegion?: string | null,
+  ) {
+    super(app, config, customUrlOrRegion);
+    this._isPerformanceCollectionEnabled = this.native.isPerformanceCollectionEnabled;
+    this._instrumentationEnabled = this.native.isInstrumentationEnabled;
+  }
+
+  get isPerformanceCollectionEnabled(): boolean {
+    return this._isPerformanceCollectionEnabled;
+  }
+
+  get instrumentationEnabled(): boolean {
+    return this._instrumentationEnabled;
+  }
+
+  set instrumentationEnabled(enabled: boolean) {
+    if (!isBoolean(enabled)) {
+      throw new Error("firebase.perf().instrumentationEnabled = 'enabled' must be a boolean.");
+    }
+    if (Platform.OS === 'ios') {
+      // We don't change for android as it cannot be set from code, it is set at gradle build time.
+      this._instrumentationEnabled = enabled;
+      // No need to await, as it only takes effect on the next app run.
+      this.native.instrumentationEnabled(enabled);
+    }
+  }
+
+  get dataCollectionEnabled(): boolean {
+    return this._isPerformanceCollectionEnabled;
+  }
+
+  set dataCollectionEnabled(enabled: boolean) {
+    if (!isBoolean(enabled)) {
+      throw new Error("firebase.perf().dataCollectionEnabled = 'enabled' must be a boolean.");
+    }
+    this._isPerformanceCollectionEnabled = enabled;
+    // Keep setter behavior fire-and-forget; callers that need completion should use setPerformanceCollectionEnabled().
+    void this.native.setPerformanceCollectionEnabled(enabled);
+  }
+
+  async setPerformanceCollectionEnabled(enabled: boolean): Promise<null> {
+    if (!isBoolean(enabled)) {
+      throw new Error(
+        "firebase.perf().setPerformanceCollectionEnabled(*) 'enabled' must be a boolean.",
+      );
+    }
+
+    if (Platform.OS === 'ios') {
+      // '_instrumentationEnabled' is updated here as well to maintain backward compatibility. See:
+      // https://github.com/invertase/react-native-firebase/commit/b705622e64d6ebf4ee026d50841e2404cf692f85
+      this._instrumentationEnabled = enabled;
+      await this.native.instrumentationEnabled(enabled);
+    }
+
+    this._isPerformanceCollectionEnabled = enabled;
+    return this.native.setPerformanceCollectionEnabled(enabled);
+  }
+
+  newTrace(identifier: string): Trace {
+    // TODO(VALIDATION): identifier: no leading or trailing whitespace, no leading underscore '_'
+    if (!isString(identifier) || identifier.length > 100) {
+      throw new Error(
+        "firebase.perf().newTrace(*) 'identifier' must be a string with a maximum length of 100 characters.",
+      );
+    }
+
+    return new Trace(this.native, identifier);
+  }
+
+  startTrace(identifier: string): Promise<Trace> {
+    const traceInstance = this.newTrace(identifier);
+    return traceInstance.start().then(() => traceInstance);
+  }
+
+  newScreenTrace(identifier: string): ScreenTrace {
+    if (!isString(identifier) || identifier.length > 100) {
+      throw new Error(
+        "firebase.perf().newScreenTrace(*) 'identifier' must be a string with a maximum length of 100 characters.",
+      );
+    }
+
+    return new ScreenTrace(this.native, identifier);
+  }
+
+  startScreenTrace(identifier: string): Promise<ScreenTrace> {
+    const screenTrace = this.newScreenTrace(identifier);
+    return screenTrace.start().then(() => screenTrace);
+  }
+
+  newHttpMetric(url: string, httpMethod: FirebasePerformanceTypes.HttpMethod): HttpMetric {
+    if (!isString(url)) {
+      throw new Error("firebase.perf().newHttpMetric(*, _) 'url' must be a string.");
+    }
+
+    if (!isOneOf(httpMethod, VALID_HTTP_METHODS)) {
+      throw new Error(
+        `firebase.perf().newHttpMetric(_, *) 'httpMethod' must be one of ${VALID_HTTP_METHODS.join(
+          ', ',
+        )}.`,
+      );
+    }
+
+    return new HttpMetric(this.native, url, httpMethod);
+  }
+}
+
+// import { SDK_VERSION } from '@react-native-firebase/perf';
+export const SDK_VERSION = version;
+
+export type PerfNamespace = ReactNativeFirebase.FirebaseModuleWithStaticsAndApp<
+  FirebasePerformanceTypes.Module,
+  FirebasePerformanceTypes.Statics
+> & {
+  firebase: ReactNativeFirebase.Module;
+  app(name?: string): ReactNativeFirebase.FirebaseApp;
+};
+
+const defaultExport = createModuleNamespace({
+  statics,
+  version,
+  namespace,
+  nativeModuleName,
+  nativeEvents: false,
+  hasMultiAppSupport: false,
+  hasCustomUrlOrRegionSupport: false,
+  ModuleClass: FirebasePerfModule,
+}) as unknown as PerfNamespace;
+
+export default defaultExport;
+
+// import perf, { firebase } from '@react-native-firebase/perf';
+// perf().X(...);
+// firebase.perf().X(...);
+export const firebase =
+  getFirebaseRoot() as unknown as ReactNativeFirebase.FirebaseNamespacedExport<
+    'perf',
+    FirebasePerformanceTypes.Module,
+    FirebasePerformanceTypes.Statics
+  >;

package/lib/types/internal.ts

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import type {
+  FirebasePerformance,
+  HttpMetric,
+  HttpMethod,
+  PerformanceTrace,
+  ScreenTrace,
+} from './perf';
+
+export type PerfModularDeprecationArg = string;
+
+/**
+ * Namespaced perf instance used by modular entrypoints; methods accept an optional modular deprecation token.
+ */
+export interface PerfInternal extends FirebasePerformance {
+  /**
+   * @deprecated Prefer assigning {@link FirebasePerformance.dataCollectionEnabled}.
+   */
+  setPerformanceCollectionEnabled(enabled: boolean): Promise<null>;
+  newTrace(name: string, deprecationArg?: PerfModularDeprecationArg): PerformanceTrace;
+  startTrace(name: string, deprecationArg?: PerfModularDeprecationArg): Promise<PerformanceTrace>;
+  newScreenTrace(screenName: string, deprecationArg?: PerfModularDeprecationArg): ScreenTrace;
+  startScreenTrace(
+    screenName: string,
+    deprecationArg?: PerfModularDeprecationArg,
+  ): Promise<ScreenTrace>;
+  newHttpMetric(
+    url: string,
+    httpMethod: HttpMethod,
+    deprecationArg?: PerfModularDeprecationArg,
+  ): HttpMetric;
+}
+
+export interface RNFBPerfTraceData {
+  metrics: Record<string, number>;
+  attributes: Record<string, string>;
+}
+
+export interface RNFBPerfHttpMetricData {
+  attributes: Record<string, string>;
+  httpResponseCode?: number;
+  requestPayloadSize?: number;
+  responsePayloadSize?: number;
+  responseContentType?: string;
+}
+
+export interface RNFBPerfNativeModule {
+  isPerformanceCollectionEnabled: boolean;
+  isInstrumentationEnabled: boolean;
+  setPerformanceCollectionEnabled(enabled: boolean): Promise<null>;
+  instrumentationEnabled(enabled: boolean): Promise<null>;
+  startTrace(id: number, identifier: string): Promise<null>;
+  stopTrace(id: number, traceData: RNFBPerfTraceData): Promise<null>;
+  startHttpMetric(id: number, url: string, httpMethod: HttpMethod): Promise<null>;
+  stopHttpMetric(id: number, metricData: RNFBPerfHttpMetricData): Promise<null>;
+  startScreenTrace(id: number, identifier: string): Promise<null>;
+  stopScreenTrace(id: number): Promise<null>;
+}
+
+declare module '@react-native-firebase/app/dist/module/internal/NativeModules' {
+  interface ReactNativeFirebaseNativeModules {
+    RNFBPerfModule: RNFBPerfNativeModule;
+  }
+}