paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

frontend-internal: add OpaqueType helper

Browse Source 
Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
This commit is contained in:
Patrik Oldsberg
2024-09-11 11:51:40 +02:00
parent f094dfd54a
commit 873e42497a
10 changed files with 230 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/funny-rocks-train.md
+6
View File
@@ -0,0 +1,6 @@
---
'@backstage/frontend-plugin-api': patch
'@backstage/frontend-test-utils': patch
---
Internal refactor of usage of opaque types.
packages/frontend-internal/src/wiring/InternalExtensionDefinition.ts
+21 -31
View File
@@ -25,19 +25,19 @@ import {
PortableSchema,
ResolvedExtensionInputs,
} from '@backstage/frontend-plugin-api';
import { OpaqueType } from './OpaqueType';
export type InternalExtensionDefinition<
T extends ExtensionDefinitionParameters = ExtensionDefinitionParameters,
> = ExtensionDefinition<T> & {
readonly kind?: string;
readonly namespace?: string;
readonly name?: string;
readonly attachTo: { id: string; input: string };
readonly disabled: boolean;
readonly configSchema?: PortableSchema<T['config'], T['configInput']>;
} & (
export const OpaqueExtensionDefinition = OpaqueType.create<{
public: ExtensionDefinition<ExtensionDefinitionParameters>;
versions:
| {
readonly version: 'v1';
readonly kind?: string;
readonly namespace?: string;
readonly name?: string;
readonly attachTo: { id: string; input: string };
readonly disabled: boolean;
readonly configSchema?: PortableSchema<any, any>;
readonly inputs: {
[inputName in string]: {
$$type: '@backstage/ExtensionInput';
@@ -63,6 +63,12 @@ export type InternalExtensionDefinition<
}
| {
readonly version: 'v2';
readonly kind?: string;
readonly namespace?: string;
readonly name?: string;
readonly attachTo: { id: string; input: string };
readonly disabled: boolean;
readonly configSchema?: PortableSchema<any, any>;
readonly inputs: {
[inputName in string]: ExtensionInput<
AnyExtensionDataRef,
@@ -81,24 +87,8 @@ export type InternalExtensionDefinition<
>;
}>;
}): Iterable<ExtensionDataValue<any, any>>;
}
);
/** @internal */
export function toInternalExtensionDefinition<
T extends ExtensionDefinitionParameters,
>(overrides: ExtensionDefinition<T>): InternalExtensionDefinition<T> {
const internal = overrides as InternalExtensionDefinition<T>;
if (internal.$$type !== '@backstage/ExtensionDefinition') {
throw new Error(
`Invalid extension definition instance, bad type '${internal.$$type}'`,
);
}
const version = internal.version;
if (version !== 'v1' && version !== 'v2') {
throw new Error(
`Invalid extension definition instance, bad version '${version}'`,
);
}
return internal;
}
};
}>({
type: '@backstage/ExtensionDefinition',
versions: ['v1', 'v2'],
});
packages/frontend-internal/src/wiring/OpaqueType.ts
+164
View File
@@ -0,0 +1,164 @@
/*
* Copyright 2024 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.
*/
// TODO(Rugvip): This lives here temporarily, but should be moved to a more
// central location. It's useful for backend packages too so we'll need to have
// it in a common package, but it might also be that we want to make it
// available publicly too in which case it would make sense to have this be part
// of @backstage/version-bridge. The problem with exporting it from there is
// that it would need to be very stable at that point, so it might be a bit
// early to put it there already.
/**
* A helper for working with opaque types.
*/
export class OpaqueType<
T extends {
public: { $$type: string };
versions: { version: string };
},
> {
/**
* Creates a new opaque type.
*
* @param options.type The type identifier of the opaque type
* @param options.versions The available versions of the opaque type
* @returns A new opaque type helper
*/
static create<
T extends {
public: { $$type: string };
versions: { version: string };
},
>(options: {
type: T['public']['$$type'];
versions: Array<T['versions']['version']>;
}) {
return new OpaqueType<T>(options.type, new Set(options.versions));
}
#type: string;
#versions: Set<string>;
private constructor(type: string, versions: Set<string>) {
this.#type = type;
this.#versions = versions;
}
/**
* The internal version of the opaque type, used like this: `typeof MyOpaqueType.TPublic`
*
* @remarks
*
* This property is only useful for type checking, its runtime value is `undefined`.
*/
TPublic: T['public'] = undefined as any;
/**
* The internal version of the opaque type, used like this: `typeof MyOpaqueType.TInternal`
*
* @remarks
*
* This property is only useful for type checking, its runtime value is `undefined`.
*/
TInternal: T['public'] & T['versions'] = undefined as any;
/**
* @param value Input value expected to be an instance of this opaque type
* @throws If the value is not an instance of this opaque type
* @returns The internal version of the opaque type
*/
toInternal(value: unknown): T['public'] & T['versions'] {
if (!this.#isThisType(value)) {
throw new Error(
`Invalid opaque type, expected '${
this.#type
}', but got '${this.#stringifyUnknown(value)}'`,
);
}
this.#throwIfInvalidVersion(value.version);
return value;
}
/**
* @param value Input value expected to be an instance of this opaque type
* @returns True if the value matches this opaque type
*/
isInternal(value: unknown): value is T['public'] & T['versions'] {
if (!this.#isThisType(value)) {
return false;
}
this.#throwIfInvalidVersion(value.version);
return true;
}
/**
* @param version The expected version of the opaque type
* @param value Input value expected to be an instance of this opaque type
* @returns True if the value matches this opaque type and is the expected version
*/
isVersion<TVersion extends T['versions']['version']>(
version: TVersion,
value: unknown,
): value is T['public'] &
(T['versions'] extends infer UVersion
? UVersion extends { version: TVersion }
? UVersion
: never
: never) {
return this.#isThisType(value) && value.version === version;
}
/**
* Creates an instance of the opaque type, returning the public public type.
*
* By providing a type argument you can narrow the return to specific type parameters.
*/
create<TBase extends T['public'] = T['public']>(
value: T['public'] & T['versions'] & Object, // & Object to allow for object properties too, e.g. toString()
): TBase {
return value as unknown as TBase;
}
#throwIfInvalidVersion(version: string) {
if (!this.#versions.has(version)) {
const versionsStr = Array.from(this.#versions).join("', '");
throw new Error(
`Invalid opaque type instance, bad version '${version}', expected one of '${versionsStr}'`,
);
}
}
#isThisType(value: unknown): value is T['public'] & T['versions'] {
if (value === null || typeof value !== 'object') {
return false;
}
return (value as T['public']).$$type === this.#type;
}
#stringifyUnknown(value: unknown) {
if (typeof value !== 'object') {
return `<${typeof value}>`;
}
if (value === null) {
return '<null>';
}
if ('$$type' in value) {
return String(value.$$type);
}
return String(value);
}
}
packages/frontend-internal/src/wiring/index.ts
+1 -4
View File
@@ -14,7 +14,4 @@
* limitations under the License.
*/
export {
toInternalExtensionDefinition,
type InternalExtensionDefinition,
} from './InternalExtensionDefinition';
export { OpaqueExtensionDefinition } from './InternalExtensionDefinition';
packages/frontend-plugin-api/src/wiring/createExtension.ts
+24 -24
View File
@@ -31,7 +31,7 @@ import {
import { ExtensionInput } from './createExtensionInput';
import { z } from 'zod';
import { createSchemaFromZod } from '../schema/createSchemaFromZod';
import { InternalExtensionDefinition } from '@internal/frontend';
import { OpaqueExtensionDefinition } from '@internal/frontend';
/**
* Convert a single extension input into a matching resolved input.
@@ -366,26 +366,6 @@ export function createExtension<
namespace: string | undefined extends TNamespace ? undefined : TNamespace;
name: string | undefined extends TName ? undefined : TName;
}> {
type T = {
config: string extends keyof TConfigSchema
? {}
: {
[key in keyof TConfigSchema]: z.infer<ReturnType<TConfigSchema[key]>>;
};
configInput: string extends keyof TConfigSchema
? {}
: z.input<
z.ZodObject<{
[key in keyof TConfigSchema]: ReturnType<TConfigSchema[key]>;
}>
>;
output: UOutput;
inputs: TInputs;
kind: string | undefined extends TKind ? undefined : TKind;
namespace: string | undefined extends TNamespace ? undefined : TNamespace;
name: string | undefined extends TName ? undefined : TName;
};
const schemaDeclaration = options.config?.schema;
const configSchema =
schemaDeclaration &&
@@ -397,10 +377,30 @@ export function createExtension<
),
);
return {
return OpaqueExtensionDefinition.create({
$$type: '@backstage/ExtensionDefinition',
version: 'v2',
T: undefined as unknown as T,
T: undefined as unknown as {
config: string extends keyof TConfigSchema
? {}
: {
[key in keyof TConfigSchema]: z.infer<
ReturnType<TConfigSchema[key]>
>;
};
configInput: string extends keyof TConfigSchema
? {}
: z.input<
z.ZodObject<{
[key in keyof TConfigSchema]: ReturnType<TConfigSchema[key]>;
}>
>;
output: UOutput;
inputs: TInputs;
kind: string | undefined extends TKind ? undefined : TKind;
namespace: string | undefined extends TNamespace ? undefined : TNamespace;
name: string | undefined extends TName ? undefined : TName;
},
kind: options.kind,
namespace: options.namespace,
name: options.name,
@@ -512,5 +512,5 @@ export function createExtension<
},
}) as ExtensionDefinition<any>;
},
} as InternalExtensionDefinition<T>;
});
}
packages/frontend-plugin-api/src/wiring/createExtensionBlueprint.test.tsx
+3 -3
View File
@@ -29,12 +29,12 @@ import { createExtensionInput } from './createExtensionInput';
import { RouteRef } from '../routing';
import { ExtensionDefinition } from './createExtension';
import { createExtensionDataContainer } from './createExtensionDataContainer';
import { toInternalExtensionDefinition } from '@internal/frontend';
import { OpaqueExtensionDefinition } from '@internal/frontend';
function unused(..._any: any[]) {}
function factoryOutput(ext: ExtensionDefinition, inputs: unknown = undefined) {
const int = toInternalExtensionDefinition(ext);
const int = OpaqueExtensionDefinition.toInternal(ext);
if (int.version !== 'v2') {
throw new Error('Expected v2 extension');
}
@@ -680,7 +680,7 @@ describe('createExtensionBlueprint', () => {
},
});
const ext = toInternalExtensionDefinition(
const ext = OpaqueExtensionDefinition.toInternal(
blueprint.makeWithOverrides({
output: [testDataRef2],
factory(origFactory) {
packages/frontend-plugin-api/src/wiring/createFrontendModule.ts
+3 -6
View File
@@ -14,10 +14,7 @@
* limitations under the License.
*/
import {
InternalExtensionDefinition,
toInternalExtensionDefinition,
} from '@internal/frontend';
import { OpaqueExtensionDefinition } from '@internal/frontend';
import { ExtensionDefinition } from './createExtension';
import {
Extension,
@@ -58,11 +55,11 @@ export function createFrontendModule<
const extensions = new Array<Extension<any>>();
const extensionDefinitionsById = new Map<
string,
InternalExtensionDefinition
typeof OpaqueExtensionDefinition.TInternal
>();
for (const def of options.extensions ?? []) {
const internal = toInternalExtensionDefinition(def);
const internal = OpaqueExtensionDefinition.toInternal(def);
const ext = resolveExtensionDefinition(def, { namespace: pluginId });
extensions.push(ext);
extensionDefinitionsById.set(ext.id, {
packages/frontend-plugin-api/src/wiring/createFrontendPlugin.ts
+3 -6
View File
@@ -14,10 +14,7 @@
* limitations under the License.
*/
import {
InternalExtensionDefinition,
toInternalExtensionDefinition,
} from '@internal/frontend';
import { OpaqueExtensionDefinition } from '@internal/frontend';
import { ExtensionDefinition } from './createExtension';
import {
Extension,
@@ -96,11 +93,11 @@ export function createFrontendPlugin<
const extensions = new Array<Extension<any>>();
const extensionDefinitionsById = new Map<
string,
InternalExtensionDefinition
typeof OpaqueExtensionDefinition.TInternal
>();
for (const def of options.extensions ?? []) {
const internal = toInternalExtensionDefinition(def);
const internal = OpaqueExtensionDefinition.toInternal(def);
const ext = resolveExtensionDefinition(def, { namespace: options.id });
extensions.push(ext);
extensionDefinitionsById.set(ext.id, {
packages/frontend-plugin-api/src/wiring/resolveExtensionDefinition.ts
+2 -2
View File
@@ -26,7 +26,7 @@ import {
AnyExtensionDataRef,
ExtensionDataValue,
} from './createExtensionDataRef';
import { toInternalExtensionDefinition } from '@internal/frontend';
import { OpaqueExtensionDefinition } from '@internal/frontend';
/** @public */
export interface Extension<TConfig, TConfigInput = TConfig> {
@@ -141,7 +141,7 @@ export function resolveExtensionDefinition<
definition: ExtensionDefinition<T>,
context?: { namespace?: string },
): Extension<T['config'], T['configInput']> {
const internalDefinition = toInternalExtensionDefinition(definition);
const internalDefinition = OpaqueExtensionDefinition.toInternal(definition);
const {
name,
kind,
packages/frontend-test-utils/src/app/createExtensionTester.tsx
+3 -3
View File
@@ -37,7 +37,7 @@ import { instantiateAppNodeTree } from '../../../frontend-app-api/src/tree/insta
// eslint-disable-next-line @backstage/no-relative-monorepo-imports
import { readAppExtensionsConfig } from '../../../frontend-app-api/src/tree/readAppExtensionsConfig';
import { TestApiRegistry } from '@backstage/test-utils';
import { toInternalExtensionDefinition } from '@internal/frontend';
import { OpaqueExtensionDefinition } from '@internal/frontend';
/** @public */
export class ExtensionQuery<UOutput extends AnyExtensionDataRef> {
@@ -105,7 +105,7 @@ export class ExtensionTester<UOutput extends AnyExtensionDataRef> {
);
}
const { name, namespace } = toInternalExtensionDefinition(extension);
const { name, namespace } = OpaqueExtensionDefinition.toInternal(extension);
const definition = {
...extension,
@@ -143,7 +143,7 @@ export class ExtensionTester<UOutput extends AnyExtensionDataRef> {
const tree = this.#resolveTree();
// Same fallback logic as in .add
const { name, namespace } = toInternalExtensionDefinition(extension);
const { name, namespace } = OpaqueExtensionDefinition.toInternal(extension);
const definition = {
...extension,
name: !namespace && !name ? 'test' : name,