index.js 3.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123
  1. const npm = {
  2. utils: require('./utils'),
  3. batch: require('./ext/batch'),
  4. page: require('./ext/page'),
  5. sequence: require('./ext/sequence'),
  6. stream: require('./ext/stream'),
  7. errors: require('./errors')
  8. };
  9. /**
  10. * @module spex
  11. * @summary Specialized Promise Extensions
  12. * @author Vitaly Tomilov
  13. *
  14. * @description
  15. * Attaches to an external promise library and provides additional methods built solely
  16. * on the basic promise operations:
  17. * - construct a new promise with a callback function
  18. * - resolve a promise with some result data
  19. * - reject a promise with a reason
  20. *
  21. * ### usage
  22. * For any third-party promise library:
  23. * ```js
  24. * const promise = require('bluebird');
  25. * const spex = require('spex')(promise);
  26. * ```
  27. * For ES6 promises:
  28. * ```js
  29. * const spex = require('spex')(Promise);
  30. * ```
  31. *
  32. * @param {Object|Function} promiseLib
  33. * Instance of a promise library to be used by this module.
  34. *
  35. * Some implementations use `Promise` constructor to create a new promise, while
  36. * others use the module's function for it. Both types are supported the same.
  37. *
  38. * Alternatively, an object of type {@link PromiseAdapter} can be passed in, which provides
  39. * compatibility with any promise library outside of the standard.
  40. *
  41. * Passing in a promise library that cannot be recognized will throw
  42. * `Invalid promise library specified.`
  43. *
  44. * @returns {Object}
  45. * Namespace with all supported methods.
  46. *
  47. * @see {@link PromiseAdapter}, {@link batch}, {@link page}, {@link sequence}, {@link stream}
  48. */
  49. function main(promiseLib) {
  50. const spex = {}, // library instance;
  51. promise = parsePromiseLib(promiseLib); // promise library parsing;
  52. const config = {
  53. spex: spex,
  54. promise: promise,
  55. utils: npm.utils(promise)
  56. };
  57. spex.errors = npm.errors;
  58. spex.batch = npm.batch(config);
  59. spex.page = npm.page(config);
  60. spex.sequence = npm.sequence(config);
  61. spex.stream = npm.stream(config);
  62. config.utils.extend(spex, '$p', promise);
  63. Object.freeze(spex);
  64. return spex;
  65. }
  66. //////////////////////////////////////////
  67. // Parses and validates a promise library;
  68. function parsePromiseLib(lib) {
  69. if (lib) {
  70. let promise;
  71. if (lib instanceof main.PromiseAdapter) {
  72. promise = function (func) {
  73. return lib.create(func);
  74. };
  75. promise.resolve = lib.resolve;
  76. promise.reject = lib.reject;
  77. return promise;
  78. }
  79. const t = typeof lib;
  80. if (t === 'function' || t === 'object') {
  81. const Root = typeof lib.Promise === 'function' ? lib.Promise : lib;
  82. promise = function (func) {
  83. return new Root(func);
  84. };
  85. promise.resolve = Root.resolve;
  86. promise.reject = Root.reject;
  87. if (typeof promise.resolve === 'function' && typeof promise.reject === 'function') {
  88. return promise;
  89. }
  90. }
  91. }
  92. throw new TypeError('Invalid promise library specified.');
  93. }
  94. main.PromiseAdapter = require('./adapter');
  95. main.errors = npm.errors;
  96. Object.freeze(main);
  97. module.exports = main;
  98. /**
  99. * @external Error
  100. * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
  101. */
  102. /**
  103. * @external TypeError
  104. * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError
  105. */
  106. /**
  107. * @external Promise
  108. * @see https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise
  109. */