Expose appConfig.toHierarchicalData() instead of appConfig.data

Author: Eskibear

src/AzureAppConfiguration.ts

@@ -16,12 +16,40 @@ export type AzureAppConfiguration = {
      * @param thisArg - Optional. Value to use as `this` when executing callback.
      */
     onRefresh(listener: () => any, thisArg?: any): Disposable;
-} & IGettable & AppConfigurationData;
+} & IGettable & IHierarchicalData;
 
-interface AppConfigurationData {
-    data: { [key: string]: any };
+interface IHierarchicalData {
+    /**
+     * Convert the Map-styled data structure to hierarchical object properties.
+     * @param options - The options to control the conversion behavior.
+     */
+    toHierarchicalData(options?: HierarchicalDataConversionOptions): Record<string, any>;
+}
+
+export interface HierarchicalDataConversionOptions {
+    /**
+     * The separator to use when converting hierarchical keys to object properties.
+     * Default is '.'.
+     */
+    separator?: string;
+
+    /**
+     * The prefix of hierarchical keys to be converted object properties, usefull when converting a subset of the keys.
+     * Default is '', representing the root of the object.
+     */
+    prefix?: string;
+
+    /**
+     * The behavior when error or amibiguity occurs on converting hierarchical keys.
+     * Default is 'error'.
+     */
+    onError?: "error" | "ignore";
 }
 
 interface IGettable {
+    /**
+     * Get the value of a key-value from the Map-styled data structure.
+     * @param key - The key of the key-value to be retrieved.
+     */
     get<T>(key: string): T | undefined;
 }

src/AzureAppConfigurationImpl.ts

@@ -3,7 +3,7 @@
 
 import { AppConfigurationClient, ConfigurationSetting, ConfigurationSettingId, GetConfigurationSettingOptions, GetConfigurationSettingResponse, ListConfigurationSettingsOptions } from "@azure/app-configuration";
 import { RestError } from "@azure/core-rest-pipeline";
-import { AzureAppConfiguration } from "./AzureAppConfiguration";
+import { AzureAppConfiguration, HierarchicalDataConversionOptions } from "./AzureAppConfiguration";
 import { AzureAppConfigurationOptions } from "./AzureAppConfigurationOptions";
 import { IKeyValueAdapter } from "./IKeyValueAdapter";
 import { JsonKeyValueAdapter } from "./JsonKeyValueAdapter";
@@ -16,16 +16,6 @@ import { createCorrelationContextHeader, requestTracingEnabled } from "./request
 import { KeyFilter, LabelFilter, SettingSelector } from "./types";
 
 export class AzureAppConfigurationImpl implements AzureAppConfiguration {
-    /**
-     * App Configuration data
-     */
-    readonly data: { [key: string]: any } = {};
-
-    /**
-     * Separator for hierarchical keys.
-     */
-    readonly #SEP: string = ".";
-
     /**
      * Hosting key-value pairs in the configuration store.
      */
@@ -178,8 +168,6 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
         for (const [k, v] of keyValues) {
             this.#configMap.set(k, v);
         }
-        // also construct hierarchical data object from map
-        this.#constructDataFromMap();
     }
 
     /**
@@ -193,30 +181,52 @@ export class AzureAppConfigurationImpl implements AzureAppConfiguration {
 
     /**
      * Construct hierarchical data object from map.
-     *
-     * @remarks
-     * This method is used to construct hierarchical data object from map, and it is called after the initial load and each refresh.
      */
-    #constructDataFromMap() {
-        // clean data object in-place
-        for (const key of Object.keys(this.data)) {
-            delete this.data[key];
-        }
+    toHierarchicalData(options?: HierarchicalDataConversionOptions): Record<string, any> {
+        const separator = options?.separator ?? ".";
+        const prefix = options?.prefix ?? "";
+        const onError = options?.onError ?? "error";
+
         // construct hierarchical data object from map
+        const data: Record<string, any> = {};
         for (const [key, value] of this.#configMap) {
-            const segments = key.split(this.#SEP);
-            let current = this.data;
-            // construct hierarchical data object along the path
-            for (let i = 0; i < segments.length - 1; i++) {
-                const segment = segments[i];
-                if (typeof current[segment] !== "object") { // Note: it overwrites existing value if it's not an object
-                    current[segment] = {};
+            if (key.startsWith(prefix)) {
+                const segments = key.slice(prefix.length).split(separator);
+                let current = data;
+                // construct hierarchical data object along the path
+                for (let i = 0; i < segments.length - 1; i++) {
+                    const segment = segments[i];
+                    // undefined or empty string
+                    if (!segment) {
+                        if (onError === "error") {
+                            throw new Error(`invalid key: ${key}`);
+                        } else if (onError === "ignore") {
+                            continue;
+                        } else {
+                            throw new Error(`The value of 'onError' is not supported: ${onError}`);
+                        }
+                    }
+                    // create path if not exist
+                    if (current[segment] === undefined) {
+                        current[segment] = {};
+                    }
+                    // The path has been occupied by a non-object value, causing ambiguity.
+                    if (typeof current[segment] !== "object") {
+                        if (onError === "error") {
+                            throw new Error(`The key '${prefix}${segments.slice(0, i + 1).join(separator)}' is not a valid path.`);
+                        } else if (onError === "ignore") {
+                            current[segment] = {}; // overwrite the non-object value
+                        } else {
+                            throw new Error(`The value of 'onError' is not supported: ${onError}`);
+                        }
+                    }
+                    current = current[segment];
                 }
-                current = current[segment];
+                // set value to the last segment
+                current[segments[segments.length - 1]] = value;
             }
-            // set value to the last segment
-            current[segments[segments.length - 1]] = value;
         }
+        return data;
     }
 
     /**

test/load.test.ts

@@ -174,25 +174,39 @@ describe("load", function () {
     // access data property
     it("should directly access data property", async () => {
         const connectionString = createMockedConnectionString();
-        const settings = await load(connectionString);
+        const settings = await load(connectionString, {
+            selectors: [{
+                keyFilter: "app.settings.*"
+            }]
+        });
         expect(settings).not.undefined;
-        expect(settings.data).not.undefined;
-        expect(settings.data.app.settings.fontColor).eq("red");
-        expect(settings.data.app.settings.fontSize).eq("40");
+        const data = settings.toHierarchicalData();
+        expect(data).not.undefined;
+        expect(data.app.settings.fontColor).eq("red");
+        expect(data.app.settings.fontSize).eq("40");
     });
 
     it("should access property of JSON object content-type with data accessor", async () => {
         const connectionString = createMockedConnectionString();
-        const settings = await load(connectionString);
+        const settings = await load(connectionString, {
+            selectors: [{
+                keyFilter: "app2.*"
+            }]
+        });
         expect(settings).not.undefined;
-        expect(settings.data).not.undefined;
-        expect(settings.data.app2.settings.fontColor).eq("blue");
-        expect(settings.data.app2.settings.fontSize).eq(20);
+        const data = settings.toHierarchicalData();
+        expect(data).not.undefined;
+        expect(data.app2.settings.fontColor).eq("blue");
+        expect(data.app2.settings.fontSize).eq(20);
     });
 
     it("should not access property of JSON content-type object with get()", async () => {
         const connectionString = createMockedConnectionString();
-        const settings = await load(connectionString);
+        const settings = await load(connectionString, {
+            selectors: [{
+                keyFilter: "app2.*"
+            }]
+        });
         expect(settings).not.undefined;
         expect(settings.get("app2.settings")).not.undefined; // JSON object accessed as a whole
         expect(settings.get("app2.settings.fontColor")).undefined;
@@ -207,15 +221,33 @@ describe("load", function () {
      * get() will return "placeholder" for "app3.settings" and "yellow" for "app3.settings.fontColor", as expected.
      * data.app3.settings will return "placeholder" as a whole JSON object, which is not guarenteed to be correct.
      */
-    it("Edge case: Hierarchical key-value pairs with overlapped key prefix.", async () => {
+    it("Edge case: Hierarchical key-value pairs with overlapped key prefix. Ignore error.", async () => {
         const connectionString = createMockedConnectionString();
-        const settings = await load(connectionString);
+        const settings = await load(connectionString, {
+            selectors: [{
+                keyFilter: "app3.settings*"
+            }]
+        });
         expect(settings).not.undefined;
         // use get() method
         expect(settings.get("app3.settings")).eq("placeholder");
         expect(settings.get("app3.settings.fontColor")).eq("yellow");
         // use data property
-        expect(settings.data.app3.settings).not.eq("placeholder"); // not as expected.
-        expect(settings.data.app3.settings.fontColor).eq("yellow");
+        const data = settings.toHierarchicalData({ onError: "ignore" }); // ignore error on hierarchical key conversion
+        expect(data.app3.settings).not.eq("placeholder"); // not as expected.
+        expect(data.app3.settings.fontColor).eq("yellow");
+    });
+
+    it("Edge case: Hierarchical key-value pairs with overlapped key prefix. Default error.", async () => {
+        const connectionString = createMockedConnectionString();
+        const settings = await load(connectionString, {
+            selectors: [{
+                keyFilter: "app3.settings*"
+            }]
+        });
+        expect(settings).not.undefined;
+        expect(() => {
+            settings.toHierarchicalData();
+        }).to.throw("The key 'app3.settings' is not a valid path.");
     });
 });