yipromise

#YPromise

基于 Common JS Promises/A 建议的js异步编程库，提供一种Promise机制来管理js中的异步交互。

##使用

function fun3(){
     return new YPro(function(comp,err){
        setTimeout(function(){
             comp('fun3 done');
        },3000);
     })
}
function fun4(){
     return new YPro(function(comp,err){
        setTimeout(function(){
             comp('fun4 done');
        },1000);
     })
}
var aPromise = fun3()
				.then(function(d){console.log(d); return fun4();})
				.then(function(){return fun3();})
				.then(function(){return fun4();})
				.done(function(){
					console.log("fun3->fun4->fun3->fun4 done");
				})

setTimeout(function(){
	aPromise.cancel(function(){
		console.log("Promise canceled");
	});
},9000);

##API 如果你以前使用过window8开发中的WinJS.promise对象，你可以快速上手。

###YPro(Function) or YPromise(Function) 构造器 初始化一个promise对象,其中YPro提供一个对YPromise的简洁访问

var aPromise = new YPromise(init);

init方法中可传入三个参数，后面两个为可选

• completeDispatch 初始化代码中操作完成后需要调用这个函数传递结果
• errorDispatch 当发生错误时需要调用这方法传递错误
• progressDispatch 如果异步操作需要支持进度条，初始化代码应该定期调用这个功能，并传递一个进度中间值

你需要使用这个返回一个promise对象来包裹你的异步函数

/*example for constructor*/

function fn1(){
	return new YPro(function(comp,err,prog){
		var i = 0;
		function sleep(){
			i++;
			if(i>100){
				comp('fun1 done');
			}else{
				prog(i);
				setTimeout(function(){
					sleep();
				},100);
			}			
		}
		sleep();
	});
}

###.then

指定promise完成后执行的函数，如果promise未完成则进行错误处理，以及处理进度变化通知

YPro.then(onComplete, onError, onProgress).done();

参数:

• onComplete promise成功后将会执行此方法，参数来自构造函数中的 completeDispatch 传递
• onError promise发生错误将会调用此方法
• onProgress 如果promise函数中有来自 progressDispatch 调用将会触发此方法

返回： 该方法将会返回一个 YPromise 对象

var PromiseA = fun1()
	.then(
		function(data){
			console.log(data);
		},
		function(error){
			console.error(error);
		},
		function(prog){
			console.log(prog+"%");
		}
	);

###.done (待完善) 提供和then一样的作用，此方法不会传递错误值，将会把异常直接抛出

YPro.done(omComplete);

###YPromise.join

合并多个promise，当所有Promise完成后将会执行then方法，返回对应位置promise的返回，若promise返回参数多于一个，将会以数组的形式传递返回。

YPro.join(promise1,promise2,...).then(onComplete);

参数： 一个或多个YPromsie对象

返回：该方法将会返回一个YPromise对象

var PromiseAll = YPro.join(fn1(),fn2())
			.then(function(data1,data2){
				console.log(data1,data2);
			})

###YPromise.queue 执行一个返回Ypromise的队列方法

 YPromise.queue(array,isOrder).then()

该方法传入两个参数，第二个参数为可选

• array 一个待执行包含返回promise对象的function数组
• isOrder 默认false，若为true，将会按顺序执行array队列中的方法，且设置为true后，将会把单个方法错误信息放到onComplete回调中

返回，该方法返回一个 Ypromise 对象

javascript var args = []; for(var i=0;i<50; i++){ args.push(i); }

var taskList = args.map(function(arg){ return function(){ return new YPro(function(comp,err,prog){ setTimeout(function(){ console.log('in function',arg); comp('callback '+arg); },300); }); }; });

YPro.queue(taskList) .then(function(){ cosole.log(arguments); return YPro.queue(taskList,true); }) .then(function(){ console.log(arguments); });

###`YPromise.any`
用法类似`YPromise.join`,但不需要等待所有proimise完成，一旦其中任意一个promise完成将会立即传递这个promise的返回值。
<pre>
YPro.any(promise1,promise2,…).then(onComplete);
</pre>

返回，该方法返回一个`YPromise`对象

<pre>
var PromiseAny = YPro.join(fn1(),fn2())
			.then(function(data){
				console.log(data);
			});
</pre>

###`YPromise.as`
此方法将会把同步方法以Promise的方式调用,以解决特殊时候需求

<pre>
YPro.as(Function).then(onComplete);
</pre>

返回：该方法将会返回一个`YPromise`对象

<pre>
function fn5(){
	return 'function 5 done';
}
var PromiseAs = YPro.as(fn5())
			.then(function(data){
				console.log(data);
			});

</pre>

###`YPromise.cancel`
调用该方法将会取消promise链的向下执行
<pre>
YPromsise.cancel();
</pre>

***
更多用法请参考/example例子