iswear

iswear is a light-weight utility library for performant asynchronous programming with Promises (Promises/A+ specification).

• 2KB unzipped
• dependency-free
• available as npm package and browser bundle

To learn about asynchronous programming with Promises, please explore the appendix.

Created by Clark Feusier

1. Installation
2. Basic Usage Example
3. Documentation
   1. API Reference
4. Roadmap
5. Contributing
6. Development Requirements
   1. Installing Development Requirements
   2. Development Dependencies
   3. Installing Development Dependencies
   4. Building for Deployment
   5. Running Tests
7. License
8. Appendix

Installation

iswear is available in two different formats:

• an npm package
• a browser bundle

Install iswear for node environments

Install npm package from command-line

npm install iswear

Require module for use in desired file

var iswear = require('iswear');

Install iswear for the browser

Download iswear from the iswear release page

Unzip the downloaded file, and move iswear.min.js to a desired project location

Within web pages of the desired project, include iswear.min.js

<script src="iswear.min.js"></script>
<!-- iswear is now attached to window and ready for use -->

Basic Usage Example

The primary use-case of iswear is the iswear.swearify method, which the example in this section demonstrates. For documentation and examples covering other methods on the iswear object, please refer to the API Reference section.

var iswear = require('iswear'); // assuming we are in node environment
var fs = require('fs');

// create a Promise interface for the fs.readFile method
var readFilePromised = iswear.swearify(fs.readFile, fs);

readFilePromised('/example/file.html', 'utf8').then(function(result) {
  // do something with the result of promise resolution
});

Documentation

iswear

This object provides the utility methods of this library.

Access iswear by requiring the npm package in node environments.

var iswear = require('iswear'); // node environment

Access iswear by including the browser bundle in a web document

<script src="iswear.min.js"></script>
<script>
  window.iswear // browser environment
</script>

API Reference

• swearify
• defer
• resolved
• rejected

swearify

swearify(cb: function, ctx: object): function

Wraps the supplied function in a promise and binds the wrapped function to the supplied context. This method is especially useful for converting asynchronous a node.js method (that receives a callback) into a promise.

var iswear = require('iswear');
var users = require('./models/users');

// create a Promise interface for the users.find method
var findPromised = iswear.swearify(users.find, users);

findPromised({ email: "[email protected]" }).then(function(user) {
  // do something cool with the promise resolution (the user record)
}).catch(function(err) {
  // do something cool with the result of the promise rejection
});

defer

defer(): Deferred<T>

Returns a new Deferred object that acts as a proxy for managing a new Promise object. Note, more often than not, the swearify method is a better choice, but occassionally you will need the defer interface.

var iswear = require('iswear');

function exampleAsync(arg) {
  var sworn = iswear.defer();

  sworn.promise.then(function(data) {
    // do something with data
  }).catch(function(err) {
    // do something with err
  });

  someAsyncFunction(arg, function(err, data) {
    if (err) {
      sworn.reject(err);
    } else {
      sworn.resolve(data);
    }
  });

  return sworn.promise;
}

resolved

resolved(val: *): Promise<T>

Returns a new promise object that has been resolved with the supplied value.

var iswear = require('iswear');
var someData = 'data coming from some async operation, probably';

var resolvedPromise = iswear.resolved(someData);
// do something with resolvedPromise

rejected

rejected(error: *): Promise<T>

Returns a new promise object that has been rejected with the supplied error.

var iswear = require('iswear');
var someError = 'some error resulting from some async operation, probably';

var rejectedPromise = iswear.rejected(someError);
// do something with rejectedPromise

Roadmap

The future of iswear is managed through this repository's issues — view the roadmap here.

Contributing to iswear

We welcome contributions, but please read our contribution guidelines before submitting your work. The development requirements and instructions are below.

Development Requirements

• Node 0.10.x
• npm 2.x.x

Installing Development Requirements

Install Node (bundled with npm) using Homebrew:

brew install node

Development Dependencies

• grunt-cli (global install)
• grunt
• grunt-contrib-uglify
• grunt-shell
• mocha
• chai
• underscore

Installing Development Dependencies

Install project and development dependencies using npm:

npm install

Building for Deployment

To build src/iswear.js into dist/iswear.min.js, use the following grunt task:

grunt build

Running Tests

After installing the above dependencies, tests can be run using the following command:

grunt test

License

iswear - light-weight Promise library for performant asynchronous programming

Copyright (C) 2015 Clark Feusier [email protected] - All Rights Reserved

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.

COMPLETE LICENSE

Appendix

Asynchronous Processing Model

This model processes instructions of a certain type (usually costly operations like I/O) asynchronously. The processor starts to process those instructions’ operations, and then hands those operations an instruction of how to return the result when complete; then, the processor continues to the next instruction without waiting for the prior instructions’ operations to complete. As soon as any operations complete, they can use the instructions they were provided at start to notify the processor of the result. This model allows the processor to avoid getting blocked by costly operations (source).

Promises

The Promise interface represents a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers to an asynchronous action's eventual success or failure. This lets asynchronous methods return values like synchronous methods: instead of the final value, the asynchronous method returns a promise of having a value at some point in the future (source).

Callbacks

A callback is a piece of executable code that is passed as an argument to other code, which is expected to call back (execute) the argument at some convenient time (source).

Back to Top

© 2015 Clark Feusier. All rights reserved.