core-plugin-api: deprecate old routing types and introduce AnyRouteRefParams + report fixes

Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>

.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.

.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.

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<AppLanguageApi>;
 
+// @public
+export function convertLegacyRouteRef<TParams extends AnyRouteRefParams>(
+  ref: RouteRef<TParams>,
+): NewRouteRef<TParams>;
+
+// @public
+export function convertLegacyRouteRef<TParams extends AnyRouteRefParams>(
+  ref: SubRouteRef<TParams>,
+): NewSubRouteRef<TParams>;
+
+// @public
+export function convertLegacyRouteRef<
+  TParams extends AnyRouteRefParams,
+  TOptional extends boolean,
+>(
+  ref: ExternalRouteRef<TParams, TOptional>,
+): NewExternalRouteRef<TParams, TOptional>;
+
 // @alpha
 export function createTranslationMessages<
   TId extends string,

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<IdentityApi>;
 
-// @public
+// @public @deprecated
 export type MakeSubRouteRef<
   Params extends {
     [param in string]: string;
@@ -533,7 +536,7 @@ export type MakeSubRouteRef<
   ? SubRouteRef<OptionalParams<MergeParams<Params, ParentParams>>>
   : never;
 
-// @public
+// @public @deprecated
 export type MergeParams<
   P1 extends {
     [param in string]: string;
@@ -606,30 +609,30 @@ export type OpenIdConnectApi = {
   getIdToken(options?: AuthRequestOptions): Promise<string>;
 };
 
-// @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<Params extends AnyParams> = keyof Params extends never
   ? []
   : (keyof Params)[];
 
-// @public
+// @public @deprecated
 export type ParamNames<S extends string> =
   S extends `${infer Part}/${infer Rest}`
     ? ParamPart<Part> | ParamNames<Rest>
     : ParamPart<S>;
 
-// @public
+// @public @deprecated
 export type ParamPart<S extends string> = S extends `:${infer Param}`
   ? Param
   : never;
 
-// @public
+// @public @deprecated
 export type PathParams<S extends string> = {
   [name in ParamNames<S>]: string;
 };

packages/core-plugin-api/src/routing/SubRouteRef.ts

@@ -51,6 +51,7 @@ export class SubRouteRefImpl<Params extends AnyParams>
 /**
  * Used in {@link PathParams} type declaration.
  * @public
+ * @deprecated this type is deprecated and will be removed in the future
  */
 export type ParamPart<S extends string> = S extends `:${infer Param}`
   ? Param
@@ -59,6 +60,7 @@ export type ParamPart<S extends string> = 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 string> =
   S extends `${infer Part}/${infer Rest}`
@@ -68,12 +70,14 @@ export type ParamNames<S extends string> =
  * 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<S extends string> = { [name in ParamNames<S>]: 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 },

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<TParams extends AnyRouteRefParams = AnyRouteRefParams> =
+  RouteRef<TParams>;
+
+/** @ignore */
+type NewSubRouteRef<TParams extends AnyRouteRefParams = AnyRouteRefParams> =
+  SubRouteRef<TParams>;
+
+/** @ignore */
+type NewExternalRouteRef<
+  TParams extends AnyRouteRefParams = AnyRouteRefParams,
+  TOptional extends boolean = boolean,
+> = ExternalRouteRef<TParams, TOptional>;
+
 /**
  * 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<TParams extends AnyRouteParams>(
+export function convertLegacyRouteRef<TParams extends AnyRouteRefParams>(
   ref: LegacyRouteRef<TParams>,
-): RouteRef<TParams>;
+): NewRouteRef<TParams>;
 
 /**
  * A temporary helper to convert a legacy sub route ref to the new system.
@@ -60,9 +76,9 @@ export function convertLegacyRouteRef<TParams extends AnyRouteParams>(
  *
  * In the future the legacy createSubRouteRef will instead create refs compatible with both systems.
  */
-export function convertLegacyRouteRef<TParams extends AnyRouteParams>(
+export function convertLegacyRouteRef<TParams extends AnyRouteRefParams>(
   ref: LegacySubRouteRef<TParams>,
-): SubRouteRef<TParams>;
+): NewSubRouteRef<TParams>;
 
 /**
  * A temporary helper to convert a legacy external route ref to the new system.
@@ -73,17 +89,18 @@ export function convertLegacyRouteRef<TParams extends AnyRouteParams>(
  * 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<TParams, TOptional>,
-): ExternalRouteRef<TParams, TOptional>;
+): NewExternalRouteRef<TParams, TOptional>;
+
 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];

packages/core-plugin-api/src/routing/index.ts

@@ -16,6 +16,7 @@
 
 export type {
   AnyParams,
+  AnyRouteRefParams,
   RouteRef,
   SubRouteRef,
   ExternalRouteRef,

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<Params extends AnyParams> = keyof Params extends never
   ? []
@@ -36,6 +43,7 @@ export type ParamKeys<Params extends AnyParams> = keyof Params extends never
  * Optional route params.
  *
  * @public
+ * @deprecated this type is deprecated and will be removed in the future
  */
 export type OptionalParams<Params extends { [param in string]: string }> =
   Params[keyof Params] extends never ? undefined : Params;
@@ -81,8 +89,10 @@ export const routeRefType: unique symbol = getOrCreateGlobalSingleton<any>(
  * @public
  */
 export type RouteRef<Params extends AnyParams = any> = {
+  /** @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<Params>;
 };
 
@@ -96,12 +106,15 @@ export type RouteRef<Params extends AnyParams = any> = {
  * @public
  */
 export type SubRouteRef<Params extends AnyParams = any> = {
+  /** @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<Params>;
 };
 
@@ -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<Params>;
 
   optional?: Optional;