/*
* Copyright (c) 2017 Thomas Otterson
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of
* this software and associated documentation files (the "Software"), to deal in
* the Software without restriction, including without limitation the rights to
* use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
* the Software, and to permit persons to whom the Software is furnished to do so,
* subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
* FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
* COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
* IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
/**
* Protocols for iteration and reduction. The source for these protocols depends on which protocol it is.
*
* Iteration: a part of the ES6 standard.
* Transduction: agreed to by several parties who maintain transducer libraries in the comment thread for an issue on
* one of them ({@link https://github.com/cognitect-labs/transducers-js/issues/20}).
*
* @module protocol
* @private
*/
const { isFunction } = require('./util');
/**
* Whether or not to use symbols for protocol property names if they're available. Even if this is set to `true`,
* strings will be used for the names if symbols are not available.
*
* @private
* @type {boolean}
*/
const USE_SYMBOLS = true;
/**
* Whether or not symbols are available in the environment.
*
* @private
* @type {boolean}
*/
const symbol = typeof Symbol !== 'undefined';
/**
* Generation of the key used on an object to store a protocol function. This is a symbol if symbols are available and
* {@link module:protocol~USE_SYMBOLS} is set to true; if not, it's a regular string. If a symbol of the supplied name
* already exists, it'll be used instead of having a new one generated.
*
* @private
*
* @param {name} name The name of the protocol to generate a key name for.
* @return {(string|Symbol)} The property key name to use. This is a Symbol if configured to use symbols and if they're
* available; otherwise it's a string.
*/
function generateKey(name) {
return USE_SYMBOLS && symbol ? Symbol.for(name) : `@@${name}`;
}
/**
* **The mapping of protocol names to their respective property key names.**
*
* The values of this map will depend on whether symbols are available, whatever is present here will be used as key
* names for protocol properties throughout the library.
*
* @memberof module:xduce
* @type {module:xduce~protocolMap}
*/
const protocols = {
// Since this one is built in, it already has a custom Symbol property, so we don't need to generate a symbol for a
// key when symbols are supported.
iterator: symbol ? Symbol.iterator : '@@iterator',
// Reduction protocols
init: generateKey('transducer/init'),
step: generateKey('transducer/step'),
result: generateKey('transducer/result'),
reduced: generateKey('transducer/reduced'),
value: generateKey('transducer/value')
};
/**
* Determines whether an object implements a given protocol. Generally, a protocol is implemented if the object has a
* function property with the name of that protocol (as given in the protocol object). For iteration, it's accepted that
* an object with a `next` function is also an iterator, so we make a specific check for that.
*
* For the reduced and value protocols, the requirement that the property be a function is waived.
*
* @private
*
* @param {*} obj The value to be checked to see if it implements a protocol.
* @param {string} protocol The short name of the protocol, as reflected in {@link module:xduce.protocols|protocols}.
* This is one of `iterator`, `init`, `step`, `result`, `reduced`, or `value`.
* @return {boolean} Either `true` if the value implements the protocol or `false` if it does not.
*/
function isImplemented(obj, protocol) {
if (obj == null) {
return false;
}
switch (protocol) {
case 'iterator':
return isFunction(obj[protocols.iterator] || obj.next);
case 'reduced':
case 'value':
return protocols[protocol] in obj;
default:
return isFunction(obj[protocols[protocol]]);
}
}
module.exports = {
protocols,
isImplemented
};