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/README.md

@@ -31,6 +31,11 @@ The tooling is responsible for the following tasks:
 1. Create a Sink and commit the result of the schematics to the Sink. Many sinks are provided by the library; FileSystemSink and DryRunSink are examples.
 1. Output any logs propagated by the library, including debugging information.
 
+The tooling API is composed of the following pieces:
+
+## Engine
+The `SchematicEngine` is responsible for loading and constructing `Collection`s and `Schematics`'. When creating an engine, the tooling provides an `EngineHost` interface that understands how to create a `CollectionDescription` from a name, and how to create a `Schematic
+
 # Examples
 
 ## Simple
@@ -50,7 +55,7 @@ export default function MySchematic(options: any) {
 A few things from this example:
 
 1. The function receives the list of options from the tooling.
-2. It returns a [`Rule`](src/engine/interface.ts#L73), which is a transformation from a `Tree` to another `Tree`.
+1. It returns a [`Rule`](src/engine/interface.ts#L73), which is a transformation from a `Tree` to another `Tree`.
 
 
 

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 _options: 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._options.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._options.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,78 +11,98 @@ import {Observable} from 'rxjs/Observable';
 import {Url} from 'url';
 
 
-export interface EngineHost {
-  loadCollection(name: string): CollectionDescription | null;
-  loadSchematic<T>(name: string,
-                   collection: Collection,
-                   options: T): ResolvedSchematicDescription | 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;
+};
 
-export interface Schematic {
+/**
+ * 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;
-  readonly description: string;
-  readonly path: string;
-  readonly collection: Collection;
+};
 
-  call(host: Observable<Tree>, parentContext: Partial<SchematicContext>): Observable<Tree>;
-}
 
+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>;
 
-export interface ProtocolHandler {
-  (url: Url): Source;
+  readonly defaultMergeStrategy?: MergeStrategy;
 }
 
 
-
-export interface Engine {
-  createCollection(name: string): Collection | null;
-  createSchematic<T>(name: string, collection: Collection, options: T): Schematic | 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 Collection {
-  readonly engine: Engine;
-  readonly name: string;
-  readonly path: string;
+export interface Schematic<CollectionT, SchematicT> {
+  readonly description: SchematicDescription<CollectionT, SchematicT>;
+  readonly collection: Collection<CollectionT, SchematicT>;
 
-  listSchematicNames(): string[];
-  getSchematicDescription(name: string): SchematicDescription | null;
-  createSchematic<T>(name: string, options: T): Schematic;
+  call<T>(options: T, host: Observable<Tree>): Observable<Tree>;
 }
 
 
-export interface SchematicContext {
-  readonly engine: Engine;
-  readonly schematic: Schematic;
-  readonly host: Observable<Tree>;
-  readonly strategy: MergeStrategy;
+export interface ProtocolHandler {
+  (url: Url): Source;
 }
 
 
-export interface CollectionDescription {
-  readonly path: string;
-  readonly name?: string;
-  readonly version?: string;
-  readonly schematics: { [name: string]: SchematicDescription };
-}
 
-export interface SchematicDescription {
-  readonly factory: string;
-  readonly description: string;
-  readonly schema?: string;
+export interface Collection<CollectionT, SchematicT> {
+  readonly name: string;
+  readonly description: CollectionDescription<CollectionT>;
+
+  createSchematic(name: string): Schematic<CollectionT, SchematicT>;
 }
 
 
-export interface ResolvedSchematicDescription extends SchematicDescription {
-  readonly name: string;
-  readonly path: string;
-  readonly rule: Rule;
+export interface TypedSchematicContext<CollectionT, SchematicT> {
+  readonly engine: Engine<CollectionT, SchematicT>;
+  readonly schematic: Schematic<CollectionT, SchematicT>;
+  readonly host: Observable<Tree>;
+  readonly strategy: MergeStrategy;
 }
+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>;