Merge pull request #7724 from backstage/freben/core-types

introduce `@backstage/types`

.changeset/rotten-melons-carry.md

@@ -0,0 +1,8 @@
+---
+'@backstage/config': patch
+'@backstage/core-app-api': patch
+'@backstage/core-plugin-api': patch
+'@backstage/plugin-scaffolder-backend': patch
+---
+
+Start using the new `@backstage/types` package. Initially, this means using the `Observable` and `Json*` types from there. The types also remain in their old places but deprecated, and will be removed in a future release.

packages/config/api-report.md

@@ -3,10 +3,15 @@
 > Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
 
 ```ts
+import type { JsonArray as JsonArray_2 } from '@backstage/types';
+import { JsonObject as JsonObject_2 } from '@backstage/types';
+import type { JsonPrimitive as JsonPrimitive_2 } from '@backstage/types';
+import { JsonValue as JsonValue_2 } from '@backstage/types';
+
 // @public
 export type AppConfig = {
   context: string;
-  data: JsonObject;
+  data: JsonObject_2;
   filteredKeys?: string[];
 };
 
@@ -17,8 +22,8 @@ export type Config = {
   };
   has(key: string): boolean;
   keys(): string[];
-  get<T = JsonValue>(key?: string): T;
-  getOptional<T = JsonValue>(key?: string): T | undefined;
+  get<T = JsonValue_2>(key?: string): T;
+  getOptional<T = JsonValue_2>(key?: string): T | undefined;
   getConfig(key: string): Config;
   getOptionalConfig(key: string): Config | undefined;
   getConfigArray(key: string): Config[];
@@ -36,7 +41,7 @@ export type Config = {
 // @public
 export class ConfigReader implements Config {
   constructor(
-    data: JsonObject | undefined,
+    data: JsonObject_2 | undefined,
     context?: string,
     fallback?: ConfigReader | undefined,
     prefix?: string,
@@ -44,7 +49,7 @@ export class ConfigReader implements Config {
   // (undocumented)
   static fromConfigs(configs: AppConfig[]): ConfigReader;
   // (undocumented)
-  get<T = JsonValue>(key?: string): T;
+  get<T = JsonValue_2>(key?: string): T;
   // (undocumented)
   getBoolean(key: string): boolean;
   // (undocumented)
@@ -54,7 +59,7 @@ export class ConfigReader implements Config {
   // (undocumented)
   getNumber(key: string): number;
   // (undocumented)
-  getOptional<T = JsonValue>(key?: string): T | undefined;
+  getOptional<T = JsonValue_2>(key?: string): T | undefined;
   // (undocumented)
   getOptionalBoolean(key: string): boolean | undefined;
   // (undocumented)
@@ -77,17 +82,15 @@ export class ConfigReader implements Config {
   keys(): string[];
 }
 
-// @public
-export interface JsonArray extends Array<JsonValue> {}
+// @public @deprecated
+export type JsonArray = JsonArray_2;
 
-// @public
-export type JsonObject = {
-  [key in string]?: JsonValue;
-};
+// @public @deprecated
+export type JsonObject = JsonObject_2;
 
-// @public
-export type JsonPrimitive = number | string | boolean | null;
+// @public @deprecated
+export type JsonPrimitive = JsonPrimitive_2;
 
-// @public
-export type JsonValue = JsonObject | JsonArray | JsonPrimitive;
+// @public @deprecated
+export type JsonValue = JsonValue_2;
 ```

packages/config/package.json

@@ -30,6 +30,7 @@
     "clean": "backstage-cli clean"
   },
   "dependencies": {
+    "@backstage/types": "^0.1.0",
     "lodash": "^4.17.21"
   },
   "devDependencies": {

packages/config/src/deprecatedTypes.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+// Temporarily re-export the JSON types from @backstage/types
+import type {
+  JsonArray as CoreJsonArray,
+  JsonObject as CoreJsonObject,
+  JsonPrimitive as CoreJsonPrimitive,
+  JsonValue as CoreJsonValue,
+} from '@backstage/types';
+
+/**
+ * A type representing all allowed JSON primitive values.
+ *
+ * @public
+ * @deprecated Please use the same type from `@backstage/types` instead
+ */
+export type JsonPrimitive = CoreJsonPrimitive;
+
+/**
+ * A type representing all allowed JSON object values.
+ *
+ * @public
+ * @deprecated Please use the same type from `@backstage/types` instead
+ */
+export type JsonObject = CoreJsonObject;
+
+/**
+ * A type representing all allowed JSON array values.
+ *
+ * @public
+ * @deprecated Please use the same type from `@backstage/types` instead
+ */
+export type JsonArray = CoreJsonArray;
+
+/**
+ * A type representing all allowed JSON values.
+ *
+ * @public
+ * @deprecated Please use the same type from `@backstage/types` instead
+ */
+export type JsonValue = CoreJsonValue;

packages/config/src/index.ts

@@ -20,12 +20,11 @@
  * @packageDocumentation
  */
 
-export { ConfigReader } from './reader';
 export type {
-  AppConfig,
-  Config,
   JsonArray,
   JsonObject,
   JsonPrimitive,
   JsonValue,
-} from './types';
+} from './deprecatedTypes';
+export { ConfigReader } from './reader';
+export type { AppConfig, Config } from './types';

packages/config/src/reader.ts

@@ -14,7 +14,8 @@
  * limitations under the License.
  */
 
-import { AppConfig, Config, JsonValue, JsonObject } from './types';
+import { JsonValue, JsonObject } from '@backstage/types';
+import { AppConfig, Config } from './types';
 import cloneDeep from 'lodash/cloneDeep';
 import mergeWith from 'lodash/mergeWith';
 

packages/config/src/types.ts

@@ -14,33 +14,7 @@
  * 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<JsonValue> {}
-
-/**
- * A type representing all allowed JSON values.
- *
- * @public
- */
-export type JsonValue = JsonObject | JsonArray | JsonPrimitive;
+import { JsonObject, JsonValue } from '@backstage/types';
 
 /**
  * A serialized form of configuration data that carries additional context.

packages/core-app-api/api-report.md

@@ -41,6 +41,7 @@ import { microsoftAuthApiRef } from '@backstage/core-plugin-api';
 import { OAuthApi } from '@backstage/core-plugin-api';
 import { OAuthRequestApi } from '@backstage/core-plugin-api';
 import { Observable } from '@backstage/core-plugin-api';
+import { Observable as Observable_2 } from '@backstage/types';
 import { oktaAuthApiRef } from '@backstage/core-plugin-api';
 import { oneloginAuthApiRef } from '@backstage/core-plugin-api';
 import { OpenIdConnectApi } from '@backstage/core-plugin-api';
@@ -340,7 +341,7 @@ export const defaultConfigLoader: AppConfigLoader;
 export class ErrorAlerter implements ErrorApi {
   constructor(alertApi: AlertApi, errorApi: ErrorApi);
   // (undocumented)
-  error$(): Observable<{
+  error$(): Observable_2<{
     error: {
       name: string;
       message: string;

packages/core-plugin-api/api-report.md

@@ -8,9 +8,12 @@
 import { BackstageTheme } from '@backstage/theme';
 import { ComponentType } from 'react';
 import { Config } from '@backstage/config';
+import { Observable as Observable_2 } from '@backstage/types';
+import { Observer as Observer_2 } from '@backstage/types';
 import { default as React_2 } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { Subscription as Subscription_2 } from '@backstage/types';
 import { SvgIconProps } from '@material-ui/core';
 
 // Warning: (ae-missing-release-tag) "AlertApi" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -18,7 +21,7 @@ import { SvgIconProps } from '@material-ui/core';
 // @public
 export type AlertApi = {
   post(alert: AlertMessage): void;
-  alert$(): Observable<AlertMessage>;
+  alert$(): Observable_2<AlertMessage>;
 };
 
 // Warning: (ae-missing-release-tag) "alertApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -201,7 +204,7 @@ export type AppTheme = {
 // @public
 export type AppThemeApi = {
   getInstalledThemes(): AppTheme[];
-  activeThemeId$(): Observable<string | undefined>;
+  activeThemeId$(): Observable_2<string | undefined>;
   getActiveThemeId(): string | undefined;
   setActiveThemeId(themeId?: string): void;
 };
@@ -478,7 +481,7 @@ export interface ElementCollection {
 // @public
 export type ErrorApi = {
   post(error: Error_2, context?: ErrorContext): void;
-  error$(): Observable<{
+  error$(): Observable_2<{
     error: Error_2;
     context?: ErrorContext;
   }>;
@@ -674,7 +677,7 @@ export type OAuthRequestApi = {
   createAuthRequester<AuthResponse>(
     options: AuthRequesterOptions<AuthResponse>,
   ): AuthRequester<AuthResponse>;
-  authRequest$(): Observable<PendingAuthRequest[]>;
+  authRequest$(): Observable_2<PendingAuthRequest[]>;
 };
 
 // Warning: (ae-missing-release-tag) "oauthRequestApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -687,27 +690,11 @@ export const oauthRequestApiRef: ApiRef<OAuthRequestApi>;
 // @public
 export type OAuthScope = string | string[];
 
-// Warning: (ae-missing-release-tag) "Observable" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
-export type Observable<T> = {
-  [Symbol.observable](): Observable<T>;
-  subscribe(observer: Observer<T>): Subscription;
-  subscribe(
-    onNext?: (value: T) => void,
-    onError?: (error: Error) => void,
-    onComplete?: () => void,
-  ): Subscription;
-};
+// @public @deprecated
+export type Observable<T> = Observable_2<T>;
 
-// Warning: (ae-missing-release-tag) "Observer" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
-export type Observer<T> = {
-  next?(value: T): void;
-  error?(error: Error): void;
-  complete?(): void;
-};
+// @public @deprecated
+export type Observer<T> = Observer_2<T>;
 
 // Warning: (ae-missing-release-tag) "oidcAuthApiRef" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
@@ -836,7 +823,7 @@ export const samlAuthApiRef: ApiRef<
 export type SessionApi = {
   signIn(): Promise<void>;
   signOut(): Promise<void>;
-  sessionState$(): Observable<SessionState>;
+  sessionState$(): Observable_2<SessionState>;
 };
 
 // Warning: (ae-missing-release-tag) "SessionState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -881,7 +868,7 @@ export interface StorageApi {
   get<T>(key: string): T | undefined;
   // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
-  observe$<T>(key: string): Observable<StorageValueChange<T>>;
+  observe$<T>(key: string): Observable_2<StorageValueChange<T>>;
   // Warning: (tsdoc-param-tag-missing-hyphen) The @param block should be followed by a parameter name and then a hyphen
   // Warning: (tsdoc-param-tag-with-invalid-type) The @param block should not include a JSDoc-style '{type}'
   remove(key: string): Promise<void>;
@@ -913,13 +900,8 @@ export type SubRouteRef<Params extends AnyParams = any> = {
   params: ParamKeys<Params>;
 };
 
-// Warning: (ae-missing-release-tag) "Subscription" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
-//
-// @public
-export type Subscription = {
-  unsubscribe(): void;
-  readonly closed: boolean;
-};
+// @public @deprecated
+export type Subscription = Subscription_2;
 
 // Warning: (ae-missing-release-tag) "TypesToApiRefs" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //

packages/core-plugin-api/package.json

@@ -31,6 +31,7 @@
   "dependencies": {
     "@backstage/config": "^0.1.9",
     "@backstage/theme": "^0.2.9",
+    "@backstage/types": "^0.1.0",
     "@backstage/version-bridge": "^0.1.0",
     "@material-ui/core": "^4.12.2",
     "@types/react": "*",

packages/core-plugin-api/src/apis/definitions/AlertApi.ts

@@ -13,8 +13,9 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 import { createApiRef, ApiRef } from '../system';
-import { Observable } from '../../types';
+import { Observable } from '@backstage/types';
 
 export type AlertMessage = {
   message: string;

packages/core-plugin-api/src/apis/definitions/AppThemeApi.ts

@@ -16,7 +16,7 @@
 
 import { ApiRef, createApiRef } from '../system';
 import { BackstageTheme } from '@backstage/theme';
-import { Observable } from '../../types';
+import { Observable } from '@backstage/types';
 
 /**
  * Describes a theme provided by the app.

packages/core-plugin-api/src/apis/definitions/ErrorApi.ts

@@ -15,7 +15,7 @@
  */
 
 import { ApiRef, createApiRef } from '../system';
-import { Observable } from '../../types';
+import { Observable } from '@backstage/types';
 
 /**
  * Mirrors the JavaScript Error class, for the purpose of

packages/core-plugin-api/src/apis/definitions/OAuthRequestApi.ts

@@ -15,7 +15,7 @@
  */
 
 import { IconComponent } from '../../icons/types';
-import { Observable } from '../../types';
+import { Observable } from '@backstage/types';
 import { ApiRef, createApiRef } from '../system';
 
 /**

packages/core-plugin-api/src/apis/definitions/StorageApi.ts

@@ -15,7 +15,7 @@
  */
 
 import { ApiRef, createApiRef } from '../system';
-import { Observable } from '../../types';
+import { Observable } from '@backstage/types';
 
 export type StorageValueChange<T = any> = {
   key: string;

packages/core-plugin-api/src/apis/definitions/auth.ts

@@ -15,7 +15,7 @@
  */
 
 import { ApiRef, createApiRef } from '../system';
-import { Observable } from '../../types';
+import { Observable } from '@backstage/types';
 
 /**
  * This file contains declarations for common interfaces of auth-related APIs.

packages/core-plugin-api/src/deprecatedTypes.ts

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  Observer as CoreObserver,
+  Subscription as CoreSubscription,
+  Observable as CoreObservable,
+} from '@backstage/types';
+
+/**
+ * Observer interface for consuming an Observer, see TC39.
+ *
+ * @public
+ * @deprecated Please use the same type from `@backstage/types` instead
+ */
+export type Observer<T> = CoreObserver<T>;
+
+/**
+ * Subscription returned when subscribing to an Observable, see TC39.
+ *
+ * @public
+ * @deprecated Please use the same type from `@backstage/types` instead
+ */
+export type Subscription = CoreSubscription;
+
+/**
+ * Observable sequence of values and errors, see TC39.
+ *
+ * https://github.com/tc39/proposal-observable
+ *
+ * This is used as a common return type for observable values and can be created
+ * using many different observable implementations, such as zen-observable or RxJS 5.
+ *
+ * @public
+ * @deprecated Please use the same type from `@backstage/types` instead
+ */
+export type Observable<T> = CoreObservable<T>;

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

@@ -27,4 +27,4 @@ export * from './extensions';
 export * from './icons';
 export * from './plugin';
 export * from './routing';
-export * from './types';
+export * from './deprecatedTypes';

packages/types/.eslintrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  extends: [require.resolve('@backstage/cli/config/eslint')],
+};

packages/types/README.md

@@ -0,0 +1,9 @@
+# Common TypeScript types used within Backstage
+
+Contains some common types that are used widely within the rest of the Backstage project and in plugins.
+
+This package will be imported both by the frontend and backend.
+
+## Links
+
+- [The Backstage homepage](https://backstage.io)

packages/types/api-report.md

@@ -0,0 +1,43 @@
+## API Report File for "@backstage/types"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+// @public
+export interface JsonArray extends Array<JsonValue> {}
+
+// @public
+export type JsonObject = {
+  [key in string]?: JsonValue;
+};
+
+// @public
+export type JsonPrimitive = number | string | boolean | null;
+
+// @public
+export type JsonValue = JsonObject | JsonArray | JsonPrimitive;
+
+// @public
+export type Observable<T> = {
+  [Symbol.observable](): Observable<T>;
+  subscribe(observer: Observer<T>): Subscription;
+  subscribe(
+    onNext?: (value: T) => void,
+    onError?: (error: Error) => void,
+    onComplete?: () => void,
+  ): Subscription;
+};
+
+// @public
+export type Observer<T> = {
+  next?(value: T): void;
+  error?(error: Error): void;
+  complete?(): void;
+};
+
+// @public
+export type Subscription = {
+  unsubscribe(): void;
+  readonly closed: boolean;
+};
+```

packages/types/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@backstage/types",
+  "description": "Common TypeScript types used within Backstage",
+  "version": "0.1.0",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "license": "Apache-2.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.esm.js",
+    "types": "dist/index.d.ts"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/backstage/backstage",
+    "directory": "packages/types"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "scripts": {
+    "build": "backstage-cli build",
+    "lint": "backstage-cli lint",
+    "test": "backstage-cli test",
+    "prepack": "backstage-cli prepack",
+    "postpack": "backstage-cli postpack",
+    "clean": "backstage-cli clean"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@backstage/cli": "^0.7.11",
+    "@types/zen-observable": "^0.8.0",
+    "zen-observable": "^0.8.15"
+  },
+  "files": [
+    "dist"
+  ]
+}

packages/types/src/index.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Common TypeScript types used within Backstage
+ *
+ * @packageDocumentation
+ */
+
+export type { JsonArray, JsonObject, JsonPrimitive, JsonValue } from './json';
+export type { Observable, Observer, Subscription } from './observable';

packages/types/src/json.test.ts

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { JsonPrimitive, JsonArray, JsonObject, JsonValue } from './json';
+
+describe('json', () => {
+  it('JsonPrimitive', () => {
+    function isValid(..._v: JsonPrimitive[]) {}
+    isValid(1, 's', true, false, null);
+
+    // @ts-expect-error
+    const v1: JsonPrimitive = [];
+    // @ts-expect-error
+    const v2: JsonPrimitive = {};
+
+    expect(true).toBe(true);
+  });
+
+  it('JsonArray', () => {
+    function isValid(..._v: JsonArray[]) {}
+    isValid([], [1, 's', true, false, null, {}, []]);
+
+    // @ts-expect-error
+    const v1: JsonArray = 1;
+    // @ts-expect-error
+    const v2: JsonArray = 's';
+    // @ts-expect-error
+    const v3: JsonArray = true;
+    // @ts-expect-error
+    const v4: JsonArray = false;
+    // @ts-expect-error
+    const v5: JsonArray = null;
+    // @ts-expect-error
+    const v6: JsonArray = {};
+
+    expect(true).toBe(true);
+  });
+
+  it('JsonObject', () => {
+    function isValid(..._v: JsonObject[]) {}
+    isValid(
+      {},
+      { v1: 1, v2: 's', v3: true, v4: false, v5: null, v6: {}, v7: [] },
+    );
+
+    // @ts-expect-error
+    const v1: JsonObject = 1;
+    // @ts-expect-error
+    const v2: JsonObject = 's';
+    // @ts-expect-error
+    const v3: JsonObject = true;
+    // @ts-expect-error
+    const v4: JsonObject = false;
+    // @ts-expect-error
+    const v5: JsonObject = null;
+    // @ts-expect-error
+    const v6: JsonObject = [];
+
+    expect(true).toBe(true);
+  });
+
+  it('JsonValue', () => {
+    function isValid(..._v: JsonValue[]) {}
+    isValid(1, 's', true, false, null, {}, []);
+
+    expect(true).toBe(true);
+  });
+});

packages/types/src/json.ts

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * 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<JsonValue> {}
+
+/**
+ * A type representing all allowed JSON values.
+ *
+ * @public
+ */
+export type JsonValue = JsonObject | JsonArray | JsonPrimitive;

packages/types/src/observable.test.ts

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2021 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import ZenObservable from 'zen-observable';
+import { Observable, Observer, Subscription } from './observable';
+
+describe('observable', () => {
+  it('works in conjunction with zen-observables', () => {
+    // Use ZenObservable as the concrete implementation, but use our types in
+    // all other possible places in the code
+    const observable: Observable<string> = new ZenObservable<string>(
+      (subscriber: Observer<string>) => {
+        subscriber.next!('a');
+        subscriber.error!(new Error('e'));
+        subscriber.complete!();
+      },
+    );
+
+    const subscription: Subscription = observable.subscribe(
+      _value => {},
+      _error => {},
+      () => {},
+    );
+
+    subscription.unsubscribe();
+
+    expect(true).toBe(true);
+  });
+});

packages/types/src/observable.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 The Backstage Authors
+ * Copyright 2021 The Backstage Authors
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -14,12 +14,10 @@
  * limitations under the License.
  */
 
-/**
- * This file contains non-react related core types used throughout Backstage.
- */
-
 /**
  * Observer interface for consuming an Observer, see TC39.
+ *
+ * @public
  */
 export type Observer<T> = {
   next?(value: T): void;
@@ -29,6 +27,8 @@ export type Observer<T> = {
 
 /**
  * Subscription returned when subscribing to an Observable, see TC39.
+ *
+ * @public
  */
 export type Subscription = {
   /**
@@ -57,6 +57,8 @@ declare global {
  *
  * This is used as a common return type for observable values and can be created
  * using many different observable implementations, such as zen-observable or RxJS 5.
+ *
+ * @public
  */
 export type Observable<T> = {
   [Symbol.observable](): Observable<T>;

packages/types/src/setupTests.ts

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {};

plugins/scaffolder-backend/api-report.md

@@ -15,7 +15,9 @@ import { createPullRequest } from 'octokit-plugin-create-pull-request';
 import { Entity } from '@backstage/catalog-model';
 import express from 'express';
 import { JsonObject } from '@backstage/config';
+import { JsonObject as JsonObject_2 } from '@backstage/types';
 import { JsonValue } from '@backstage/config';
+import { JsonValue as JsonValue_2 } from '@backstage/types';
 import { LocationSpec } from '@backstage/catalog-model';
 import { Logger as Logger_2 } from 'winston';
 import { Octokit } from '@octokit/rest';
@@ -183,7 +185,7 @@ export function createRouter(options: RouterOptions): Promise<express.Router>;
 // @public (undocumented)
 export const createTemplateAction: <
   Input extends Partial<{
-    [name: string]: JsonValue | Partial<JsonObject> | undefined;
+    [name: string]: JsonValue_2 | Partial<JsonObject_2> | undefined;
   }>,
 >(
   templateAction: TemplateAction<Input>,