feat(plugin): Create plugin API

Closes #7

Author: christopherthielen

src/interface.ts

@@ -11,6 +11,7 @@
 
 // Need to import or export at least one concrete something
 import {noop} from "./common/common";
+import {UIRouter} from "./router";
 
 /**
  * An interface for getting values from dependency injection.
@@ -81,3 +82,7 @@ export interface UIInjector {
   getNative(token: any): any;
   getNative<T>(token: any): T;
 }
+
+export abstract class UIRouterPlugin {
+  abstract name(): string;
+}

src/router.ts

@@ -7,6 +7,7 @@ import {ViewService} from "./view/view";
 import {StateRegistry} from "./state/stateRegistry";
 import {StateService} from "./state/stateService";
 import {UIRouterGlobals, Globals} from "./globals";
+import {UIRouterPlugin} from "./interface";
 
 /**
  * The master class used to instantiate an instance of UI-Router.
@@ -41,5 +42,65 @@ export class UIRouter {
     this.globals.$current = this.stateRegistry.root();
     this.globals.current = this.globals.$current.self;
   }
-}
 
+  private _plugins: { [key: string]: UIRouterPlugin } = {};
+
+  /**
+   * Adds a plugin to UI-Router
+   *
+   * This method adds a UI-Router Plugin.
+   * A plugin can enhance or change UI-Router behavior using any public API.
+   *
+   * #### Example:
+   * ```js
+   * import { MyCoolPlugin } from "ui-router-cool-plugin";
+   *
+   * var plugin = router.addPlugin(MyCoolPlugin);
+   * ```
+   *
+   * ### Plugin authoring
+   *
+   * A plugin is simply a class (or constructor function) which accepts a [[UIRouter]] instance and (optionally) an options object.
+   *
+   * The plugin can implement its functionality using any of the public APIs of [[UIRouter]].
+   * For example, it may configure router options or add a Transition Hook.
+   *
+   * The plugin can then be published as a separate module.
+   *
+   * #### Example:
+   * ```js
+   * export class MyAuthPlugin {
+   *   constructor(router: UIRouter, options: any) {
+   *     let $transitions = router.transitionService;
+   *     let $state = router.stateService;
+   *
+   *     let authCriteria = {
+   *       to: (state) => state.data && state.data.requiresAuth
+   *     };
+   *
+   *     function authHook(transition: Transition) {
+   *       let authService = transition.injector().get('AuthService');
+   *       if (!authService.isAuthenticated()) {
+   *         return $state.target('login');
+   *       }
+   *     }
+   *
+   *     $transitions.onStart(authCriteria, authHook);
+   *   }
+   * }
+   * ```
+   *
+   * @param PluginClass a UI-Router Plugin class (or constructor function).
+   * @param options options to pass to the plugin
+   * @returns {T}
+   */
+  addPlugin<T extends UIRouterPlugin>(PluginClass: { new(router: UIRouter, options?: any): T }, options: any = {}): T {
+    let pluginInstance = new PluginClass(this, options);
+    var pluginName = pluginInstance.name();
+    return this._plugins[pluginName] = pluginInstance;
+  }
+
+  getPlugin(pluginName: string): UIRouterPlugin {
+    return this._plugins[pluginName];
+  }
+}

test/pluginSpec.ts

@@ -0,0 +1,63 @@
+import { UIRouter, TransitionService, StateService } from "../src/index";
+import "../src/justjs";
+import { StateRegistry } from "../src/state/stateRegistry";
+import { UrlRouter } from "../src/url/urlRouter";
+import {UIRouterPlugin} from "../src/interface";
+
+describe('plugin api', function () {
+  let router: UIRouter;
+  let $registry: StateRegistry;
+  let $transitions: TransitionService;
+  let $state: StateService;
+  let $urlRouter: UrlRouter;
+
+  beforeEach(() => {
+    router = new UIRouter();
+    $registry = router.stateRegistry;
+    $state = router.stateService;
+    $transitions = router.transitionService;
+    $urlRouter = router.urlRouter;
+    router.stateRegistry.stateQueue.autoFlush($state);
+  });
+
+  class FancyPlugin extends UIRouterPlugin {
+    constructor(public router: UIRouter) {
+      super();
+
+    }
+    name() { return "fancyplugin" }
+  }
+
+  describe('initialization', () => {
+    it('should return an instance of the plugin', () => {
+      let plugin = router.addPlugin(FancyPlugin);
+      expect(plugin instanceof FancyPlugin).toBeTruthy();
+    });
+
+    it('should pass the router instance to the plugin constructor', () => {
+      let pluginRouterInstance = undefined;
+      function Plugin(router) {
+        pluginRouterInstance = router;
+        this.name = () => "plugin";
+      }
+
+      router.addPlugin(<any> Plugin);
+      expect(pluginRouterInstance).toBe(router);
+    });
+
+    it('should throw if the plugin constructor returns an object without name() getter', () => {
+      function Plugin(router) {
+      }
+
+      expect(() => router.addPlugin(<any> Plugin)).toThrow()
+    });
+  });
+
+  describe('getPlugin', () => {
+    it('should return the plugin instance', () => {
+      router.addPlugin(FancyPlugin);
+      let plugin = router.getPlugin('fancyplugin');
+      expect(plugin instanceof FancyPlugin).toBeTruthy();
+    });
+  })
+});