Add mixin that implements a common adapter pattern

Author: tomasbasham

README.md

@@ -1,25 +1,159 @@
-# Ember-cli-adapter-pattern
+# Ember-cli-adapter-pattern [![Build Status](https://travis-ci.org/tomasbasham/ember-cli-adapter-pattern.svg?branch=master)](https://travis-ci.org/tomasbasham/ember-cli-adapter-pattern)
 
-This README outlines the details of collaborating on this Ember addon.
+An [Ember CLI](http://www.ember-cli.com/) addon to standardise a common adapter pattern.
+
+The adapter pattern helps to provide a common interface from which two incompatible interface may work together. For example you may wish to include in your applications the ability to authenticate users through a variety of social platforms (i.e. Facebook and Twitter). Each platform defines its own API which to interface with it's servers. Using the adapter pattern you can separate the logic of both APIs into their own adapter objects, using a common interface to work with both.
+
+This addon implements a common adapter pattern that can be included in any ember object allowing it to act as a proxy between the application and any external interface.
 
 ## Installation
 
+From within your Ember CLI project directory run:
+```
+ember install ember-cli-adapter-pattern
+```
+
+## Usage
+
+This addon implements a mixin that should be included in any object you wish to act as the interface between your application and any external platform or API.
+
+### Adaptable Mixin
+
+In order to implement the adapter pattern, it is recommended you include the `Adaptable` mixin into an ember object that will act as a singleton, i.e. a service.
+
+##### <a name="adaptable-example"></a>Example:
+
+```JavaScript
+// app/services/social.js
+import Ember from 'ember';
+import Adaptable from 'ember-cli-adapter-pattern/mixins/adaptable';
+import proxyToAdapter from 'ember-cli-adapter-pattern/utils/proxy-to-adapter';
+
+export default Ember.Service.extend(Adaptable, {
+  login: proxyToAdapter('login'), // Provides a safe method to proxy your API to each adapter.
+
+  /*
+   * There are potentially many ways
+   * to activate adapters, but it is
+   * imperative that somewhere the
+   * `activateAdapters` method is
+   * called.
+   */
+  createAdapters: Ember.on('init', function() {
+    const adapters = Ember.getWithDefault(this, 'property.with.adapter.configurations', Ember.A());
+
+    this.set('_adapters', {});
+    this.set('context', {});
+
+    this.activateAdapters(adapters); // This is important and activates configured adapters.
+  }),
+
+  /*
+   * This is the only method that you
+   * are required to write and defines
+   * how you look up your adapters. It
+   * is not limited to using the
+   * container.
+   */
+  _lookupAdapter(adapterName) {
+    Ember.assert('Could not find adapter without a name', adapterName);
+
+    const container = this.get('container');
+    const dasherizedAdapterName = Ember.String.dasherize(adapterName);
+    const adapter = container.lookup(`container:${dasherizedAdapterName}`);
+
+    return adapter;
+  }
+});
+```
+
+This creates a service that will act as the common API for each of your adapters. Here you can see I have defined a single common API method named `login`.
+
+### Making API Calls
+
+To make calls to your API you must inject the `Adaptable` object into another ember object (i.e. a controller) and invoke it as normal.
+
+##### <a name="all-adapters-example"></a>Example:
+
+```JavaScript
+// app/controller/application.js
+import Ember from 'ember';
+
+export default Ember.Controller.extend({
+  social: Ember.Service.inject(),
+
+  actions: {
+    loginWithService() {
+      this.get('social').login({ username: 'Jean-Luc Picard', password: 'Enterprise-D' });
+    }
+  }
+});
+```
+
+The action defined in the controller will call the `login` method on the `social` service. This will in turn forward the invocation on to each of the adapters. Of course in this example it would make little sense to login with more than one platform at the same time. If you wish to call only one adapter then you must pass in it's name to the API call.
+
+##### <a name="single-adapter-example"></a>Example:
+
+```JavaScript
+// app/controller/application.js
+import Ember from 'ember';
+
+export default Ember.Controller.extend({
+  social: Ember.Service.inject(),
+
+  actions: {
+    loginWithService() {
+      this.get('social').login('Facebook', { username: 'Jean-Luc Picard', password: 'Enterprise-D' });
+    }
+  }
+});
+```
+
+This will only make the API call to the 'Facebook' adapter.
+
+Each API call will be wrapped within a promise that resolves with the returned result of the adapter mapped to the adapter name.
+
+### ProxyToAdapter Utility
+
+The `proxyToAdapter` utility method simply forwards calls made to each of your API methods to all defined adapters, or just a single adapter if specified. It is recommended you use `proxyToAdapter` because it implements guard statements to prevent the application from throwing errors.
+
+If however you need to extend the functionality of your API methods then somewhere in its implementation it needs to call the `invoke` method defined within the `Adaptable` mixin.
+
+```JavaScript
+// app/services/social.js
+import Ember from 'ember';
+import Adaptable from 'ember-cli-adapter-pattern/mixins/adaptable';
+
+export default Ember.Service.extend(Adaptable, {
+  login(...args) {
+    // Extended operations here.
+    this.invoke('login', ...args);
+  }
+});
+```
+
+Here we are passing the name of the API call as the first argument to `invoke` followed by the arguments that were passed into the API call.
+
+## Development
+
+### Installation
+
 * `git clone` this repository
 * `npm install`
 * `bower install`
 
-## Running
+### Running
 
 * `ember server`
 * Visit your app at http://localhost:4200.
 
-## Running Tests
+### Running Tests
 
 * `npm test` (Runs `ember try:testall` to test your addon against multiple Ember versions)
 * `ember test`
 * `ember test --server`
 
-## Building
+### Building
 
 * `ember build`
 

addon/mixins/adaptable.js

@@ -0,0 +1,164 @@
+import Ember from 'ember';
+import requiredMethod from 'ember-cli-adapter-pattern/utils/required-method';
+
+const {
+  assert,
+  copy,
+  get,
+  merge,
+  on,
+  set
+} = Ember;
+
+const {
+  resolve
+} = Ember.RSVP;
+
+const {
+  keys
+} = Object;
+
+export default Ember.Mixin.create({
+
+  /*
+   * A cache of active adapters to save
+   * time on expensive container lookups.
+   *
+   * @type {Object}
+   */
+  _adapters: null,
+
+  /*
+   * Extra information you can attach to
+   * every adapter call. This can be handy
+   * when there is a value that needs to
+   * be present with every aapter call,
+   * reducing the need to pass the value
+   * each time.
+   *
+   * @type {Object}
+   */
+  context: null,
+
+  /*
+   * Instantiates a series of adapters as
+   * defined in the application config and
+   * caches them to save on expensive future
+   * lookups.
+   *
+   * @method activateAdapters
+   *
+   * @param {Array} adapterOptions
+   *   Adapter configuration options.
+   */
+  activateAdapters(adapterOptions) {
+    const cachedAdapters = get(this, '_adapters');
+    const activatedAdapters = {};
+
+    adapterOptions.forEach((adapterOption) => {
+      const { name } = adapterOption;
+      const adapter = cachedAdapters[name] ? cachedAdapters[name] : this.activateAdapter(adapterOption);
+
+      set(activatedAdapters, name, adapter);
+    });
+
+    set(this, '_adapters', activatedAdapters);
+  },
+
+  /*
+   * Instantiates a single adapter from a
+   * configuration object.
+   *
+   * @method activateAdapter
+   *
+   * @params {Object} adapterOptions
+   *   Adapter configuration options. Must have a name property, and optioanlly a config property.
+   *
+   * @return {Object}
+   *   An instantiated adpater.
+   */
+  activateAdapter({ name, config } = {}) {
+    const adapter = this._lookupAdapter(name);
+    assert(`Could not find adapter ${name}`, adapter);
+
+    return adapter.create({ this, config });
+  },
+
+  /*
+   * Invoke a method on a registered
+   * adpater. If a specific adapter
+   * name is supplied then the method
+   * will only be invoked on that
+   * adapter, providing it exists.
+   *
+   * @method invoke
+   *
+   * @param {String} methodName
+   *   The name of the method to invoke.
+   *
+   * @param {Rest} args
+   *   Any other supplied arguments.
+   *
+   * @return {Ember.RSVP}
+   *   A hash of promise objects.
+   */
+  invoke(methodName, ...args) {
+    const cachedAdapters = get(this, '_adapters');
+    const adapterNames = keys(cachedAdapters);
+    const [selectedAdapterNames, options] = args.length > 1 ? [[args[0]], args[1]] : [adapterNames, args[0]];
+    const context = copy(get(this, 'context'));
+    const mergedOptions = merge(context, options);
+
+    // Store a promise for each adapter response.
+    const promises = {};
+
+    selectedAdapterNames.map((adapterName) => {
+      const adapter = get(cachedAdapters, adapterName);
+      promises[adapterName] = resolve(adapter[methodName].call(adapter, mergedOptions));
+    });
+
+    return Ember.RSVP.hash(promises);
+  },
+
+  /*
+   * Ensure that we have a clean cache
+   * of adapters. It may be beneficial
+   * to override this method in a
+   * consuming application or addon so
+   * the adapters can be activated
+   * here also.
+   *
+   * @method createAdapters
+   * @on init
+   */
+  createAdapters: on('init', function() {
+    set(this, '_adapters', {});
+    set(this, 'context', {});
+  }),
+
+  /*
+   * Tear down any cached adapters.
+   *
+   * @method destroyAdapters
+   * @on willDestroy
+   */
+  destroyAdapters: on('willDestroy', function() {
+    const cachedAdapters = get(this, '_adapters');
+
+    for(let adapterName in cachedAdapters) {
+      get(cachedAdapters, adapterName).destroy();
+    }
+  }),
+
+  /*
+   * An abstract method that needs to
+   * be defined on the consuming
+   * application or addon responsible
+   * for the lookup of adapter objects
+   * from the container.
+   *
+   * @method lookupAdapter
+   * @private
+   */
+  _lookupAdapter: requiredMethod('_lookupAdapter')
+});

addon/utils/proxy-to-adapter.js

@@ -0,0 +1,31 @@
+import Ember from 'ember';
+
+const {
+  assert
+} = Ember;
+
+/*
+ * Utility method, returning a proxy function
+ * that looks up a function on the intended
+ * adapter. The proxy funtion will return a
+ * resolved promise with a value.
+ *
+ * @method proxyToAdapter
+ *
+ * @param {String} methodName
+ *   Name of the method to proxy.
+ *
+ * @return {Function}
+ *   A proxy function returning a resolved promise.
+ */
+export default function proxyToAdapter(methodName) {
+  assert('Method name is required for proxyToAdapter.', methodName);
+
+  return function(...args) {
+    if (!this.invoke && typeof this.invoke !== 'function') {
+      throw new Ember.Error('No invoke method. Have you forgotten to include the Adaptable mixin?');
+    }
+
+    return this.invoke(methodName, ...args);
+  };
+}

addon/utils/required-method.js

@@ -0,0 +1,26 @@
+import Ember from 'ember';
+
+const {
+  assert
+} = Ember;
+
+/*
+ * Utility method, returning a function that
+ * throws an error unless defined. This is
+ * like implementing abstract methods.
+ *
+ * @method requiredMethod
+ *
+ * @param {String} methodName
+ *   Name of the required method.
+ *
+ * @return {Function}
+ *   An 'abstract' method implementation.
+ */
+export default function requiredMethod(methodName) {
+  assert('Method name is required for requiredMethod.', methodName);
+
+  return function() {
+    throw new Ember.Error(`Definition of method ${methodName} is required.`);
+  };
+}