# promise-value

A tiny wrapper for Promise to carry a promise and (if known) a value, plus a resolved flag.

This makes it easy to bridge between async promise-based code, and single-thread code.

Use-cases: e.g. within a React render() function.

### Example code

	import PromiseValue from 'promise-value';

	// Make from a promise, e.g. an ajax call
	let pvAjax = new PromiseValue($.get("https://bbc.co.uk"));
	
	console.log(pvAjax.resolved, " = false");

	// You can add a then() handler
	pvAjax.promise.then(function(result) {
		console.log("Web-page get promise resolved", result);
	});

	// Error handling? just check pvAjax.error

	// Or you can make a PromiseValue directly from a value
	let pvInstant = new PromiseValue("hello");
	
	console.log(pvInstant.resolved, " = true");
	
	// once a promise resolves, you can get the value. Until then value is null.
	console.log(pvInstant.value);

	pvInstant.promise.then(function(result) {
		console.log("Instant Promise resolved to: "+result);
	});


### React Example: Using PromiseValue to manage web requests inside a render function

	import React, {useState} from 'react';
	import PromiseValue from 'promise-value';
	import $ from 'jquery';

	const MyAjaxWidget = () => {
		// What is the state?
		let [pvMyAjaxData, setpvMyAjaxData] = useState();
		// Hack: a dummy state var to trigger a react update
		let [dummy, setDummy] = useState();
		if ( ! pvMyAjaxData) {
			// Start the ajax call
			const pAjax = $.get("https://mysite.com/endpoint?foo=blah");		
			pvMyAjaxData = new PromiseValue(pAjax);
			setpvMyAjaxData(pvMyAjaxData); // Update the state, so we won't keep calling the server
			// trigger a react render when the response comes back (inc on error)
			pAjax.then(() => setDummy(":)"), () => setDummy(":("));
		}
		// Has the web request come back?
		if ( ! pvMyAjaxData.resolved) {
			// ...no -- return a spinner
			return <div className='spinner'>Loading...</div>;
		}
		// Error handling
		if (pvMyAjaxData.error) return <div>Web Request Failed :( {JSON.stringify(pvMyAjaxData.error)}</div>;
		// yes! We have data
		return <div>Lovely data! {JSON.stringify(pvMyAjaxData.value)}</div>;
	};

## Documentation

	class PromiseValue {
		/** @type {!Promise} */
		promise;
		/** @type {!boolean} */
		resolved;
		/** @type {?Object} */
		value;
		/** @type {?Error} */
		error;
	}

Call it like this: `new PromiseValue(x)` where `x` can be a Promise or a value.

The promise part of a PromiseValue is always set. The behaviour depends on the input `x`:

 - If it's a value -> you'll have a resolved Promise
 - If it's a Promise (or thenable) -> the input Promise
 - null/undefined -> rejected Promise

The `value` and `error` properties will be set instantly if known, and otherwise auto-set when the promise resolves.
The `resolved` flag records the promise status, and changes to true once the promise is resolved.