Merge pull request #50 from Azure/main

Merge main to release/preview/v1

Author: Eskibear

examples/README.md

@@ -4,35 +4,47 @@ These examples show how to use the JavaScript Provider for Azure App Configurati
 
 ## Prerequisites
 
-The sample programs are compatible with [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule).
+The examples are compatible with [LTS versions of Node.js](https://github.com/nodejs/release#release-schedule).
 
-You need [an Azure subscription](https://azure.microsoft.com/free/) and the following Azure resources to run these sample programs:
+You need [an Azure subscription](https://azure.microsoft.com/free/) and the following Azure resources to run the examples:
 
 - [Azure App Configuration store](https://learn.microsoft.com/en-us/azure/azure-app-configuration/quickstart-azure-app-configuration-create?tabs=azure-portal)
 
-Samples retrieve credentials to access your App Configuration store from environment variables.
+The examples retrieve credentials to access your App Configuration store from environment variables.
 Alternatively, edit the source code to include the appropriate credentials.
-See each individual sample for details on which environment variables/credentials it requires to function.
+See each individual example for details on which environment variables/credentials it requires to function.
 
-## Setup
+## Add a key-value
+Add the following key-value to the App Configuration store and leave **Label** and **Content Type** with their default values. For more information about how to add key-values to a store using the Azure portal or the CLI, go to [Create a key-value](./quickstart-azure-app-configuration-create.md#create-a-key-value).
 
-To run the samples using the published version of the package:
+| Key                    | Value          |
+|------------------------|----------------|
+| *app.settings.message* | *Hello World!* |
+
+## Setup & Run
+
+To run the examples using the published version of the package:
 
 1. Install the dependencies using `npm`:
 
     ```bash
     npm install
     ```
 
-2. There are two ways to run the samples using correct credentials:
+2. There are two ways to run the examples using correct credentials:
+
+    - Edit the file `.env.template`, adding the access keys to your App Configuration store. and rename the file from `.env.template` to just `.env`. The examples will read this file automatically.
 
-- Edit the file `.env.template`, adding the correct credentials to access your Azure App Configuration store and rename the file from `.env.template` to just `.env`.
-Then run the samples, it will read this file automatically.
+    - Alternatively, you can set the environment variables to the access keys to your App Configuration store. In this case, setting up the `.env` file is not required. 
+        ```bash
+        npx cross-env APPCONFIG_CONNECTION_STRING="<appconfig connection string>" 
+        ```
+    
+3. Run the examples:
     ```bash
     node helloworld.mjs
     ```
-
-- Alternatively, run a single sample with the correct environment variables set (setting up the `.env` file is not required if you do this), for example (cross-platform):
-    ```bash
-    npx cross-env APPCONFIG_CONNECTION_STRING="<appconfig connection string>" node helloworld.mjs
+    You should see the following output:
+    ```Output
+    Message from Azure App Configuration: Hello World!
     ```

examples/configObject.mjs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+dotenv.config()
+
+/**
+ * This example demonstrates how to construct a configuration object from settings loaded from Azure App Configuration.
+ * If you are using configuration object instead of Map-styled settings, it would minimize the code changes required to use Azure App Configuration in your application.
+ *
+ * When you import configuration into Azure App Configuration from a local .json file, the keys are automatically flattened with a separator if specified.
+ * E.g. if you import the following .json file, specifying the separator as ".":
+ * {
+ *   "app": {
+ *     "settings": {
+ *       "message": "Hello, Azure!"
+ *     }
+ *   }
+ * }
+ *
+ * In the configuration explorer, the key-values will be:
+ *  - Key: "app.settings.message", Value: "Hello, Azure!"
+ *
+ * With the API `constructConfigurationObject`, you can construct a configuration object with the same shape as the original .json file.
+ * The separator is used to split the keys and construct the object.
+ * The constructed object will be: { app: { settings: { message: "Hello, Azure!" } } }
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_CONNECTION_STRING
+ */
+
+import { load } from "@azure/app-configuration-provider";
+const connectionString = process.env.APPCONFIG_CONNECTION_STRING;
+const settings = await load(connectionString, {
+    selectors: [{
+        keyFilter: "app.settings.*"
+    }]
+});
+
+const config = settings.constructConfigurationObject({
+    separator: "."
+});
+
+console.log("Constructed object 'config': ", config);
+console.log(`Message from Azure App Configuration: ${config.app.settings.message}`);

examples/package.json

@@ -1,7 +1,7 @@
 {
   "dependencies": {
     "@azure/app-configuration-provider": "latest",
-    "@azure/identity": "^3.3.0",
+    "@azure/identity": "^4.0.0",
     "dotenv": "^16.3.1"
   }
 }

examples/refresh.mjs

@@ -0,0 +1,44 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import * as dotenv from "dotenv";
+import { promisify } from "util";
+dotenv.config();
+const sleepInMs = promisify(setTimeout);
+
+/**
+ * This example retrives all settings with key following pattern "app.settings.*", i.e. starting with "app.settings.".
+ * With the option `trimKeyPrefixes`, it trims the prefix "app.settings." from keys for simplicity.
+ * Value of config "app.settings.message" will be printed.
+ * It also watches for changes to the key "app.settings.sentinel" and refreshes the configuration when it changes.
+ *
+ * Below environment variables are required for this example:
+ * - APPCONFIG_CONNECTION_STRING
+ */
+
+import { load } from "@azure/app-configuration-provider";
+const connectionString = process.env.APPCONFIG_CONNECTION_STRING;
+const settings = await load(connectionString, {
+    selectors: [{
+        keyFilter: "app.settings.*"
+    }],
+    trimKeyPrefixes: ["app.settings."],
+    refreshOptions: {
+        watchedSettings: [{ key: "app.settings.sentinel" }],
+        refreshIntervalInMs: 10 * 1000 // Default value is 30 seconds, shorted for this sample
+    }
+});
+
+console.log("Using Azure portal or CLI, update the `app.settings.message` value, and then update the `app.settings.sentinel` value in your App Configuration store.")
+
+// eslint-disable-next-line no-constant-condition
+while (true) {
+    // Refreshing the configuration setting
+    await settings.refresh();
+
+    // Current value of message
+    console.log(settings.get("message"));
+
+    // Waiting before the next refresh
+    await sleepInMs(5000);
+}

package-lock.json

@@ -25,7 +25,7 @@
     "dev": "rollup --config --watch",
     "lint": "eslint src/ test/",
     "fix-lint": "eslint src/ test/ --fix",
-    "test": "mocha out/test/*.test.{js,cjs,mjs} --timeout 10000"
+    "test": "mocha out/test/*.test.{js,cjs,mjs} --parallel"
   },
   "repository": {
     "type": "git",
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@azure/app-configuration": "^1.5.0",
-    "@azure/identity": "^3.3.2",
+    "@azure/identity": "^4.0.0",
     "@azure/keyvault-secrets": "^4.7.0"
   }
 }

package.json

@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# Stop on error.
+set -e
+
+# Get the directory of the script.
+SCRIPT_DIR=$(dirname $(readlink -f $0))
+
+# Get the directory of the project.
+PROJECT_BASE_DIR=$(dirname $SCRIPT_DIR)
+
+# Change to the project directory.
+cd $PROJECT_BASE_DIR
+
+# Install dependencies, build, and test.
+echo "npm clean install"
+npm ci
+
+echo "npm run build"
+npm run build
+
+echo "npm run test"
+npm run test
+
+# Create a tarball.
+echo "npm pack"
+npm pack