From f88b2c7dbef54ab0575d5df35393a3cd06b3ced8 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Sat, 4 Sep 2021 18:00:53 +0200 Subject: [PATCH] config: document interface and mark types as public Signed-off-by: Patrik Oldsberg --- .changeset/great-balloons-walk.md | 5 ++ packages/config/api-report.md | 28 ++------ packages/config/src/reader.ts | 6 ++ packages/config/src/types.ts | 106 ++++++++++++++++++++++++++++++ 4 files changed, 124 insertions(+), 21 deletions(-) create mode 100644 .changeset/great-balloons-walk.md diff --git a/.changeset/great-balloons-walk.md b/.changeset/great-balloons-walk.md new file mode 100644 index 0000000000..7675a2badd --- /dev/null +++ b/.changeset/great-balloons-walk.md @@ -0,0 +1,5 @@ +--- +'@backstage/config': patch +--- + +Documented `Config` interface and mark types as public. diff --git a/packages/config/api-report.md b/packages/config/api-report.md index 91f37894c0..068498b17a 100644 --- a/packages/config/api-report.md +++ b/packages/config/api-report.md @@ -3,18 +3,14 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts -// Warning: (ae-missing-release-tag) "AppConfig" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type AppConfig = { context: string; data: JsonObject; filteredKeys?: string[]; }; -// Warning: (ae-missing-release-tag) "Config" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type Config = { subscribe?(onChange: () => void): { unsubscribe: () => void; @@ -37,9 +33,7 @@ export type Config = { getOptionalStringArray(key: string): string[] | undefined; }; -// Warning: (ae-missing-release-tag) "ConfigReader" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export class ConfigReader implements Config { constructor( data: JsonObject | undefined, @@ -83,26 +77,18 @@ export class ConfigReader implements Config { keys(): string[]; } -// Warning: (ae-missing-release-tag) "JsonArray" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export interface JsonArray extends Array {} -// Warning: (ae-missing-release-tag) "JsonObject" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type JsonObject = { [key in string]?: JsonValue; }; -// Warning: (ae-missing-release-tag) "JsonPrimitive" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type JsonPrimitive = number | string | boolean | null; -// Warning: (ae-missing-release-tag) "JsonValue" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) -// -// @public (undocumented) +// @public export type JsonValue = JsonObject | JsonArray | JsonPrimitive; // (No @packageDocumentation comment for this package) diff --git a/packages/config/src/reader.ts b/packages/config/src/reader.ts index c6f69e5b29..92ca0eede3 100644 --- a/packages/config/src/reader.ts +++ b/packages/config/src/reader.ts @@ -54,6 +54,12 @@ const errors = { }, }; +/** + * 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 + */ export class ConfigReader implements Config { /** * A set of key paths that where removed from the config due to not being visible. diff --git a/packages/config/src/types.ts b/packages/config/src/types.ts index 84de5dae70..d5f551cd69 100644 --- a/packages/config/src/types.ts +++ b/packages/config/src/types.ts @@ -14,17 +14,61 @@ * limitations under the License. */ +/** + * A type representing all allowed JSON primitive values. + * + * @public + */ export type JsonPrimitive = number | string | boolean | null; + +/** + * A type representing all allowed JSON object values. + * + * @public + */ export type JsonObject = { [key in string]?: JsonValue }; + +/** + * A type representing all allowed JSON array values. + * + * @public + */ export interface JsonArray extends Array {} + +/** + * A type representing all allowed JSON values. + * + * @public + */ export type JsonValue = JsonObject | JsonArray | JsonPrimitive; +/** + * A serialized form of configuration data that carries additional context. + * + * @public + */ export 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 + */ export type Config = { /** * Subscribes to the configuration object in order to receive a notification @@ -37,28 +81,90 @@ export type Config = { 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(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(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; };