app-storage-behavior.html

<!--
@license
Copyright (c) 2016 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->
<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../promise-polyfill/promise-polyfill.html">
<script>
  (function() {
    'use strict';

    var SPLICES_RX = /\.splices$/;
    var LENGTH_RX = /\.length$/;
    var NUMBER_RX = /\.?#?([0-9]+)$/;

    /**
     * AppStorageBehavior is an abstract behavior that makes it easy to
     * synchronize in-memory data and a persistant storage system, such as
     * the browser's IndexedDB, or a remote database like Firebase.
     *
     * For examples of how to use this behavior to write your own app storage
     * elements see `<app-localstorage-document>` here, or check out
     * [polymerfire](https://github.com/Firebase/polymerfire) and
     * [app-pouchdb](https://github.com/PolymerElements/app-pouchdb).
     *
     * @polymerBehavior
     */
    Polymer.AppStorageBehavior = {
      properties: {
        /**
         * The data to synchronize.
         */
        data: {
          type: Object,
          notify: true,
          value: function() {
            return this.zeroValue;
          }
        },

        /**
         * If this is true transactions will happen one after the other,
         * never in parallel.
         *
         * Specifically, no transaction will begin until every previously
         * enqueued transaction by this element has completed.
         *
         * If it is false, new transactions will be executed as they are
         * received.
         */
        sequentialTransactions: {
          type: Boolean,
          value: false
        },

        /**
         * When true, will perform detailed logging.
         */
        log: {
          type: Boolean,
          value: false
        }
      },

      observers: [
        '__dataChanged(data.*)'
      ],

      created: function() {
        this.__initialized = false;
        this.__syncingToMemory = false;
        this.__initializingStoredValue = null;
        this.__transactionQueueAdvances = Promise.resolve();
      },

      ready: function() {
        this._initializeStoredValue();
      },

      /**
       * Override this getter to return true if the value has never been
       * persisted to storage.
       *
       * @type {boolean}
       */
      get isNew() {
        return true;
      },

      /**
       * A promise that will resolve once all queued transactions
       * have completed.
       *
       * This field is updated as new transactions are enqueued, so it will
       * only wait for transactions which were enqueued when the field
       * was accessed.
       *
       * This promise never rejects.
       *
       * @type {Promise}
       */
      get transactionsComplete() {
        return this.__transactionQueueAdvances;
      },

      /**
       * Override this getter to define the default value to use when
       * there's no data stored.
       *
       * @type {*}
       */
      get zeroValue() {
        return undefined;
      },

      /**
       * Override this method.
       *
       * If the data value represented by this storage instance is new, this
       * method generates an attempt to write the value to storage.
       *
       * @abstract
       * @return {Promise} a Promise that settles only once the write has.
       */
      save: function() {
        return Promise.resolve();
      },

      /**
       * Optional. Override this method to clear out the mapping of this
       * storage object and a logical location within storage.
       *
       * If this method is supported, after it's called, isNew() should be
       * true.
       */
      reset: function() {},

      /**
       * Remove the data from storage.
       *
       * @return {Promise} A promise that settles once the destruction is
       *   complete.
       */
      destroy: function() {
        this.data = this.zeroValue;
        return this.save();
      },

      /**
       * Perform the initial sync between storage and memory. This method
       * is called automatically while the element is being initialized.
       * Implementations may override it.
       *
       * If an implementation intends to call this method, it should instead
       * call _initializeStoredValue, which provides reentrancy protection.
       *
       * @return {Promise} A promise that settles once this process is
       *     complete.
       */
      initializeStoredValue: function() {
        if (this.isNew) {
          return Promise.resolve();
        }

        // If this is not a "new" model, then we should attempt
        // to read an initial value from storage:
        return this._getStoredValue('data').then(function(data) {
          this._log('Got stored value!', data, this.data);
          if (data == null) {
            return this._setStoredValue(
                'data', this.data || this.zeroValue);
          } else {
            this.syncToMemory(function() {
              this.set('data', data);
            });
          }
        }.bind(this));
      },

      /**
       * Override this method to implement reading a value from storage.
       *
       * @abstract
       * @param {string} storagePath The path (through storage) of the value to
       *   create, relative to the root of storage associated with this instance.
       * @return {Promise} A promise that resolves with the canonical value stored
       *   at the provided path when the transaction has completed. _If there is no
       *   such value at the provided path through storage, then the promise will
       *   resolve to `undefined`._ The promise will be rejected if the transaction
       *   fails for any reason.
       */
      getStoredValue: function(storagePath) {
        return Promise.resolve();
      },

      /**
       * Override this method to implement creating and updating
       * stored values.
       *
       * @abstract
       * @param {string} storagePath The path of the value to update, relative
       *   to the root storage path configured for this instance.
       * @param {*} value The updated in-memory value to apply to the stored value
       *   at the provided path.
       * @return {Promise} A promise that resolves with the canonical value stored
       *   at the provided path when the transaction has completed. The promise
       *   will be rejected if the transaction fails for any reason.
       */
      setStoredValue: function(storagePath, value) {
        return Promise.resolve(value);
      },

      /**
       * Maps a Polymer databinding path to the corresponding path in the
       * storage system. Override to define a custom mapping.
       *
       * The inverse of storagePathToMemoryPath.
       *
       * @param {string} path An in-memory path through a storage object.
       * @return {string} The provided path mapped to the equivalent location in
       *   storage. This mapped version of the path is suitable for use with the
       *   CRUD operations on both memory and storage.
       */
      memoryPathToStoragePath: function(path) {
        return path;
      },

      /**
       * Maps a storage path to the corresponding Polymer databinding path.
       * Override to define a custom mapping.
       *
       * The inverse of memoryPathToStoragePath.
       *
       * @param {string} path The storage path through a storage object.
       * @return {string} The provided path through storage mapped to the
       *   equivalent Polymer path through the in-memory representation of storage.
       */
      storagePathToMemoryPath: function(path) {
        return path;
      },

      /**
       * Enables performing transformations on the in-memory representation of
       * storage without activating observers that will cause those
       * transformations to be re-applied to the storage backend. This is useful
       * for preventing redundant (or cyclical) application of transformations.
       *
       * @param {Function} operation A function that will perform the desired
       *   transformation. It will be called synchronously, when it is safe to
       *   apply the transformation.
       */
      syncToMemory: function(operation) {
        if (this.__syncingToMemory) {
          return;
        }

        this._group('Sync to memory.');

        this.__syncingToMemory = true;
        operation.call(this);
        this.__syncingToMemory = false;

        this._groupEnd('Sync to memory.');
      },

      /**
       * A convenience method. Returns true iff value is null, undefined,
       * an empty array, or an object with no keys.
       */
      valueIsEmpty: function(value) {
        if (Array.isArray(value)) {
          return value.length === 0;
        } else if (Object.prototype.isPrototypeOf(value)) {
          return Object.keys(value).length === 0;
        } else {
          return value == null;
        }
      },

      /**
       * Like `getStoredValue` but called with a Polymer path rather than
       * a storage path.
       *
       * @param {string} path The Polymer path to get.
       * @return {Promise} A Promise of the value stored at that path.
       */
      _getStoredValue: function(path) {
        return this.getStoredValue(this.memoryPathToStoragePath(path));
      },

      /**
       * Like `setStoredValue` but called with a Polymer path rather than
       * a storage path.
       *
       * @param {string} path The Polymer path to update.
       * @param {*} value The updated in-memory value to apply to the stored value
       *   at the provided path.
       * @return {Promise} A promise that resolves with the canonical value stored
       *   at the provided path when the transaction has completed. The promise
       *   will be rejected if the transaction fails for any reason.
       */
      _setStoredValue: function(path, value) {
        return this.setStoredValue(this.memoryPathToStoragePath(path), value);
      },

      /**
       * Enqueues the given function in the transaction queue.
       *
       * The transaction queue allows for optional parallelism/sequentiality
       * via the `sequentialTransactions` boolean property, as well as giving
       * the user a convenient way to wait for all pending transactions to
       * finish.
       *
       * The given function may be called immediately or after an arbitrary
       * delay. Its `this` context will be bound to the element.
       *
       * If the transaction performs any asynchronous operations it must
       * return a promise.
       *
       * @param {Function} transaction A function implementing the transaction.
       * @return {Promise} A promise that resolves once the transaction has
       *   finished. This promise will never reject.
       */
      _enqueueTransaction: function(transaction) {
        if (this.sequentialTransactions) {
          transaction = transaction.bind(this);
        } else {
          var result = transaction.call(this);
          transaction = function() {
            return result;
          };
        }

        return this.__transactionQueueAdvances = this.__transactionQueueAdvances
            .then(transaction)
            .catch(function(error) {
              this._error('Error performing queued transaction.', error);
            }.bind(this));
      },

      /**
       * A wrapper around `console.log`.
       */
      _log: function() {
        if (this.log) {
          console.log.apply(console, arguments);
        }
      },

      /**
       * A wrapper around `console.error`.
       */
      _error: function() {
        if (this.log) {
          console.error.apply(console, arguments);
        }
      },

      /**
       * A wrapper around `console.group`.
       */
      _group: function() {
        if (this.log) {
          console.group.apply(console, arguments);
        }
      },

      /**
       * A wrapper around `console.groupEnd`.
       */
      _groupEnd: function() {
        if (this.log) {
          console.groupEnd.apply(console, arguments);
        }
      },

      /**
       * A reentrancy-save wrapper around `this.initializeStoredValue`.
       * Prefer calling this method over that one.
       *
       * @return {Promise} The result of calling `initializeStoredValue`,
       *   or `undefined` if called while initializing.
       */
      _initializeStoredValue: function() {
         if (this.__initializingStoredValue) {
          if (!this.__willReenter) {
            this.__willReenter = true;
            this.__initializingStoredValue.then(function(){
              this.__willReenter = false;
              this._initializeStoredValue();
            }.bind(this));
          }
          return;
        }

        this._group('Initializing stored value.');

        var initializingStoredValue =
            this.__initializingStoredValue =
            this.initializeStoredValue().then(function() {
              this.__initialized = true;
              this.__initializingStoredValue = null;
              this._groupEnd('Initializing stored value.');
            }.bind(this));

        return this._enqueueTransaction(function() {
          return initializingStoredValue;
        });
      },

      __dataChanged: function(change) {
        if (this.isNew ||
            this.__syncingToMemory ||
            !this.__initialized ||
            this.__pathCanBeIgnored(change.path)) {
          return;
        }

        var path = this.__normalizeMemoryPath(change.path);
        var value = change.value;
        var indexSplices = value && value.indexSplices;

        this._enqueueTransaction(function() {

          this._log('Setting', path + ':', indexSplices || value);

          if (indexSplices && this.__pathIsSplices(path)) {
            path = this.__parentPath(path);
            value = this.get(path);
          }

          return this._setStoredValue(path, value);
        });
      },

      __normalizeMemoryPath: function(path) {
        var parts = path.split('.');
        var parentPath = [];
        var currentPath = [];
        var normalizedPath = [];
        var index;

        for (var i = 0; i < parts.length; ++i) {
          currentPath.push(parts[i]);
          if (/^#/.test(parts[i])) {
            normalizedPath.push(
                this.get(parentPath).indexOf(this.get(currentPath)));
          } else {
            normalizedPath.push(parts[i]);
          }
          parentPath.push(parts[i]);
        }

        return normalizedPath.join('.');
      },

      __parentPath: function(path) {
        var parentPath = path.split('.');
        return parentPath.slice(0, parentPath.length - 1).join('.');
      },

      __pathCanBeIgnored: function(path) {
        return LENGTH_RX.test(path) &&
            Array.isArray(this.get(this.__parentPath(path)));
      },

      __pathIsSplices: function(path) {
        return SPLICES_RX.test(path) &&
            Array.isArray(this.get(this.__parentPath(path)));
      },

      __pathRefersToArray: function(path) {
        return (SPLICES_RX.test(path) || LENGTH_RX.test(path)) &&
            Array.isArray(this.get(this.__parentPath(path)));
      },

      __pathTailToIndex: function(path) {
        var tail = path.split('.').pop();
        return window.parseInt(tail.replace(NUMBER_RX, '$1'), 10);
      }
    };
  })();
</script>