├── .editorconfig ├── .gitattributes ├── license └── readme.md /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_style = tab 5 | end_of_line = lf 6 | charset = utf-8 7 | trim_trailing_whitespace = true 8 | insert_final_newline = true 9 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto eol=lf 2 | -------------------------------------------------------------------------------- /license: -------------------------------------------------------------------------------- 1 | Creative Commons Legal Code 2 | 3 | CC0 1.0 Universal 4 | 5 | CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE 6 | LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN 7 | ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS 8 | INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES 9 | REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS 10 | PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM 11 | THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED 12 | HEREUNDER. 13 | 14 | Statement of Purpose 15 | 16 | The laws of most jurisdictions throughout the world automatically confer 17 | exclusive Copyright and Related Rights (defined below) upon the creator 18 | and subsequent owner(s) (each and all, an "owner") of an original work of 19 | authorship and/or a database (each, a "Work"). 20 | 21 | Certain owners wish to permanently relinquish those rights to a Work for 22 | the purpose of contributing to a commons of creative, cultural and 23 | scientific works ("Commons") that the public can reliably and without fear 24 | of later claims of infringement build upon, modify, incorporate in other 25 | works, reuse and redistribute as freely as possible in any form whatsoever 26 | and for any purposes, including without limitation commercial purposes. 27 | These owners may contribute to the Commons to promote the ideal of a free 28 | culture and the further production of creative, cultural and scientific 29 | works, or to gain reputation or greater distribution for their Work in 30 | part through the use and efforts of others. 31 | 32 | For these and/or other purposes and motivations, and without any 33 | expectation of additional consideration or compensation, the person 34 | associating CC0 with a Work (the "Affirmer"), to the extent that he or she 35 | is an owner of Copyright and Related Rights in the Work, voluntarily 36 | elects to apply CC0 to the Work and publicly distribute the Work under its 37 | terms, with knowledge of his or her Copyright and Related Rights in the 38 | Work and the meaning and intended legal effect of CC0 on those rights. 39 | 40 | 1. Copyright and Related Rights. A Work made available under CC0 may be 41 | protected by copyright and related or neighboring rights ("Copyright and 42 | Related Rights"). Copyright and Related Rights include, but are not 43 | limited to, the following: 44 | 45 | i. the right to reproduce, adapt, distribute, perform, display, 46 | communicate, and translate a Work; 47 | ii. moral rights retained by the original author(s) and/or performer(s); 48 | iii. publicity and privacy rights pertaining to a person's image or 49 | likeness depicted in a Work; 50 | iv. rights protecting against unfair competition in regards to a Work, 51 | subject to the limitations in paragraph 4(a), below; 52 | v. rights protecting the extraction, dissemination, use and reuse of data 53 | in a Work; 54 | vi. database rights (such as those arising under Directive 96/9/EC of the 55 | European Parliament and of the Council of 11 March 1996 on the legal 56 | protection of databases, and under any national implementation 57 | thereof, including any amended or successor version of such 58 | directive); and 59 | vii. other similar, equivalent or corresponding rights throughout the 60 | world based on applicable law or treaty, and any national 61 | implementations thereof. 62 | 63 | 2. Waiver. To the greatest extent permitted by, but not in contravention 64 | of, applicable law, Affirmer hereby overtly, fully, permanently, 65 | irrevocably and unconditionally waives, abandons, and surrenders all of 66 | Affirmer's Copyright and Related Rights and associated claims and causes 67 | of action, whether now known or unknown (including existing as well as 68 | future claims and causes of action), in the Work (i) in all territories 69 | worldwide, (ii) for the maximum duration provided by applicable law or 70 | treaty (including future time extensions), (iii) in any current or future 71 | medium and for any number of copies, and (iv) for any purpose whatsoever, 72 | including without limitation commercial, advertising or promotional 73 | purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each 74 | member of the public at large and to the detriment of Affirmer's heirs and 75 | successors, fully intending that such Waiver shall not be subject to 76 | revocation, rescission, cancellation, termination, or any other legal or 77 | equitable action to disrupt the quiet enjoyment of the Work by the public 78 | as contemplated by Affirmer's express Statement of Purpose. 79 | 80 | 3. Public License Fallback. Should any part of the Waiver for any reason 81 | be judged legally invalid or ineffective under applicable law, then the 82 | Waiver shall be preserved to the maximum extent permitted taking into 83 | account Affirmer's express Statement of Purpose. In addition, to the 84 | extent the Waiver is so judged Affirmer hereby grants to each affected 85 | person a royalty-free, non transferable, non sublicensable, non exclusive, 86 | irrevocable and unconditional license to exercise Affirmer's Copyright and 87 | Related Rights in the Work (i) in all territories worldwide, (ii) for the 88 | maximum duration provided by applicable law or treaty (including future 89 | time extensions), (iii) in any current or future medium and for any number 90 | of copies, and (iv) for any purpose whatsoever, including without 91 | limitation commercial, advertising or promotional purposes (the 92 | "License"). The License shall be deemed effective as of the date CC0 was 93 | applied by Affirmer to the Work. Should any part of the License for any 94 | reason be judged legally invalid or ineffective under applicable law, such 95 | partial invalidity or ineffectiveness shall not invalidate the remainder 96 | of the License, and in such case Affirmer hereby affirms that he or she 97 | will not (i) exercise any of his or her remaining Copyright and Related 98 | Rights in the Work or (ii) assert any associated claims and causes of 99 | action with respect to the Work, in either case contrary to Affirmer's 100 | express Statement of Purpose. 101 | 102 | 4. Limitations and Disclaimers. 103 | 104 | a. No trademark or patent rights held by Affirmer are waived, abandoned, 105 | surrendered, licensed or otherwise affected by this document. 106 | b. Affirmer offers the Work as-is and makes no representations or 107 | warranties of any kind concerning the Work, express, implied, 108 | statutory or otherwise, including without limitation warranties of 109 | title, merchantability, fitness for a particular purpose, non 110 | infringement, or the absence of latent or other defects, accuracy, or 111 | the present or absence of errors, whether or not discoverable, all to 112 | the greatest extent permissible under applicable law. 113 | c. Affirmer disclaims responsibility for clearing rights of other persons 114 | that may apply to the Work or any use thereof, including without 115 | limitation any person's Copyright and Related Rights in the Work. 116 | Further, Affirmer disclaims responsibility for obtaining any necessary 117 | consents, permissions or other rights required for any use of the 118 | Work. 119 | d. Affirmer understands and acknowledges that Creative Commons is not a 120 | party to this document and has no duty or obligation with respect to 121 | this CC0 or use of the Work. 122 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # promise-fun 2 | 3 | I intend to use this space to document my promise modules, useful promise patterns, and how to solve common problems. For now though, you can see all my promise modules below. 4 | 5 | ## Contents 6 | 7 | - [Packages](#packages) 8 | - [FAQ](#faq) 9 | 10 | ## Packages 11 | 12 | *Not accepting additions, but happy to take requests.* 13 | 14 | - **[pify](https://github.com/sindresorhus/pify)**: Promisify a callback-style function 15 | - **[delay](https://github.com/sindresorhus/delay)**: Delay a promise a specified amount of time 16 | - **[yoctodelay](https://github.com/sindresorhus/yoctodelay)**: Delay a promise a specified amount of time 17 | - **[p-map](https://github.com/sindresorhus/p-map)**: Map over promises concurrently 18 | - **[p-all](https://github.com/sindresorhus/p-all)**: Run promise-returning & async functions concurrently with optional limited concurrency 19 | - **[p-event](https://github.com/sindresorhus/p-event)**: Promisify an event by waiting for it to be emitted 20 | - **[p-debounce](https://github.com/sindresorhus/p-debounce)**: Debounce promise-returning & async functions 21 | - **[p-throttle](https://github.com/sindresorhus/p-throttle)**: Throttle promise-returning & async functions 22 | - **[p-timeout](https://github.com/sindresorhus/p-timeout)**: Timeout a promise after a specified amount of time 23 | - **[p-retry](https://github.com/sindresorhus/p-retry)**: Retry a promise-returning or async function 24 | - **[p-any](https://github.com/sindresorhus/p-any)**: Wait for any promise to be fulfilled 25 | - **[p-some](https://github.com/sindresorhus/p-some)**: Wait for a specified number of promises to be fulfilled 26 | - **[p-mutex](https://github.com/sindresorhus/p-mutex)**: Ensure that only one operation accesses a particular resource at a time 27 | - **[p-locate](https://github.com/sindresorhus/p-locate)**: Get the first fulfilled promise that satisfies the provided testing function 28 | - **[p-limit](https://github.com/sindresorhus/p-limit)**: Run multiple promise-returning & async functions with limited concurrency 29 | - **[p-series](https://github.com/sindresorhus/p-series)**: Run promise-returning & async functions in series 30 | - **[p-memoize](https://github.com/sindresorhus/p-memoize)**: Memoize promise-returning & async functions 31 | - **[p-pipe](https://github.com/sindresorhus/p-pipe)**: Compose promise-returning & async functions into a reusable pipeline 32 | - **[p-props](https://github.com/sindresorhus/p-props)**: Like `Promise.all()` but for `Map` and `Object` 33 | - **[p-waterfall](https://github.com/sindresorhus/p-waterfall)**: Run promise-returning & async functions in series, each passing its result to the next 34 | - **[p-cancelable](https://github.com/sindresorhus/p-cancelable)**: Create a promise that can be canceled 35 | - **[p-progress](https://github.com/sindresorhus/p-progress)**: Create a promise that reports progress 36 | - **[p-reflect](https://github.com/sindresorhus/p-reflect)**: Make a promise always fulfill with its actual fulfillment value or rejection reason 37 | - **[p-filter](https://github.com/sindresorhus/p-filter)**: Filter promises concurrently 38 | - **[p-reduce](https://github.com/sindresorhus/p-reduce)**: Reduce a list of values using promises into a promise for a value 39 | - **[p-settle](https://github.com/sindresorhus/p-settle)**: Settle promises concurrently and get their fulfillment value or rejection reason with optional limited concurrency 40 | - **[p-map-series](https://github.com/sindresorhus/p-map-series)**: Map over promises serially 41 | - **[p-each-series](https://github.com/sindresorhus/p-each-series)**: Iterate over promises serially 42 | - **[p-times](https://github.com/sindresorhus/p-times)**: Run promise-returning & async functions a specific number of times concurrently 43 | - **[p-lazy](https://github.com/sindresorhus/p-lazy)**: Create a lazy promise that defers execution until `.then()` or `.catch()` is called 44 | - **[p-whilst](https://github.com/sindresorhus/p-whilst)**: While a condition returns true, calls a function repeatedly, and then resolves the promise 45 | - **[p-do-whilst](https://github.com/sindresorhus/p-do-whilst)**: Calls a function repeatedly while a condition returns true and then resolves the promise 46 | - **[p-forever](https://github.com/sindresorhus/p-forever)**: Run promise-returning & async functions repeatedly until you end it 47 | - **[p-wait-for](https://github.com/sindresorhus/p-wait-for)**: Wait for a condition to be true 48 | - **[p-min-delay](https://github.com/sindresorhus/p-min-delay)**: Delay a promise a minimum amount of time 49 | - **[p-try](https://github.com/sindresorhus/p-try)**: `Promise.try()` ponyfill - Starts a promise chain 50 | - **[p-race](https://github.com/sindresorhus/p-race)**: A better `Promise.race()` 51 | - **[p-immediate](https://github.com/sindresorhus/p-immediate)**: Returns a promise resolved in the next event loop - think `setImmediate()` 52 | - **[p-time](https://github.com/sindresorhus/p-time)**: Measure the time a promise takes to resolve 53 | - **[p-defer](https://github.com/sindresorhus/p-defer)**: Create a deferred promise 54 | - **[p-is-promise](https://github.com/sindresorhus/p-is-promise)**: Check if something is a promise 55 | - **[p-state](https://github.com/sindresorhus/p-state)**: Inspect the state of a promise 56 | - **[p-queue](https://github.com/sindresorhus/p-queue)**: Promise queue with concurrency control 57 | - **[make-synchronous](https://github.com/sindresorhus/make-synchronous)**: Make an asynchronous function synchronous 58 | 59 | ### `.then`/`.catch`-based packages 60 | 61 | *You should generally avoid using `.then` except in edge cases.* 62 | 63 | - **[p-catch-if](https://github.com/sindresorhus/p-catch-if)**: Conditional promise catch handler 64 | - **[p-if](https://github.com/sindresorhus/p-if)**: Conditional promise chains 65 | - **[p-tap](https://github.com/sindresorhus/p-tap)**: Tap into a promise chain without affecting its value or state 66 | - **[p-log](https://github.com/sindresorhus/p-log)**: Log the value/error of a promise 67 | - **[p-break](https://github.com/sindresorhus/p-break)**: Break out of a promise chain 68 | 69 | ## FAQ 70 | 71 | ### How can I run 100 async/promise-returning functions with only 5 running at once? 72 | 73 | This is a good use-case for [`p-map`](https://github.com/sindresorhus/p-map). You might ask why you can't just specify an array of promises. Promises represent values of a computation and not the computation itself - they are eager. So by the time `p-map` starts reading the array, all the actions creating those promises have already started running. `p-map` works by executing a promise-returning function in a mapper function. This way the promises are created lazily and can be concurrency limited. Check out [`p-all`](https://github.com/sindresorhus/p-all) instead if you're using different functions to get each promise. 74 | 75 | ```js 76 | import pMap from 'p-map'; 77 | 78 | const urls = [ 79 | 'https://sindresorhus.com', 80 | 'https://avajs.dev', 81 | 'https://github.com', 82 | … 83 | ]; 84 | 85 | console.log(urls.length); 86 | //=> 100 87 | 88 | const mapper = url => fetchStats(url); //=> Promise 89 | 90 | const result = await pMap(urls, mapper, {concurrency: 5}); 91 | 92 | console.log(result); 93 | //=> [{url: 'https://sindresorhus.com', stats: {…}}, …] 94 | ``` 95 | --------------------------------------------------------------------------------