refactor: refactor interfaces

Better separation of concern between tooling and schematic library.

Engine, Collection and Schematic now take a generic type that can add tooling-specific metadata to each
parts, in a type-safe manner.

Context exposed to schematics is a context of <any, any>, while the tool should use TypedContext for
better support internally.

The Engine Host now only deals with Descriptions of collection and
schematics, does not deal with actual implementation.

Renamed CliEngineHost to NodeModules, since its kind of reusable if you only implement a NodeModules
schematic tool. Tempted to move this into the schematics library as its highly reusable.

Author: hansl

lib/packages.js

@@ -23,9 +23,9 @@ const packages =
       glob.sync(path.join(packageRoot, '*/package.json')),
       glob.sync(path.join(packageRoot, '*/*/package.json')))
     .filter(p => !p.match(/blueprints/))
-    .map(pkgPath => path.relative(packageRoot, path.dirname(pkgPath)))
-    .map(pkgName => {
-      return { name: pkgName, root: path.join(packageRoot, pkgName) };
+    .map(pkgPath => [pkgPath, path.relative(packageRoot, path.dirname(pkgPath))])
+    .map(([pkgPath, pkgName]) => {
+      return { name: pkgName, root: path.dirname(pkgPath) };
     })
     .reduce((packages, pkg) => {
       let pkgJson = JSON.parse(fs.readFileSync(path.join(pkg.root, 'package.json'), 'utf8'));

packages/schematics/src/engine/collection.ts

@@ -6,55 +6,19 @@
  * found in the LICENSE file at https://angular.io/license
  */
 import {SchematicEngine} from './engine';
-import {Collection, CollectionDescription, Schematic, SchematicDescription} from './interface';
-import {BaseException} from '../exception/exception';
+import {Collection, CollectionDescription, Schematic} from './interface';
 
 
-
-export class UnknownSchematicNameException extends BaseException {
-  constructor(collection: string, name: string) {
-    super(`Schematic named "${name}" could not be found in collection "${collection}".`);
-  }
-}
-export class InvalidSchematicException extends BaseException {
-  constructor(name: string) { super(`Invalid schematic: "${name}".`); }
-}
-
-
-export class CollectionImpl implements Collection {
-  private _schematics: { [name: string]: (options: any) => Schematic | null } = {};
-
-  constructor(private _description: CollectionDescription,
-              private _engine: SchematicEngine) {
-    Object.keys(this._description.schematics).forEach(name => {
-      this._schematics[name] = (options: any) => this._engine.createSchematic(name, this, options);
-    });
-  }
-
-  get engine() { return this._engine; }
-  get name() { return this._description.name || '<unknown>'; }
-  get path() { return this._description.path || '<unknown>'; }
-
-  listSchematicNames(): string[] {
-    return Object.keys(this._schematics);
-  }
-
-  getSchematicDescription(name: string): SchematicDescription | null {
-    if (!(name in this._description.schematics)) {
-      return null;
-    }
-    return this._description.schematics[name];
+export class CollectionImpl<CollectionT, SchematicT>
+    implements Collection<CollectionT, SchematicT> {
+  constructor(private _description: CollectionDescription<CollectionT>,
+              private _engine: SchematicEngine<CollectionT, SchematicT>) {
   }
 
-  createSchematic<T>(name: string, options: T): Schematic {
-    if (!(name in this._schematics)) {
-      throw new UnknownSchematicNameException(this.name, name);
-    }
+  get description() { return this._description; }
+  get name() { return this.description.name || '<unknown>'; }
 
-    const schematic = this._schematics[name](options);
-    if (!schematic) {
-      throw new InvalidSchematicException(name);
-    }
-    return schematic;
+  createSchematic(name: string): Schematic<CollectionT, SchematicT> {
+    return this._engine.createSchematic(name, this);
   }
 }

packages/schematics/src/engine/context.ts

@@ -8,31 +8,39 @@
 import {CollectionImpl} from './collection';
 import {
   Collection,
-  Engine, EngineHost,
+  Engine,
+  EngineHost,
   ProtocolHandler,
   Schematic,
-  SchematicContext,
-  Source
+  Source,
+  TypedSchematicContext
 } from './interface';
 import {SchematicImpl} from './schematic';
 import {BaseException} from '../exception/exception';
 import {empty} from '../tree/static';
 
 import {Url, parse, format} from 'url';
+import {MergeStrategy} from '../tree/interface';
 
 
-export class InvalidSourceUrlException extends BaseException {
-  constructor(url: string) { super(`Invalid source url: "${url}".`); }
-}
 export class UnknownUrlSourceProtocol extends BaseException {
   constructor(url: string) { super(`Unknown Protocol on url "${url}".`); }
 }
 
+export class UnknownCollectionException extends BaseException {
+  constructor(name: string) { super(`Unknown collection "${name}".`); }
+}
+export class UnknownSchematicException extends BaseException {
+  constructor(name: string, collection: Collection<any, any>) {
+    super(`Schematic "${name}" not found in collection "${collection.name}".`);
+  }
+}
+
 
-export class SchematicEngine implements Engine {
+export class SchematicEngine<CollectionT, SchematicT> implements Engine<CollectionT, SchematicT> {
   private _protocolMap = new Map<string, ProtocolHandler>();
 
-  constructor(private _host: EngineHost) {
+  constructor(private _host: EngineHost<CollectionT, SchematicT>) {
     // Default implementations.
     this._protocolMap.set('null', () => {
       return () => empty();
@@ -41,26 +49,33 @@ export class SchematicEngine implements Engine {
       // Make a copy, change the protocol.
       const fileUrl = parse(format(url));
       fileUrl.protocol = 'file:';
-      return (context: SchematicContext) => context.engine.createSourceFromUrl(fileUrl)(context);
+      return (context: TypedSchematicContext<CollectionT, SchematicT>) => {
+        return context.engine.createSourceFromUrl(fileUrl)(context);
+      };
     });
   }
 
-  createCollection(name: string): Collection | null {
-    const description = this._host.loadCollection(name);
+  get defaultMergeStrategy() { return this._host.defaultMergeStrategy || MergeStrategy.Default; }
+
+  createCollection(name: string): Collection<CollectionT, SchematicT> {
+    const description = this._host.createCollectionDescription(name);
     if (!description) {
-      return null;
+      throw new UnknownCollectionException(name);
     }
 
-    return new CollectionImpl(description, this);
+    return new CollectionImpl<CollectionT, SchematicT>(description, this);
   }
 
-  createSchematic<T>(name: string, collection: Collection, options: T): Schematic | null {
-    const description = this._host.loadSchematic<T>(name, collection, options);
+  createSchematic(
+      name: string,
+      collection: Collection<CollectionT, SchematicT>): Schematic<CollectionT, SchematicT> {
+    const description = this._host.createSchematicDescription(name, collection.description);
     if (!description) {
-      return null;
+      throw new UnknownSchematicException(name, collection);
     }
+    const factory = this._host.getSchematicRuleFactory(description, collection.description);
 
-    return new SchematicImpl(description, collection);
+    return new SchematicImpl<CollectionT, SchematicT>(description, factory, collection, this);
   }
 
   registerUrlProtocolHandler(protocol: string, handler: ProtocolHandler) {

packages/schematics/src/engine/engine.ts

@@ -11,26 +11,66 @@ import {Observable} from 'rxjs/Observable';
 import {Url} from 'url';
 
 
-export interface EngineHost {
-  loadCollection<T>(name: string): CollectionDescription<T> | null;
-  loadSchematic<CT, ST>(name: string,
-                        collection: CollectionDescription<CT>): SchematicDescription<ST> | null;
+/**
+ * The description (metadata) of a collection. This type contains every information the engine
+ * needs to run. The CollectionT type parameter contains additional metadata that you want to
+ * store while remaining type-safe.
+ */
+export type CollectionDescription<CollectionT extends {}> = CollectionT & {
+  readonly name: string;
+};
+
+/**
+ * The description (metadata) of a schematic. This type contains every information the engine
+ * needs to run. The SchematicT and CollectionT type parameters contain additional metadata
+ * that you want to store while remaining type-safe.
+ */
+export type SchematicDescription<CollectionT extends {}, SchematicT extends {}> = SchematicT & {
+  readonly collection: CollectionDescription<CollectionT>;
+  readonly name: string;
+};
+
+
+export interface EngineHost<CollectionT extends {}, SchematicT extends {}> {
+  createCollectionDescription(name: string): CollectionDescription<CollectionT> | null;
+  createSchematicDescription(
+      name: string,
+      collection: CollectionDescription<CollectionT>):
+        SchematicDescription<CollectionT, SchematicT> | null;
+  getSchematicRuleFactory<OptionT>(
+      schematic: SchematicDescription<CollectionT, SchematicT>,
+      collection: CollectionDescription<CollectionT>): RuleFactory<OptionT>;
+
+  readonly defaultMergeStrategy?: MergeStrategy;
 }
 
 
-export interface Engine {
-  createCollection<T>(name: string): Collection<T> | null;
-  createSchematic<CT, ST>(name: string, collection: Collection<CT>): Schematic<CT, ST> | null;
+/**
+ * The root Engine for creating and running schematics and collections. Everything related to
+ * a schematic execution starts from this interface.
+ *
+ * CollectionT is, by default, a generic Collection metadata type. This is used throughout the
+ * engine typings so that you can use a type that's merged into descriptions, while being type-safe.
+ *
+ * SchematicT is a type that contains additional typing for the Schematic Description.
+ */
+export interface Engine<CollectionT extends {}, SchematicT extends {}> {
+  createCollection(name: string): Collection<CollectionT, SchematicT>;
+  createSchematic(
+      name: string,
+      collection: Collection<CollectionT, SchematicT>): Schematic<CollectionT, SchematicT>;
   registerUrlProtocolHandler(protocol: string, handler: ProtocolHandler): void;
   createSourceFromUrl(url: Url): Source;
+
+  readonly defaultMergeStrategy: MergeStrategy;
 }
 
 
-export interface Schematic<CT, ST> {
-  readonly description: SchematicDescription<ST>;
-  readonly collection: Collection<CT>;
+export interface Schematic<CollectionT, SchematicT> {
+  readonly description: SchematicDescription<CollectionT, SchematicT>;
+  readonly collection: Collection<CollectionT, SchematicT>;
 
-  call(host: Observable<Tree>, parentContext: SchematicContext | null): Observable<Tree>;
+  call<T>(options: T, host: Observable<Tree>): Observable<Tree>;
 }
 
 
@@ -40,34 +80,29 @@ export interface ProtocolHandler {
 
 
 
-export interface Collection<T> {
+export interface Collection<CollectionT, SchematicT> {
   readonly name: string;
-  readonly description: CollectionDescription<T>;
+  readonly description: CollectionDescription<CollectionT>;
 
-  listSchematicNames(): string[];
-  getSchematicDescription<T>(name: string): SchematicDescription<T> | null;
-  createSchematic(name: string): Schematic;
+  createSchematic(name: string): Schematic<CollectionT, SchematicT>;
 }
 
 
-export interface SchematicContext {
-  readonly engine: Engine;
-  readonly schematic: Schematic;
+export interface TypedSchematicContext<CollectionT, SchematicT> {
+  readonly engine: Engine<CollectionT, SchematicT>;
+  readonly schematic: Schematic<CollectionT, SchematicT>;
   readonly host: Observable<Tree>;
   readonly strategy: MergeStrategy;
 }
-
-
-export type CollectionDescription<T> = T & {
-  readonly name: string;
-};
-export type SchematicDescription<T, OT> = T & {
-  readonly name: string;
-  readonly factory: RuleFactory<OT>;
-};
+export type SchematicContext = TypedSchematicContext<any, any>;
 
 
 export type RuleFactory<T> = (options: T) => Rule;
 
-export type Source = (context: SchematicContext) => Tree | Observable<Tree>;
-export type Rule = (tree: Tree, context: SchematicContext) => Tree | Observable<Tree>;
+/**
+ * We obfuscate the context of Source and Rule because the schematic implementation should not
+ * know which types is the schematic or collection metadata, as they are both tooling specific.
+ */
+export type Source = (context: TypedSchematicContext<any, any>) => Tree | Observable<Tree>;
+export type Rule = (tree: Tree,
+                    context: TypedSchematicContext<any, any>) => Tree | Observable<Tree>;

packages/schematics/src/engine/interface.ts

@@ -5,9 +5,15 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-import {SchematicContextImpl} from './context';
-import {Collection, ResolvedSchematicDescription, Schematic, SchematicContext} from './interface';
-import {MergeStrategy, Tree} from '../tree/interface';
+import {
+  Collection,
+  Engine,
+  RuleFactory,
+  Schematic,
+  SchematicDescription,
+  TypedSchematicContext
+} from './interface';
+import {Tree} from '../tree/interface';
 import {BaseException} from '../exception/exception';
 
 import {Observable} from 'rxjs/Observable';
@@ -17,30 +23,35 @@ import 'rxjs/add/operator/concatMap';
 
 
 export class InvalidSchematicsNameException extends BaseException {
-  constructor(path: string, name: string) {
-    super(`Schematics at path "${path}" has invalid name "${name}".`);
+  constructor(name: string) {
+    super(`Schematics has invalid name: "${name}".`);
   }
 }
 
 
-export class SchematicImpl implements Schematic {
-  constructor(private _descriptor: ResolvedSchematicDescription,
-              private _collection: Collection) {
-    if (!_descriptor.name.match(/^[-_.a-zA-Z0-9]+$/)) {
-      throw new InvalidSchematicsNameException(_descriptor.path, _descriptor.name);
+export class SchematicImpl<CollectionT, SchematicT> implements Schematic<CollectionT, SchematicT> {
+  constructor(private _description: SchematicDescription<CollectionT, SchematicT>,
+              private _factory: RuleFactory<any>,
+              private _collection: Collection<CollectionT, SchematicT>,
+              private _engine: Engine<CollectionT, SchematicT>) {
+    if (!_description.name.match(/^[-_.a-zA-Z0-9]+$/)) {
+      throw new InvalidSchematicsNameException(_description.name);
     }
   }
 
-  get name() { return this._descriptor.name; }
-  get description() { return this._descriptor.description; }
-  get path() { return this._descriptor.path; }
+  get description() { return this._description; }
   get collection() { return this._collection; }
 
-  call(host: Observable<Tree>, parentContext: Partial<SchematicContext>): Observable<Tree> {
-    const context = new SchematicContextImpl(this, host,
-        parentContext.strategy || MergeStrategy.Default);
+  call<OptionT>(options: OptionT, host: Observable<Tree>): Observable<Tree> {
+    let context: TypedSchematicContext<CollectionT, SchematicT> = {
+      engine: this._engine,
+      schematic: this,
+      host,
+      strategy: this._engine.defaultMergeStrategy
+    };
+
     return host.concatMap(tree => {
-      const result = this._descriptor.rule(tree, context);
+      const result = this._factory(options)(tree, context);
       if (result instanceof Observable) {
         return result;
       } else {