Merge 8f92245 into e25317f

Author: Samruddhi90

common/api-review/remote-config.api.md

@@ -5,10 +5,23 @@
 ```ts
 
 import { FirebaseApp } from '@firebase/app';
+import { FirebaseError } from '@firebase/app';
 
 // @public
 export function activate(remoteConfig: RemoteConfig): Promise<boolean>;
 
+// @public
+export interface ConfigUpdate {
+    getUpdatedKeys(): Set<string>;
+}
+
+// @public
+export interface ConfigUpdateObserver {
+    complete: () => void;
+    error: (error: FirebaseError) => void;
+    next: (configUpdate: ConfigUpdate) => void;
+}
+
 // @public
 export interface CustomSignals {
     // (undocumented)
@@ -64,6 +77,9 @@ export function isSupported(): Promise<boolean>;
 // @public
 export type LogLevel = 'debug' | 'error' | 'silent';
 
+// @public
+export function onConfigUpdate(remoteConfig: RemoteConfig, observer: ConfigUpdateObserver): Promise<Unsubscribe>;
+
 // @public
 export interface RemoteConfig {
     app: FirebaseApp;
@@ -93,6 +109,9 @@ export function setCustomSignals(remoteConfig: RemoteConfig, customSignals: Cust
 // @public
 export function setLogLevel(remoteConfig: RemoteConfig, logLevel: LogLevel): void;
 
+// @public
+export type Unsubscribe = () => void;
+
 // @public
 export interface Value {
     asBoolean(): boolean;

docs-devsite/_toc.yaml

@@ -607,6 +607,10 @@ toc:
 - title: remote-config
   path: /docs/reference/js/remote-config.md
   section:
+  - title: ConfigUpdate
+    path: /docs/reference/js/remote-config.configupdate.md
+  - title: ConfigUpdateObserver
+    path: /docs/reference/js/remote-config.configupdateobserver.md
   - title: CustomSignals
     path: /docs/reference/js/remote-config.customsignals.md
   - title: FetchResponse

docs-devsite/remote-config.configupdate.md

@@ -0,0 +1,39 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# ConfigUpdate interface
+Contains information about which keys have been updated.
+
+<b>Signature:</b>
+
+```typescript
+export interface ConfigUpdate 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [getUpdatedKeys()](./remote-config.configupdate.md#configupdategetupdatedkeys) | Parameter keys whose values have been updated from the currently activated values. Includes keys that are added, deleted, or whose value, value source, or metadata has changed. |
+
+## ConfigUpdate.getUpdatedKeys()
+
+Parameter keys whose values have been updated from the currently activated values. Includes keys that are added, deleted, or whose value, value source, or metadata has changed.
+
+<b>Signature:</b>
+
+```typescript
+getUpdatedKeys(): Set<string>;
+```
+<b>Returns:</b>
+
+Set&lt;string&gt;
+

docs-devsite/remote-config.configupdateobserver.md

@@ -0,0 +1,59 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# ConfigUpdateObserver interface
+Observer interface for receiving real-time Remote Config update notifications.
+
+NOTE: Although an `complete` callback can be provided, it will never be called because the ConfigUpdate stream is never-ending.
+
+<b>Signature:</b>
+
+```typescript
+export interface ConfigUpdateObserver 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [complete](./remote-config.configupdateobserver.md#configupdateobservercomplete) | () =&gt; void | Called when the stream is gracefully terminated. |
+|  [error](./remote-config.configupdateobserver.md#configupdateobservererror) | (error: [FirebaseError](./util.firebaseerror.md#firebaseerror_class)<!-- -->) =&gt; void | Called if an error occurs during the stream. |
+|  [next](./remote-config.configupdateobserver.md#configupdateobservernext) | (configUpdate: [ConfigUpdate](./remote-config.configupdate.md#configupdate_interface)<!-- -->) =&gt; void | Called when a new ConfigUpdate is available. |
+
+## ConfigUpdateObserver.complete
+
+Called when the stream is gracefully terminated.
+
+<b>Signature:</b>
+
+```typescript
+complete: () => void;
+```
+
+## ConfigUpdateObserver.error
+
+Called if an error occurs during the stream.
+
+<b>Signature:</b>
+
+```typescript
+error: (error: FirebaseError) => void;
+```
+
+## ConfigUpdateObserver.next
+
+Called when a new ConfigUpdate is available.
+
+<b>Signature:</b>
+
+```typescript
+next: (configUpdate: ConfigUpdate) => void;
+```

docs-devsite/remote-config.md

@@ -28,6 +28,7 @@ The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environm
 |  [getNumber(remoteConfig, key)](./remote-config.md#getnumber_476c09f) | Gets the value for the given key as a number.<!-- -->Convenience method for calling <code>remoteConfig.getValue(key).asNumber()</code>. |
 |  [getString(remoteConfig, key)](./remote-config.md#getstring_476c09f) | Gets the value for the given key as a string. Convenience method for calling <code>remoteConfig.getValue(key).asString()</code>. |
 |  [getValue(remoteConfig, key)](./remote-config.md#getvalue_476c09f) | Gets the [Value](./remote-config.value.md#value_interface) for the given key. |
+|  [onConfigUpdate(remoteConfig, observer)](./remote-config.md#onconfigupdate_8b13b26) | Starts listening for real-time config updates from the Remote Config backend and automatically fetches updates from the RC backend when they are available.<p>If a connection to the Remote Config backend is not already open, calling this method will open it. Multiple listeners can be added by calling this method again, but subsequent calls re-use the same connection to the backend. |
 |  [setCustomSignals(remoteConfig, customSignals)](./remote-config.md#setcustomsignals_aeeb95e) | Sets the custom signals for the app instance. |
 |  [setLogLevel(remoteConfig, logLevel)](./remote-config.md#setloglevel_039a45b) | Defines the log level to use. |
 |  <b>function()</b> |
@@ -37,6 +38,8 @@ The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environm
 
 |  Interface | Description |
 |  --- | --- |
+|  [ConfigUpdate](./remote-config.configupdate.md#configupdate_interface) | Contains information about which keys have been updated. |
+|  [ConfigUpdateObserver](./remote-config.configupdateobserver.md#configupdateobserver_interface) | Observer interface for receiving real-time Remote Config update notifications.<!-- -->NOTE: Although an <code>complete</code> callback can be provided, it will never be called because the ConfigUpdate stream is never-ending. |
 |  [CustomSignals](./remote-config.customsignals.md#customsignals_interface) | Defines the type for representing custom signals and their values.<p>The values in CustomSignals must be one of the following types:<ul> <li><code>string</code> <li><code>number</code> <li><code>null</code> </ul> |
 |  [FetchResponse](./remote-config.fetchresponse.md#fetchresponse_interface) | Defines a successful response (200 or 304).<p>Modeled after the native <code>Response</code> interface, but simplified for Remote Config's use case. |
 |  [FirebaseRemoteConfigObject](./remote-config.firebaseremoteconfigobject.md#firebaseremoteconfigobject_interface) | Defines a self-descriptive reference for config key-value pairs. |
@@ -51,6 +54,7 @@ The Firebase Remote Config Web SDK. This SDK does not work in a Node.js environm
 |  --- | --- |
 |  [FetchStatus](./remote-config.md#fetchstatus) | Summarizes the outcome of the last attempt to fetch config from the Firebase Remote Config server.<ul> <li>"no-fetch-yet" indicates the [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance has not yet attempted to fetch config, or that SDK initialization is incomplete.</li> <li>"success" indicates the last attempt succeeded.</li> <li>"failure" indicates the last attempt failed.</li> <li>"throttle" indicates the last attempt was rate-limited.</li> </ul> |
 |  [LogLevel](./remote-config.md#loglevel) | Defines levels of Remote Config logging. |
+|  [Unsubscribe](./remote-config.md#unsubscribe) | A function that unsubscribes from a real-time event stream. |
 |  [ValueSource](./remote-config.md#valuesource) | Indicates the source of a value.<ul> <li>"static" indicates the value was defined by a static constant.</li> <li>"default" indicates the value was defined by default config.</li> <li>"remote" indicates the value was defined by fetched config.</li> </ul> |
 
 ## function(app, ...)
@@ -282,6 +286,31 @@ export declare function getValue(remoteConfig: RemoteConfig, key: string): Value
 
 The value for the given key.
 
+### onConfigUpdate(remoteConfig, observer) {:#onconfigupdate_8b13b26}
+
+Starts listening for real-time config updates from the Remote Config backend and automatically fetches updates from the RC backend when they are available.
+
+<p>If a connection to the Remote Config backend is not already open, calling this method will open it. Multiple listeners can be added by calling this method again, but subsequent calls re-use the same connection to the backend.
+
+<b>Signature:</b>
+
+```typescript
+export declare function onConfigUpdate(remoteConfig: RemoteConfig, observer: ConfigUpdateObserver): Promise<Unsubscribe>;
+```
+
+#### Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  remoteConfig | [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) | The [RemoteConfig](./remote-config.remoteconfig.md#remoteconfig_interface) instance. |
+|  observer | [ConfigUpdateObserver](./remote-config.configupdateobserver.md#configupdateobserver_interface) | The [ConfigUpdateObserver](./remote-config.configupdateobserver.md#configupdateobserver_interface) to be notified of config updates. |
+
+<b>Returns:</b>
+
+Promise&lt;[Unsubscribe](./remote-config.md#unsubscribe)<!-- -->&gt;
+
+An [Unsubscribe](./remote-config.md#unsubscribe) function to remove the listener.
+
 ### setCustomSignals(remoteConfig, customSignals) {:#setcustomsignals_aeeb95e}
 
 Sets the custom signals for the app instance.
@@ -365,6 +394,16 @@ Defines levels of Remote Config logging.
 export type LogLevel = 'debug' | 'error' | 'silent';
 ```
 
+## Unsubscribe
+
+A function that unsubscribes from a real-time event stream.
+
+<b>Signature:</b>
+
+```typescript
+export type Unsubscribe = () => void;
+```
+
 ## ValueSource
 
 Indicates the source of a value.

packages/remote-config/src/api.ts

@@ -22,7 +22,9 @@ import {
   LogLevel as RemoteConfigLogLevel,
   RemoteConfig,
   Value,
-  RemoteConfigOptions
+  RemoteConfigOptions,
+  ConfigUpdateObserver,
+  Unsubscribe
 } from './public_types';
 import { RemoteConfigAbortSignal } from './client/remote_config_fetch_client';
 import {
@@ -351,3 +353,29 @@ export async function setCustomSignals(
     );
   }
 }
+
+// TODO: Add public document for the Remote Config Realtime API guide on the Web Platform.
+/**
+ * Starts listening for real-time config updates from the Remote Config backend and automatically
+ * fetches updates from the RC backend when they are available.
+ *
+ * <p>If a connection to the Remote Config backend is not already open, calling this method will
+ * open it. Multiple listeners can be added by calling this method again, but subsequent calls
+ * re-use the same connection to the backend.
+ *
+ * @param remoteConfig - The {@link RemoteConfig} instance.
+ * @param observer - The {@link ConfigUpdateObserver} to be notified of config updates.
+ * @returns An {@link Unsubscribe} function to remove the listener.
+ *
+ * @public
+ */
+export async function onConfigUpdate(
+  remoteConfig: RemoteConfig,
+  observer: ConfigUpdateObserver
+): Promise<Unsubscribe> {
+  const rc = getModularInstance(remoteConfig) as RemoteConfigImpl;
+  await rc._realtimeHandler.addObserver(observer);
+  return () => {
+    rc._realtimeHandler.removeObserver(observer);
+  };
+}

packages/remote-config/src/client/eventEmitter.ts

@@ -0,0 +1,104 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file 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 { assert } from '@firebase/util';
+
+// TODO: Consolidate the Visibility monitoring API code into a shared utility function in firebase/util to be used by both packages/database and packages/remote-config.
+/**
+ * Base class to be used if you want to emit events. Call the constructor with
+ * the set of allowed event names.
+ */
+export abstract class EventEmitter {
+  private listeners_: {
+    [eventType: string]: Array<{
+      callback(...args: unknown[]): void;
+      context: unknown;
+    }>;
+  } = {};
+
+  constructor(private allowedEvents_: string[]) {
+    assert(
+      Array.isArray(allowedEvents_) && allowedEvents_.length > 0,
+      'Requires a non-empty array'
+    );
+  }
+
+  /**
+   * To be overridden by derived classes in order to fire an initial event when
+   * somebody subscribes for data.
+   *
+   * @returns {Array.<*>} Array of parameters to trigger initial event with.
+   */
+  abstract getInitialEvent(eventType: string): unknown[];
+
+  /**
+   * To be called by derived classes to trigger events.
+   */
+  protected trigger(eventType: string, ...varArgs: unknown[]): void {
+    if (Array.isArray(this.listeners_[eventType])) {
+      // Clone the list, since callbacks could add/remove listeners.
+      const listeners = [...this.listeners_[eventType]];
+
+      for (let i = 0; i < listeners.length; i++) {
+        listeners[i].callback.apply(listeners[i].context, varArgs);
+      }
+    }
+  }
+
+  on(
+    eventType: string,
+    callback: (a: unknown) => void,
+    context: unknown
+  ): void {
+    this.validateEventType_(eventType);
+    this.listeners_[eventType] = this.listeners_[eventType] || [];
+    this.listeners_[eventType].push({ callback, context });
+
+    const eventData = this.getInitialEvent(eventType);
+    if (eventData) {
+      //@ts-ignore
+      callback.apply(context, eventData);
+    }
+  }
+
+  off(
+    eventType: string,
+    callback: (a: unknown) => void,
+    context: unknown
+  ): void {
+    this.validateEventType_(eventType);
+    const listeners = this.listeners_[eventType] || [];
+    for (let i = 0; i < listeners.length; i++) {
+      if (
+        listeners[i].callback === callback &&
+        (!context || context === listeners[i].context)
+      ) {
+        listeners.splice(i, 1);
+        return;
+      }
+    }
+  }
+
+  private validateEventType_(eventType: string): void {
+    assert(
+      this.allowedEvents_.find(et => {
+        return et === eventType;
+      }),
+      'Unknown event: ' + eventType
+    );
+  }
+}