/
package.json
65 lines (65 loc) · 13.4 KB
/
package.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
"name": "promised-io",
"version": "0.3.4",
"author": {
"name": "Kris Zyp"
},
"description": "Promise-based IO",
"licenses": [
{
"type": "AFLv2.1",
"url": "http://trac.dojotoolkit.org/browser/dojo/trunk/LICENSE#L43"
},
{
"type": "BSD",
"url": "http://trac.dojotoolkit.org/browser/dojo/trunk/LICENSE#L13"
}
],
"repository": {
"type": "git",
"url": "http://github.com/kriszyp/promised-io"
},
"contributors": [
{
"name": "Dean Landolt"
},
{
"name": "Nathan Stott",
"email": "nathan.stott@whiteboard-it.com"
},
{
"name": "Mark Wubben",
"email": "mark@novemberborn.net"
},
{
"name": "Vladimir Dronnikov",
"email": "dronnikov@gmail.com"
}
],
"keywords": [
"promise",
"io"
],
"mappings": {
"patr": "http://github.com/kriszyp/patr/zipball/v0.2.5"
},
"directories": {
"lib": "."
},
"main": "./promise",
"devDependencies": {
"patr": ">0.2.6",
"vows": ">=0.5.10"
},
"readme": "Promised-IO is a cross-platform package for asynchronous promise-based IO. Promises\r\nprovide a simple robust mechanism asynchronicity with separation of concerns by encapsulating\r\neventual completion of an operation with side effect free callback registration\r\nseparate from call invocation. Promised-IO provides cross-platform \r\nfile, HTTP, and system interaction with promises for asynchronous operations.\r\n\r\nPromised-IO also utilizes \"lazy arrays\" for progressively completed \r\nactions or for streaming of data. Lazy arrays provide all the standard iterative Array methods for\r\nreceiving callbacks as actions are completed. Lazy arrays are utilized\r\nfor progressive loading of files and HTTP responses.\r\n\r\n# Installation\r\n\r\nPromised-IO can be installed via npm:\r\n\r\n\tnpm install promised-io\r\n\r\n# promise\r\n\r\nThe promise module provides the primary tools for creating new promises and interacting\r\nwith promises. The promise API used by promised-io is the [Promises/A](http://wiki.commonjs.org/wiki/Promises/A)\r\nproposal used by Dojo, jQuery, and other toolkits. Within promised-io, a promise is \r\ndefined as any object that implements the Promises/A API, that is they provide a\r\nthen() method that can take a callback. The then() methods definition is:\r\n\r\n promise.then(fulfilledHandler, errorHandler);\r\n\r\nPromises can originate from a variety of sources, and promised-io provides a constructor, Deferred,\r\nto create promises.\r\n\r\n## when\r\n\r\n\twhen = require(\"promised-io/promise\");\r\n\twhen(promiseOrValue, fulfilledHandler, errorHandler);\r\n\t\r\nYou can pass a promise to the when() function and the fulfillment and error handlers will be registered for it's\r\ncompletion *or* you can pass a regular value, and the fulfillment handler will be \r\nimmediately be called. The when function is a staple of working with promises because\r\nit allows you to write code that normalizes interaction with synchronous values and asynchronous promises.\r\nIf you pass in a promise, a new promise for the result of execution of the callback handler\r\nwill be returned. If you pass a normal value, the return value will be the value returned\r\nfrom the fulfilledHandler.\r\n\r\n## Deferred\r\n\r\n\tdeferred = require(\"promised-io/promise\").Deferred(canceler);\r\n\r\nThe Deferred constructor is the primary mechanism for creating new promises. The Deferred\r\nobject is a form of a promise that with an interface for fulfilling or rejecting the promise.\r\nA Deferred object is a means for a producer to resolve a promise and it also provides\r\na promise for consumers that are listening for the resolution of the promise. The basic\r\nusage pattern looks like:\r\n\r\n\tvar Deferred = require(\"promised-io/promise\").Deferred;\r\n function delay(ms, value){\r\n \t// create a new Deferred\r\n \tvar deferred = new Deferred();\r\n \tsetTimeout(function(){\r\n \t\t// fulfill the deferred/promise, all listeners to the promise will be notified, and \r\n \t\t// provided the value as the value of the promise \r\n \t\tdeferred.resolve(value);\r\n \t}, ms);\r\n \t// return the promise that is associated with the Deferred object\r\n \treturn deferred.promise;\r\n }\r\n\r\nThe Deferred can optional take a canceler function. This function will cause resulting\r\npromises to have a cancel() method, and if the cancel() method is called, the \r\nDeferred will be canceled and the canceler function will be called.\r\n\r\nThe Deferred object has the following methods and properties:\r\n\r\n### resolve\r\n\r\n deferred.resolve(value);\r\n\r\nThis will fulfill the Deferred's promise with the provided value. The fulfillment listeners to the promise\r\nwill be notified.\r\n\r\n### reject\r\n\r\n deferred.reject(error);\r\n\r\nThis will reject the Deferred's promise with the provided error. The error listeners to the promise\r\nwill be notified.\r\n\r\n### promise\r\n\r\nThis is the promise object associated with the Deferred instance. The promise object \r\nwill not have any of the Deferred's fulfill or reject methods, and only provides an interface\r\nfor listening. This can be safely provided to consumers without any chance of being modified.\r\n\r\n### cancel\r\n\r\n deferred.cancel();\r\n\r\nThis will cancel the Deferred.\r\n \r\n## currentContext\r\n\r\nOne of the challenges with working asynchronous code is that there can be times when\r\nyou wish for some contextual state information to be preserved across multiple\r\nasynchronous actions, without having to actually pass the state to each function in\r\nthe asynchronous chain. A common examples of such contextual state would be tracking\r\nthe current transaction, or the currently logged in user. Such state information could be \r\nstored in a singleton (a module property or a global variable), but with asynchronous\r\nactions being interleaved, this is unsuitable for tracking state across asynchronous continuations\r\nof an action. \r\n\r\nThe promised-io package's promise module provides a facility for tracking state across\r\nasynchronous operations. The promise module tracks the \"currentContext\" global variable,\r\nand whatever value that was in the variable at the time a promise was created\r\nwill be restored when that promise is fulfilled (or rejected). \r\n\r\n## all\r\n\r\n\tgroup = require(\"promised-io/promise\").all(arrayOfPromises);\r\n\r\nThe all() function can be passed an array of promises, or multiple promises as individual\r\narguments, and all() will return a new promise that represents the completed values when all the promises\r\nhave been fulfilled. This allows you to easily run multiple asynchronous actions, and wait\r\nfor the completion (\"join\") of all the actions. For example:\r\n \r\n\tgroup = all(promise1, promise2, promise3);\r\n\tgroup.then(function(array){\r\n\t\tvar value1 = array[0]; // result of promise1\r\n\t\tvar value2 = array[1]; // result of promise2\r\n\t\tvar value3 = array[2]; // result of promise3\r\n\t});\r\n\r\n## first\r\n\r\n\tfirst = require(\"promised-io/promise\").first(arrayOfPromises);\r\n\r\nThe first() function can be passed an array of promises, or multiple promises as individual\r\narguments, and first() will return a new promise that represents the completed value when the first promise\r\nis fulfilled. This allows you to run multiple asynchronous actions get the first result. For example:\r\n \r\n\tresponse = first(requestToMainSite, requestToMirrorSite1, requestToMirrorSite2);\r\n\tresponse.then(function(response){\r\n\t\t// response from the first site to respond\r\n\t});\r\n\r\n## seq\r\n\r\n\tresult = require(\"promised-io/promise\").seq(arrayOfActionFunctions, startingValue);\r\n\r\nThe seq() function can be passed an array of functions, and seq() will execute each function\r\nin sequence, waiting for the promise returned from each one to complete before executing\r\nthe next function. Each function will be called with the result of the last function (or the\r\nstartingValue for the first function).\r\n\r\n## whenPromise\r\n\r\n\tresultPromise = require(\"promised-io/promise\").whenPromise(valueOrPromise, fulfillmentHandler, errorHandler); \r\n\r\nThe whenPromise() function behaves exactly like when() except that whenPromise\r\nwill always return a promise, even if a non-promise value is passed in.\r\n\r\n## allKeys\r\n\r\n\tgroup = require(\"promised-io/promise\").allKeys(hashOfPromises);\r\n\r\nTakes a hash of promises and returns a promise that is fulfilled once all the promises in the hash keys are fulfilled.\r\n\r\n# fs\r\n\t\r\nThis module provides promise-based access to the filesystem. The API of the fs module\r\nbasically follows the [Node File System module API](http://nodejs.org/api/fs.html).\r\nEach of the asynchronous functions in the Node's FS API is reflected with a corresponding \r\nfunction in the fs module that returns a promise (instead of requiring a callback argument in the initial call).\r\nFor example, where Node has fs.rename(path1, path2, [callback]), with promised-io\r\nyou would call it:\r\n\r\n\tvar fs = require(\"promised-io/fs\").fs;\r\n\tfs.rename(path1, path2).then(function(){\r\n\t\t// finished renaming\r\n\t}); \r\n\r\nOne function that does differ from NodeJS's fs module is the open() function.\r\n\r\n## open\r\n\r\n\tvar file = require(\"promised-io/fs\").open(path, mode);\r\n\r\nThe open() function differs from simply being a promise-based version of the Node's\r\nopen() function in that it immediately returns (even though the opening of the\r\nfile is asynchronous) a file object that be used to read from and write to the file.\r\n\r\nTo write to the file object, we can write:\r\n\r\n\tpromiseForCompletion = file.write(contents, options, encoding);\r\n\r\nTo close the file object, we can write:\r\n\r\n\tpromiseForCompletion = file.close();\r\n\r\nWe can also use file.writeSync and file.closeSync for the synchronous versions of these\r\nfunctions.\r\n\r\nThe file object is also a lazy array, which means you can read from the file using \r\nstandard array methods. To asynchronously read the contents of a file, you can do:\r\n \r\n\tfile.forEach(function(chunk){\r\n\t\t// called for each chunk of the file until the end of the file is reached.\r\n\t});\r\n\r\n# lazy-array\r\n\r\nThe lazy-array module provides the functionality for creating and using lazy arrays,\r\nwhich are objects that implement the interface of the standard iterative array methods for accessing\r\nstreams of data. Array methods can be called and they will be\r\nasynchronously executed as data is available. Lazy arrays are powerful way to model\r\nasynchronous streams since they can used like other JavaScript arrays.\r\n\r\nTypically you don't need to directly use this module, rather other IO modules like the \r\nfile system (fs) and HTTP (http-client) modules provide lazy arrays that you can interact\r\nwith. For example, we could search through a file for the string \"lazy\" and stop reading\r\nonce we find it using the standard some() method:\r\n\r\n\tif(file.some(function(chunk){\r\n\t\treturn chunk.toString().indexOf(\"lazy\") > -1;\r\n\t}));\r\n\r\nLazy arrays include the follow standard array methods, providing access to the data\r\nas the stream data becomes available:\r\n\r\n* forEach\r\n* concat\r\n\r\nAdditional iterative methods can also access data as it available *and* as it is requested from\r\nthe returned lazy array. This means that in order for this function to be excuted, the\r\nresulting array should have a forEach (or any of the other standard methods) called on \r\nit to trigger the request for data. These methods follow this behavior: \r\n\r\n* filter\r\n* every\r\n* some\r\n* map\r\n\r\nAnd also these standard methods, although these must fully fetch the stream:\r\n\r\n* join\r\n* sort\r\n* reverse\r\n\r\nAlso the following additional methods are available on lazy arrays:\r\n\r\n* toRealArray() - This will fetch all the data and return it as a real JavaScript array.\r\n* get(index) - This retrieves an element by index.\r\n\r\n## LazyArray\r\n\r\n\tlazyArray = require(\"promised-io/lazy-array\").LazyArray({\r\n\t\tsome: someImplementation,\r\n\t\tlength: arrayLength\r\n\t});\r\n\r\nThis function is a constructor for creating your own lazy arrays. With this function,\r\nyou don't need to implement the entire set of array methods, you can just implement\r\nthe some() method and provide an array length, if it is known.\r\n\r\n## first\r\n\r\n\tfirst = require(\"promised-io/lazy-array\").first(lazyArray);\r\n\t\r\nThis function returns the first element in a lazy array.\r\n\r\n## last\r\n\r\n\tlast = require(\"promised-io/lazy-array\").last(lazyArray);\r\n\t\r\nThis function returns the last element in a lazy array.\r\n\r\n## get\r\n\r\n\titem = require(\"promised-io/lazy-array\").get(index);\r\n\t\r\nThis function returns the an element by index from a lazy array.\r\n\r\n# http-client\r\n\r\nThis module provides convenient promise-based access to making HTTP requests.\r\n\r\nPromised-IO is part of the Persevere project, and therefore is licensed under the\r\nAFL or BSD license. The Persevere project is administered under the Dojo foundation,\r\nand all contributions require a Dojo CLA.",
"readmeFilename": "README.md",
"bugs": {
"url": "https://github.com/kriszyp/promised-io/issues"
},
"_id": "promised-io@0.3.4",
"dist": {
"shasum": "d503fb68c16b3c9c3db2619e8c128a52db4bb859"
},
"_from": "promised-io@0.3.x",
"_resolved": "https://registry.npmjs.org/promised-io/-/promised-io-0.3.4.tgz"
}