feat(@angular-devkit/architect): QoL changes for builders

Add a scheduling options to scheduleTarget and Builder on the context so
builders can schedule sub-builds and override the logger.

Add a getTargetOptions() for builders to get access to options from the
host for a specific target. This allows builders to get options, override
some, then scheduleBuilder with those new options, for example.

Author: hansl

packages/angular_devkit/architect/src/api.ts

@@ -99,6 +99,17 @@ export interface BuilderRun {
   stop(): Promise<void>;
 }
 
+/**
+ * Additional optional scheduling options.
+ */
+export interface ScheduleOptions {
+  /**
+   * Logger to pass to the builder. Note that messages will stop being forwarded, and if you want
+   * to log a builder scheduled from your builder you should forward log events yourself.
+   */
+  logger?: logging.Logger;
+}
+
 /**
  * The context received as a second argument in your builder.
  */
@@ -148,25 +159,38 @@ export interface BuilderContext {
    * Targets are considered the same if the project, the target AND the configuration are the same.
    * @param target The target to schedule.
    * @param overrides A set of options to override the workspace set of options.
+   * @param scheduleOptions Additional optional scheduling options.
    * @return A promise of a run. It will resolve when all the members of the run are available.
    */
   scheduleTarget(
     target: Target,
     overrides?: json.JsonObject,
+    scheduleOptions?: ScheduleOptions,
   ): Promise<BuilderRun>;
 
   /**
    * Schedule a builder by its name. This can be the same builder that is being executed.
    * @param builderName The name of the builder, ie. its `packageName:builderName` tuple.
    * @param options All options to use for the builder (by default empty object). There is no
    *     additional options added, e.g. from the workspace.
+   * @param scheduleOptions Additional optional scheduling options.
    * @return A promise of a run. It will resolve when all the members of the run are available.
    */
   scheduleBuilder(
     builderName: string,
     options?: json.JsonObject,
+    scheduleOptions?: ScheduleOptions,
   ): Promise<BuilderRun>;
 
+  /**
+   * 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.
+   * @param target The target to resolve the options of.
+   * @return A non-validated object resolved from the workspace.
+   */
+  getTargetOptions(target: Target): Promise<json.JsonObject>;
+
   /**
    * Set the builder to running. This should be used if an external event triggered a re-run,
    * e.g. a file watched was changed.

packages/angular_devkit/architect/src/architect.ts

@@ -108,7 +108,7 @@ export interface ScheduleOptions {
 /**
  * A JobRegistry that resolves builder targets from the host.
  */
-export class ArchitectBuilderJobRegistry implements BuilderRegistry {
+class ArchitectBuilderJobRegistry implements BuilderRegistry {
   constructor(
     protected _host: ArchitectHost,
     protected _registry: json.schema.SchemaRegistry,
@@ -172,18 +172,16 @@ export class ArchitectBuilderJobRegistry implements BuilderRegistry {
     return result;
   }
 
-  get<
-    A extends json.JsonObject,
-    I extends BuilderInput,
-    O extends BuilderOutput,
-    >(name: string): Observable<experimental.jobs.JobHandler<A, I, O> | null> {
+  get<A extends json.JsonObject, I extends BuilderInput, O extends BuilderOutput>(
+    name: string,
+  ): Observable<experimental.jobs.JobHandler<A, I, O> | null> {
     const m = name.match(/^([^:]+):([^:]+)$/i);
     if (!m) {
       return of(null);
     }
 
     return from(this._resolveBuilder(name)).pipe(
-      concatMap(builderInfo => builderInfo ? this._createBuilder(builderInfo) : of(null)),
+      concatMap(builderInfo => (builderInfo ? this._createBuilder(builderInfo) : of(null))),
       first(null, null),
     ) as Observable<experimental.jobs.JobHandler<A, I, O> | null>;
   }
@@ -192,12 +190,10 @@ export class ArchitectBuilderJobRegistry implements BuilderRegistry {
 /**
  * A JobRegistry that resolves targets from the host.
  */
-export class ArchitectTargetJobRegistry extends ArchitectBuilderJobRegistry {
-  get<
-    A extends json.JsonObject,
-    I extends BuilderInput,
-    O extends BuilderOutput,
-    >(name: string): Observable<experimental.jobs.JobHandler<A, I, O> | null> {
+class ArchitectTargetJobRegistry extends ArchitectBuilderJobRegistry {
+  get<A extends json.JsonObject, I extends BuilderInput, O extends BuilderOutput>(
+    name: string,
+  ): Observable<experimental.jobs.JobHandler<A, I, O> | null> {
     const m = name.match(/^{([^:]+):([^:]+)(?::([^:]*))?}$/i);
     if (!m) {
       return of(null);
@@ -209,10 +205,12 @@ export class ArchitectTargetJobRegistry extends ArchitectBuilderJobRegistry {
       configuration: m[3],
     };
 
-    return from(Promise.all([
-      this._host.getBuilderNameForTarget(target),
-      this._host.getOptionsForTarget(target),
-    ])).pipe(
+    return from(
+      Promise.all([
+        this._host.getBuilderNameForTarget(target),
+        this._host.getOptionsForTarget(target),
+      ]),
+    ).pipe(
       concatMap(([builderStr, options]) => {
         if (builderStr === null || options === null) {
           return of(null);
@@ -234,6 +232,22 @@ export class ArchitectTargetJobRegistry extends ArchitectBuilderJobRegistry {
 }
 
 
+function _getTargetOptionsFactory(host: ArchitectHost) {
+  return experimental.jobs.createJobHandler<Target, json.JsonValue, json.JsonObject>(
+    target => {
+      return host.getOptionsForTarget(target).then(options => {
+        return options || {};
+      });
+    },
+    {
+      name: '..getTargetOptions',
+      output: { type: 'object' },
+      argument: inputSchema.properties.target,
+    },
+  );
+}
+
+
 export class Architect {
   private readonly _scheduler: experimental.jobs.Scheduler;
   private readonly _jobCache = new Map<string, Observable<BuilderJobHandler>>();
@@ -244,9 +258,14 @@ export class Architect {
     private _registry: json.schema.SchemaRegistry = new json.schema.CoreSchemaRegistry(),
     additionalJobRegistry?: experimental.jobs.Registry,
   ) {
+    const privateArchitectJobRegistry = new experimental.jobs.SimpleJobRegistry();
+    // Create private jobs.
+    privateArchitectJobRegistry.register(_getTargetOptionsFactory(_host));
+
     const jobRegistry = new experimental.jobs.FallbackRegistry([
       new ArchitectTargetJobRegistry(_host, _registry, this._jobCache, this._infoCache),
       new ArchitectBuilderJobRegistry(_host, _registry, this._jobCache, this._infoCache),
+      privateArchitectJobRegistry,
       ...(additionalJobRegistry ? [additionalJobRegistry] : []),
     ] as experimental.jobs.Registry[]);
 

packages/angular_devkit/architect/src/create-builder.ts

@@ -16,6 +16,7 @@ import {
   BuilderOutput,
   BuilderOutputLike,
   BuilderProgressState,
+  ScheduleOptions,
   Target,
   TypedBuilderProgress,
   targetStringFromTarget,
@@ -96,10 +97,14 @@ export function createBuilder<
           target: i.target as Target,
           logger: logger,
           id: i.id,
-          async scheduleTarget(target: Target, overrides: json.JsonObject = {}) {
+          async scheduleTarget(
+            target: Target,
+            overrides: json.JsonObject = {},
+            scheduleOptions: ScheduleOptions = {},
+          ) {
             const run = await scheduleByTarget(target, overrides, {
               scheduler,
-              logger: logger.createChild(''),
+              logger: scheduleOptions.logger || logger.createChild(''),
               workspaceRoot: i.workspaceRoot,
               currentDirectory: i.currentDirectory,
             });
@@ -109,10 +114,14 @@ export function createBuilder<
 
             return run;
           },
-          async scheduleBuilder(builderName: string, options: json.JsonObject = {}) {
+          async scheduleBuilder(
+            builderName: string,
+            options: json.JsonObject = {},
+            scheduleOptions: ScheduleOptions = {},
+          ) {
             const run = await scheduleByName(builderName, options, {
               scheduler,
-              logger: logger.createChild(''),
+              logger: scheduleOptions.logger || logger.createChild(''),
               workspaceRoot: i.workspaceRoot,
               currentDirectory: i.currentDirectory,
             });
@@ -122,18 +131,22 @@ export function createBuilder<
 
             return run;
           },
+          async getTargetOptions(target: Target) {
+            return scheduler.schedule<Target, json.JsonValue, json.JsonObject>(
+                    '..getTargetOptions', target).output.toPromise();
+          },
           reportRunning() {
             switch (currentState) {
               case BuilderProgressState.Waiting:
               case BuilderProgressState.Stopped:
-                progress({state: BuilderProgressState.Running, current: 0, total}, context);
+                progress({ state: BuilderProgressState.Running, current: 0, total  }, context);
                 break;
             }
           },
           reportStatus(status: string) {
             switch (currentState) {
               case BuilderProgressState.Running:
-                progress({ state: currentState, status, current, total }, context);
+                progress({ state: currentState, status, current, total  }, context);
                 break;
               case BuilderProgressState.Waiting:
                 progress({ state: currentState, status }, context);

packages/angular_devkit/architect/src/index2_spec.ts

@@ -13,6 +13,7 @@ import { BuilderOutput, BuilderRun } from './api';
 import { Architect } from './architect';
 import { createBuilder } from './create-builder';
 
+// tslint:disable-next-line:no-big-function
 describe('architect', () => {
   let testArchitectHost: TestingArchitectHost;
   let architect: Architect;
@@ -185,4 +186,42 @@ describe('architect', () => {
       await run.stop();
     }
   });
+
+  it('exposes getTargetOptions() properly', async () => {
+    const goldenOptions = {
+      value: 'value',
+    };
+    let options = {} as object;
+
+    const target = {
+      project: 'project',
+      target: 'target',
+    };
+    testArchitectHost.addTarget(target, 'package:target', goldenOptions);
+
+    testArchitectHost.addBuilder('package:getTargetOptions', createBuilder(async (_, context) => {
+      options = await context.getTargetOptions(target);
+
+      return { success: true };
+    }));
+
+    const run = await architect.scheduleBuilder('package:getTargetOptions', {});
+    const output = await run.output.toPromise();
+    expect(output.success).toBe(true);
+    expect(options).toEqual(goldenOptions);
+    await run.stop();
+
+    // Use an invalid target and check for error.
+    target.target = 'invalid';
+    options = {};
+
+    // This should not error.
+    const run2 = await architect.scheduleBuilder('package:getTargetOptions', {});
+
+    // But this should.
+    try {
+      await run2.output.toPromise();
+    } catch {}
+    await run2.stop();
+  });
 });