moodle/lib/amd/src/user_date.js

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.

/**
 * Fetch and render dates from timestamps.
 *
 * @module     core/user_date
 * @copyright  2017 Ryan Wyllie <ryan@moodle.com>
 * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
 */
define(['jquery', 'core/ajax', 'core/sessionstorage', 'core/config'],
        function($, Ajax, Storage, Config) {

    var SECONDS_IN_DAY = 86400;

    /** @var {object} promisesCache Store all promises we've seen so far. */
    var promisesCache = {};

    /**
     * Generate a cache key for the given request. The request should
     * have a timestamp and format key.
     *
     * @param {object} request
     * @return {string}
     */
    var getKey = function(request) {
        return 'core_user_date/' +
               Config.language + '/' +
               Config.usertimezone + '/' +
               request.timestamp + '/' +
               request.format;
    };

    /**
     * Retrieve a transformed date from the browser's storage.
     *
     * @param {string} key
     * @return {string}
     */
    var getFromLocalStorage = function(key) {
        return Storage.get(key);
    };

    /**
     * Save the transformed date in the browser's storage.
     *
     * @param {string} key
     * @param {string} value
     */
    var addToLocalStorage = function(key, value) {
        Storage.set(key, value);
    };

    /**
     * Check if a key is in the module's cache.
     *
     * @param {string} key
     * @return {bool}
     */
    var inPromisesCache = function(key) {
        return (typeof promisesCache[key] !== 'undefined');
    };

    /**
     * Retrieve a promise from the module's cache.
     *
     * @param {string} key
     * @return {object} jQuery promise
     */
    var getFromPromisesCache = function(key) {
        return promisesCache[key];
    };

    /**
     * Save the given promise in the module's cache.
     *
     * @param {string} key
     * @param {object} promise
     */
    var addToPromisesCache = function(key, promise) {
        promisesCache[key] = promise;
    };

    /**
     * Send a request to the server for each of the required timestamp
     * and format combinations.
     *
     * Resolves the date's deferred with the values returned from the
     * server and saves the value in local storage.
     *
     * @param {array} dates
     * @return {object} jQuery promise
     */
    var loadDatesFromServer = function(dates) {
        var args = dates.map(function(data) {
            var fixDay = data.hasOwnProperty('fixday') ? data.fixday : 1;
            var fixHour = data.hasOwnProperty('fixhour') ? data.fixhour : 1;
            return {
                timestamp: data.timestamp,
                format: data.format,
                type: data.type || null,
                fixday: fixDay,
                fixhour: fixHour
            };
        });

        var request = {
            methodname: 'core_get_user_dates',
            args: {
                contextid: Config.contextid,
                timestamps: args
            }
        };

        return Ajax.call([request], true, true)[0].then(function(results) {
            results.dates.forEach(function(value, index) {
                var date = dates[index];
                var key = getKey(date);

                addToLocalStorage(key, value);
                date.deferred.resolve(value);
            });
            return;
        })
        .catch(function(ex) {
            // If we failed to retrieve the dates then reject the date's
            // deferred objects to make sure they don't hang.
            dates.forEach(function(date) {
                date.deferred.reject(ex);
            });
        });
    };

    /**
     * Takes an array of request objects and returns a promise that
     * is resolved with an array of formatted dates.
     *
     * The values in the returned array will be ordered the same as
     * the request array.
     *
     * This function will check both the module's static promises cache
     * and the browser's session storage to see if the user dates have
     * already been loaded in order to avoid sending a network request
     * if possible.
     *
     * Only dates not found in either cache will be sent to the server
     * for transforming.
     *
     * A request object must have a timestamp key and a format key and
     * optionally may have a type key.
     *
     * E.g.
     * var request = [
     *     {
     *         timestamp: 1293876000,
     *         format: '%d %B %Y'
     *     },
     *     {
     *         timestamp: 1293876000,
     *         format: '%A, %d %B %Y, %I:%M %p',
     *         type: 'gregorian',
     *         fixday: false,
     *         fixhour: false
     *     }
     * ];
     *
     * UserDate.get(request).done(function(dates) {
     *     console.log(dates[0]); // prints "1 January 2011".
     *     console.log(dates[1]); // prints "Saturday, 1 January 2011, 10:00 AM".
     * });
     *
     * @param {array} requests
     * @return {object} jQuery promise
     */
    var get = function(requests) {
        var ajaxRequests = [];
        var promises = [];

        // Loop over each of the requested timestamp/format combos
        // and add a promise to the promises array for them.
        requests.forEach(function(request) {
            var key = getKey(request);

            // If we've already got a promise then use it.
            if (inPromisesCache(key)) {
                promises.push(getFromPromisesCache(key));
            } else {
                var deferred = $.Deferred();
                var cached = getFromLocalStorage(key);

                if (cached) {
                    // If we were able to get the value from session storage
                    // then we can resolve the deferred with that value. No
                    // need to ask the server to transform it for us.
                    deferred.resolve(cached);
                } else {
                    // Add this request to the list of ones we need to load
                    // from the server. Include the deferred so that it can
                    // be resolved when the server has responded with the
                    // transformed values.
                    request.deferred = deferred;
                    ajaxRequests.push(request);
                }

                // Remember this promise for next time so that we can
                // bail out early if it is requested again.
                addToPromisesCache(key, deferred.promise());
                promises.push(deferred.promise());
            }
        });

        // If we have any requests that we couldn't resolve from the caches
        // then let's ask the server to get them for us.
        if (ajaxRequests.length) {
            loadDatesFromServer(ajaxRequests);
        }

        // Wait for all of the promises to resolve. Some of them may be waiting
        // for a response from the server.
        return $.when.apply($, promises).then(function() {
            // This looks complicated but it's just converting an unknown
            // length of arguments into an array for the promise to resolve
            // with.
            return arguments.length === 1 ? [arguments[0]] : Array.apply(null, arguments);
        });
    };


    /**
     * For a given timestamp get the midnight value in the user's timezone.
     *
     * The calculation is performed relative to the user's midnight timestamp
     * for today to ensure that timezones are preserved.
     *
     * E.g.
     * Input:
     * timestamp: 1514836800 (01/01/2018 8pm GMT)(02/01/2018 4am GMT+8)
     * midnight: 1514851200 (02/01/2018 midnight GMT)
     * Output:
     * 1514764800 (01/01/2018 midnight GMT)
     *
     * Input:
     * timestamp: 1514836800 (01/01/2018 8pm GMT)(02/01/2018 4am GMT+8)
     * midnight: 1514822400 (02/01/2018 midnight GMT+8)
     * Output:
     * 1514822400 (02/01/2018 midnight GMT+8)
     *
     * @param {Number} timestamp The timestamp to calculate from
     * @param {Number} todayMidnight The user's midnight timestamp
     * @return {Number} The midnight value of the user's timestamp
     */
    var getUserMidnightForTimestamp = function(timestamp, todayMidnight) {
        var future = timestamp > todayMidnight;
        var diffSeconds = Math.abs(timestamp - todayMidnight);
        var diffDays = future ? Math.floor(diffSeconds / SECONDS_IN_DAY) : Math.ceil(diffSeconds / SECONDS_IN_DAY);
        var diffDaysInSeconds = diffDays * SECONDS_IN_DAY;
        // Is the timestamp in the future or past?
        var dayTimestamp = future ? todayMidnight + diffDaysInSeconds : todayMidnight - diffDaysInSeconds;
        return dayTimestamp;
    };

    return {
        get: get,
        getUserMidnightForTimestamp: getUserMidnightForTimestamp
    };
});