@@ -56,4 +56,110 @@ export class CoreSchemaRegistry implements SchemaRegistry {
56
56
57
57
# Utils
58
58
59
- # Virtual FS
59
+ # Virtual FS
60
+
61
+ # Workspaces
62
+
63
+ The ` workspaces ` namespace provides an API for interacting with the workspace file formats.
64
+ It provides an abstraction of the underlying storage format of the workspace and provides
65
+ support for both reading and writing. Currently, the only supported format is the JSON-based
66
+ format used by the Angular CLI. For this format, the API provides internal change tracking of values which
67
+ enables fine-grained updates to the underlying storage of the workspace. This allows for the
68
+ retention of existing formatting and comments.
69
+
70
+ A workspace is defined via the following object model. Definition collection objects are specialized
71
+ Javascript ` Map ` objects with an additional ` add ` method to simplify addition and provide more localized
72
+ error checking of the newly added values.
73
+
74
+ ``` ts
75
+ export interface WorkspaceDefinition {
76
+ readonly extensions: Record <string , JsonValue | undefined >;
77
+ readonly projects: ProjectDefinitionCollection ;
78
+ }
79
+
80
+ export interface ProjectDefinition {
81
+ readonly extensions: Record <string , JsonValue | undefined >;
82
+ readonly targets: TargetDefinitionCollection ;
83
+ root: string ;
84
+ prefix? : string ;
85
+ sourceRoot? : string ;
86
+ }
87
+
88
+ export interface TargetDefinition {
89
+ options? : Record <string , JsonValue | undefined >;
90
+ configurations? : Record <string , Record <string , JsonValue | undefined > | undefined >;
91
+ builder: string ;
92
+ }
93
+ ```
94
+
95
+ The API is asynchronous and has two main functions to facilitate reading, creation, and modifying
96
+ a workspace: ` readWorkspace ` and ` writeWorkspace ` .
97
+
98
+ ``` ts
99
+ export enum WorkspaceFormat {
100
+ JSON ,
101
+ }
102
+ ```
103
+
104
+ ``` ts
105
+ export function readWorkspace(
106
+ path : string ,
107
+ host : WorkspaceHost ,
108
+ format ? : WorkspaceFormat ,
109
+ ): Promise <{ workspace: WorkspaceDefinition ; }>;
110
+ ```
111
+
112
+ ``` ts
113
+ export function writeWorkspace(
114
+ workspace : WorkspaceDefinition ,
115
+ host : WorkspaceHost ,
116
+ path ? : string ,
117
+ format ? : WorkspaceFormat ,
118
+ ): Promise <void >;
119
+ ```
120
+
121
+ A ` WorkspaceHost ` abstracts the underlying data access methods from the functions. It provides
122
+ methods to read, write, and analyze paths. A utility function is provided to create
123
+ an instance of a ` WorkspaceHost ` from the Angular DevKit's virtual filesystem host abstraction.
124
+
125
+ ``` ts
126
+ export interface WorkspaceHost {
127
+ readFile(path : string ): Promise <string >;
128
+ writeFile(path : string , data : string ): Promise <void >;
129
+ isDirectory(path : string ): Promise <boolean >;
130
+ isFile(path : string ): Promise <boolean >;
131
+ }
132
+
133
+ export function createWorkspaceHost(host : virtualFs .Host ): WorkspaceHost ;
134
+ ```
135
+
136
+ ## Usage Example
137
+
138
+ To demonstrate the usage of the API, the following code will show how to add a option property
139
+ to a build target for an application.
140
+
141
+ ``` ts
142
+ import { NodeJsSyncHost } from ' @angular-devkit/core/node' ;
143
+ import { workspaces } from ' @angular-devkit/core' ;
144
+
145
+ async function demonstrate() {
146
+ const host = workspaces .createWorkspaceHost (new NodeJsSyncHost ());
147
+ const workspace = await workspaces .readWorkspace (' path/to/workspace/directory/' , host );
148
+
149
+ const project = workspace .projects .get (' my-app' );
150
+ if (! project ) {
151
+ throw new Error (' my-app does not exist' );
152
+ }
153
+
154
+ const buildTarget = project .targets .get (' build' );
155
+ if (! buildTarget ) {
156
+ throw new Error (' build target does not exist' );
157
+ }
158
+
159
+ buildTarget .options .optimization = true ;
160
+
161
+ await workspaces .writeWorkspace (workspace , host );
162
+ }
163
+
164
+ demonstrate ();
165
+ ```
0 commit comments