diff --git a/.changeset/moody-bats-matter.md b/.changeset/moody-bats-matter.md new file mode 100644 index 0000000000..a2c974cd09 --- /dev/null +++ b/.changeset/moody-bats-matter.md @@ -0,0 +1,5 @@ +--- +'@backstage/config-loader': minor +--- + +Removed the `EnvFunc` public export. Its only usage was to be passed in to `LoadConfigOptions.experimentalEnvFunc`. If you were using this type, add a definition in your own project instead with the signature `(name: string) => Promise`. diff --git a/.changeset/quick-frogs-double.md b/.changeset/quick-frogs-double.md new file mode 100644 index 0000000000..c083abe609 --- /dev/null +++ b/.changeset/quick-frogs-double.md @@ -0,0 +1,6 @@ +--- +'@backstage/config-loader': patch +'@backstage/errors': patch +--- + +Add public tags and documentation diff --git a/packages/config-loader/api-report.md b/packages/config-loader/api-report.md index 355839c5af..b47119d470 100644 --- a/packages/config-loader/api-report.md +++ b/packages/config-loader/api-report.md @@ -26,18 +26,15 @@ export type ConfigSchemaProcessingOptions = { // @public export type ConfigVisibility = 'frontend' | 'backend' | 'secret'; -// @public (undocumented) -export type EnvFunc = (name: string) => Promise; - // @public export function loadConfig(options: LoadConfigOptions): Promise; -// @public (undocumented) +// @public export type LoadConfigOptions = { configRoot: string; configPaths: string[]; env?: string; - experimentalEnvFunc?: EnvFunc; + experimentalEnvFunc?: (name: string) => Promise; watch?: { onChange: (configs: AppConfig[]) => void; stopSignal?: Promise; @@ -49,7 +46,7 @@ export function loadConfigSchema( options: LoadConfigSchemaOptions, ): Promise; -// @public (undocumented) +// @public export type LoadConfigSchemaOptions = | { dependencies: string[]; diff --git a/packages/config-loader/src/index.ts b/packages/config-loader/src/index.ts index 0e66c59ec4..888c68ef70 100644 --- a/packages/config-loader/src/index.ts +++ b/packages/config-loader/src/index.ts @@ -25,7 +25,6 @@ export type { ConfigSchema, ConfigSchemaProcessingOptions, ConfigVisibility, - EnvFunc, LoadConfigSchemaOptions, TransformFunc, } from './lib'; diff --git a/packages/config-loader/src/lib/schema/load.ts b/packages/config-loader/src/lib/schema/load.ts index 0e9ddabcb3..f3ea0b900e 100644 --- a/packages/config-loader/src/lib/schema/load.ts +++ b/packages/config-loader/src/lib/schema/load.ts @@ -25,7 +25,11 @@ import { CONFIG_VISIBILITIES, } from './types'; -/** @public */ +/** + * Options that control the loading of configuration schema files in the backend. + * + * @public + */ export type LoadConfigSchemaOptions = | { dependencies: string[]; diff --git a/packages/config-loader/src/lib/transform/index.ts b/packages/config-loader/src/lib/transform/index.ts index eaa85cca3c..5053cd7443 100644 --- a/packages/config-loader/src/lib/transform/index.ts +++ b/packages/config-loader/src/lib/transform/index.ts @@ -17,4 +17,3 @@ export { applyConfigTransforms } from './apply'; export { createIncludeTransform } from './include'; export { createSubstitutionTransform } from './substitution'; -export type { EnvFunc } from './types'; diff --git a/packages/config-loader/src/lib/transform/types.ts b/packages/config-loader/src/lib/transform/types.ts index afd3550984..20e5f88718 100644 --- a/packages/config-loader/src/lib/transform/types.ts +++ b/packages/config-loader/src/lib/transform/types.ts @@ -16,7 +16,6 @@ import { JsonValue } from '@backstage/config'; -/** @public */ export type EnvFunc = (name: string) => Promise; export type ReadFileFunc = (path: string) => Promise; diff --git a/packages/config-loader/src/loader.ts b/packages/config-loader/src/loader.ts index 4abcc2e314..6803d61786 100644 --- a/packages/config-loader/src/loader.ts +++ b/packages/config-loader/src/loader.ts @@ -26,9 +26,12 @@ import { createIncludeTransform, createSubstitutionTransform, } from './lib'; -import { EnvFunc } from './lib/transform/types'; -/** @public */ +/** + * Options that control the loading of configuration files in the backend. + * + * @public + */ export type LoadConfigOptions = { // The root directory of the config loading context. Used to find default configs. configRoot: string; @@ -44,7 +47,7 @@ export type LoadConfigOptions = { * * @experimental This API is not stable and may change at any point */ - experimentalEnvFunc?: EnvFunc; + experimentalEnvFunc?: (name: string) => Promise; /** * An optional configuration that enables watching of config files. diff --git a/packages/errors/api-report.md b/packages/errors/api-report.md index 489f68463c..6552e111ce 100644 --- a/packages/errors/api-report.md +++ b/packages/errors/api-report.md @@ -14,7 +14,7 @@ export class AuthenticationError extends CustomErrorBase {} // @public export class ConflictError extends CustomErrorBase {} -// @public (undocumented) +// @public export class CustomErrorBase extends Error { constructor(message?: string, cause?: Error | unknown); // (undocumented) diff --git a/packages/errors/src/errors/CustomErrorBase.ts b/packages/errors/src/errors/CustomErrorBase.ts index 79ab6e302c..5c5c032de2 100644 --- a/packages/errors/src/errors/CustomErrorBase.ts +++ b/packages/errors/src/errors/CustomErrorBase.ts @@ -16,7 +16,21 @@ import { isError } from './assertion'; -/** @public */ +/** + * A base class that custom Error classes can inherit from. + * + * @public + * @example + *```ts + * class MyCustomError extends CustomErrorBase {} + * + * const e = new MyCustomError('Some message', cause); + * // e.name === 'MyCustomError' + * // e.message === 'Some message' + * // e.cause === cause + * // e.stack is set if the runtime supports it + * ``` + */ export class CustomErrorBase extends Error { readonly cause?: Error;