1 | /**
|
2 | * @license
|
3 | * Copyright Google LLC All Rights Reserved.
|
4 | *
|
5 | * Use of this source code is governed by an MIT-style license that can be
|
6 | * found in the LICENSE file at https://angular.io/license
|
7 | */
|
8 | import { analytics, experimental, json, logging } from '@angular-devkit/core';
|
9 | import { Observable, SubscribableOrPromise } from 'rxjs';
|
10 | import { Schema as RealBuilderInput, Target as RealTarget } from './input-schema';
|
11 | import { Schema as RealBuilderOutput } from './output-schema';
|
12 | import { State as BuilderProgressState, Schema as RealBuilderProgress } from './progress-schema';
|
13 | export declare type Target = json.JsonObject & RealTarget;
|
14 | export { BuilderProgressState };
|
15 | export declare type BuilderRegistry = experimental.jobs.Registry<json.JsonObject, BuilderInput, BuilderOutput>;
|
16 | /**
|
17 | * An API typed BuilderProgress. The interface generated from the schema is too permissive,
|
18 | * so this API is the one we show in our API. Please note that not all fields are in there; this
|
19 | * is in addition to fields in the schema.
|
20 | */
|
21 | export declare type TypedBuilderProgress = {
|
22 | state: BuilderProgressState.Stopped;
|
23 | } | {
|
24 | state: BuilderProgressState.Error;
|
25 | error: json.JsonValue;
|
26 | } | {
|
27 | state: BuilderProgressState.Waiting;
|
28 | status?: string;
|
29 | } | {
|
30 | state: BuilderProgressState.Running;
|
31 | status?: string;
|
32 | current: number;
|
33 | total?: number;
|
34 | };
|
35 | /**
|
36 | * Declaration of those types as JsonObject compatible. JsonObject is not compatible with
|
37 | * optional members, so those wouldn't be directly assignable to our internal Json typings.
|
38 | * Forcing the type to be both a JsonObject and the type from the Schema tells Typescript they
|
39 | * are compatible (which they are).
|
40 | * These types should be used everywhere.
|
41 | */
|
42 | export declare type BuilderInput = json.JsonObject & RealBuilderInput;
|
43 | export declare type BuilderOutput = json.JsonObject & RealBuilderOutput;
|
44 | export declare type BuilderProgress = json.JsonObject & RealBuilderProgress & TypedBuilderProgress;
|
45 | /**
|
46 | * A progress report is what the tooling will receive. It contains the builder info and the target.
|
47 | * Although these are serializable, they are only exposed through the tooling interface, not the
|
48 | * builder interface. The watch dog sends BuilderProgress and the Builder has a set of functions
|
49 | * to manage the state.
|
50 | */
|
51 | export declare type BuilderProgressReport = BuilderProgress & {
|
52 | target?: Target;
|
53 | builder: BuilderInfo;
|
54 | };
|
55 | /**
|
56 | * A Run, which is what is returned by scheduleBuilder or scheduleTarget functions. This should
|
57 | * be reconstructed across memory boundaries (it's not serializable but all internal information
|
58 | * are).
|
59 | */
|
60 | export interface BuilderRun {
|
61 | /**
|
62 | * Unique amongst runs. This is the same ID as the context generated for the run. It can be
|
63 | * used to identify multiple unique runs. There is no guarantee that a run is a single output;
|
64 | * a builder can rebuild on its own and will generate multiple outputs.
|
65 | */
|
66 | id: number;
|
67 | /**
|
68 | * The builder information.
|
69 | */
|
70 | info: BuilderInfo;
|
71 | /**
|
72 | * The next output from a builder. This is recommended when scheduling a builder and only being
|
73 | * interested in the result of that single run, not of a watch-mode builder.
|
74 | */
|
75 | result: Promise<BuilderOutput>;
|
76 | /**
|
77 | * The output(s) from the builder. A builder can have multiple outputs.
|
78 | * This always replay the last output when subscribed.
|
79 | */
|
80 | output: Observable<BuilderOutput>;
|
81 | /**
|
82 | * The progress report. A progress also contains an ID, which can be different than this run's
|
83 | * ID (if the builder calls scheduleBuilder or scheduleTarget).
|
84 | * This will always replay the last progress on new subscriptions.
|
85 | */
|
86 | progress: Observable<BuilderProgressReport>;
|
87 | /**
|
88 | * Stop the builder from running. Returns a promise that resolves when the builder is stopped.
|
89 | * Some builders might not handle stopping properly and should have a timeout here.
|
90 | */
|
91 | stop(): Promise<void>;
|
92 | }
|
93 | /**
|
94 | * Additional optional scheduling options.
|
95 | */
|
96 | export interface ScheduleOptions {
|
97 | /**
|
98 | * Logger to pass to the builder. Note that messages will stop being forwarded, and if you want
|
99 | * to log a builder scheduled from your builder you should forward log events yourself.
|
100 | */
|
101 | logger?: logging.Logger;
|
102 | /**
|
103 | * Target to pass to the builder.
|
104 | */
|
105 | target?: Target;
|
106 | }
|
107 | /**
|
108 | * The context received as a second argument in your builder.
|
109 | */
|
110 | export interface BuilderContext {
|
111 | /**
|
112 | * Unique amongst contexts. Contexts instances are not guaranteed to be the same (but it could
|
113 | * be the same context), and all the fields in a context could be the same, yet the builder's
|
114 | * context could be different. This is the same ID as the corresponding run.
|
115 | */
|
116 | id: number;
|
117 | /**
|
118 | * The builder info that called your function. Since the builder info is from the builder.json
|
119 | * (or the host), it could contain information that is different than expected.
|
120 | */
|
121 | builder: BuilderInfo;
|
122 | /**
|
123 | * A logger that appends messages to a log. This could be a separate interface or completely
|
124 | * ignored. `console.log` could also be completely ignored.
|
125 | */
|
126 | logger: logging.LoggerApi;
|
127 | /**
|
128 | * The absolute workspace root of this run. This is a system path and will not be normalized;
|
129 | * ie. on Windows it will starts with `C:\\` (or whatever drive).
|
130 | */
|
131 | workspaceRoot: string;
|
132 | /**
|
133 | * The current directory the user is in. This could be outside the workspace root. This is a
|
134 | * system path and will not be normalized; ie. on Windows it will starts with `C:\\` (or
|
135 | * whatever drive).
|
136 | */
|
137 | currentDirectory: string;
|
138 | /**
|
139 | * The target that was used to run this builder.
|
140 | * Target is optional if a builder was ran using `scheduleBuilder()`.
|
141 | */
|
142 | target?: Target;
|
143 | /**
|
144 | * Schedule a target in the same workspace. This can be the same target that is being executed
|
145 | * right now, but targets of the same name are serialized.
|
146 | * Running the same target and waiting for it to end will result in a deadlocking scenario.
|
147 | * Targets are considered the same if the project, the target AND the configuration are the same.
|
148 | * @param target The target to schedule.
|
149 | * @param overrides A set of options to override the workspace set of options.
|
150 | * @param scheduleOptions Additional optional scheduling options.
|
151 | * @return A promise of a run. It will resolve when all the members of the run are available.
|
152 | */
|
153 | scheduleTarget(target: Target, overrides?: json.JsonObject, scheduleOptions?: ScheduleOptions): Promise<BuilderRun>;
|
154 | /**
|
155 | * Schedule a builder by its name. This can be the same builder that is being executed.
|
156 | * @param builderName The name of the builder, ie. its `packageName:builderName` tuple.
|
157 | * @param options All options to use for the builder (by default empty object). There is no
|
158 | * additional options added, e.g. from the workspace.
|
159 | * @param scheduleOptions Additional optional scheduling options.
|
160 | * @return A promise of a run. It will resolve when all the members of the run are available.
|
161 | */
|
162 | scheduleBuilder(builderName: string, options?: json.JsonObject, scheduleOptions?: ScheduleOptions): Promise<BuilderRun>;
|
163 | /**
|
164 | * Resolve and return options for a specified target. If the target isn't defined in the
|
165 | * workspace this will reject the promise. This object will be read directly from the workspace
|
166 | * but not validated against the builder of the target.
|
167 | * @param target The target to resolve the options of.
|
168 | * @return A non-validated object resolved from the workspace.
|
169 | */
|
170 | getTargetOptions(target: Target): Promise<json.JsonObject>;
|
171 | getProjectMetadata(projectName: string): Promise<json.JsonObject>;
|
172 | getProjectMetadata(target: Target): Promise<json.JsonObject>;
|
173 | /**
|
174 | * Resolves and return a builder name. The exact format of the name is up to the host,
|
175 | * so it should not be parsed to gather information (it's free form). This string can be
|
176 | * used to validate options or schedule a builder directly.
|
177 | * @param target The target to resolve the builder name.
|
178 | */
|
179 | getBuilderNameForTarget(target: Target): Promise<string>;
|
180 | /**
|
181 | * Validates the options against a builder schema. This uses the same methods as the
|
182 | * scheduleTarget and scheduleBrowser methods to validate and apply defaults to the options.
|
183 | * It can be generically typed, if you know which interface it is supposed to validate against.
|
184 | * @param options A generic option object to validate.
|
185 | * @param builderName The name of a builder to use. This can be gotten for a target by using the
|
186 | * getBuilderForTarget() method on the context.
|
187 | */
|
188 | validateOptions<T extends json.JsonObject = json.JsonObject>(options: json.JsonObject, builderName: string): Promise<T>;
|
189 | /**
|
190 | * Set the builder to running. This should be used if an external event triggered a re-run,
|
191 | * e.g. a file watched was changed.
|
192 | */
|
193 | reportRunning(): void;
|
194 | /**
|
195 | * Update the status string shown on the interface.
|
196 | * @param status The status to set it to. An empty string can be used to remove the status.
|
197 | */
|
198 | reportStatus(status: string): void;
|
199 | /**
|
200 | * Update the progress for this builder run.
|
201 | * @param current The current progress. This will be between 0 and total.
|
202 | * @param total A new total to set. By default at the start of a run this is 1. If omitted it
|
203 | * will use the same value as the last total.
|
204 | * @param status Update the status string. If omitted the status string is not modified.
|
205 | */
|
206 | reportProgress(current: number, total?: number, status?: string): void;
|
207 | /**
|
208 | * API to report analytics. This might be undefined if the feature is unsupported. This might
|
209 | * not be undefined, but the backend could also not report anything.
|
210 | */
|
211 | readonly analytics: analytics.Analytics;
|
212 | /**
|
213 | * Add teardown logic to this Context, so that when it's being stopped it will execute teardown.
|
214 | */
|
215 | addTeardown(teardown: () => Promise<void> | void): void;
|
216 | }
|
217 | /**
|
218 | * An accepted return value from a builder. Can be either an Observable, a Promise or a vector.
|
219 | */
|
220 | export declare type BuilderOutputLike = AsyncIterable<BuilderOutput> | SubscribableOrPromise<BuilderOutput> | BuilderOutput;
|
221 | export declare function isBuilderOutput(obj: any): obj is BuilderOutput;
|
222 | export declare function fromAsyncIterable<T>(iterable: AsyncIterable<T>): Observable<T>;
|
223 | /**
|
224 | * A builder handler function. The function signature passed to `createBuilder()`.
|
225 | */
|
226 | export interface BuilderHandlerFn<A> {
|
227 | /**
|
228 | * Builders are defined by users to perform any kind of task, like building, testing or linting,
|
229 | * and should use this interface.
|
230 | * @param input The options (a JsonObject), validated by the schema and received by the
|
231 | * builder. This can include resolved options from the CLI or the workspace.
|
232 | * @param context A context that can be used to interact with the Architect framework.
|
233 | * @return One or many builder output.
|
234 | */
|
235 | (input: A, context: BuilderContext): BuilderOutputLike;
|
236 | }
|
237 | /**
|
238 | * A Builder general information. This is generated by the host and is expanded by the host, but
|
239 | * the public API contains those fields.
|
240 | */
|
241 | export declare type BuilderInfo = json.JsonObject & {
|
242 | builderName: string;
|
243 | description: string;
|
244 | optionSchema: json.schema.JsonSchema;
|
245 | };
|
246 | /**
|
247 | * Returns a string of "project:target[:configuration]" for the target object.
|
248 | */
|
249 | export declare function targetStringFromTarget({ project, target, configuration }: Target): string;
|
250 | /**
|
251 | * Return a Target tuple from a string.
|
252 | */
|
253 | export declare function targetFromTargetString(str: string): Target;
|
254 | /**
|
255 | * Schedule a target, and forget about its run. This will return an observable of outputs, that
|
256 | * as a a teardown will stop the target from running. This means that the Run object this returns
|
257 | * should not be shared.
|
258 | *
|
259 | * The reason this is not part of the Context interface is to keep the Context as normal form as
|
260 | * possible. This is really an utility that people would implement in their project.
|
261 | *
|
262 | * @param context The context of your current execution.
|
263 | * @param target The target to schedule.
|
264 | * @param overrides Overrides that are used in the target.
|
265 | * @param scheduleOptions Additional scheduling options.
|
266 | */
|
267 | export declare function scheduleTargetAndForget(context: BuilderContext, target: Target, overrides?: json.JsonObject, scheduleOptions?: ScheduleOptions): Observable<BuilderOutput>;
|