@angular-devkit/architect

constructor

constructor(
    _host: ArchitectHost<any>,
    registry?: json.schema.SchemaRegistry,
    additionalJobRegistry?: Registry<JsonValue, JsonValue, JsonValue>
);

method has

has: (name: JobName) => Observable<boolean>;

method scheduleBuilder

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

method scheduleTarget

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

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<json.JsonObject>;
};

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?: json.JsonObject,
    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?: json.JsonObject,
    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 json.JsonObject = json.JsonObject>(
    options: json.JsonObject,
    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.

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.

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.

property logger

logger?: logging.Logger;

member Error

Error = 'error'

member Running

Running = 'running'

member Stopped

Stopped = 'stopped'

member Waiting

Waiting = 'waiting'

function createDispatcher

createDispatcher: <
    A extends JsonValue,
    I extends JsonValue,
    O extends JsonValue
>(
    options?: Partial<Readwrite<JobDescription>>
) => JobDispatcher<A, I, O>;

• OnReady a dispatcher that can dispatch to a sub job, depending on conditions.

  Parameter options

function createJobFactory

createJobFactory: <
    A extends JsonValue,
    I extends JsonValue,
    O extends JsonValue
>(
    loader: () => Promise<JobHandler<A, I, O>>,
    options?: Partial<JobDescription>
) => JobHandler<A, I, O>;

• Lazily create a job using a function.

  Parameter loader

  A factory function that returns a promise/observable of a JobHandler.

  Parameter options

  Same options as createJob.

function createJobHandler

createJobHandler: <
    A extends JsonValue,
    I extends JsonValue,
    O extends JsonValue
>(
    fn: SimpleJobHandlerFn<A, I, O>,
    options?: Partial<JobDescription>
) => JobHandler<A, I, O>;

• Make a simple job handler that sets start and end from a function that's synchronous.

  Parameter fn

  The function to create a handler for.

  Parameter options

  An optional set of properties to set on the handler. Some fields might be required by registry or schedulers.

function createLoggerJob

createLoggerJob: <A extends JsonValue, I extends JsonValue, O extends JsonValue>(
    job: JobHandler<A, I, O>,
    logger: logging.LoggerApi
) => JobHandler<A, I, O>;

• Creates a job that logs out input/output messages of another Job. The messages are still propagated to the other job.

function isJobHandler

isJobHandler: <A extends JsonValue, I extends JsonValue, O extends JsonValue>(
    value: unknown
) => value is JobHandler<A, I, O>;

type JobInboundMessage

type JobInboundMessage<InputT extends JsonValue> =
    | JobInboundMessagePing
    | JobInboundMessageStop
    | JobInboundMessageInput<InputT>;

type JobName

type JobName = string;

• A job name is just a string (needs to be serializable).

type JobOutboundMessage

type JobOutboundMessage<OutputT extends JsonValue> =
    | JobOutboundMessageOnReady
    | JobOutboundMessageStart
    | JobOutboundMessageOutput<OutputT>
    | JobOutboundMessageChannelCreate
    | JobOutboundMessageChannelMessage
    | JobOutboundMessageChannelError
    | JobOutboundMessageChannelComplete
    | JobOutboundMessageEnd
    | JobOutboundMessagePong;

• Generic message type.

type SimpleJobHandlerFn

type SimpleJobHandlerFn<
    A extends JsonValue,
    I extends JsonValue,
    O extends JsonValue
> = (
    input: A,
    context: SimpleJobHandlerContext<A, I, O>
) => O | Promise<O> | Observable<O>;

• A simple version of the JobHandler. This simplifies a lot of the interaction with the job scheduler and registry. For example, instead of returning a JobOutboundMessage observable, you can directly return an output.

function memoize

memoize: <
    A extends JsonValue = JsonValue,
    I extends JsonValue = JsonValue,
    O extends JsonValue = JsonValue
>(
    replayMessages?: boolean
) => JobStrategy<A, I, O>;

• Creates a JobStrategy that will reuse a running job if the argument matches.

  Parameter replayMessages

  Replay ALL messages if a job is reused, otherwise just hook up where it is.

function reuse

reuse: <
    A extends JsonValue = JsonValue,
    I extends JsonValue = JsonValue,
    O extends JsonValue = JsonValue
>(
    replayMessages?: boolean
) => JobStrategy<A, I, O>;

• Creates a JobStrategy that will always reuse a running job, and restart it if the job ended.

  Parameter replayMessages

  Replay ALL messages if a job is reused, otherwise just hook up where it is.

function serialize

serialize: <
    A extends JsonValue = JsonValue,
    I extends JsonValue = JsonValue,
    O extends JsonValue = JsonValue
>() => JobStrategy<A, I, O>;

• Creates a JobStrategy that serializes every call. This strategy can be mixed between jobs.

type JobStrategy

type JobStrategy<
    A extends JsonValue = JsonValue,
    I extends JsonValue = JsonValue,
    O extends JsonValue = JsonValue
> = (
    handler: JobHandler<A, I, O>,
    options?: Partial<Readonly<JobDescription>>
) => JobHandler<A, I, O>;