feat(PoolStore): create a dynamic pool store

This commit adds in a new service `PoolStore` to solve the issues of
selectively hiding data from lists when "used" and brought back when
"freed".  It includes Karma unit tests.

The scenario to think about is a typeahead that must hide data selective
when it is used. This allows dynamic lists to be formed where the data
needs to be hidden after used.

client/src/js/services/PoolStore.js

@@ -0,0 +1,60 @@
+angular.module('bhima.services')
+  .service('PoolStore', PoolStoreService);
+
+PoolStoreService.$inject = [ 'Store' ];
+
+function PoolStoreService(Store) {
+
+  function PoolStore(identifier, data) {
+    this.initialize(identifier, data);
+  }
+
+  // initialize the stores with data
+  PoolStore.prototype.initialize = function initialize(identifier, data) {
+
+    // make sure the data array is defined
+    data = data || [];
+
+    // default to indexing on 'id'
+    identifier = identifier || 'id';
+
+    this.available = new Store({
+      identifier : identifier,
+      data : data
+    });
+
+    this.unavailable = new Store({
+      identifier : identifier,
+      data : []
+    });
+
+    this._size = data.length;
+  };
+
+  // remove the item from the pool
+  PoolStore.prototype.use = function use(id) {
+    var item = this.available.get(id);
+    if (item) {
+      this.available.remove(id);
+      this.unavailable.post(item);
+    }
+    return item;
+  };
+
+  // return the unavailable item to the pool
+  PoolStore.prototype.free = function free(id) {
+    var item = this.unavailable.get(id);
+    if (item) {
+      this.unavailable.remove(id);
+      this.available.post(item);
+    }
+    return item;
+  };
+
+  // the total number of items stored in the PoolStore
+  PoolStore.prototype.size = function size() {
+    return this._size;
+  };
+
+  return PoolStore;
+}

client/test/unit/services/PoolStore.spec.js

@@ -0,0 +1,81 @@
+/* jshint expr: true */
+/* global inject, expect */
+describe('PoolStore', function () {
+  'use strict';
+
+  const data = [{
+    id: 1,
+    name: 'Bob'
+  }, {
+    id: 2,
+    name: 'Sarah'
+  }];
+
+  let PoolStore;
+
+  beforeEach(() => {
+    module('bhima.services');
+  });
+
+  beforeEach(inject((_PoolStore_) => {
+    PoolStore = _PoolStore_;
+  }));
+
+  it('#constructor() runs with sane defaults', () => {
+    let PS = new PoolStore();
+    expect(PS).to.be.defined;
+    expect(PS.available.identifier).to.equal('id');
+    expect(PS.available.data).to.have.length(0);
+
+    PS = new PoolStore('uuid');
+    expect(PS.available.identifier).to.equal('uuid');
+    expect(PS.available.data).to.have.length(0);
+    expect(PS.unavailable.identifier).to.equal('uuid');
+
+    PS = new PoolStore('id', data);
+    expect(PS.available.identifier).to.equal('id');
+    expect(PS.available.data).to.have.length(2);
+    expect(PS.unavailable.data).to.have.length(0);
+  });
+
+  it('#use() retrieves items stored in it', () => {
+    let PS = new PoolStore('id', data);
+
+    let bob = PS.use(1);
+    expect(bob.id).to.equal(1);
+    expect(bob.name).to.equal('Bob');
+
+    let sarah = PS.use(2);
+    expect(sarah.id).to.equal(2);
+    expect(sarah.name).to.equal('Sarah');
+
+    // cannot retrieve the same item twice
+    let bobDuplicate = PS.use(1);
+    expect(bobDuplicate).to.be.undefined;
+  });
+
+  it('#free() returns items to the available pool', () => {
+    let PS = new PoolStore('id', data);
+
+    let bob = PS.use(1);
+    expect(bob.id).to.equal(1);
+
+    let duplicate = PS.use(1);
+    expect(duplicate).to.be.undefined;
+
+    // return bob to the pool
+    PS.free(1);
+
+    let bobAgain = PS.use(1);
+    expect(bobAgain.id).to.equal(1);
+  });
+
+  it('#size() reports the proper size', () => {
+    let PS = new PoolStore('id', []);
+    expect(PS.size()).to.equal(0);
+
+    PS = new PoolStore('id', data);
+    expect(PS.size()).to.equal(2);
+  });
+});
+