Define type-specific getters for SSRC (#2519)

RC's existing SDKs define type-specific getters, like getBoolean.
These aren't idiomatic for TS/JS, but have a couple advantages:

1. RC param names, values and types are mutable remotely, so a
simple object can’t guarantee a strict type for application logic. A
formal schema would address this, but feels excessive for the
common case. Type-specific methods are consistent with RC's
current SDKs and ensure appropriate types for application logic.
2. RC Android and iOS SDKs log events when personalized values
are used. A method interface facilitates such additional functionality

Author: erikeldridge

etc/firebase-admin.remote-config.api.md

@@ -13,6 +13,11 @@ export interface AndCondition {
     conditions?: Array<OneOfCondition>;
 }
 
+// @public
+export type DefaultConfig = {
+    [key: string]: string | number | boolean;
+};
+
 // @public
 export type EvaluationContext = {
     randomizationId?: string;
@@ -30,7 +35,7 @@ export function getRemoteConfig(app?: App): RemoteConfig;
 
 // @public
 export interface GetServerTemplateOptions {
-    defaultConfig?: ServerConfig;
+    defaultConfig?: DefaultConfig;
 }
 
 // @public
@@ -169,9 +174,12 @@ export interface RemoteConfigUser {
 }
 
 // @public
-export type ServerConfig = {
-    [key: string]: string | boolean | number;
-};
+export interface ServerConfig {
+    getBoolean(key: string): boolean;
+    getNumber(key: string): number;
+    getString(key: string): string;
+    getValue(key: string): Value;
+}
 
 // @public
 export interface ServerTemplate {
@@ -193,6 +201,17 @@ export interface ServerTemplateData {
 // @public
 export type TagColor = 'BLUE' | 'BROWN' | 'CYAN' | 'DEEP_ORANGE' | 'GREEN' | 'INDIGO' | 'LIME' | 'ORANGE' | 'PINK' | 'PURPLE' | 'TEAL';
 
+// @public
+export interface Value {
+    asBoolean(): boolean;
+    asNumber(): number;
+    asString(): string;
+    getSource(): ValueSource;
+}
+
+// @public
+export type ValueSource = 'static' | 'default' | 'remote';
+
 // @public
 export interface Version {
     description?: string;

src/remote-config/index.ts

@@ -26,6 +26,7 @@ import { RemoteConfig } from './remote-config';
 
 export {
   AndCondition,
+  DefaultConfig,
   EvaluationContext,
   ExplicitParameterValue,
   GetServerTemplateOptions,
@@ -50,6 +51,8 @@ export {
   ServerTemplate,
   ServerTemplateData,
   TagColor,
+  Value,
+  ValueSource,
   Version,
 } from './remote-config-api';
 export { RemoteConfig } from './remote-config';

src/remote-config/internal/value-impl.ts

@@ -0,0 +1,61 @@
+/*!
+ * Copyright 2024 Google Inc.
+ *
+ * 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.
+ */
+
+'use strict';
+
+import {
+  Value,
+  ValueSource,
+} from '../remote-config-api';
+
+/**
+ * Implements type-safe getters for parameter values.
+ * 
+ * Visible for testing.
+ * 
+ * @internal
+ */
+export class ValueImpl implements Value {
+  public static readonly DEFAULT_VALUE_FOR_BOOLEAN = false;
+  public static readonly DEFAULT_VALUE_FOR_STRING = '';
+  public static readonly DEFAULT_VALUE_FOR_NUMBER = 0;
+  public static readonly BOOLEAN_TRUTHY_VALUES = ['1', 'true', 't', 'yes', 'y', 'on'];
+  constructor(
+    private readonly source: ValueSource,
+    private readonly value = ValueImpl.DEFAULT_VALUE_FOR_STRING) { }
+  asString(): string {
+    return this.value;
+  }
+  asBoolean(): boolean {
+    if (this.source === 'static') {
+      return ValueImpl.DEFAULT_VALUE_FOR_BOOLEAN;
+    }
+    return ValueImpl.BOOLEAN_TRUTHY_VALUES.indexOf(this.value.toLowerCase()) >= 0;
+  }
+  asNumber(): number {
+    if (this.source === 'static') {
+      return ValueImpl.DEFAULT_VALUE_FOR_NUMBER;
+    }
+    const num = Number(this.value);
+    if (isNaN(num)) {
+      return ValueImpl.DEFAULT_VALUE_FOR_NUMBER;
+    }
+    return num;
+  }
+  getSource(): ValueSource {
+    return this.source;
+  }
+}

src/remote-config/remote-config-api.ts

@@ -361,7 +361,7 @@ export interface GetServerTemplateOptions {
    * intended before it connects to the Remote Config backend, and so that
    * default values are available if none are set on the backend.
    */
-  defaultConfig?: ServerConfig,
+  defaultConfig?: DefaultConfig;
 }
 
 /**
@@ -541,4 +541,98 @@ export interface ListVersionsOptions {
 /**
  * Represents the configuration produced by evaluating a server template.
  */
-export type ServerConfig = { [key: string]: string | boolean | number }
+export interface ServerConfig {
+
+  /**
+   * Gets the value for the given key as a boolean.
+   *
+   * Convenience method for calling <code>serverConfig.getValue(key).asBoolean()</code>.
+   *
+   * @param key - The name of the parameter.
+   *
+   * @returns The value for the given key as a boolean.
+   */
+  getBoolean(key: string): boolean;
+
+  /**
+   * Gets the value for the given key as a number.
+   *
+   * Convenience method for calling <code>serverConfig.getValue(key).asNumber()</code>.
+   *
+   * @param key - The name of the parameter.
+   *
+   * @returns The value for the given key as a number.
+   */
+  getNumber(key: string): number;
+
+  /**
+   * Gets the value for the given key as a string.
+   * Convenience method for calling <code>serverConfig.getValue(key).asString()</code>.
+   *
+   * @param key - The name of the parameter.
+   *
+   * @returns The value for the given key as a string.
+   */
+  getString(key: string): string;
+
+  /**
+   * Gets the {@link Value} for the given key.
+   *
+   * Ensures application logic will always have a type-safe reference,
+   * even if the parameter is removed remotely.
+   *
+   * @param key - The name of the parameter.
+   *
+   * @returns The value for the given key.
+   */
+  getValue(key: string): Value;
+}
+
+/**
+ * Wraps a parameter value with metadata and type-safe getters.
+ *
+ * Type-safe getters insulate application logic from remote
+ * changes to parameter names and types.
+ */
+export interface Value {
+
+  /**
+   * Gets the value as a boolean.
+   *
+   * The following values (case insensitive) are interpreted as true:
+   * "1", "true", "t", "yes", "y", "on". Other values are interpreted as false.
+   */
+  asBoolean(): boolean;
+
+  /**
+   * Gets the value as a number. Comparable to calling <code>Number(value) || 0</code>.
+   */
+  asNumber(): number;
+
+  /**
+   * Gets the value as a string.
+   */
+  asString(): string;
+
+  /**
+   * Gets the {@link ValueSource} for the given key.
+   */
+  getSource(): 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 config produced by
+ *   evaluating a template.</li>
+ * </ul>
+ */
+export type ValueSource = 'static' | 'default' | 'remote';
+
+/**
+ * Defines the format for in-app default parameter values.
+ */
+export type DefaultConfig = { [key: string]: string | number | boolean };

src/remote-config/remote-config.ts

@@ -18,6 +18,7 @@ import { App } from '../app';
 import * as validator from '../utils/validator';
 import { FirebaseRemoteConfigError, RemoteConfigApiClient } from './remote-config-api-client-internal';
 import { ConditionEvaluator } from './condition-evaluator-internal';
+import { ValueImpl } from './internal/value-impl';
 import {
   ListVersionsOptions,
   ListVersionsResult,
@@ -30,12 +31,13 @@ import {
   Version,
   ExplicitParameterValue,
   InAppDefaultValue,
-  ParameterValueType,
   ServerConfig,
   RemoteConfigParameterValue,
   EvaluationContext,
   ServerTemplateData,
   NamedCondition,
+  Value,
+  DefaultConfig,
   GetServerTemplateOptions,
   InitServerTemplateOptions,
 } from './remote-config-api';
@@ -306,12 +308,20 @@ class RemoteConfigTemplateImpl implements RemoteConfigTemplate {
  */
 class ServerTemplateImpl implements ServerTemplate {
   public cache: ServerTemplateData;
+  private stringifiedDefaultConfig: {[key: string]: string} = {};
 
   constructor(
     private readonly apiClient: RemoteConfigApiClient,
     private readonly conditionEvaluator: ConditionEvaluator,
-    private readonly defaultConfig: ServerConfig = {}
-  ) { }
+    public readonly defaultConfig: DefaultConfig = {}
+  ) {
+    // RC stores all remote values as string, but it's more intuitive
+    // to declare default values with specific types, so this converts
+    // the external declaration to an internal string representation.
+    for (const key in defaultConfig) {
+      this.stringifiedDefaultConfig[key] = String(defaultConfig[key]);
+    }
+  }
 
   /**
    * Fetches and caches the current active version of the project's {@link ServerTemplate}.
@@ -340,10 +350,16 @@ class ServerTemplateImpl implements ServerTemplate {
     const evaluatedConditions = this.conditionEvaluator.evaluateConditions(
       this.cache.conditions, context);
 
-    const evaluatedConfig: ServerConfig = {};
+    const configValues: { [key: string]: Value } = {};
 
+    // Initializes config Value objects with default values.
+    for (const key in this.stringifiedDefaultConfig) {
+      configValues[key] = new ValueImpl('default', this.stringifiedDefaultConfig[key]);
+    }
+
+    // Overlays config Value objects derived by evaluating the template.
     for (const [key, parameter] of Object.entries(this.cache.parameters)) {
-      const { conditionalValues, defaultValue, valueType } = parameter;
+      const { conditionalValues, defaultValue } = parameter;
 
       // Supports parameters with no conditional values.
       const normalizedConditionalValues = conditionalValues || {};
@@ -366,7 +382,7 @@ class ServerTemplateImpl implements ServerTemplate {
 
       if (parameterValueWrapper) {
         const parameterValue = (parameterValueWrapper as ExplicitParameterValue).value;
-        evaluatedConfig[key] = this.parseRemoteConfigParameterValue(valueType, parameterValue);
+        configValues[key] = new ValueImpl('remote', parameterValue);
         continue;
       }
 
@@ -381,46 +397,28 @@ class ServerTemplateImpl implements ServerTemplate {
       }
 
       const parameterDefaultValue = (defaultValue as ExplicitParameterValue).value;
-      evaluatedConfig[key] = this.parseRemoteConfigParameterValue(valueType, parameterDefaultValue);
+      configValues[key] = new ValueImpl('remote', parameterDefaultValue);
     }
 
-    const mergedConfig = {};
-
-    // Merges default config and rendered config, prioritizing the latter.
-    Object.assign(mergedConfig, this.defaultConfig, evaluatedConfig);
-
-    // Enables config to be a convenient object, but with the ability to perform additional
-    // functionality when a value is retrieved.
-    const proxyHandler = {
-      get(target: ServerConfig, prop: string) {
-        return target[prop];
-      }
-    };
-
-    return new Proxy(mergedConfig, proxyHandler);
+    return new ServerConfigImpl(configValues);
   }
+}
 
-  /**
-   * Private helper method that coerces a parameter value string to the {@link ParameterValueType}.
-   */
-  private parseRemoteConfigParameterValue(parameterType: ParameterValueType | undefined,
-    parameterValue: string): string | number | boolean {
-    const BOOLEAN_TRUTHY_VALUES = ['1', 'true', 't', 'yes', 'y', 'on'];
-    const DEFAULT_VALUE_FOR_NUMBER = 0;
-    const DEFAULT_VALUE_FOR_STRING = '';
-
-    if (parameterType === 'BOOLEAN') {
-      return BOOLEAN_TRUTHY_VALUES.indexOf(parameterValue) >= 0;
-    } else if (parameterType === 'NUMBER') {
-      const num = Number(parameterValue);
-      if (isNaN(num)) {
-        return DEFAULT_VALUE_FOR_NUMBER;
-      }
-      return num;
-    } else {
-      // Treat everything else as string
-      return parameterValue || DEFAULT_VALUE_FOR_STRING;
-    }
+class ServerConfigImpl implements ServerConfig {
+  constructor(
+    private readonly configValues: { [key: string]: Value },
+  ){}
+  getBoolean(key: string): boolean {
+    return this.getValue(key).asBoolean();
+  }
+  getNumber(key: string): number {
+    return this.getValue(key).asNumber();
+  }
+  getString(key: string): string {
+    return this.getValue(key).asString();
+  }
+  getValue(key: string): Value {
+    return this.configValues[key] || new ValueImpl('static');
   }
 }
 

test/unit/index.spec.ts

@@ -98,6 +98,7 @@ import './remote-config/index.spec';
 import './remote-config/remote-config.spec';
 import './remote-config/remote-config-api-client.spec';
 import './remote-config/condition-evaluator.spec';
+import './remote-config/internal/value-impl.spec';
 
 // AppCheck
 import './app-check/app-check.spec';