@angular-devkit/architect

  • Version 0.1200.3
  • Published
  • 94.7 kB
  • 2 dependencies
  • MIT license

Install

npm i @angular-devkit/architect
yarn add @angular-devkit/architect
pnpm add @angular-devkit/architect

Overview

Angular Build Facade

Index

Functions

function createBuilder

createBuilder: <OptT = any, OutT extends unknown = any>(
fn: BuilderHandlerFn<OptT>
) => Builder<OptT & json.JsonObject>;

    function fromAsyncIterable

    fromAsyncIterable: <T>(iterable: AsyncIterable<T>) => any;

      function isBuilderOutput

      isBuilderOutput: (obj: any) => obj is any;

        function scheduleTargetAndForget

        scheduleTargetAndForget: (
        context: BuilderContext,
        target: Target,
        overrides?: any,
        scheduleOptions?: ScheduleOptions
        ) => any;
        • Schedule a target, and forget about its run. This will return an observable of outputs, that as a a teardown will stop the target from running. This means that the Run object this returns should not be shared.

          The reason this is not part of the Context interface is to keep the Context as normal form as possible. This is really an utility that people would implement in their project.

          Parameter context

          The context of your current execution.

          Parameter target

          The target to schedule.

          Parameter overrides

          Overrides that are used in the target.

          Parameter scheduleOptions

          Additional scheduling options.

        function targetFromTargetString

        targetFromTargetString: (str: string) => Target;
        • Return a Target tuple from a string.

        function targetStringFromTarget

        targetStringFromTarget: ({ project, target, configuration }: Target) => string;
        • Returns a string of "project:target[:configuration]" for the target object.

        Classes

        class Architect

        class Architect {}

          constructor

          constructor(
          _host: ArchitectHost<any>,
          registry?: any,
          additionalJobRegistry?: any
          );

            method has

            has: (name: any) => any;

              method scheduleBuilder

              scheduleBuilder: (
              name: string,
              options: any,
              scheduleOptions?: ScheduleOptions
              ) => Promise<BuilderRun>;

                method scheduleTarget

                scheduleTarget: (
                target: Target,
                overrides?: any,
                scheduleOptions?: ScheduleOptions
                ) => Promise<BuilderRun>;

                  Interfaces

                  interface BuilderContext

                  interface BuilderContext {}
                  • The context received as a second argument in your builder.

                  property analytics

                  readonly analytics: analytics.Analytics;
                  • API to report analytics. This might be undefined if the feature is unsupported. This might not be undefined, but the backend could also not report anything.

                  property builder

                  builder: BuilderInfo;
                  • The builder info that called your function. Since the builder info is from the builder.json (or the host), it could contain information that is different than expected.

                  property currentDirectory

                  currentDirectory: string;
                  • The current directory the user is in. This could be outside the workspace root. This is a system path and will not be normalized; ie. on Windows it will starts with C:\\ (or whatever drive).

                  property id

                  id: number;
                  • Unique amongst contexts. Contexts instances are not guaranteed to be the same (but it could be the same context), and all the fields in a context could be the same, yet the builder's context could be different. This is the same ID as the corresponding run.

                  property logger

                  logger: logging.LoggerApi;
                  • A logger that appends messages to a log. This could be a separate interface or completely ignored. console.log could also be completely ignored.

                  property target

                  target?: Target;
                  • The target that was used to run this builder. Target is optional if a builder was ran using scheduleBuilder().

                  property workspaceRoot

                  workspaceRoot: string;
                  • The absolute workspace root of this run. This is a system path and will not be normalized; ie. on Windows it will starts with C:\\ (or whatever drive).

                  method addTeardown

                  addTeardown: (teardown: () => Promise<void> | void) => void;
                  • Add teardown logic to this Context, so that when it's being stopped it will execute teardown.

                  method getBuilderNameForTarget

                  getBuilderNameForTarget: (target: Target) => Promise<string>;
                  • Resolves and return a builder name. The exact format of the name is up to the host, so it should not be parsed to gather information (it's free form). This string can be used to validate options or schedule a builder directly.

                    Parameter target

                    The target to resolve the builder name.

                  method getProjectMetadata

                  getProjectMetadata: {
                  (projectName: string): Promise<json.JsonObject>;
                  (target: any): Promise<any>;
                  };

                    method getTargetOptions

                    getTargetOptions: (target: Target) => Promise<json.JsonObject>;
                    • Resolve and return options for a specified target. If the target isn't defined in the workspace this will reject the promise. This object will be read directly from the workspace but not validated against the builder of the target.

                      Parameter target

                      The target to resolve the options of. A non-validated object resolved from the workspace.

                    method reportProgress

                    reportProgress: (current: number, total?: number, status?: string) => void;
                    • Update the progress for this builder run.

                      Parameter current

                      The current progress. This will be between 0 and total.

                      Parameter total

                      A new total to set. By default at the start of a run this is 1. If omitted it will use the same value as the last total.

                      Parameter status

                      Update the status string. If omitted the status string is not modified.

                    method reportRunning

                    reportRunning: () => void;
                    • Set the builder to running. This should be used if an external event triggered a re-run, e.g. a file watched was changed.

                    method reportStatus

                    reportStatus: (status: string) => void;
                    • Update the status string shown on the interface.

                      Parameter status

                      The status to set it to. An empty string can be used to remove the status.

                    method scheduleBuilder

                    scheduleBuilder: (
                    builderName: string,
                    options?: any,
                    scheduleOptions?: ScheduleOptions
                    ) => Promise<BuilderRun>;
                    • Schedule a builder by its name. This can be the same builder that is being executed.

                      Parameter builderName

                      The name of the builder, ie. its packageName:builderName tuple.

                      Parameter options

                      All options to use for the builder (by default empty object). There is no additional options added, e.g. from the workspace.

                      Parameter scheduleOptions

                      Additional optional scheduling options. A promise of a run. It will resolve when all the members of the run are available.

                    method scheduleTarget

                    scheduleTarget: (
                    target: Target,
                    overrides?: any,
                    scheduleOptions?: ScheduleOptions
                    ) => Promise<BuilderRun>;
                    • Schedule a target in the same workspace. This can be the same target that is being executed right now, but targets of the same name are serialized. Running the same target and waiting for it to end will result in a deadlocking scenario. Targets are considered the same if the project, the target AND the configuration are the same.

                      Parameter target

                      The target to schedule.

                      Parameter overrides

                      A set of options to override the workspace set of options.

                      Parameter scheduleOptions

                      Additional optional scheduling options. A promise of a run. It will resolve when all the members of the run are available.

                    method validateOptions

                    validateOptions: <T extends any = any>(
                    options: any,
                    builderName: string
                    ) => Promise<T>;
                    • Validates the options against a builder schema. This uses the same methods as the scheduleTarget and scheduleBrowser methods to validate and apply defaults to the options. It can be generically typed, if you know which interface it is supposed to validate against.

                      Parameter options

                      A generic option object to validate.

                      Parameter builderName

                      The name of a builder to use. This can be gotten for a target by using the getBuilderForTarget() method on the context.

                    interface BuilderHandlerFn

                    interface BuilderHandlerFn<A> {}
                    • A builder handler function. The function signature passed to createBuilder().

                    call signature

                    (input: A, context: BuilderContext): BuilderOutputLike;
                    • Builders are defined by users to perform any kind of task, like building, testing or linting, and should use this interface.

                      Parameter input

                      The options (a JsonObject), validated by the schema and received by the builder. This can include resolved options from the CLI or the workspace.

                      Parameter context

                      A context that can be used to interact with the Architect framework. One or many builder output.

                    interface BuilderRun

                    interface BuilderRun {}
                    • A Run, which is what is returned by scheduleBuilder or scheduleTarget functions. This should be reconstructed across memory boundaries (it's not serializable but all internal information are).

                    property id

                    id: number;
                    • Unique amongst runs. This is the same ID as the context generated for the run. It can be used to identify multiple unique runs. There is no guarantee that a run is a single output; a builder can rebuild on its own and will generate multiple outputs.

                    property info

                    info: BuilderInfo;
                    • The builder information.

                    property output

                    output: Observable<BuilderOutput>;
                    • The output(s) from the builder. A builder can have multiple outputs. This always replay the last output when subscribed.

                    property progress

                    progress: Observable<BuilderProgressReport>;
                    • The progress report. A progress also contains an ID, which can be different than this run's ID (if the builder calls scheduleBuilder or scheduleTarget). This will always replay the last progress on new subscriptions.

                    property result

                    result: Promise<BuilderOutput>;
                    • The next output from a builder. This is recommended when scheduling a builder and only being interested in the result of that single run, not of a watch-mode builder.

                    method stop

                    stop: () => Promise<void>;
                    • Stop the builder from running. Returns a promise that resolves when the builder is stopped. Some builders might not handle stopping properly and should have a timeout here.

                    interface ScheduleOptions

                    interface ScheduleOptions {}

                      property analytics

                      analytics?: analytics.Analytics;

                        property logger

                        logger?: logging.Logger;

                          Enums

                          enum BuilderProgressState

                          enum BuilderProgressState {
                          Error = 'error',
                          Running = 'running',
                          Stopped = 'stopped',
                          Waiting = 'waiting',
                          }

                            member Error

                            Error = 'error'

                              member Running

                              Running = 'running'

                                member Stopped

                                Stopped = 'stopped'

                                  member Waiting

                                  Waiting = 'waiting'

                                    Type Aliases

                                    type BuilderInfo

                                    type BuilderInfo = json.JsonObject & {
                                    builderName: string;
                                    description: string;
                                    optionSchema: json.schema.JsonSchema;
                                    };
                                    • A Builder general information. This is generated by the host and is expanded by the host, but the public API contains those fields.

                                    type BuilderInput

                                    type BuilderInput = json.JsonObject & RealBuilderInput;
                                    • Declaration of those types as JsonObject compatible. JsonObject is not compatible with optional members, so those wouldn't be directly assignable to our internal Json typings. Forcing the type to be both a JsonObject and the type from the Schema tells Typescript they are compatible (which they are). These types should be used everywhere.

                                    type BuilderOutput

                                    type BuilderOutput = json.JsonObject & RealBuilderOutput;

                                      type BuilderOutputLike

                                      type BuilderOutputLike =
                                      | AsyncIterable<BuilderOutput>
                                      | SubscribableOrPromise<BuilderOutput>
                                      | BuilderOutput;
                                      • An accepted return value from a builder. Can be either an Observable, a Promise or a vector.

                                      type BuilderProgress

                                      type BuilderProgress = json.JsonObject & RealBuilderProgress & TypedBuilderProgress;

                                        type BuilderProgressReport

                                        type BuilderProgressReport = BuilderProgress & {
                                        target?: Target;
                                        builder: BuilderInfo;
                                        };
                                        • A progress report is what the tooling will receive. It contains the builder info and the target. Although these are serializable, they are only exposed through the tooling interface, not the builder interface. The watch dog sends BuilderProgress and the Builder has a set of functions to manage the state.

                                        type BuilderRegistry

                                        type BuilderRegistry = experimental.jobs.Registry<
                                        json.JsonObject,
                                        BuilderInput,
                                        BuilderOutput
                                        >;

                                          type Target

                                          type Target = json.JsonObject & RealTarget;

                                            type TypedBuilderProgress

                                            type TypedBuilderProgress =
                                            | {
                                            state: BuilderProgressState.Stopped;
                                            }
                                            | {
                                            state: BuilderProgressState.Error;
                                            error: json.JsonValue;
                                            }
                                            | {
                                            state: BuilderProgressState.Waiting;
                                            status?: string;
                                            }
                                            | {
                                            state: BuilderProgressState.Running;
                                            status?: string;
                                            current: number;
                                            total?: number;
                                            };
                                            • An API typed BuilderProgress. The interface generated from the schema is too permissive, so this API is the one we show in our API. Please note that not all fields are in there; this is in addition to fields in the schema.

                                            Package Files (5)

                                            Dependencies (2)

                                            Dev Dependencies (0)

                                            No dev dependencies.

                                            Peer Dependencies (0)

                                            No peer dependencies.

                                            Badge

                                            To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                            You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@angular-devkit/architect.

                                            • Markdown
                                              [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@angular-devkit/architect)
                                            • HTML
                                              <a href="https://www.jsdocs.io/package/@angular-devkit/architect"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>