@backstage/config-loader 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -1,30 +1,6 @@
-import { AppConfig } from '@backstage/config';
 import { JSONSchema7 } from 'json-schema';
-import { JsonObject } from '@backstage/types';
-
-/**
- * Read runtime configuration from the environment.
- *
- * Only environment variables prefixed with APP_CONFIG_ will be considered.
- *
- * For each variable, the prefix will be removed, and rest of the key will
- * be split by '_'. Each part will then be used as keys to build up a nested
- * config object structure. The treatment of the entire environment variable
- * is case-sensitive.
- *
- * The value of the variable should be JSON serialized, as it will be parsed
- * and the type will be kept intact. For example "true" and true are treated
- * differently, as well as "42" and 42.
- *
- * For example, to set the config app.title to "My Title", use the following:
- *
- * APP_CONFIG_app_title='"My Title"'
- *
- * @public
- */
-declare function readEnvConfig(env: {
-    [name: string]: string | undefined;
-}): AppConfig[];
+import { JsonObject, HumanDuration, Observable } from '@backstage/types';
+import { AppConfig, Config } from '@backstage/config';
 
 /**
  * A type representing the possible configuration value visibilities
@@ -98,11 +74,13 @@ declare function mergeConfigSchemas(schemas: JSONSchema7[]): JSONSchema7;
  *
  * @public
  */
-type LoadConfigSchemaOptions = {
+type LoadConfigSchemaOptions = ({
     dependencies: string[];
     packagePaths?: string[];
 } | {
     serialized: JsonObject;
+}) & {
+    noUndeclaredProperties?: boolean;
 };
 /**
  * Loads config schema for a Backstage instance.
@@ -111,13 +89,19 @@ type LoadConfigSchemaOptions = {
  */
 declare function loadConfigSchema(options: LoadConfigSchemaOptions): Promise<ConfigSchema>;
 
-/** @public */
+/**
+ * @public
+ * @deprecated Use {@link ConfigSources.default} instead.
+ */
 type ConfigTarget = {
     path: string;
 } | {
     url: string;
 };
-/** @public */
+/**
+ * @public
+ * @deprecated Use {@link ConfigSources.default} instead.
+ */
 type LoadConfigOptionsWatch = {
     /**
      * A listener that is called when a config file is changed.
@@ -128,7 +112,10 @@ type LoadConfigOptionsWatch = {
      */
     stopSignal?: Promise<void>;
 };
-/** @public */
+/**
+ * @public
+ * @deprecated Use {@link ConfigSources.default} instead.
+ */
 type LoadConfigOptionsRemote = {
     /**
      * A remote config reloading period, in seconds
@@ -139,6 +126,7 @@ type LoadConfigOptionsRemote = {
  * Options that control the loading of configuration files in the backend.
  *
  * @public
+ * @deprecated Use {@link ConfigSources.default} instead.
  */
 type LoadConfigOptions = {
     configRoot: string;
@@ -161,6 +149,7 @@ type LoadConfigOptions = {
 /**
  * Results of loading configuration files.
  * @public
+ * @deprecated Use {@link ConfigSources.default} instead.
  */
 type LoadConfigResult = {
     /**
@@ -172,7 +161,427 @@ type LoadConfigResult = {
  * Load configuration data.
  *
  * @public
+ * @deprecated Use {@link ConfigSources.default} instead.
  */
 declare function loadConfig(options: LoadConfigOptions): Promise<LoadConfigResult>;
 
-export { ConfigSchema, ConfigSchemaProcessingOptions, ConfigTarget, ConfigVisibility, LoadConfigOptions, LoadConfigOptionsRemote, LoadConfigOptionsWatch, LoadConfigResult, LoadConfigSchemaOptions, TransformFunc, loadConfig, loadConfigSchema, mergeConfigSchemas, readEnvConfig };
+/**
+ * The data returned by {@link ConfigSource.readConfigData}.
+ *
+ * @public
+ */
+interface ConfigSourceData extends AppConfig {
+    /**
+     * The file path that this configuration was loaded from, if it was loaded from a file.
+     */
+    path?: string;
+}
+/**
+ * Options for {@link ConfigSource.readConfigData}.
+ *
+ * @public
+ */
+interface ReadConfigDataOptions {
+    signal?: AbortSignal;
+}
+/**
+ * The the generator returned by {@link ConfigSource.readConfigData}.
+ *
+ * @public
+ */
+type AsyncConfigSourceGenerator = AsyncGenerator<{
+    configs: ConfigSourceData[];
+}, void, void>;
+/**
+ * A source of configuration data.
+ *
+ * @remarks
+ *
+ * It is recommended to implement the `readConfigData` method as an async generator.
+ *
+ * @example
+ *
+ * ```ts
+ * class MyConfigSource implements ConfigSource {
+ *   async *readConfigData() {
+ *     yield {
+ *       config: [{
+ *         context: 'example',
+ *         data: { backend: { baseUrl: 'http://localhost' } }
+ *       }]
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+interface ConfigSource {
+    readConfigData(options?: ReadConfigDataOptions): AsyncConfigSourceGenerator;
+}
+/**
+ * A custom function to be used for substitution withing configuration files.
+ *
+ * @remarks
+ *
+ * Substitutions use the following syntax: `baseUrl: https://${HOSTNAME}`, where
+ * `'HOSTNAME'` is the name of the variable to be substituted.
+ *
+ * The default substitution function will read the value of the environment.
+ *
+ * @public
+ */
+type SubstitutionFunc = (name: string) => Promise<string | undefined>;
+
+/**
+ * Options for {@link RemoteConfigSource.create}.
+ *
+ * @public
+ */
+interface RemoteConfigSourceOptions {
+    /**
+     * The URL to load the config from.
+     */
+    url: string;
+    /**
+     * How often to reload the config from the remote URL, defaults to 1 minute.
+     *
+     * Set to Infinity to disable reloading, for example `{ days: Infinity }`.
+     */
+    reloadInterval?: HumanDuration;
+    /**
+     * A substitution function to use instead of the default environment substitution.
+     */
+    substitutionFunc?: SubstitutionFunc;
+}
+/**
+ * A config source that loads configuration from a remote URL.
+ *
+ * @public
+ */
+declare class RemoteConfigSource implements ConfigSource {
+    #private;
+    /**
+     * Creates a new {@link RemoteConfigSource}.
+     *
+     * @param options - Options for the source.
+     * @returns A new remote config source.
+     */
+    static create(options: RemoteConfigSourceOptions): ConfigSource;
+    private constructor();
+    readConfigData(options?: ReadConfigDataOptions | undefined): AsyncConfigSourceGenerator;
+    toString(): string;
+}
+
+/**
+ * A target to read configuration from.
+ *
+ * @public
+ */
+type ConfigSourceTarget = {
+    type: 'path';
+    target: string;
+} | {
+    type: 'url';
+    target: string;
+};
+/**
+ * A config implementation that can be closed.
+ *
+ * @remarks
+ *
+ * Closing the configuration instance will stop the reading from the underlying source.
+ *
+ * @public
+ */
+interface ClosableConfig extends Config {
+    /**
+     * Closes the configuration instance.
+     *
+     * @remarks
+     *
+     * The configuration instance will still be usable after closing, but it will
+     * no longer be updated with new values from the underlying source.
+     */
+    close(): void;
+}
+/**
+ * Common options for the default Backstage configuration sources.
+ *
+ * @public
+ */
+interface BaseConfigSourcesOptions {
+    rootDir?: string;
+    remote?: Pick<RemoteConfigSourceOptions, 'reloadInterval'>;
+    substitutionFunc?: SubstitutionFunc;
+}
+/**
+ * Options for {@link ConfigSources.defaultForTargets}.
+ *
+ * @public
+ */
+interface ConfigSourcesDefaultForTargetsOptions extends BaseConfigSourcesOptions {
+    targets: ConfigSourceTarget[];
+}
+/**
+ * Options for {@link ConfigSources.default}.
+ *
+ * @public
+ */
+interface ConfigSourcesDefaultOptions extends BaseConfigSourcesOptions {
+    argv?: string[];
+    env?: Record<string, string>;
+}
+/**
+ * A collection of utilities for working with and creating {@link ConfigSource}s.
+ *
+ * @public
+ */
+declare class ConfigSources {
+    /**
+     * Parses command line arguments and returns the config targets.
+     *
+     * @param argv - The command line arguments to parse. Defaults to `process.argv`
+     * @returns A list of config targets
+     */
+    static parseArgs(argv?: string[]): ConfigSourceTarget[];
+    /**
+     * Creates the default config sources for the provided targets.
+     *
+     * @remarks
+     *
+     * This will create {@link FileConfigSource}s and {@link RemoteConfigSource}s
+     * for the provided targets, and merge them together to a single source.
+     * If no targets are provided it will fall back to `app-config.yaml` and
+     * `app-config.local.yaml`.
+     *
+     * URL targets are only supported if the `remote` option is provided.
+     *
+     * @param options - Options
+     * @returns A config source for the provided targets
+     */
+    static defaultForTargets(options: ConfigSourcesDefaultForTargetsOptions): ConfigSource;
+    /**
+     * Creates the default config source for Backstage.
+     *
+     * @remarks
+     *
+     * This will read from `app-config.yaml` and `app-config.local.yaml` by
+     * default, as well as environment variables prefixed with `APP_CONFIG_`.
+     * If `--config <path|url>` command line arguments are passed, these will
+     * override the default configuration file paths. URLs are only supported
+     * if the `remote` option is provided.
+     *
+     * @param options - Options
+     * @returns The default Backstage config source
+     */
+    static default(options: ConfigSourcesDefaultOptions): ConfigSource;
+    /**
+     * Merges multiple config sources into a single source that reads from all
+     * sources and concatenates the result.
+     *
+     * @param sources - The config sources to merge
+     * @returns A single config source that concatenates the data from the given sources
+     */
+    static merge(sources: ConfigSource[]): ConfigSource;
+    /**
+     * Creates an observable {@link @backstage/config#Config} implementation from a {@link ConfigSource}.
+     *
+     * @remarks
+     *
+     * If you only want to read the config once you can close the returned config immediately.
+     *
+     * @example
+     *
+     * ```ts
+     * const sources = ConfigSources.default(...)
+     * const config = await ConfigSources.toConfig(source)
+     * config.close()
+     * const example = config.getString(...)
+     * ```
+     *
+     * @param source - The config source to read from
+     * @returns A promise that resolves to a closable config
+     */
+    static toConfig(source: ConfigSource): Promise<ClosableConfig>;
+}
+
+/**
+ * Options for {@link EnvConfigSource.create}.
+ *
+ * @public
+ */
+interface EnvConfigSourceOptions {
+    /**
+     * The environment variables to use, defaults to `process.env`.
+     */
+    env?: Record<string, string | undefined>;
+}
+/**
+ * A config source that reads configuration from the environment.
+ *
+ * @remarks
+ *
+ * Only environment variables prefixed with APP_CONFIG_ will be considered.
+ *
+ * For each variable, the prefix will be removed, and rest of the key will
+ * be split by '_'. Each part will then be used as keys to build up a nested
+ * config object structure. The treatment of the entire environment variable
+ * is case-sensitive.
+ *
+ * The value of the variable should be JSON serialized, as it will be parsed
+ * and the type will be kept intact. For example "true" and true are treated
+ * differently, as well as "42" and 42.
+ *
+ * For example, to set the config app.title to "My Title", use the following:
+ *
+ * APP_CONFIG_app_title='"My Title"'
+ *
+ * @public
+ */
+declare class EnvConfigSource implements ConfigSource {
+    private readonly env;
+    /**
+     * Creates a new config source that reads from the environment.
+     *
+     * @param options - Options for the config source.
+     * @returns A new config source that reads from the environment.
+     */
+    static create(options: EnvConfigSourceOptions): ConfigSource;
+    private constructor();
+    readConfigData(): AsyncConfigSourceGenerator;
+    toString(): string;
+}
+/**
+ * Read runtime configuration from the environment.
+ *
+ * @remarks
+ *
+ * Only environment variables prefixed with APP_CONFIG_ will be considered.
+ *
+ * For each variable, the prefix will be removed, and rest of the key will
+ * be split by '_'. Each part will then be used as keys to build up a nested
+ * config object structure. The treatment of the entire environment variable
+ * is case-sensitive.
+ *
+ * The value of the variable should be JSON serialized, as it will be parsed
+ * and the type will be kept intact. For example "true" and true are treated
+ * differently, as well as "42" and 42.
+ *
+ * For example, to set the config app.title to "My Title", use the following:
+ *
+ * APP_CONFIG_app_title='"My Title"'
+ *
+ * @public
+ * @deprecated Use {@link EnvConfigSource} instead
+ */
+declare function readEnvConfig(env: {
+    [name: string]: string | undefined;
+}): AppConfig[];
+
+/**
+ * Options for {@link FileConfigSource.create}.
+ *
+ * @public
+ */
+interface FileConfigSourceOptions {
+    /**
+     * The path to the config file that should be loaded.
+     */
+    path: string;
+    /**
+     * A substitution function to use instead of the default environment substitution.
+     */
+    substitutionFunc?: SubstitutionFunc;
+}
+/**
+ * A config source that loads configuration from a local file.
+ *
+ * @public
+ */
+declare class FileConfigSource implements ConfigSource {
+    #private;
+    /**
+     * Creates a new config source that loads configuration from the given path.
+     *
+     * @remarks
+     *
+     * The source will watch the file for changes, as well as any referenced files.
+     *
+     * @param options - Options for the config source.
+     * @returns A new config source that loads from the given path.
+     */
+    static create(options: FileConfigSourceOptions): ConfigSource;
+    private constructor();
+    readConfigData(options?: ReadConfigDataOptions): AsyncConfigSourceGenerator;
+    toString(): string;
+}
+
+/**
+ * Options for {@link MutableConfigSource.create}.
+ *
+ * @public
+ */
+interface MutableConfigSourceOptions {
+    data?: JsonObject;
+    context?: string;
+}
+/**
+ * A config source that can be updated with new data.
+ *
+ * @public
+ */
+declare class MutableConfigSource implements ConfigSource {
+    #private;
+    /**
+     * Creates a new mutable config source.
+     *
+     * @param options - Options for the config source.
+     * @returns A new mutable config source.
+     */
+    static create(options?: MutableConfigSourceOptions): MutableConfigSource;
+    private constructor();
+    readConfigData(options?: ReadConfigDataOptions | undefined): AsyncConfigSourceGenerator;
+    /**
+     * Set the data of the config source.
+     *
+     * @param data - The new data to set
+     */
+    setData(data: JsonObject): void;
+    /**
+     * Close the config source, preventing any further updates.
+     */
+    close(): void;
+    toString(): string;
+}
+
+/**
+ * Options for {@link StaticConfigSource.create}.
+ *
+ * @public
+ */
+interface StaticConfigSourceOptions {
+    data: JsonObject | Observable<JsonObject> | PromiseLike<JsonObject> | AsyncIterable<JsonObject>;
+    context?: string;
+}
+/**
+ * A configuration source that reads from a static object, promise, iterable, or observable.
+ *
+ * @public
+ */
+declare class StaticConfigSource implements ConfigSource {
+    private readonly promise;
+    private readonly context;
+    /**
+     * Creates a new {@link StaticConfigSource}.
+     *
+     * @param options - Options for the config source
+     * @returns A new static config source
+     */
+    static create(options: StaticConfigSourceOptions): ConfigSource;
+    private constructor();
+    readConfigData(): AsyncConfigSourceGenerator;
+    toString(): string;
+}
+
+export { AsyncConfigSourceGenerator, BaseConfigSourcesOptions, ClosableConfig, ConfigSchema, ConfigSchemaProcessingOptions, ConfigSource, ConfigSourceData, ConfigSourceTarget, ConfigSources, ConfigSourcesDefaultForTargetsOptions, ConfigSourcesDefaultOptions, ConfigTarget, ConfigVisibility, EnvConfigSource, EnvConfigSourceOptions, SubstitutionFunc as EnvFunc, FileConfigSource, FileConfigSourceOptions, LoadConfigOptions, LoadConfigOptionsRemote, LoadConfigOptionsWatch, LoadConfigResult, LoadConfigSchemaOptions, MutableConfigSource, MutableConfigSourceOptions, ReadConfigDataOptions, RemoteConfigSource, RemoteConfigSourceOptions, StaticConfigSource, StaticConfigSourceOptions, TransformFunc, loadConfig, loadConfigSchema, mergeConfigSchemas, readEnvConfig };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/config-loader",
   "description": "Config loading functionality used by Backstage backend, and CLI",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "publishConfig": {
     "access": "public",
     "main": "dist/index.cjs.js",
@@ -44,19 +44,23 @@
     "json-schema": "^0.4.0",
     "json-schema-merge-allof": "^0.8.1",
     "json-schema-traverse": "^1.0.0",
+    "lodash": "^4.17.21",
+    "minimist": "^1.2.5",
     "node-fetch": "^2.6.7",
     "typescript-json-schema": "^0.55.0",
     "yaml": "^2.0.0",
     "yup": "^0.32.9"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.22.6",
+    "@backstage/backend-test-utils": "^0.1.37",
+    "@backstage/cli": "^0.22.7",
     "@types/json-schema-merge-allof": "^0.6.0",
     "@types/mock-fs": "^4.10.0",
     "@types/node": "^16.11.26",
     "@types/yup": "^0.29.13",
     "mock-fs": "^5.1.0",
-    "msw": "^1.0.0"
+    "msw": "^1.0.0",
+    "zen-observable": "^0.10.0"
   },
   "files": [
     "dist"