app-reader.html

<!--
@license
Copyright (c) 2017 The expand.js authors. All rights reserved.
This code may only be used under the BSD style license found at https://expandjs.github.io/LICENSE.txt
The complete set of authors may be found at https://expandjs.github.io/AUTHORS.txt
The complete set of contributors may be found at https://expandjs.github.io/CONTRIBUTORS.txt
-->

<!--
A web component used to provide automated source reading.

@element app-reader
@since 1.0.0
@category functionality
@description A web component used to automate source reading
@keywords expandjs, web app, web components

@homepage https://expandjs.com/components/app-reader
@repository https://github.com/expandjs/app-behaviors
@source https://github.com/expandjs/app-behaviors/blob/master/app-reader.html

@behavior app-receiver-behavior /bower_components/app-behaviors/app-receiver-behavior.html
-->

<link rel="import" href="../polymer/polymer.html">
<link rel="import" href="../expandjs/expandjs.html">
<link rel="import" href="app-receiver-behavior.html">

<dom-module id="app-reader">

    <template strip-whitespace>

        <style>
            :host {
                display: none !important;
            }
        </style>

    </template>

    <script>
        Polymer({

            // ELEMENT
            is: 'app-reader',

            // BEHAVIORS
            behaviors: [
                Polymer.APPReceiverBehavior
            ],

            // CLASSES
            classes: ['reader'],

            /*********************************************************************/

            /**
             * Fired when the reader is about to refresh due to a successful write.
             *
             * @event app-reader-refresh
             * @param {string} command
             * @param {Array | Object | number} current
             * @bubbles
             * @cancelable
             */

            /*********************************************************************/

            /**
             * Refreshes the reader.
             *
             * @method refresh
             * @param {Function} [callback]
             */
            refresh(callback) {

                // Preparing
                if (XP.isVoid(callback)) { callback = function () {} ; }

                // Asserting
                XP.assertArgument(XP.isFunction(callback), 1, 'Function');

                // Resetting
                if (this.preserve === 'none') { this.reset(); }

                // Preventing
                if (!this.readable || !this.resource || !this.source) { callback(); return; }

                // Reading
                this.source.read(this.options, (error, data) => {

                    // Preparing
                    if (this.keyBy && XP.isArray(data)) { data = XP.keyBy(data, item => item[this.keyBy]); }

                    // Ensuring
                    this.ensure('error', error || null);
                    this.ensure('data',  data || null);

                    // Callback
                    callback(this.error, this.data);
                });
            },

            /**
             * Resets the reader.
             *
             * @method reset
             * @param {Function} [callback]
             */
            reset(callback) {

                // Preparing
                if (XP.isVoid(callback)) { callback = function () {} ; }

                // Asserting
                XP.assertArgument(XP.isFunction(callback), 1, 'Function');

                // Ensuring
                this.ensure('data', null);
                this.ensure('error', null);

                // Callback
                callback(this.error, this.data);
            },

            /*********************************************************************/

            // OBSERVERS
            observers: [
                '_optionsChanged(app, keyBy, options, refresher, source)',
                '_optionsChanger(count, distinct, except, exclude, groupBy, include, limit, order, orderBy, pk, resource, skip, where)'
            ],

            // PROPERTIES
            properties: {

                /**
                 * If set to true, the data count will be returned instead of data.
                 *
                 * @attribute count
                 * @type boolean
                 * @default false
                 */
                count: {
                    type: Boolean,
                    value: false
                },

                /**
                 * The received data.
                 *
                 * @attribute data
                 * @type Array | Object | number
                 * @notifies
                 * @readonly
                 */
                data: {
                    notify: true,
                    readOnly: true,
                    value: null
                },

                /**
                 * The amount of ms to wait before reading.
                 *
                 * @attribute delay
                 * @type number
                 * @default 0
                 */
                delay: {
                    type: Number,
                    value: 0
                },

                /**
                 * If set to true, `data` will be duplicate free.
                 *
                 * @attribute distinct
                 * @type boolean
                 * @default false
                 */
                distinct: {
                    type: Boolean,
                    value: false
                },

                /**
                 * The received error.
                 *
                 * @attribute error
                 * @type Object
                 * @notifies
                 * @readonly
                 */
                error: {
                    notify: true,
                    readOnly: true,
                    value: null
                },

                /**
                 * The primary key to exclude.
                 *
                 * @attribute except
                 * @type string
                 */
                except: {
                    type: String,
                    value: null
                },

                /**
                 * The fields to exclude.
                 *
                 * @attribute exclude
                 * @type string
                 */
                exclude: {
                    type: String,
                    value: null
                },

                /**
                 * The field used to group data.
                 *
                 * @attribute group-by
                 * @type string
                 */
                groupBy: {
                    type: String,
                    value: null
                },

                /**
                 * The fields to include.
                 *
                 * @attribute include
                 * @type string
                 */
                include: {
                    type: String,
                    value: null
                },

                /**
                 * Returns true if `token` is expired.
                 *
                 * @method isExpired
                 * @param {Object} token
                 * @returns boolean
                 */
                isExpired: {
                    computed: 'computeValue(source, "isExpired")',
                    type: Function
                },

                /**
                 * The field to use as key.
                 *
                 * @attribute key-by
                 * @type string
                 */
                keyBy: {
                    type: String,
                    value: null
                },

                /**
                 * The maximum number of items to read.
                 *
                 * @attribute limit
                 * @type number
                 */
                limit: {
                    type: Number,
                    value: null
                },

                /**
                 * The reader options.
                 *
                 * @attribute options
                 * @type Object
                 * @readonly
                 */
                options: {
                    readOnly: true,
                    type: Object,
                    value() { return {}; }
                },

                /**
                 * The data order.
                 *
                 * @attribute order
                 * @type "asc" | "desc" | "random"
                 */
                order: {
                    type: String,
                    value: null
                },

                /**
                 * The index used to order data.
                 *
                 * @attribute order-by
                 * @type string
                 */
                orderBy: {
                    type: String,
                    value: null
                },

                /**
                 * The primary key of the item to read.
                 *
                 * @attribute pk
                 * @type string
                 */
                pk: {
                    type: String,
                    value: null
                },

                /**
                 * Specifies how data should be preserved:
                 *
                 * - `default`: data will be emptied only when the request options change
                 * - `always`: data will never be emptied, it will only be replaced by new data
                 * - `none`: data will be emptied before each read
                 *
                 * @attribute preserve
                 * @type "always" | "default" | "none"
                 */
                preserve: {
                    type: String,
                    value: 'default'
                },

                /**
                 * If set to true, the reader is able to read.
                 *
                 * @attribute readable
                 * @type boolean
                 * @default false
                 */
                readable: {
                    observer: '_readableChanged',
                    type: Boolean,
                    value: false
                },

                /**
                 * The current refresh token.
                 *
                 * @attribute refresher
                 * @type string
                 * @readonly
                 */
                refresher: {
                    computed: '_computeRefresher(token)',
                    type: String,
                    value: null
                },

                /**
                 * The resource to read.
                 *
                 * @attribute resource
                 * @type string
                 */
                resource: {
                    type: String,
                    value: null
                },

                /**
                 * The number of items to skip.
                 *
                 * @attribute skip
                 * @type number
                 */
                skip: {
                    type: Number,
                    value: null
                },

                /**
                 * The reader's source.
                 *
                 * @attribute source
                 * @type Element
                 * @readonly
                 */
                source: {
                    master: '.source',
                    observer: '_sourceChanged',
                    readOnly: true
                },

                /**
                 * The filter applied when reading.
                 *
                 * @attribute where
                 * @type string
                 */
                where: {
                    type: String,
                    value: null
                }
            },

            /*********************************************************************/

            // COMPUTER
            _computeRefresher(token) {
                return token && !this.isExpired(token) ? token.refreshToken || token.accessToken : null;
            },

            /*********************************************************************/

            // OBSERVER
            _optionsChanged() {

                // Resetting
                if (this.preserve !== 'always') { this.reset(); }

                // Refreshing
                this.refresh();
            },

            // OBSERVER
            _optionsChanger() {

                // Let
                let keys = ['count', 'distinct', 'except', 'exclude', 'groupBy', 'include', 'limit', 'order', 'orderBy', 'pk', 'resource', 'skip', 'where'];

                // Ensuring
                this.ensure('options', keys.reduce((options, key) => Object.assign(options, XP.isUseful(this[key]) && !XP.isFalse(this[key]) && {[key]: this[key]}), {}));
            },

            // OBSERVER
            _readableChanged() {

                // Refreshing
                this.refresh();
            },

            // OBSERVER
            _sourceChanged(post, pre) {

                // Listening
                if (pre) { this.unlisten(pre, 'app-source-write', '_handleWrite'); }
                if (post) { this.listen(post, 'app-source-write', '_handleWrite'); }
            },

            /*********************************************************************/

            // LISTENER
            created() {

                // Debouncing
                this.refresh = XP.debounce(this.refresh.bind(this));
            },

            /*********************************************************************/

            // HANDLER
            _handleWrite(event) {

                // Firing
                if (this.fire('app-reader-refresh', {command: event.detail.command, current: this.data}, {cancelable: true}).defaultPrevented) { return; }

                // Refreshing
                if (this.resource === event.detail.resource) { this.refresh(); }
            }
        });
    </script>

</dom-module>