Introduction Post Canva

/**
 * @license
 * Copyright Google LLC All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.dev/license
 */
 
import { logging } from '@angular-devkit/core';
import { Url } from 'node:url';
import { Observable } from 'rxjs';
import { FileEntry, MergeStrategy, Tree } from '../tree/interface';
import { Workflow } from '../workflow/interface';
 
export interface TaskConfiguration<T = {}> {
 name: string;
 dependencies?: Array<TaskId>;
 options?: T;
}
 
export interface TaskConfigurationGenerator<T = {}> {
 toConfiguration(): TaskConfiguration<T>;
}
 
export type TaskExecutor<T = {}> = (
 options: T | undefined,
 context: SchematicContext,
) => Promise<void> | Observable<void>;
 
export interface TaskExecutorFactory<T> {
 readonly name: string;
 create(options?: T): Promise<TaskExecutor> | Observable<TaskExecutor>;
}
 
export interface TaskId {
 readonly id: number;
}
 
export interface TaskInfo {
 readonly id: number;
 readonly priority: number;
 readonly configuration: TaskConfiguration;
 readonly context: SchematicContext;
}
 
export interface ExecutionOptions {
 scope: string;
 interactive: boolean;
}
 
/**
 * The description (metadata) of a collection. This type contains every information the engine
 * needs to run. The CollectionMetadataT type parameter contains additional metadata that you
 * want to store while remaining type-safe.
 */
export type CollectionDescription<CollectionMetadataT extends object> = CollectionMetadataT & {
 readonly name: string;
 readonly extends?: string[];
};
 
/**
 * The description (metadata) of a schematic. This type contains every information the engine
 * needs to run. The SchematicMetadataT and CollectionMetadataT type parameters contain additional
 * metadata that you want to store while remaining type-safe.
 */
export type SchematicDescription<
 CollectionMetadataT extends object,
 SchematicMetadataT extends object,
> = SchematicMetadataT & {
 readonly collection: CollectionDescription<CollectionMetadataT>;
 readonly name: string;
 readonly private?: boolean;
 readonly hidden?: boolean;
};
 
/**
 * The Host for the Engine. Specifically, the piece of the tooling responsible for resolving
 * collections and schematics descriptions. The SchematicMetadataT and CollectionMetadataT type
 * parameters contain additional metadata that you want to store while remaining type-safe.
 */
export interface EngineHost<CollectionMetadataT extends object, SchematicMetadataT extends object> {
 createCollectionDescription(
 name: string,
 requester?: CollectionDescription<CollectionMetadataT>,
 ): CollectionDescription<CollectionMetadataT>;
 listSchematicNames(
 collection: CollectionDescription<CollectionMetadataT>,
 includeHidden?: boolean,
 ): string[];
 
 createSchematicDescription(
 name: string,
 collection: CollectionDescription<CollectionMetadataT>,
 ): SchematicDescription<CollectionMetadataT, SchematicMetadataT> | null;
 getSchematicRuleFactory<OptionT extends object>(
 schematic: SchematicDescription<CollectionMetadataT, SchematicMetadataT>,
 collection: CollectionDescription<CollectionMetadataT>,
 ): RuleFactory<OptionT>;
 createSourceFromUrl(
 url: Url,
 context: TypedSchematicContext<CollectionMetadataT, SchematicMetadataT>,
 ): Source | null;
 transformOptions<OptionT extends object, ResultT extends object>(
 schematic: SchematicDescription<CollectionMetadataT, SchematicMetadataT>,
 options: OptionT,
 context?: TypedSchematicContext<CollectionMetadataT, SchematicMetadataT>,
 ): Observable<ResultT>;
 transformContext(
 context: TypedSchematicContext<CollectionMetadataT, SchematicMetadataT>,
 ): TypedSchematicContext<CollectionMetadataT, SchematicMetadataT> | void;
 createTaskExecutor(name: string): Observable<TaskExecutor>;
 hasTaskExecutor(name: string): boolean;
 
 readonly defaultMergeStrategy?: MergeStrategy;
}
 
/**
 * The root Engine for creating and running schematics and collections. Everything related to
 * a schematic execution starts from this interface.
 *
 * CollectionMetadataT is, by default, a generic Collection metadata type. This is used throughout
 * the engine typings so that you can use a type that's merged into descriptions, while being
 * type-safe.
 *
 * SchematicMetadataT is a type that contains additional typing for the Schematic Description.
 */
export interface Engine<CollectionMetadataT extends object, SchematicMetadataT extends object> {
 createCollection(
 name: string,
 requester?: Collection<CollectionMetadataT, SchematicMetadataT>,
 ): Collection<CollectionMetadataT, SchematicMetadataT>;
 createContext(
 schematic: Schematic<CollectionMetadataT, SchematicMetadataT>,
 parent?: Partial<TypedSchematicContext<CollectionMetadataT, SchematicMetadataT>>,
 executionOptions?: Partial<ExecutionOptions>,
 ): TypedSchematicContext<CollectionMetadataT, SchematicMetadataT>;
 createSchematic(
 name: string,
 collection: Collection<CollectionMetadataT, SchematicMetadataT>,
 ): Schematic<CollectionMetadataT, SchematicMetadataT>;
 createSourceFromUrl(
 url: Url,
 context: TypedSchematicContext<CollectionMetadataT, SchematicMetadataT>,
 ): Source;
 transformOptions<OptionT extends object, ResultT extends object>(
 schematic: Schematic<CollectionMetadataT, SchematicMetadataT>,
 options: OptionT,
 context?: TypedSchematicContext<CollectionMetadataT, SchematicMetadataT>,
 ): Observable<ResultT>;
 executePostTasks(): Observable<void>;
 
 readonly defaultMergeStrategy: MergeStrategy;
 readonly workflow: Workflow | null;
}
 
/**
 * A Collection as created by the Engine. This should be used by the tool to create schematics,
 * or by rules to create other schematics as well.
 */
export interface Collection<CollectionMetadataT extends object, SchematicMetadataT extends object> {
 readonly description: CollectionDescription<CollectionMetadataT>;
 readonly baseDescriptions?: Array<CollectionDescription<CollectionMetadataT>>;
 
 createSchematic(
 name: string,
 allowPrivate?: boolean,
 ): Schematic<CollectionMetadataT, SchematicMetadataT>;
 listSchematicNames(includeHidden?: boolean): string[];
}
 
/**
 * A Schematic as created by the Engine. This should be used by the tool to execute the main
 * schematics, or by rules to execute other schematics as well.
 */
export interface Schematic<CollectionMetadataT extends object, SchematicMetadataT extends object> {
 readonly description: SchematicDescription<CollectionMetadataT, SchematicMetadataT>;
 readonly collection: Collection<CollectionMetadataT, SchematicMetadataT>;
 
 call<OptionT extends object>(
 options: OptionT,
 host: Observable<Tree>,
 parentContext?: Partial<TypedSchematicContext<CollectionMetadataT, SchematicMetadataT>>,
 executionOptions?: Partial<ExecutionOptions>,
 ): Observable<Tree>;
}
 
/**
 * A SchematicContext. Contains information necessary for Schematics to execute some rules, for
 * example when using another schematics, as we need the engine and collection.
 */
export interface TypedSchematicContext<
 CollectionMetadataT extends object,
 SchematicMetadataT extends object,
> {
 readonly debug: boolean;
 readonly engine: Engine<CollectionMetadataT, SchematicMetadataT>;
 readonly logger: logging.LoggerApi;
 readonly schematic: Schematic<CollectionMetadataT, SchematicMetadataT>;
 readonly strategy: MergeStrategy;
 readonly interactive: boolean;
 addTask<T extends object>(
 task: TaskConfigurationGenerator<T>,
 dependencies?: Array<TaskId>,
 ): TaskId;
}
 
/**
 * This is used by the Schematics implementations in order to avoid needing to have typing from
 * the tooling. Schematics are not specific to a tool.
 */
export type SchematicContext = TypedSchematicContext<{}, {}>;
 
/**
 * A rule factory, which is normally the way schematics are implemented. Returned by the tooling
 * after loading a schematic description.
 */
export type RuleFactory<T extends object> = (options: T) => Rule;
 
/**
 * A FileOperator applies changes synchronously to a FileEntry. An async operator returns
 * asynchronously. We separate them so that the type system can catch early errors.
 */
export type FileOperator = (entry: FileEntry) => FileEntry | null;
export type AsyncFileOperator = (tree: FileEntry) => Observable<FileEntry | null>;
 
/**
 * A source is a function that generates a Tree from a specific context. A rule transforms a tree
 * into another tree from a specific context. In both cases, an Observable can be returned if
 * the source or the rule are asynchronous. Only the last Tree generated in the observable will
 * be used though.
 *
 * We obfuscate the context of Source and Rule because the schematic implementation should not
 * know which types is the schematic or collection metadata, as they are both tooling specific.
 */
export type Source = (context: SchematicContext) => Tree | Observable<Tree>;
export type Rule = (
 tree: Tree,
 context: SchematicContext,
) => Tree | Observable<Tree> | Rule | Promise<void | Tree | Rule> | void;