const {PageError} = require('../errors/page'); /** * @method page * @description * Resolves a dynamic sequence of pages/arrays with [mixed values]{@tutorial mixed}. * * The method acquires pages (arrays of [mixed values]{@tutorial mixed}) from the `source` function, one by one, * and resolves each page as a {@link batch}, till no more pages left or an error/reject occurs. * * @param {Function|generator} source * Expected to return a [mixed value]{@tutorial mixed} that resolves with the next page of data (array of [mixed values]{@tutorial mixed}). * Returning or resolving with `undefined` ends the sequence, and the method resolves. * * The function inherits `this` context from the calling method. * * Parameters: * - `index` = index of the page being requested * - `data` = previously returned page, resolved as a {@link batch} (`undefined` when `index=0`) * - `delay` = number of milliseconds since the last call (`undefined` when `index=0`) * * If the function throws an error or returns a rejected promise, the method rejects with * {@link errors.PageError PageError}, which will have property `source` set. * * And if the function returns or resolves with anything other than an array or `undefined`, * the method rejects with the same {@link errors.PageError PageError}, but with `error` set to * `Unexpected data returned from the source.` * * Passing in anything other than a function will reject with {@link external:TypeError TypeError} = `Parameter 'source' must be a function.` * * @param {Object} [options] * Optional Parameters. * * @param {Function|generator} [options.dest] * Optional destination function (or generator), to receive a resolved {@link batch} of data * for each page, process it and respond as required. * * Parameters: * - `index` = page index in the sequence * - `data` = page data resolved as a {@link batch} * - `delay` = number of milliseconds since the last call (`undefined` when `index=0`) * * The function inherits `this` context from the calling method. * * It can optionally return a promise object, if notifications are handled asynchronously. * And if a promise is returned, the method will not request another page from the `source` * function until the promise has been resolved. * * If the function throws an error or returns a rejected promise, the sequence terminates, * and the method rejects with {@link errors.PageError PageError}, which will have property `dest` set. * * @param {Number} [options.limit=0] * Limits the maximum number of pages to be requested from the `source`. If the value is greater * than 0, the method will successfully resolve once the specified limit has been reached. * * When `limit` isn't specified (default), the sequence is unlimited, and it will continue * till one of the following occurs: * - `source` returns or resolves with `undefined` or an invalid value (non-array) * - either `source` or `dest` functions throw an error or return a rejected promise * * @returns {external:Promise} * * When successful, the method resolves with object `{pages, total, duration}`: * - `pages` = number of pages resolved * - `total` = the sum of all page sizes (total number of values resolved) * - `duration` = number of milliseconds consumed by the method * * When the method fails, it rejects with {@link errors.PageError PageError}. * */ function page(source, options, config) { const $p = config.promise, spex = config.spex, utils = config.utils; if (typeof source !== 'function') { return $p.reject(new TypeError('Parameter \'source\' must be a function.')); } options = options || {}; source = utils.wrap(source); const limit = (options.limit > 0) ? parseInt(options.limit) : 0, dest = utils.wrap(options.dest), self = this, start = Date.now(); let request, srcTime, destTime, total = 0; return $p((resolve, reject) => { function loop(idx) { const srcNow = Date.now(), srcDelay = idx ? (srcNow - srcTime) : undefined; srcTime = srcNow; utils.resolve.call(self, source, [idx, request, srcDelay], value => { if (value === undefined) { success(); } else { if (value instanceof Array) { spex.batch(value) .then(data => { request = data; total += data.length; if (dest) { const destNow = Date.now(), destDelay = idx ? (destNow - destTime) : undefined; let destResult; destTime = destNow; try { destResult = dest.call(self, idx, data, destDelay); } catch (err) { fail({ error: err, dest: data }, 4, dest.name); return; } if (utils.isPromise(destResult)) { destResult .then(next) .catch(error => { fail({ error: error, dest: data }, 3, dest.name); }); } else { next(); } } else { next(); } return null; // this dummy return is just to prevent Bluebird warnings; }) .catch(error => { fail({ error: error }, 0); }); } else { fail({ error: new Error('Unexpected data returned from the source.'), source: request }, 5, source.name); } } }, (reason, isRej) => { fail({ error: reason, source: request }, isRej ? 1 : 2, source.name); }); function next() { if (limit === ++idx) { success(); } else { loop(idx); } return null; // this dummy return is just to prevent Bluebird warnings; } function success() { resolve({ pages: idx, total: total, duration: Date.now() - start }); } function fail(reason, code, cbName) { reason.index = idx; reject(new PageError(reason, code, cbName, Date.now() - start)); } } loop(0); }); } module.exports = function (config) { return function (source, options) { return page.call(this, source, options, config); }; };