#context-block Contextualized promise blocks by name and symbol. Supports async, promises, generators, and manual reject/resolve.

###What/Why? context-block is intended to assist in managing promises and asynchronous behaviors.

Imagine you want to update a UI based on the result of a service request - or multiple service requests without blocking user input. Maybe you are writing server logic and you want to ensure that you avoid sending multiple of database lookups simultaneously.

Context-block provides a developer friendly syntax that will ensure multiple of the same asynchronous activities are not occurring.

###Install

npm install --save-dev context-block

API Reference

• Block
• Context
• ReverseContext

• Blocks are segments of code associated with a name. Blocks can either be Forward or Reverse. Forward blocks ALWAYS execute the latest code segment. Reverse blocks only execute the latest code segment if one is not already scheduled to run.

  Blocks return Contexts or ReverseContexts (which extend Promise) and associate the behavior of an asynchronous action with a name. A name can be either string or symbol, allowing asynchronous behaviors to be managed at various hierarchies (component vs global levels). Blocks also support a tagged literal format to help differentiate Blocks from other code (example)

  There are three forward and reverse block behavior functions defined.

  • block.dismiss(name[,fn,delay]) Returns a Context for name and executes fn. If another block of the same name is created, the returned Context will be dismissed (rejected).
  • block.stop(name[,fn,delay])Returns a Context for name and executes fn. If another block of the same name is created, the returned Context will NOT be resolved or rejected.
  • block.join(name[,fn,delay]) Returns a Context for name and executes fn. If another block of the same name is created, the returned Context will resolve/reject with the result of the new block.
  • block.reverse.dismiss(name[,fn,delay])Returns a ReverseContext for name and only executes fn if another block of the same name is not already scheduled to activate. If another block already exists, the returned ReverseContext will be automatically dismissed.
  • block.reverse.stop(name[,fn,delay])Returns a ReverseContext for name and only executes fn if another block of the same name is not already scheduled to activate. If another block already exists, the returned ReverseContext will not resolve or reject
  • block.reverse.join(name[,fn,delay])Returns a ReverseContext for name and only executes fn if another block of the same name is not already scheduled to activate. If another block already exists, the returned ReverseContext will resolve or reject with the result of the existing block. Additionally, if a block of the same name is created, the returned ReverseContext will resolve/reject with the result of the new block

  Blocks accept the following arguments:

• Contexts are the returned value from a Block and are not intended to be constructed directly. Contexts extend from promises and integrate Promise functionality such as Promise.all, Promise.race (example) and much more!

  The premise behind Contexts are that multiple contexts can potentially exist for a given Block name. However, each context decides how to act in the event multiple Contexts of the same name are created. Context actions include:

  • dismiss Rejects if another Context of the same name is created
  • stop Does not resolve or reject if another Context of the same name is created
  • join Resolves or rejects with the latest result

• ReverseContexts take Contexts a step further by deciding the action if a Block already exists.

  ReverseContexts work under the premise that priority lies with an earlier Context, which naturally changes the meaning of dismiss, stop, and join:

###Examples

const block = require('context-block');

//tagged literal block with unspecified dismiss,stop,join defaults to dismiss.
block `test` (({reject,resolve})=>{
	//never called
}).then(()=>{
	//never called
}).catch((v)=>{
	console.error(v); // "dismissed"
});

//tagged literal block with specified method
//context will be dismissed as another context will activate with the same name
block.dismiss `test` (()=>{
	return new Promise((resolve,reject)=>{
		resolve('hello world');
	});
}).catch ((v)=>{
	console.error(v); //v is "dismissed"
}); 

//untagged equivalents for reference
//another context of the same is defined again, so nothing nothing will get called
block.stop('test',({reject,resolve})=> {
	//never called
}).catch((v)=>{
    	//never called
});

//join context will result in "world" because the last context resolves "world"
block('test').join(({reject,resolve})=>{
	resolve('hello');
}).then((v)=>{
    	console.error(v); //v is "world"
});

block.join `test` (({reject,resolve})=>{
	resolve('world');
}).then((v)=>{
    	console.error(v); //v is "world"
});

OUTPUT:
dismissed
dismissed
world
world

block.dismiss `test` (new Promise((resolve,reject)=>{
	resolve('hi');
})).then((v)=>{
	console.error(v); //v is "hi"
});


OUTPUT:
hi

//note the es6 destructure syntax
//if you specify resolve, reject arguments, you must resolve the context using them!!!
block `test` (({resolve,reject})=>{
	resolve(1);
}).then((v)=>{
	console.error(v); //v is 1
});

OUTPUT:
1

block `test` (()=>{
	return new Promise((resolve,reject)=>{
		resolve(2);
	});
}).then((v)=>{
	console.error(v); //v is 2
});

OUTPUT:
1

async function getSomething () {
	return new Promise((resolve,reject)=>{
		resolve('banana');
	});
}
block `test` (async ()=>{
	return await getSomething('for my monkey');
}).then((v)=>{
	console.error(v); //v is "banana"
});

OUTPUT:
banana

block `test` (function * () {
	yield new Promise((resolve,reject)=>{
		setTimeout(()=>resolve(1),20)
	});
	yield 2;
	yield new Promise((resolve,reject)=>{
		resolve(3);
	});
	return 4
}).then((v)=>{
	console.error(v); //v is [1,2,3,4]
});

OUTPUT:
1,2,3,4

Promise.all([
	block `test1` (({resolve,reject})=>{resolve(1);}),
	block `test2` (({resolve,reject})=>{resolve(2);})
]).then((v)=>{
	console.log(v);
});


OUTPUT:
1,2

------------

Promise.race([
	block `test1` (({resolve,reject})=>{resolve(1);}),
	block `test2` (({resolve,reject})=>{setTimeout(()=>resolve(2));})
]).then((v)=>{
	console.log(v);
});


OUTPUT:
1