Introduce Schematics Tree methods for readText and readJSON

goldens/public-api/angular_devkit/schematics/index.md

@@ -7,6 +7,7 @@
 /// <reference types="node" />
 
 import { BaseException } from '@angular-devkit/core';
+import { JsonValue } from '@angular-devkit/core';
 import { logging } from '@angular-devkit/core';
 import { Observable } from 'rxjs';
 import { Path } from '@angular-devkit/core';
@@ -235,6 +236,10 @@ export class DelegateTree implements Tree_2 {
     // (undocumented)
     read(path: string): Buffer | null;
     // (undocumented)
+    readJson(path: string): JsonValue;
+    // (undocumented)
+    readText(path: string): string;
+    // (undocumented)
     rename(from: string, to: string): void;
     // (undocumented)
     get root(): DirEntry;
@@ -547,6 +552,10 @@ export class HostTree implements Tree_2 {
     // (undocumented)
     read(path: string): Buffer | null;
     // (undocumented)
+    readJson(path: string): JsonValue;
+    // (undocumented)
+    readText(path: string): string;
+    // (undocumented)
     rename(from: string, to: string): void;
     // (undocumented)
     get root(): DirEntry;

goldens/public-api/angular_devkit/schematics/testing/index.md

@@ -6,6 +6,7 @@
 
 /// <reference types="node" />
 
+import { JsonValue } from '@angular-devkit/core';
 import { logging } from '@angular-devkit/core';
 import { Observable } from 'rxjs';
 import { Path } from '@angular-devkit/core';

goldens/public-api/angular_devkit/schematics/tools/index.md

@@ -8,6 +8,7 @@
 
 import { BaseException } from '@angular-devkit/core';
 import { JsonObject } from '@angular-devkit/core';
+import { JsonValue } from '@angular-devkit/core';
 import { logging } from '@angular-devkit/core';
 import { Observable } from 'rxjs';
 import { Path } from '@angular-devkit/core';

packages/angular_devkit/schematics/BUILD.bazel

@@ -37,6 +37,7 @@ ts_library(
         "//packages/angular_devkit/core",
         "//packages/angular_devkit/core/node",  # TODO: get rid of this for 6.0
         "@npm//@types/node",
+        "@npm//jsonc-parser",
         "@npm//magic-string",
         "@npm//rxjs",
     ],

packages/angular_devkit/schematics/src/tree/delegate.ts

@@ -6,6 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import { JsonValue } from '@angular-devkit/core';
 import { Action } from './action';
 import {
   DirEntry,
@@ -35,6 +36,12 @@ export class DelegateTree implements Tree {
   read(path: string): Buffer | null {
     return this._other.read(path);
   }
+  readText(path: string): string {
+    return this._other.readText(path);
+  }
+  readJson(path: string): JsonValue {
+    return this._other.readJson(path);
+  }
   exists(path: string): boolean {
     return this._other.exists(path);
   }

packages/angular_devkit/schematics/src/tree/host-tree.ts

@@ -7,6 +7,7 @@
  */
 
 import {
+  JsonValue,
   Path,
   PathFragment,
   PathIsDirectoryException,
@@ -16,8 +17,10 @@ import {
   normalize,
   virtualFs,
 } from '@angular-devkit/core';
+import { ParseError, parse as jsoncParse, printParseErrorCode } from 'jsonc-parser';
 import { EMPTY, Observable } from 'rxjs';
 import { concatMap, map, mergeMap } from 'rxjs/operators';
+import { TextDecoder } from 'util';
 import {
   ContentHasMutatedException,
   FileAlreadyExistException,
@@ -162,10 +165,10 @@ export class HostTree implements Tree {
       return tree._ancestry.has(this._id);
     }
     if (tree instanceof DelegateTree) {
-      return this.isAncestorOf(((tree as unknown) as { _other: Tree })._other);
+      return this.isAncestorOf((tree as unknown as { _other: Tree })._other);
     }
     if (tree instanceof ScopedTree) {
-      return this.isAncestorOf(((tree as unknown) as { _base: Tree })._base);
+      return this.isAncestorOf((tree as unknown as { _base: Tree })._base);
     }
 
     return false;
@@ -206,9 +209,9 @@ export class HostTree implements Tree {
               throw new MergeConflictException(path);
             }
 
-            this._record.overwrite(path, (content as {}) as virtualFs.FileBuffer).subscribe();
+            this._record.overwrite(path, content as {} as virtualFs.FileBuffer).subscribe();
           } else {
-            this._record.create(path, (content as {}) as virtualFs.FileBuffer).subscribe();
+            this._record.create(path, content as {} as virtualFs.FileBuffer).subscribe();
           }
 
           return;
@@ -234,7 +237,7 @@ export class HostTree implements Tree {
           }
           // We use write here as merge validation has already been done, and we want to let
           // the CordHost do its job.
-          this._record.write(path, (content as {}) as virtualFs.FileBuffer).subscribe();
+          this._record.write(path, content as {} as virtualFs.FileBuffer).subscribe();
 
           return;
         }
@@ -289,6 +292,42 @@ export class HostTree implements Tree {
 
     return entry ? entry.content : null;
   }
+
+  readText(path: string): string {
+    const data = this.read(path);
+    if (data === null) {
+      throw new FileDoesNotExistException(path);
+    }
+
+    const decoder = new TextDecoder('utf-8', { fatal: true });
+
+    try {
+      // With the `fatal` option enabled, invalid data will throw a TypeError
+      return decoder.decode(data);
+    } catch (e) {
+      if (e instanceof TypeError) {
+        throw new Error(`Failed to decode "${path}" as UTF-8 text.`);
+      }
+      throw e;
+    }
+  }
+
+  readJson(path: string): JsonValue {
+    const content = this.readText(path);
+    const errors: ParseError[] = [];
+    const result = jsoncParse(content, errors, { allowTrailingComma: true });
+
+    // If there is a parse error throw with the error information
+    if (errors[0]) {
+      const { error, offset } = errors[0];
+      throw new Error(
+        `Failed to parse "${path}" as JSON. ${printParseErrorCode(error)} at offset: ${offset}.`,
+      );
+    }
+
+    return result;
+  }
+
   exists(path: string): boolean {
     return this._recordSync.isFile(this._normalizePath(path));
   }
@@ -337,7 +376,7 @@ export class HostTree implements Tree {
       throw new FileDoesNotExistException(p);
     }
     const c = typeof content == 'string' ? Buffer.from(content) : content;
-    this._record.overwrite(p, (c as {}) as virtualFs.FileBuffer).subscribe();
+    this._record.overwrite(p, c as {} as virtualFs.FileBuffer).subscribe();
   }
   beginUpdate(path: string): UpdateRecorder {
     const entry = this.get(path);
@@ -371,7 +410,7 @@ export class HostTree implements Tree {
       throw new FileAlreadyExistException(p);
     }
     const c = typeof content == 'string' ? Buffer.from(content) : content;
-    this._record.create(p, (c as {}) as virtualFs.FileBuffer).subscribe();
+    this._record.create(p, c as {} as virtualFs.FileBuffer).subscribe();
   }
   delete(path: string): void {
     this._recordSync.delete(this._normalizePath(path));
@@ -476,7 +515,7 @@ export class FilterHostTree extends HostTree {
             return EMPTY;
           }
 
-          return newBackend.write(path, (content as {}) as virtualFs.FileBuffer);
+          return newBackend.write(path, content as {} as virtualFs.FileBuffer);
         }),
       );
     };

packages/angular_devkit/schematics/src/tree/host-tree_spec.ts

@@ -11,6 +11,84 @@ import { FilterHostTree, HostTree } from './host-tree';
 import { MergeStrategy } from './interface';
 
 describe('HostTree', () => {
+  describe('readText', () => {
+    it('returns text when reading a file that exists', () => {
+      const tree = new HostTree();
+      tree.create('/textfile1', 'abc');
+      tree.create('/textfile2', '123');
+      expect(tree.readText('/textfile1')).toEqual('abc');
+      expect(tree.readText('/textfile2')).toEqual('123');
+    });
+
+    it('throws an error when a file does not exist', () => {
+      const tree = new HostTree();
+      const path = '/textfile1';
+      expect(() => tree.readText(path)).toThrowError(`Path "${path}" does not exist.`);
+    });
+
+    it('throws an error when invalid UTF-8 characters are present', () => {
+      const tree = new HostTree();
+      const path = '/textfile1';
+      tree.create(path, Buffer.from([0xff, 0xff, 0xff, 0xff]));
+      expect(() => tree.readText(path)).toThrowError(`Failed to decode "${path}" as UTF-8 text.`);
+    });
+  });
+
+  describe('readJson', () => {
+    it('returns a JSON value when reading a file that exists', () => {
+      const tree = new HostTree();
+      tree.create('/textfile1', '{ "a": true, "b": "xyz" }');
+      tree.create('/textfile2', '123');
+      tree.create('/textfile3', 'null');
+      expect(tree.readJson('/textfile1')).toEqual({ a: true, b: 'xyz' });
+      expect(tree.readJson('/textfile2')).toEqual(123);
+      expect(tree.readJson('/textfile3')).toBeNull();
+    });
+
+    it('returns a JSON value when reading a file with comments', () => {
+      const tree = new HostTree();
+      tree.create(
+        '/textfile1',
+        '{ "a": true, /* inner object\nmultiline comment\n */ "b": "xyz" }',
+      );
+      tree.create('/textfile2', '123 // number value');
+      tree.create('/textfile3', 'null // null value');
+      expect(tree.readJson('/textfile1')).toEqual({ a: true, b: 'xyz' });
+      expect(tree.readJson('/textfile2')).toEqual(123);
+      expect(tree.readJson('/textfile3')).toBeNull();
+    });
+
+    it('returns a JSON value when reading a file with trailing commas', () => {
+      const tree = new HostTree();
+      tree.create('/textfile1', '{ "a": true, "b": "xyz", }');
+      tree.create('/textfile2', '[5, 4, 3, 2, 1, ]');
+      expect(tree.readJson('/textfile1')).toEqual({ a: true, b: 'xyz' });
+      expect(tree.readJson('/textfile2')).toEqual([5, 4, 3, 2, 1]);
+    });
+
+    it('throws an error when a file does not exist', () => {
+      const tree = new HostTree();
+      const path = '/textfile1';
+      expect(() => tree.readJson(path)).toThrowError(`Path "${path}" does not exist.`);
+    });
+
+    it('throws an error if the JSON is malformed', () => {
+      const tree = new HostTree();
+      const path = '/textfile1';
+      tree.create(path, '{ "a": true;;;;; "b": "xyz" }');
+      expect(() => tree.readJson(path)).toThrowError(
+        `Failed to parse "${path}" as JSON. InvalidSymbol at offset: 7.`,
+      );
+    });
+
+    it('throws an error when invalid UTF-8 characters are present', () => {
+      const tree = new HostTree();
+      const path = '/textfile1';
+      tree.create(path, Buffer.from([0xff, 0xff, 0xff, 0xff]));
+      expect(() => tree.readJson(path)).toThrowError(`Failed to decode "${path}" as UTF-8 text.`);
+    });
+  });
+
   describe('merge', () => {
     it('should create files from each tree', () => {
       const tree = new HostTree();

packages/angular_devkit/schematics/src/tree/interface.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import { Path, PathFragment } from '@angular-devkit/core';
+import { JsonValue, Path, PathFragment } from '@angular-devkit/core';
 import { Action } from './action';
 
 export enum MergeStrategy {
@@ -83,6 +83,31 @@ export interface Tree {
 
   // Readonly.
   read(path: string): Buffer | null;
+
+  /**
+   * Reads a file from the Tree as a UTF-8 encoded text file.
+   *
+   * @param path The path of the file to read.
+   * @returns A string containing the contents of the file.
+   * @throws {@link FileDoesNotExistException} if the file is not found.
+   * @throws An error if the file contains invalid UTF-8 characters.
+   */
+  readText(path: string): string;
+
+  /**
+   * Reads and parses a file from the Tree as a UTF-8 encoded JSON file.
+   * Supports parsing JSON (RFC 8259) with the following extensions:
+   * * Single-line and multi-line JavaScript comments
+   * * Trailing commas within objects and arrays
+   *
+   * @param path The path of the file to read.
+   * @returns A JsonValue containing the parsed contents of the file.
+   * @throws {@link FileDoesNotExistException} if the file is not found.
+   * @throws An error if the file contains invalid UTF-8 characters.
+   * @throws An error if the file contains malformed JSON.
+   */
+  readJson(path: string): JsonValue;
+
   exists(path: string): boolean;
   get(path: string): FileEntry | null;
   getDir(path: string): DirEntry;

packages/angular_devkit/schematics/src/tree/null.ts

@@ -6,7 +6,15 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import { BaseException, Path, PathFragment, dirname, join, normalize } from '@angular-devkit/core';
+import {
+  BaseException,
+  JsonValue,
+  Path,
+  PathFragment,
+  dirname,
+  join,
+  normalize,
+} from '@angular-devkit/core';
 import { FileDoesNotExistException } from '../exception/exception';
 import { Action } from './action';
 import { DirEntry, MergeStrategy, Tree, TreeSymbol, UpdateRecorder } from './interface';
@@ -57,6 +65,12 @@ export class NullTree implements Tree {
   read(_path: string) {
     return null;
   }
+  readText(path: string): string {
+    throw new FileDoesNotExistException(path);
+  }
+  readJson(path: string): JsonValue {
+    throw new FileDoesNotExistException(path);
+  }
   get(_path: string) {
     return null;
   }

packages/angular_devkit/schematics/src/tree/scoped.ts

@@ -7,6 +7,7 @@
  */
 
 import {
+  JsonValue,
   NormalizedRoot,
   Path,
   PathFragment,
@@ -113,6 +114,12 @@ export class ScopedTree implements Tree {
   read(path: string): Buffer | null {
     return this._base.read(this._fullPath(path));
   }
+  readText(path: string): string {
+    return this._base.readText(this._fullPath(path));
+  }
+  readJson(path: string): JsonValue {
+    return this._base.readJson(this._fullPath(path));
+  }
   exists(path: string): boolean {
     return this._base.exists(this._fullPath(path));
   }