@backstage/config - npm Package Compare versions

Comparing version 0.0.0-nightly-20217521743 to 0.0.0-nightly-20218622135

CHANGELOG.md

 # @backstage/config
 
-## 0.0.0-nightly-20217521743
+## 0.0.0-nightly-20218622135
 
 ### Patch Changes
 
+- f88b2c7db: Documented `Config` interface and mark types as public.
+
+## 0.1.8
+
+### Patch Changes
+
+- 47113f1f1: Only warn once per key when trying to read visibility-filtered values
+
+## 0.1.7
+
+### Patch Changes
+
+- 90f25476a: Extended the `Config` interface to have an optional `subscribe` method that can be used be notified of updates to the configuration.
+
+## 0.1.6
+
+### Patch Changes
+
 - e9d3983ee: Add warning when trying to access configuration values that have been filtered out by visibility.
@@ -8,0 +26,0 @@

dist/index.cjs.js

@@ -49,2 +49,3 @@ 'use strict';
     this.prefix = prefix;
+    this.notifiedFilteredKeys = new Set();
   }
@@ -90,3 +91,4 @@ static fromConfigs(configs) {
           const fullKey = this.fullKey(key);
-          if ((_b = this.filteredKeys) == null ? void 0 : _b.includes(fullKey)) {
+          if (((_b = this.filteredKeys) == null ? void 0 : _b.includes(fullKey)) && !this.notifiedFilteredKeys.has(fullKey)) {
+            this.notifiedFilteredKeys.add(fullKey);
             console.warn(`Failed to read configuration value at '${fullKey}' as it is not visible. See https://backstage.io/docs/conf/defining#visibility for instructions on how to make it visible.`);
@@ -144,3 +146,4 @@ }
         const fullKey = this.fullKey(key);
-        if ((_a = this.filteredKeys) == null ? void 0 : _a.some((k) => k.startsWith(fullKey))) {
+        if (((_a = this.filteredKeys) == null ? void 0 : _a.some((k) => k.startsWith(fullKey))) && !this.notifiedFilteredKeys.has(key)) {
+          this.notifiedFilteredKeys.add(key);
           console.warn(`Failed to read configuration array at '${key}' as it does not have any visible elements. See https://backstage.io/docs/conf/defining#visibility for instructions on how to make it visible.`);
@@ -225,3 +228,4 @@ }
         const fullKey = this.fullKey(key);
-        if ((_a = this.filteredKeys) == null ? void 0 : _a.includes(fullKey)) {
+        if (((_a = this.filteredKeys) == null ? void 0 : _a.includes(fullKey)) && !this.notifiedFilteredKeys.has(fullKey)) {
+          this.notifiedFilteredKeys.add(fullKey);
           console.warn(`Failed to read configuration value at '${fullKey}' as it is not visible. See https://backstage.io/docs/conf/defining#visibility for instructions on how to make it visible.`);
@@ -228,0 +232,0 @@ }

dist/index.d.ts

@@ -0,32 +1,144 @@
+/**
+ * A type representing all allowed JSON primitive values.
+ *
+ * @public
+ */
 declare type JsonPrimitive = number | string | boolean | null;
+/**
+ * A type representing all allowed JSON object values.
+ *
+ * @public
+ */
 declare type JsonObject = {
     [key in string]?: JsonValue;
 };
+/**
+ * A type representing all allowed JSON array values.
+ *
+ * @public
+ */
 interface JsonArray extends Array<JsonValue> {
 }
+/**
+ * A type representing all allowed JSON values.
+ *
+ * @public
+ */
 declare type JsonValue = JsonObject | JsonArray | JsonPrimitive;
+/**
+ * A serialized form of configuration data that carries additional context.
+ *
+ * @public
+ */
 declare type AppConfig = {
+    /**
+     * A string representing the source of this configuration data, for example a filepath.
+     */
     context: string;
+    /**
+     * The configuration data itself.
+     */
     data: JsonObject;
+    /**
+     * A list of keys that where filtered out from the configuration when it was loaded.
+     *
+     * This can be used to warn the user if they try to read any of these keys.
+     */
     filteredKeys?: string[];
 };
+/**
+ * The interface used to represent static configuration at runtime.
+ *
+ * @public
+ */
 declare type Config = {
+    /**
+     * Subscribes to the configuration object in order to receive a notification
+     * whenever any value within the configuration has changed.
+     *
+     * This method is optional to implement, and consumers need to check if it is
+     * implemented before invoking it.
+     */
+    subscribe?(onChange: () => void): {
+        unsubscribe: () => void;
+    };
+    /**
+     * Checks whether the given key is present.
+     */
     has(key: string): boolean;
+    /**
+     * Lists all available configuration keys.
+     */
     keys(): string[];
+    /**
+     * Same as `getOptional`, but will throw an error if there's no value for the given key.
+     */
     get<T = JsonValue>(key?: string): T;
+    /**
+     * Read out all configuration data for the given key.
+     *
+     * Usage of this method should be avoided as the typed alternatives provide
+     * much better error reporting. The main use-case of this method is to determine
+     * the type of a configuration value in the case where there are multiple possible
+     * shapes of the configuration.
+     */
     getOptional<T = JsonValue>(key?: string): T | undefined;
+    /**
+     * Same as `getOptionalConfig`, but will throw an error if there's no value for the given key.
+     */
     getConfig(key: string): Config;
+    /**
+     * Creates a sub-view of the configuration object.
+     * The configuration value at the position of the provided key must be an object.
+     */
     getOptionalConfig(key: string): Config | undefined;
+    /**
+     * Same as `getOptionalConfigArray`, but will throw an error if there's no value for the given key.
+     */
     getConfigArray(key: string): Config[];
+    /**
+     * Creates a sub-view of an array of configuration objects.
+     * The configuration value at the position of the provided key must be an array of objects.
+     */
     getOptionalConfigArray(key: string): Config[] | undefined;
+    /**
+     * Same as `getOptionalNumber`, but will throw an error if there's no value for the given key.
+     */
     getNumber(key: string): number;
+    /**
+     * Reads a configuration value at the given key, expecting it to be a number.
+     */
     getOptionalNumber(key: string): number | undefined;
+    /**
+     * Same as `getOptionalBoolean`, but will throw an error if there's no value for the given key.
+     */
     getBoolean(key: string): boolean;
+    /**
+     * Reads a configuration value at the given key, expecting it to be a boolean.
+     */
     getOptionalBoolean(key: string): boolean | undefined;
+    /**
+     * Same as `getOptionalString`, but will throw an error if there's no value for the given key.
+     */
     getString(key: string): string;
+    /**
+     * Reads a configuration value at the given key, expecting it to be a string.
+     */
     getOptionalString(key: string): string | undefined;
+    /**
+     * Same as `getOptionalStringArray`, but will throw an error if there's no value for the given key.
+     */
     getStringArray(key: string): string[];
+    /**
+     * Reads a configuration value at the given key, expecting it to be an array of strings.
+     */
     getOptionalStringArray(key: string): string[] | undefined;
 };
 
+/**
+ * An implementation of the `Config` interface that uses a plain JavaScript object
+ * for the backing data, with the ability of linking multiple readers together.
+ *
+ * @public
+ */
 declare class ConfigReader implements Config {
@@ -45,2 +157,3 @@ private readonly data;
     private filteredKeys?;
+    private notifiedFilteredKeys;
     static fromConfigs(configs: AppConfig[]): ConfigReader;
@@ -47,0 +160,0 @@ constructor(data: JsonObject | undefined, context?: string, fallback?: ConfigReader | undefined, prefix?: string);

dist/index.esm.js

@@ -40,2 +40,3 @@ import cloneDeep from 'lodash/cloneDeep';
     this.prefix = prefix;
+    this.notifiedFilteredKeys = new Set();
   }
@@ -81,3 +82,4 @@ static fromConfigs(configs) {
           const fullKey = this.fullKey(key);
-          if ((_b = this.filteredKeys) == null ? void 0 : _b.includes(fullKey)) {
+          if (((_b = this.filteredKeys) == null ? void 0 : _b.includes(fullKey)) && !this.notifiedFilteredKeys.has(fullKey)) {
+            this.notifiedFilteredKeys.add(fullKey);
             console.warn(`Failed to read configuration value at '${fullKey}' as it is not visible. See https://backstage.io/docs/conf/defining#visibility for instructions on how to make it visible.`);
@@ -135,3 +137,4 @@ }
         const fullKey = this.fullKey(key);
-        if ((_a = this.filteredKeys) == null ? void 0 : _a.some((k) => k.startsWith(fullKey))) {
+        if (((_a = this.filteredKeys) == null ? void 0 : _a.some((k) => k.startsWith(fullKey))) && !this.notifiedFilteredKeys.has(key)) {
+          this.notifiedFilteredKeys.add(key);
           console.warn(`Failed to read configuration array at '${key}' as it does not have any visible elements. See https://backstage.io/docs/conf/defining#visibility for instructions on how to make it visible.`);
@@ -216,3 +219,4 @@ }
         const fullKey = this.fullKey(key);
-        if ((_a = this.filteredKeys) == null ? void 0 : _a.includes(fullKey)) {
+        if (((_a = this.filteredKeys) == null ? void 0 : _a.includes(fullKey)) && !this.notifiedFilteredKeys.has(fullKey)) {
+          this.notifiedFilteredKeys.add(fullKey);
           console.warn(`Failed to read configuration value at '${fullKey}' as it is not visible. See https://backstage.io/docs/conf/defining#visibility for instructions on how to make it visible.`);
@@ -219,0 +223,0 @@ }

package.json

 {
   "name": "@backstage/config",
   "description": "Config API used by Backstage core, backend, and CLI",
-  "version": "0.0.0-nightly-20217521743",
+  "version": "0.0.0-nightly-20218622135",
   "private": false,
@@ -6,0 +6,0 @@ "publishConfig": {

No alert changes

Improved metrics

Total package byte prevSize

62374

increased by10.84%

Lines of code

689

increased by21.3%

Worsened metrics

Published versions last months

14

decreased by-17.65%

Published versions last two months

31

decreased by-3.12%

Published versions last week

5

decreased by-28.57%

No dependency changes