@azure/app-configuration-importer 1.0.0-preview

package/examples/README.md

@@ -0,0 +1,59 @@
+# Examples for Azure App Configuration Importer
+
+These examples show how to use the App Configuration Importer in some common scenarios
+
+| File Name                                                                          | Description                                                                  |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [fileSourceExample.ts](./src/fileSourceExample.ts)                                 |  Demonstrates importing configuration settings from a File source            |
+| [iterableSourceExample.ts](./src/iterableSourceExample.ts)                         |  Demonstrates importing configuration settings from an Iterable source       |
+| [stringSourceExample.ts](./src/stringSourceExample.ts)                             |  Demonstrates importing configuration settings from a String source          |
+| [readableStreamSourceExample](./src/readableStreamSourceExample.ts)                |  Demonstrates importing configuration settings from a ReadableStream source  |
+
+## Prerequisites
+
+The example are compatible with [LTS version of Node.js](https://github.com/nodejs/release#release-schedule)
+
+You'll need the following Azure resources to run the examples
+
+- An [Azure subscription](https://azure.microsoft.com/free/)
+- An [Azure App Configuration store](https://learn.microsoft.com/azure/azure-app-configuration/quickstart-azure-app-configuration-create?tabs=azure-portal)
+
+Before running the samples in Node, they must be complied to JavaScript using the TypeScript complier. For more information on TypeScript,
+see the [TypeScript documentation](https://www.typescriptlang.org/docs/home). Install the TypeScript compiler using:
+
+```bash
+    npm install -g typescript
+```
+
+## 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 examples using the correct credentials:
+
+    - Edit the file `sample.env`, adding the correct credentials to access your App Configuration. Then rename the file from `sample.env` to just `.env`. The examples will read the file automatically.
+
+    - Alternatively, you can set the environment variable 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. Compile the examples
+
+    ```bash
+        npm run build
+    ```
+
+4. Run whichever example you like 
+
+    ```bash
+        node dist\fileSourceExample.js
+    ```
+
+5. Clean up any configuration settings that may have been imported to your store if you don't plan on using them.

package/examples/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@azure-samples/app-configuration-importer-ts",
+    "private": true,
+    "version": "1.0.0",
+    "description": "Azure App Configuration Importer client library samples for TypeScript",
+    "engines": {
+      "node": ">=18.0.0"
+    },
+    "scripts": {
+      "build": "npm run clean && tsc -b",
+      "clean": "rimraf dist/"
+    },
+    "keywords": [
+      "node",
+      "azure",
+      "typescript",
+      "browser",
+      "cloud"
+    ],
+    "author": "Microsoft Corporation",
+    "license": "MIT",
+    "dependencies": {
+      "dotenv": "latest",
+      "@azure/app-configuration-importer": "latest",
+      "@azure/app-configuration-importer-file-source": "latest"
+    },
+    "devDependencies": {
+      "@types/node": "^18.0.0",
+      "typescript": "~5.4.5",
+      "rimraf": "latest"
+    }
+  }

package/examples/sample.env

@@ -0,0 +1,6 @@
+# This is the connection string for your app-configuration resource
+# You can get this from the Azure portal.
+APPCONFIG_CONNECTION_STRING=<app-configuration connection string goes here>
+
+# This is the connection string for your source app-configuration resource, will be used in the iterableSource example, when importing configuration settings from one store to another
+APPCONFIG_CONNECTION_STRING_SRC_STORE=<app-configuration connection string goes here>

package/examples/testFiles/default.json

@@ -0,0 +1,24 @@
+{
+    "app":{
+        "Settings":{
+            "FontSize": "45",
+            "BackgroundColor": "yellow",
+            "FontColor":"black"
+        }
+    },
+    "FeatureManagement": {
+        "FeatureT": true, 
+        "FeatureU": false, 
+        "FeatureV": {
+            "EnabledFor": [
+                {
+                    "Name": "TimeWindow",
+                    "Parameters": {
+                    "Start": "Wed, 01 May 2019 13:59:59 GMT",
+                    "End": "Mon, 01 July 2019 00:00:00 GMT"
+                    }
+                }
+            ]
+        }
+    }
+}

package/examples/testFiles/kvset.json

@@ -0,0 +1,35 @@
+{
+    "items": [
+      {
+        "key": ".appconfig.featureflag/Beta",
+        "value": "{\"id\":\"Beta\",\"description\":\"Beta feature\",\"enabled\":true,\"conditions\":{\"client_filters\":[]}}",
+        "label": "MyLabel",
+        "content_type": "application/vnd.microsoft.appconfig.ff+json;charset=utf-8",
+        "tags": {}
+      },
+      {
+        "key": "test:app:Database:ConnectionString",
+        "value": "{\"uri\":\"https://keyvault.vault.azure.net/secrets/db-secret\"}",
+        "label": "MyLabel",
+        "content_type": "application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8",
+        "tags": {}
+      },
+      {
+        "key": "test:app:Env",
+        "value": "Debug",
+        "label": "MyLabel",
+        "content_type": null,
+        "tags": {
+            "tag1": "value1",
+            "tag2": "value2"
+        }
+      },
+      {
+        "key": "test:app:BackgroundColor",
+        "value": "yellow",
+        "label": "MyLabel",
+        "content_type": null,
+        "tags": {}
+      }
+    ]
+  }

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@azure/app-configuration-importer",
+  "author": "Microsoft Corporation",
+  "description": "A client library for importing/exporting key-values between configuration sources and Azure App Configuration service",
+  "version": "1.0.0-preview",
+  "sdk-type": "client",
+  "keywords": [
+    "node",
+    "azure",
+    "typescript"
+  ],
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist-esm/src/index.js",
+  "browser": {
+    "./dist-esm/src/internal/stream.js": "./dist-esm/src/internal/stream.browser.js"
+  },
+  "types": "./types/azure-app-configuration-importer.d.ts",
+  "scripts": {
+    "build": "npm run clean && tsc -p . && rollup -c && api-extractor run --local",
+    "test": "cross-env TS_NODE_PROJECT=\"tsconfig.test.json\" mocha -r ts-node/register 'tests/**/*.ts'",
+    "check-format": "eslint src tests",
+    "format": "eslint src tests --fix",
+    "clean": "rimraf dist dist-* types *.tgz *.log"
+  },
+  "dependencies": {
+    "@azure/app-configuration": "1.5.0",
+    "@azure/core-paging": "^1.4.0",
+    "@azure/core-rest-pipeline": "^1.6.0",
+    "flat": "^5.0.2",
+    "js-yaml": "^4.1.0",
+    "properties-file": "^3.5.4",
+    "rxjs": "^7.5.6",
+    "tslib": "^2.2.0",
+    "strip-json-comments": "^3.1.1",
+    "lodash": "^4.17.21"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.22.2",
+    "@rollup/plugin-commonjs": "^21.0.1",
+    "@rollup/plugin-inject": "^4.0.0",
+    "@rollup/plugin-json": "^4.0.0",
+    "@rollup/plugin-multi-entry": "^3.0.0",
+    "@rollup/plugin-node-resolve": "^8.0.0",
+    "@rollup/plugin-replace": "^2.2.0",
+    "@types/chai": "^4.1.6",
+    "@types/flat": "^5.0.2",
+    "@types/js-yaml": "^3.12.7",
+    "@types/lodash": "^4.14.189",
+    "@types/mocha": "^7.0.2",
+    "@types/node": "^18.0.0",
+    "@types/nodegit": "^0.22.5",
+    "@types/sinon": "^10.0.11",
+    "@typescript-eslint/eslint-plugin": "^5.30.0",
+    "@typescript-eslint/parser": "^5.30.0",
+    "chai": "^4.2.0",
+    "colors": "1.4.0",
+    "cross-env": "^7.0.2",
+    "dotenv": "^8.2.0",
+    "eslint": "^8.18.0",
+    "esm": "^3.2.18",
+    "mocha": "^10.2.0",
+    "mocha-junit-reporter": "^2.0.0",
+    "rimraf": "^3.0.0",
+    "rollup": "^2.38.3",
+    "rollup-plugin-commonjs": "^10.1.0",
+    "rollup-plugin-dts": "^4.2.1",
+    "rollup-plugin-node-resolve": "^5.2.0",
+    "rollup-plugin-shim": "^1.0.0",
+    "rollup-plugin-sourcemaps": "^0.4.2",
+    "rollup-plugin-terser": "^5.1.1",
+    "rollup-plugin-typescript2": "^0.31.2",
+    "sinon": "^13.0.2",
+    "ts-node": "^10.0.0",
+    "typescript": "^4.6.3",
+    "@azure/core-http": "^3.0.1"
+  }
+}

package/types/azure-app-configuration-importer.d.ts

@@ -0,0 +1,203 @@
+/// <reference types="node" />
+
+import { AppConfigurationClient } from '@azure/app-configuration';
+import { ConfigurationSetting } from '@azure/app-configuration';
+import { FeatureFlagValue } from '@azure/app-configuration';
+import { ListConfigurationSettingPage } from '@azure/app-configuration';
+import { ListConfigurationSettingsOptions } from '@azure/app-configuration';
+import { PagedAsyncIterableIterator } from '@azure/core-paging';
+import { PageSettings } from '@azure/core-paging';
+import { SecretReferenceValue } from '@azure/app-configuration';
+import { SetConfigurationSettingParam } from '@azure/app-configuration';
+
+/**
+ * Entrypoint class for sync configuration
+ */
+export declare class AppConfigurationImporter {
+    private configurationClient;
+    /**
+     * Initializes a new instance of the AppConfigurationSync class.
+     * @param configurationClient - App configuration client for manipulate the target App Configuration.
+     */
+    constructor(configurationClient: AppConfigurationClient);
+    /**
+     * Import source settings into the Azure App Configuration service
+     *
+     * Example usage:
+     * ```ts
+     * const fileData = fs.readFileSync("mylocalPath").toString();
+     * const result = await asyncClient.Import(new StringConfigurationSettingsSource({data:fileData, format: ConfigurationFormat.Json}));
+     * ```
+     * @param configSettingsSource - A ConfigurationSettingsSource instance.
+     * @param strict - Use strict mode or not.
+     * @param timeout - Seconds of entire import progress timeout
+     * @param progressCallback - Callback for report the progress of import
+     * @param importMode - Determines the behavior when importing key-values. The default value, 'All' will import all key-values in the input file to App Configuration. 'Ignore-Match' will only import settings that have no matching key-value in App Configuration.
+     * @param dryRun - When dry run is enabled, no updates  will be performed to App Configuration. Instead, any updates that would have been performed in a normal run will be printed to the console for review
+     */
+    Import(configSettingsSource: ConfigurationSettingsSource, timeout: number, strict?: boolean, progressCallback?: (progress: ImportResult) => unknown, importMode?: ImportMode, dryRun?: boolean): Promise<void>;
+    private printUpdatesToConsole;
+    private applyUpdatesToServer;
+    private newAdaptiveTaskManager;
+    private executeTasksWithTimeout;
+    private validateImportMode;
+}
+
+/**
+ * Custom error type used during input validation
+ */
+export declare class ArgumentError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Custom error type used when null arguments are passed
+ */
+export declare class ArgumentNullError extends Error {
+}
+
+/**
+ * Enums of configuration Format.
+ */
+export declare enum ConfigurationFormat {
+    Json = 0,
+    Properties = 1,
+    Yaml = 2
+}
+
+/**
+ * Enums of configuration Profile.
+ */
+export declare enum ConfigurationProfile {
+    Default = 0,
+    KvSet = 1
+}
+
+/**
+ * Interface of all ConfigurationSettingsSource
+ */
+export declare interface ConfigurationSettingsSource {
+    /**
+     * Get ConfigurationSettings collection from source.
+     *
+     * @returns Collection of ConfigurationSettings
+     */
+    GetConfigurationSettings(): Promise<Array<SetConfigurationSettingParam<string | FeatureFlagValue | SecretReferenceValue>>>;
+    /**
+     * Get label and prefix filter
+     *
+     * @returns label and prefix
+     */
+    FilterOptions: ListConfigurationSettingsOptions;
+}
+
+/**
+ * Enums of import mode.
+ */
+export declare enum ImportMode {
+    All = 0,
+    IgnoreMatch = 1
+}
+
+export declare interface ImportResult {
+    successCount: number;
+    importCount: number;
+}
+
+export declare class IterableConfigurationSettingsSource implements ConfigurationSettingsSource {
+    FilterOptions: ListConfigurationSettingsOptions;
+    private data;
+    private options;
+    constructor(options: IterableSourceOptions);
+    /**
+     * @inheritdoc
+     */
+    GetConfigurationSettings(): Promise<SetConfigurationSettingParam<string | FeatureFlagValue | SecretReferenceValue>[]>;
+}
+
+export declare type IterableSourceOptions = Options & {
+    data: PagedAsyncIterableIterator<ConfigurationSetting<string>, ListConfigurationSettingPage, PageSettings>;
+    trimPrefix?: string;
+};
+
+/**
+ * Custom error type used for set configuration timeout error
+ */
+export declare class OperationTimeoutError extends Error {
+    constructor();
+}
+
+declare type Options = {
+    label?: string;
+    skipFeatureFlags?: boolean;
+    prefix?: string;
+    contentType?: string;
+    tags?: Tags;
+};
+
+/**
+ * Custom error type used during configuration file parsing
+ */
+export declare class ParseError extends Error {
+    message: string;
+    constructor(message: string);
+}
+
+export declare class ReadableStreamConfigurationSettingsSource implements ConfigurationSettingsSource {
+    FilterOptions: ListConfigurationSettingsOptions;
+    private options;
+    private data;
+    constructor(options: ReadableStreamSourceOptions);
+    GetConfigurationSettings(): Promise<SetConfigurationSettingParam<string | FeatureFlagValue | SecretReferenceValue>[]>;
+}
+
+export declare type ReadableStreamSourceOptions = SourceOptions & {
+    data: ReadableStream<Uint8Array> | NodeJS.ReadableStream;
+};
+
+/**
+ * Base options for configuration import
+ *
+ * @internal
+ */
+declare type SourceOptions = {
+    format: ConfigurationFormat;
+    separator?: string;
+    depth?: number;
+    profile?: ConfigurationProfile;
+} & Options;
+
+/**
+ * ConfigurationSettingsSource implementation of  string data configuration source
+ */
+export declare class StringConfigurationSettingsSource implements ConfigurationSettingsSource {
+    FilterOptions: ListConfigurationSettingsOptions;
+    private options;
+    private data;
+    constructor(options: StringSourceOptions);
+    /**
+     * @inheritdoc
+     */
+    GetConfigurationSettings(): Promise<SetConfigurationSettingParam<string | FeatureFlagValue | SecretReferenceValue>[]>;
+    /**
+     * Get the ConfigurationSettings from supplied data string source.
+     *
+     * @param data The string data being parsed.
+     * @returns Collection of ConfigurationSettings
+     */
+    protected getConfigurationSettingsInternal(data: string): Array<SetConfigurationSettingParam<string | FeatureFlagValue | SecretReferenceValue>>;
+}
+
+/**
+ * Provides options for importing from string data source
+ *
+ */
+export declare type StringSourceOptions = SourceOptions & {
+    data: string;
+};
+
+declare interface Tags {
+    [propertyName: string]: string;
+}
+
+export { }

package/types/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.47.0"
+    }
+  ]
+}