feat(@angular-devkit/schematics): support reading text content directly from a Tree

The schematics `Tree` now contains an additional `readText` method that supports directly
reading the content of a file as UTF-8 text. This avoids the need to manually decode a Buffer
within a schematic when text content is needed. If a file path does not exist, an exception
will be thrown. While this differs from the semantics of `read`, it helps reduce the amount
of code needed for common schematic use cases.

Author: clydin

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

@@ -235,6 +235,8 @@ export class DelegateTree implements Tree_2 {
     // (undocumented)
     read(path: string): Buffer | null;
     // (undocumented)
+    readText(path: string): string;
+    // (undocumented)
     rename(from: string, to: string): void;
     // (undocumented)
     get root(): DirEntry;
@@ -547,6 +549,8 @@ export class HostTree implements Tree_2 {
     // (undocumented)
     read(path: string): Buffer | null;
     // (undocumented)
+    readText(path: string): string;
+    // (undocumented)
     rename(from: string, to: string): void;
     // (undocumented)
     get root(): DirEntry;

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

@@ -35,6 +35,9 @@ export class DelegateTree implements Tree {
   read(path: string): Buffer | null {
     return this._other.read(path);
   }
+  readText(path: string): string {
+    return this._other.readText(path);
+  }
   exists(path: string): boolean {
     return this._other.exists(path);
   }

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

@@ -18,6 +18,7 @@ import {
 } from '@angular-devkit/core';
 import { EMPTY, Observable } from 'rxjs';
 import { concatMap, map, mergeMap } from 'rxjs/operators';
+import { TextDecoder } from 'util';
 import {
   ContentHasMutatedException,
   FileAlreadyExistException,
@@ -162,10 +163,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 +207,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 +235,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 +290,26 @@ 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;
+    }
+  }
+
   exists(path: string): boolean {
     return this._recordSync.isFile(this._normalizePath(path));
   }
@@ -337,7 +358,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 +392,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 +497,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,29 @@ 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('merge', () => {
     it('should create files from each tree', () => {
       const tree = new HostTree();

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

@@ -83,6 +83,17 @@ 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;
+
   exists(path: string): boolean;
   get(path: string): FileEntry | null;
   getDir(path: string): DirEntry;

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

@@ -57,6 +57,9 @@ export class NullTree implements Tree {
   read(_path: string) {
     return null;
   }
+  readText(path: string): string {
+    throw new FileDoesNotExistException(path);
+  }
   get(_path: string) {
     return null;
   }

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

@@ -113,6 +113,9 @@ 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));
+  }
   exists(path: string): boolean {
     return this._base.exists(this._fullPath(path));
   }