custom-promise - npm Package Compare versions

Comparing version 1.0.0 to 1.1.0

package.json

 {
   "name": "custom-promise",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "license": "MIT",
   "files": [
-    "build/module"
+    "modules",
+    "templates",
+    "tools"
   ],
-  "main": "build/module/p.node.js",
+  "main": "modules/p.node.js",
   "repository": "jacksonrayhamilton/custom-promise",
   "scripts": {
-    "prepublish": "grunt module"
+    "prepublish": "grunt modules"
   },
+  "dependencies": {
+    "lodash": "^4.11.1"
+  },
   "devDependencies": {
@@ -33,3 +38,2 @@ "bootstrap": "^3.3.6",
     "load-grunt-tasks": "^3.4.0",
-    "lodash": "^4.11.1",
     "mocha": "^2.3.4",
@@ -36,0 +40,0 @@ "promises-aplus-tests": "^2.1.1",

README.md

@@ -5,50 +5,77 @@ # custom-promise [![Build Status](https://travis-ci.org/jacksonrayhamilton/custom-promise.svg?branch=master)](https://travis-ci.org/jacksonrayhamilton/custom-promise)
 
-- Small: About 500 bytes minified and gzipped with all features.  About 300
-  bytes when built only for A+ compliance.
+- Small: About 500 bytes minified and gzipped.  About 300 bytes when built only
+  for A+ compliance.
 - Useful: `catch`, `resolve`, `reject`, `all`, `race`, old IE support.
 - Secure: No private state exposed.
-- Customizable: Include only what you need with the [Customizer][]!
+- Customizable: Include only necessary functionality with the [Customizer][]!
 
-## API
+## Usage
 
-Access the custom-promise API through the exported function `p` and its methods.
+Include the fully-featured library with `npm`:
 
+```sh
+npm install custom-promise
+```
+
+In Node, load it via `require`:
+
+```js
+var p = require('custom-promise');
+```
+
+In browsers, load it via `<script>`:
+
+```html
+<script src="node_modules/custom-promise/modules/p.script.js"></script>
+```
+
+Alternatively, create a custom build with the [Customizer][] or
+`tools/build.js`.
+
+## Promise API
+
+Access the promise API through the exported function `p` and its methods.
+
 ### `p(executor)`
 
-Create a promise.  The function `executor` is immediately called with `resolve`
-and `reject` functions as arguments, which fulfill or reject the promise.
+Returns a promise.  The function `executor` is immediately called with `resolve`
+and `reject` functions as arguments.  Call `resolve` with one argument to
+fulfill the promise with that value.  Call `reject` with one argument to reject
+the promise with that reason.
 
 ### `promise.then(onFulfilled, onRejected)`
 
-Register callbacks to receive a promise's eventual value or the reason why it
-cannot be fulfilled.
+Registers callbacks to receive a promise's eventual value or the reason why it
+cannot be fulfilled, and returns a promise resolving with the return value of
+these callbacks.
 
 ### `promise.catch(onRejected)`
 
-Register just a rejection callback.
+Registers just a rejection callback, and returns a promise resolving with the
+return value of this callback.
 
 ### `p.resolve(value)`
 
-Create a promise fulfilled with `value`.  If `value` has a `then` method, it is
-assumed to be a promise, and a new promise is returned inheriting the state of
-`value`.
+Returns a promise fulfilled with `value`.  If `value` has a `then` method, it is
+assumed to be a promise, and the returned promise inherits the state of `value`.
 
 ### `p.reject(reason)`
 
-Create a promise rejected with `reason`.
+Returns a promise rejected with `reason`.
 
 ### `p.all(collection)`
 
-Create a promise resolving the values in `collection`.  If `collection` is
-array-like (has a `length` property), the promise is resolved with an array,
-else with an object.  Each value in `collection` must be fulfilled by
-`p.resolve` before the promise is fulfilled.  If any value in `collection` is
-rejected, the promise is rejected.
+Returns a promise resolving the values in `collection`.  If `collection` is
+array-like (has a `length` property), the promise is fulfilled with an array,
+otherwise it is fulfilled with an object.  Each value in `collection` must be
+fulfilled (internally) by `p.resolve` before the returned promise is fulfilled.
+If any value in `collection` is rejected, the returned promise is rejected.
 
 ### `p.race(collection)`
 
-Create a promise resolving with the first value to resolve in `collection` via
-`p.resolve`.  If any value in `collection` is rejected, the promise is rejected.
+Returns a promise resolving with the first value to resolve in `collection` via
+`p.resolve` (internally).  If any value in `collection` is rejected, the
+returned promise is rejected.
 
-## Examples
+### Examples
 
@@ -85,3 +112,3 @@ Use `p.resolve` to create a promise and `then` to handle its fulfillment:
 
-You can use `p.all` to await the completion of multiple promises:
+Use `p.all` to await the completion of multiple promises:
 
@@ -101,3 +128,3 @@ ```js
 
-When order is unimportant, you can pass an object to `p.all` instead:
+When order is unimportant, pass an object to `p.all` instead:
 
@@ -114,4 +141,4 @@ ```js
 
-When only the value of one promise in a set of promises matters, you can use
-`p.race` with an [array-like] object:
+When only the value of one promise in a set of promises matters, use `p.race`
+with an [array-like] object:
 
@@ -127,2 +154,33 @@ ```js
 
+## Custom Build API
+
+Programmatically make custom builds with `tools/build.js`.
+
+### build(options)
+
+Returns a customized implementation of `p` as a string.  The following options
+are available:
+
+- `catch`: Provide the `catch` method on promises.
+- `resolve`, `reject`, `all`, `race`: Provide these methods on `p`.
+- `task`: Customize the task function.  The default is `setTimeout`.
+  Alternatives like `setImmediate` or `process.nextTick` may be used if they
+  will be available globally in target environments.
+- `ie`: Workaround old IE bugs.
+- `node`: Export a Node.js module.
+
+### Examples
+
+Create a custom build with `catch` and `ie` support, and save it to
+`build/p.custom.js`:
+
+```js
+var fs = require('fs');
+var build = require('custom-promise/tools/build');
+fs.writeFileSync('build/p.custom.js', build({
+  catch: true,
+  ie: true
+}));
+```
+
 ## Use cases
@@ -143,4 +201,4 @@
 `Promise` and `p` have approximately the same interface, so this implementation
-could reasonably substitute for `Promise` until it becomes ubiquitous.
+could reasonably substitute for `Promise`.
 
 [Customizer]: http://jacksonrayhamilton.github.io/custom-promise/

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

28922

increased by66.6%

Dev dependency count

23

decreased by-4.17%

Number of package files

9

increased by80%

Lines of code

445

increased by30.88%

Number of lines in readme file

199

increased by41.13%

Worsened metrics

Dependency count

1

increased byInfinity%

Number of low supply chain risk alerts

2

increased by100%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedlodash@^4.11.1

• + Addedlodash@4.17.21(transitive)