Nutritious Pomegranate Muffins

    iswear

    1.0.0 • Public • Published

    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.

    Current Stable Release Version Latest Build Status for iswear Current Stable npm Release


    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:

    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

    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: "example@gmail.com" }).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 issuesview 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 cfeusier@gmail.com - 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.

    Install

    npm i iswear

    DownloadsWeekly Downloads

    0

    Version

    1.0.0

    License

    MIT

    Last publish

    Collaborators

    • cfeusier