From cb6db75bc2f74253c716f895a7882edda0f17252 Mon Sep 17 00:00:00 2001 From: Patrik Oldsberg Date: Thu, 12 Oct 2023 19:59:29 +0200 Subject: [PATCH] core-plugin-api: deprecate old routing types and introduce AnyRouteRefParams + report fixes Signed-off-by: Patrik Oldsberg --- .changeset/stale-rice-count.md | 5 +++ .changeset/tender-maps-type.md | 5 +++ packages/core-plugin-api/alpha-api-report.md | 22 +++++++++++ packages/core-plugin-api/api-report.md | 19 +++++---- .../src/routing/SubRouteRef.ts | 5 +++ .../src/routing/convertLegacyRouteRef.ts | 39 +++++++++++++------ packages/core-plugin-api/src/routing/index.ts | 1 + packages/core-plugin-api/src/routing/types.ts | 17 +++++++- 8 files changed, 93 insertions(+), 20 deletions(-) create mode 100644 .changeset/stale-rice-count.md create mode 100644 .changeset/tender-maps-type.md diff --git a/.changeset/stale-rice-count.md b/.changeset/stale-rice-count.md new file mode 100644 index 0000000000..3d2caf168d --- /dev/null +++ b/.changeset/stale-rice-count.md @@ -0,0 +1,5 @@ +--- +'@backstage/core-plugin-api': patch +--- + +Deprecated several types related to the routing system that are scheduled to be removed, as well as several fields on the route ref types themselves. diff --git a/.changeset/tender-maps-type.md b/.changeset/tender-maps-type.md new file mode 100644 index 0000000000..11aa814a17 --- /dev/null +++ b/.changeset/tender-maps-type.md @@ -0,0 +1,5 @@ +--- +'@backstage/core-plugin-api': minor +--- + +Introduced `AnyRouteRefParams` as a replacement for `AnyParams`, which is now deprecated. diff --git a/packages/core-plugin-api/alpha-api-report.md b/packages/core-plugin-api/alpha-api-report.md index ba3583142f..0284d691a9 100644 --- a/packages/core-plugin-api/alpha-api-report.md +++ b/packages/core-plugin-api/alpha-api-report.md @@ -3,8 +3,12 @@ > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/). ```ts +import { AnyRouteRefParams } from '@backstage/core-plugin-api'; import { ApiRef } from '@backstage/core-plugin-api'; +import { ExternalRouteRef } from '@backstage/core-plugin-api'; import { Observable } from '@backstage/types'; +import { RouteRef } from '@backstage/core-plugin-api'; +import { SubRouteRef } from '@backstage/core-plugin-api'; import { TranslationMessages as TranslationMessages_2 } from '@backstage/core-plugin-api/alpha'; import { TranslationRef as TranslationRef_2 } from '@backstage/core-plugin-api/alpha'; @@ -25,6 +29,24 @@ export type AppLanguageApi = { // @alpha (undocumented) export const appLanguageApiRef: ApiRef; +// @public +export function convertLegacyRouteRef( + ref: RouteRef, +): NewRouteRef; + +// @public +export function convertLegacyRouteRef( + ref: SubRouteRef, +): NewSubRouteRef; + +// @public +export function convertLegacyRouteRef< + TParams extends AnyRouteRefParams, + TOptional extends boolean, +>( + ref: ExternalRouteRef, +): NewExternalRouteRef; + // @alpha export function createTranslationMessages< TId extends string, diff --git a/packages/core-plugin-api/api-report.md b/packages/core-plugin-api/api-report.md index 7873b23f13..789fc2bfdc 100644 --- a/packages/core-plugin-api/api-report.md +++ b/packages/core-plugin-api/api-report.md @@ -95,8 +95,11 @@ export type AnyExternalRoutes = { [name: string]: ExternalRouteRef; }; +// @public @deprecated (undocumented) +export type AnyParams = AnyRouteRefParams; + // @public -export type AnyParams = +export type AnyRouteRefParams = | { [param in string]: string; } @@ -523,7 +526,7 @@ export type IdentityApi = { // @public export const identityApiRef: ApiRef; -// @public +// @public @deprecated export type MakeSubRouteRef< Params extends { [param in string]: string; @@ -533,7 +536,7 @@ export type MakeSubRouteRef< ? SubRouteRef>> : never; -// @public +// @public @deprecated export type MergeParams< P1 extends { [param in string]: string; @@ -606,30 +609,30 @@ export type OpenIdConnectApi = { getIdToken(options?: AuthRequestOptions): Promise; }; -// @public +// @public @deprecated export type OptionalParams< Params extends { [param in string]: string; }, > = Params[keyof Params] extends never ? undefined : Params; -// @public +// @public @deprecated export type ParamKeys = keyof Params extends never ? [] : (keyof Params)[]; -// @public +// @public @deprecated export type ParamNames = S extends `${infer Part}/${infer Rest}` ? ParamPart | ParamNames : ParamPart; -// @public +// @public @deprecated export type ParamPart = S extends `:${infer Param}` ? Param : never; -// @public +// @public @deprecated export type PathParams = { [name in ParamNames]: string; }; diff --git a/packages/core-plugin-api/src/routing/SubRouteRef.ts b/packages/core-plugin-api/src/routing/SubRouteRef.ts index 14a614c2ba..b08368d74e 100644 --- a/packages/core-plugin-api/src/routing/SubRouteRef.ts +++ b/packages/core-plugin-api/src/routing/SubRouteRef.ts @@ -51,6 +51,7 @@ export class SubRouteRefImpl /** * Used in {@link PathParams} type declaration. * @public + * @deprecated this type is deprecated and will be removed in the future */ export type ParamPart = S extends `:${infer Param}` ? Param @@ -59,6 +60,7 @@ export type ParamPart = S extends `:${infer Param}` /** * Used in {@link PathParams} type declaration. * @public + * @deprecated this type is deprecated and will be removed in the future */ export type ParamNames = S extends `${infer Part}/${infer Rest}` @@ -68,12 +70,14 @@ export type ParamNames = * This utility type helps us infer a Param object type from a string path * For example, `/foo/:bar/:baz` inferred to `{ bar: string, baz: string }` * @public + * @deprecated this type is deprecated and will be removed in the future */ export type PathParams = { [name in ParamNames]: string }; /** * Merges a param object type with an optional params type into a params object. * @public + * @deprecated this type is deprecated and will be removed in the future */ export type MergeParams< P1 extends { [param in string]: string }, @@ -85,6 +89,7 @@ export type MergeParams< * The parameters types are merged together while ensuring that there is no overlap between the two. * * @public + * @deprecated this type is deprecated and will be removed in the future */ export type MakeSubRouteRef< Params extends { [param in string]: string }, diff --git a/packages/core-plugin-api/src/routing/convertLegacyRouteRef.ts b/packages/core-plugin-api/src/routing/convertLegacyRouteRef.ts index 9778625355..940a4174a9 100644 --- a/packages/core-plugin-api/src/routing/convertLegacyRouteRef.ts +++ b/packages/core-plugin-api/src/routing/convertLegacyRouteRef.ts @@ -14,12 +14,13 @@ * limitations under the License. */ +import { routeRefType } from './types'; import { - routeRefType, RouteRef as LegacyRouteRef, SubRouteRef as LegacySubRouteRef, ExternalRouteRef as LegacyExternalRouteRef, -} from './types'; + AnyRouteRefParams, +} from '@backstage/core-plugin-api'; // Relative imports to avoid dependency, at least for now @@ -28,7 +29,6 @@ import { RouteRef, SubRouteRef, ExternalRouteRef, - AnyRouteParams, createRouteRef, createSubRouteRef, createExternalRouteRef, @@ -40,6 +40,22 @@ import { toInternalSubRouteRef } from '../../../frontend-plugin-api/src/routing/ // eslint-disable-next-line @backstage/no-relative-monorepo-imports import { toInternalExternalRouteRef } from '../../../frontend-plugin-api/src/routing/ExternalRouteRef'; +// TODO(Rugvip): Once this is moved to a compat package these aliases can be removed and imported from frontend- instead + +/** @ignore */ +type NewRouteRef = + RouteRef; + +/** @ignore */ +type NewSubRouteRef = + SubRouteRef; + +/** @ignore */ +type NewExternalRouteRef< + TParams extends AnyRouteRefParams = AnyRouteRefParams, + TOptional extends boolean = boolean, +> = ExternalRouteRef; + /** * A temporary helper to convert a legacy route ref to the new system. * @@ -48,9 +64,9 @@ import { toInternalExternalRouteRef } from '../../../frontend-plugin-api/src/rou * * In the future the legacy createRouteRef will instead create refs compatible with both systems. */ -export function convertLegacyRouteRef( +export function convertLegacyRouteRef( ref: LegacyRouteRef, -): RouteRef; +): NewRouteRef; /** * A temporary helper to convert a legacy sub route ref to the new system. @@ -60,9 +76,9 @@ export function convertLegacyRouteRef( * * In the future the legacy createSubRouteRef will instead create refs compatible with both systems. */ -export function convertLegacyRouteRef( +export function convertLegacyRouteRef( ref: LegacySubRouteRef, -): SubRouteRef; +): NewSubRouteRef; /** * A temporary helper to convert a legacy external route ref to the new system. @@ -73,17 +89,18 @@ export function convertLegacyRouteRef( * In the future the legacy createExternalRouteRef will instead create refs compatible with both systems. */ export function convertLegacyRouteRef< - TParams extends AnyRouteParams, + TParams extends AnyRouteRefParams, TOptional extends boolean, >( ref: LegacyExternalRouteRef, -): ExternalRouteRef; +): NewExternalRouteRef; + export function convertLegacyRouteRef( ref: LegacyRouteRef | LegacySubRouteRef | LegacyExternalRouteRef, -): RouteRef | SubRouteRef | ExternalRouteRef { +): NewRouteRef | NewSubRouteRef | NewExternalRouteRef { // Ref has already been converted if ('$$type' in ref) { - return ref as unknown as RouteRef | SubRouteRef | ExternalRouteRef; + return ref as unknown as NewRouteRef | NewSubRouteRef | NewExternalRouteRef; } const type = (ref as unknown as { [routeRefType]: unknown })[routeRefType]; diff --git a/packages/core-plugin-api/src/routing/index.ts b/packages/core-plugin-api/src/routing/index.ts index 01d69cd4b0..4f8b12ec73 100644 --- a/packages/core-plugin-api/src/routing/index.ts +++ b/packages/core-plugin-api/src/routing/index.ts @@ -16,6 +16,7 @@ export type { AnyParams, + AnyRouteRefParams, RouteRef, SubRouteRef, ExternalRouteRef, diff --git a/packages/core-plugin-api/src/routing/types.ts b/packages/core-plugin-api/src/routing/types.ts index 80653518bb..32f26f19c1 100644 --- a/packages/core-plugin-api/src/routing/types.ts +++ b/packages/core-plugin-api/src/routing/types.ts @@ -21,12 +21,19 @@ import { getOrCreateGlobalSingleton } from '@backstage/version-bridge'; * * @public */ -export type AnyParams = { [param in string]: string } | undefined; +export type AnyRouteRefParams = { [param in string]: string } | undefined; + +/** + * @deprecated use {@link AnyRouteRefParams} instead + * @public + */ +export type AnyParams = AnyRouteRefParams; /** * Type describing the key type of a route parameter mapping. * * @public + * @deprecated this type is deprecated and will be removed in the future */ export type ParamKeys = keyof Params extends never ? [] @@ -36,6 +43,7 @@ export type ParamKeys = keyof Params extends never * Optional route params. * * @public + * @deprecated this type is deprecated and will be removed in the future */ export type OptionalParams = Params[keyof Params] extends never ? undefined : Params; @@ -81,8 +89,10 @@ export const routeRefType: unique symbol = getOrCreateGlobalSingleton( * @public */ export type RouteRef = { + /** @deprecated access to this property will be removed in the future */ $$routeRefType: 'absolute'; // See routeRefType above + /** @deprecated access to this property will be removed in the future */ params: ParamKeys; }; @@ -96,12 +106,15 @@ export type RouteRef = { * @public */ export type SubRouteRef = { + /** @deprecated access to this property will be removed in the future */ $$routeRefType: 'sub'; // See routeRefType above + /** @deprecated access to this property will be removed in the future */ parent: RouteRef; path: string; + /** @deprecated access to this property will be removed in the future */ params: ParamKeys; }; @@ -118,8 +131,10 @@ export type ExternalRouteRef< Params extends AnyParams = any, Optional extends boolean = any, > = { + /** @deprecated access to this property will be removed in the future */ $$routeRefType: 'external'; // See routeRefType above + /** @deprecated access to this property will be removed in the future */ params: ParamKeys; optional?: Optional;