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

add enhanced/documented filter/global types and creator functions

Browse Source 
Signed-off-by: Matt Benson <gudnabrsam@gmail.com>
This commit is contained in:
Matt Benson
2025-02-07 11:55:49 -06:00
parent 846ed95c0e
commit dc8dd4bea7
19 changed files with 983 additions and 235 deletions
Download Patch File Download Diff File Expand all files Collapse all files
plugins/scaffolder-node/package.json
+2 -2
View File
@@ -26,7 +26,7 @@
"license": "Apache-2.0",
"exports": {
".": "./src/index.ts",
"./alpha": "./src/alpha.ts",
"./alpha": "./src/alpha/index.ts",
"./package.json": "./package.json"
},
"main": "src/index.ts",
@@ -34,7 +34,7 @@
"typesVersions": {
"*": {
"alpha": [
"src/alpha.ts"
"src/alpha/index.ts"
],
"package.json": [
"package.json"
plugins/scaffolder-node/report-alpha.api.md
+140 -4
View File
@@ -6,10 +6,12 @@
/// <reference types="node" />
import { ExtensionPoint } from '@backstage/backend-plugin-api';
import { JsonValue } from '@backstage/types';
import { TaskBroker } from '@backstage/plugin-scaffolder-node';
import { TemplateAction } from '@backstage/plugin-scaffolder-node';
import { TemplateFilter } from '@backstage/plugin-scaffolder-node';
import { TemplateGlobal } from '@backstage/plugin-scaffolder-node';
import { TemplateFilter as TemplateFilter_2 } from '@backstage/plugin-scaffolder-node';
import { TemplateGlobal as TemplateGlobal_2 } from '@backstage/plugin-scaffolder-node';
import { z } from 'zod';
// @alpha
export type AutocompleteHandler = ({
@@ -27,6 +29,92 @@ export type AutocompleteHandler = ({
}[];
}>;
// @alpha (undocumented)
export type CreatedTemplateFilter<
TSchema extends
| TemplateFilterSchema<any, any>
| undefined
| unknown = unknown,
TFilterSchema extends TSchema extends TemplateFilterSchema<any, any>
? z.infer<ReturnType<TSchema>>
: TSchema extends unknown
? unknown
: TemplateFilter = TSchema extends TemplateFilterSchema<any, any>
? z.infer<ReturnType<TSchema>>
: TSchema extends unknown
? unknown
: TemplateFilter,
> = {
id: string;
description?: string;
examples?: TemplateFilterExample[];
schema?: TSchema;
filter: TFilterSchema;
};
// @alpha (undocumented)
export type CreatedTemplateGlobal =
| CreatedTemplateGlobalValue
| CreatedTemplateGlobalFunction<unknown, unknown>;
// @alpha (undocumented)
export type CreatedTemplateGlobalFunction<
TSchema extends
| TemplateGlobalFunctionSchema<any, any>
| undefined
| unknown = unknown,
TFilterSchema extends TSchema extends TemplateGlobalFunctionSchema<any, any>
? z.infer<ReturnType<TSchema>>
: TSchema extends unknown
? unknown
: Exclude<
TemplateGlobal,
JsonValue
> = TSchema extends TemplateGlobalFunctionSchema<any, any>
? z.infer<ReturnType<TSchema>>
: TSchema extends unknown
? unknown
: Exclude<TemplateGlobal, JsonValue>,
> = {
id: string;
description?: string;
examples?: TemplateGlobalFunctionExample[];
schema?: TSchema;
fn: TFilterSchema;
};
// @alpha (undocumented)
export type CreatedTemplateGlobalValue<T extends JsonValue = JsonValue> = {
id: string;
value: T;
description?: string;
};
// @alpha
export const createTemplateFilter: <
TSchema extends TemplateFilterSchema<any, any> | undefined,
TFunctionSchema extends TSchema extends TemplateFilterSchema<any, any>
? z.TypeOf<ReturnType<TSchema>>
: (arg: JsonValue, ...rest: JsonValue[]) => JsonValue | undefined,
>(
filter: CreatedTemplateFilter<TSchema, TFunctionSchema>,
) => CreatedTemplateFilter<unknown, unknown>;
// @alpha
export const createTemplateGlobalFunction: <
TSchema extends TemplateGlobalFunctionSchema<any, any> | undefined,
TFilterSchema extends TSchema extends TemplateGlobalFunctionSchema<any, any>
? z.TypeOf<ReturnType<TSchema>>
: (...args: JsonValue[]) => JsonValue | undefined,
>(
fn: CreatedTemplateGlobalFunction<TSchema, TFilterSchema>,
) => CreatedTemplateGlobalFunction<any, any>;
// @alpha
export const createTemplateGlobalValue: (
v: CreatedTemplateGlobalValue,
) => CreatedTemplateGlobalValue;
// @alpha
export const restoreWorkspace: (opts: {
path: string;
@@ -69,9 +157,13 @@ export const scaffolderTaskBrokerExtensionPoint: ExtensionPoint<ScaffolderTaskBr
// @alpha
export interface ScaffolderTemplatingExtensionPoint {
// (undocumented)
addTemplateFilters(filters: Record<string, TemplateFilter>): void;
addTemplateFilters(
filters: Record<string, TemplateFilter_2> | CreatedTemplateFilter[],
): void;
// (undocumented)
addTemplateGlobals(filters: Record<string, TemplateGlobal>): void;
addTemplateGlobals(
globals: Record<string, TemplateGlobal_2> | CreatedTemplateGlobal[],
): void;
}
// @alpha
@@ -91,6 +183,50 @@ export const serializeWorkspace: (opts: { path: string }) => Promise<{
contents: Buffer;
}>;
// @public (undocumented)
export type TemplateFilter = (
arg: JsonValue,
...rest: JsonValue[]
) => JsonValue | undefined;
// @alpha (undocumented)
export type TemplateFilterExample = {
description?: string;
example: string;
notes?: string;
};
// @alpha (undocumented)
export type TemplateFilterSchema<
Args extends z.ZodTuple<
| [z.ZodType<JsonValue>]
| [z.ZodType<JsonValue>, ...(z.ZodType<JsonValue> | z.ZodUnknown)[]],
z.ZodType<JsonValue> | z.ZodUnknown | null
>,
Result extends z.ZodType<JsonValue> | z.ZodUndefined,
> = (zod: typeof z) => z.ZodFunction<Args, Result>;
// @public (undocumented)
export type TemplateGlobal =
| ((...args: JsonValue[]) => JsonValue | undefined)
| JsonValue;
// @alpha (undocumented)
export type TemplateGlobalFunctionExample = {
description?: string;
example: string;
notes?: string;
};
// @alpha (undocumented)
export type TemplateGlobalFunctionSchema<
Args extends z.ZodTuple<
[] | [z.ZodType<JsonValue>, ...(z.ZodType<JsonValue> | z.ZodUnknown)[]],
z.ZodType<JsonValue> | z.ZodUnknown | null
>,
Result extends z.ZodType<JsonValue> | z.ZodUndefined,
> = (zod: typeof z) => z.ZodFunction<Args, Result>;
// @alpha
export interface WorkspaceProvider {
// (undocumented)
plugins/scaffolder-node/report.api.md
+4 -1
View File
@@ -482,7 +482,10 @@ export type TemplateExample = {
};
// @public (undocumented)
export type TemplateFilter = (...args: JsonValue[]) => JsonValue | undefined;
export type TemplateFilter = (
arg: JsonValue,
...rest: JsonValue[]
) => JsonValue | undefined;
// @public (undocumented)
export type TemplateGlobal =
plugins/scaffolder-node/src/alpha/filters/createTemplateFilter.ts
+32
View File
@@ -0,0 +1,32 @@
/*
* Copyright 2025 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 { JsonValue } from '@backstage/types';
import { CreatedTemplateFilter, TemplateFilterSchema } from './types';
import { z } from 'zod';
/**
* This function is used to create new template filters in type-safe manner.
* @alpha
*/
export const createTemplateFilter = <
TSchema extends TemplateFilterSchema<any, any> | undefined,
TFunctionSchema extends TSchema extends TemplateFilterSchema<any, any>
? z.infer<ReturnType<TSchema>>
: (arg: JsonValue, ...rest: JsonValue[]) => JsonValue | undefined,
>(
filter: CreatedTemplateFilter<TSchema, TFunctionSchema>,
): CreatedTemplateFilter<unknown, unknown> => filter;
plugins/scaffolder-node/src/alpha/filters/index.ts
+17
View File
@@ -0,0 +1,17 @@
/*
* Copyright 2025 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 * from './types';
export * from './createTemplateFilter';
plugins/scaffolder-node/src/alpha/filters/types.ts
+60
View File
@@ -0,0 +1,60 @@
/*
* Copyright 2025 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 { z } from 'zod';
import { TemplateFilter } from '../../types';
import { JsonValue } from '@backstage/types';
export type { TemplateFilter } from '../../types';
/** @alpha */
export type TemplateFilterSchema<
Args extends z.ZodTuple<
| [z.ZodType<JsonValue>]
| [z.ZodType<JsonValue>, ...(z.ZodType<JsonValue> | z.ZodUnknown)[]],
z.ZodType<JsonValue> | z.ZodUnknown | null
>,
Result extends z.ZodType<JsonValue> | z.ZodUndefined,
> = (zod: typeof z) => z.ZodFunction<Args, Result>;
/** @alpha */
export type TemplateFilterExample = {
description?: string;
example: string;
notes?: string;
};
/** @alpha */
export type CreatedTemplateFilter<
TSchema extends
| TemplateFilterSchema<any, any>
| undefined
| unknown = unknown,
TFilterSchema extends TSchema extends TemplateFilterSchema<any, any>
? z.infer<ReturnType<TSchema>>
: TSchema extends unknown
? unknown
: TemplateFilter = TSchema extends TemplateFilterSchema<any, any>
? z.infer<ReturnType<TSchema>>
: TSchema extends unknown
? unknown
: TemplateFilter,
> = {
id: string;
description?: string;
examples?: TemplateFilterExample[];
schema?: TSchema;
filter: TFilterSchema;
};
plugins/scaffolder-node/src/alpha/globals/createTemplateGlobal.ts
+48
View File
@@ -0,0 +1,48 @@
/*
* Copyright 2025 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 { z } from 'zod';
import {
CreatedTemplateGlobalFunction,
CreatedTemplateGlobalValue,
TemplateGlobalFunctionSchema,
} from './types';
import { JsonValue } from '@backstage/types';
/**
* This function is used to create new template global values in type-safe manner.
* @param t - CreatedTemplateGlobalValue | CreatedTemplateGlobalFunction
* @returns t
* @alpha
*/
export const createTemplateGlobalValue = (
v: CreatedTemplateGlobalValue,
): CreatedTemplateGlobalValue => v;
/**
* This function is used to create new template global functions in type-safe manner.
* @param fn - CreatedTemplateGlobalFunction
* @returns fn
* @alpha
*/
export const createTemplateGlobalFunction = <
TSchema extends TemplateGlobalFunctionSchema<any, any> | undefined,
TFilterSchema extends TSchema extends TemplateGlobalFunctionSchema<any, any>
? z.infer<ReturnType<TSchema>>
: (...args: JsonValue[]) => JsonValue | undefined,
>(
fn: CreatedTemplateGlobalFunction<TSchema, TFilterSchema>,
): CreatedTemplateGlobalFunction<any, any> => fn;
plugins/scaffolder-node/src/alpha/globals/index.ts
+17
View File
@@ -0,0 +1,17 @@
/*
* Copyright 2025 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 * from './types';
export * from './createTemplateGlobal';
plugins/scaffolder-node/src/alpha/globals/types.ts
+74
View File
@@ -0,0 +1,74 @@
/*
* Copyright 2025 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 { JsonValue } from '@backstage/types';
import { z } from 'zod';
import { TemplateGlobal } from '../../types';
export type { TemplateGlobal } from '../../types';
/** @alpha */
export type CreatedTemplateGlobalValue<T extends JsonValue = JsonValue> = {
id: string;
value: T;
description?: string;
};
/** @alpha */
export type TemplateGlobalFunctionSchema<
Args extends z.ZodTuple<
[] | [z.ZodType<JsonValue>, ...(z.ZodType<JsonValue> | z.ZodUnknown)[]],
z.ZodType<JsonValue> | z.ZodUnknown | null
>,
Result extends z.ZodType<JsonValue> | z.ZodUndefined,
> = (zod: typeof z) => z.ZodFunction<Args, Result>;
/** @alpha */
export type TemplateGlobalFunctionExample = {
description?: string;
example: string;
notes?: string;
};
/** @alpha */
export type CreatedTemplateGlobalFunction<
TSchema extends
| TemplateGlobalFunctionSchema<any, any>
| undefined
| unknown = unknown,
TFilterSchema extends TSchema extends TemplateGlobalFunctionSchema<any, any>
? z.infer<ReturnType<TSchema>>
: TSchema extends unknown
? unknown
: Exclude<
TemplateGlobal,
JsonValue
> = TSchema extends TemplateGlobalFunctionSchema<any, any>
? z.infer<ReturnType<TSchema>>
: TSchema extends unknown
? unknown
: Exclude<TemplateGlobal, JsonValue>,
> = {
id: string;
description?: string;
examples?: TemplateGlobalFunctionExample[];
schema?: TSchema;
fn: TFilterSchema;
};
/** @alpha */
export type CreatedTemplateGlobal =
| CreatedTemplateGlobalValue
| CreatedTemplateGlobalFunction<unknown, unknown>;
plugins/scaffolder-node/src/alpha.ts → plugins/scaffolder-node/src/alpha/index.ts
+11 -3
View File
@@ -21,8 +21,12 @@ import {
TemplateFilter,
TemplateGlobal,
} from '@backstage/plugin-scaffolder-node';
import { CreatedTemplateFilter } from './filters';
import { CreatedTemplateGlobal } from './globals';
export * from './tasks/alpha';
export * from '../tasks/alpha';
export * from './filters';
export * from './globals';
/**
* Extension point for managing scaffolder actions.
@@ -68,9 +72,13 @@ export const scaffolderTaskBrokerExtensionPoint =
* @alpha
*/
export interface ScaffolderTemplatingExtensionPoint {
addTemplateFilters(filters: Record<string, TemplateFilter>): void;
addTemplateFilters(
filters: Record<string, TemplateFilter> | CreatedTemplateFilter[],
): void;
addTemplateGlobals(filters: Record<string, TemplateGlobal>): void;
addTemplateGlobals(
globals: Record<string, TemplateGlobal> | CreatedTemplateGlobal[],
): void;
}
/**
plugins/scaffolder-node/src/index.ts
+1 -1
View File
@@ -23,4 +23,4 @@
export * from './actions';
export * from './tasks';
export * from './files';
export type { TemplateFilter, TemplateGlobal } from './types';
export * from './types';