source: trip-planner-front/node_modules/@angular-devkit/architect/src/api.d.ts@ 6a3a178

Last change on this file since 6a3a178 was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 12.4 KB
Line 
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 */
8import { analytics, experimental, json, logging } from '@angular-devkit/core';
9import { Observable, SubscribableOrPromise } from 'rxjs';
10import { Schema as RealBuilderInput, Target as RealTarget } from './input-schema';
11import { Schema as RealBuilderOutput } from './output-schema';
12import { State as BuilderProgressState, Schema as RealBuilderProgress } from './progress-schema';
13export declare type Target = json.JsonObject & RealTarget;
14export { BuilderProgressState };
15export 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 */
21export 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 */
42export declare type BuilderInput = json.JsonObject & RealBuilderInput;
43export declare type BuilderOutput = json.JsonObject & RealBuilderOutput;
44export 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 */
51export 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 */
60export 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 */
96export 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 */
110export 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 */
220export declare type BuilderOutputLike = AsyncIterable<BuilderOutput> | SubscribableOrPromise<BuilderOutput> | BuilderOutput;
221export declare function isBuilderOutput(obj: any): obj is BuilderOutput;
222export declare function fromAsyncIterable<T>(iterable: AsyncIterable<T>): Observable<T>;
223/**
224 * A builder handler function. The function signature passed to `createBuilder()`.
225 */
226export 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 */
241export 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 */
249export declare function targetStringFromTarget({ project, target, configuration }: Target): string;
250/**
251 * Return a Target tuple from a string.
252 */
253export 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 */
267export declare function scheduleTargetAndForget(context: BuilderContext, target: Target, overrides?: json.JsonObject, scheduleOptions?: ScheduleOptions): Observable<BuilderOutput>;
Note: See TracBrowser for help on using the repository browser.