using ZenFulcrum.EmbeddedBrowser.Promises; using System; using System.Collections; using System.Collections.Generic; using System.Linq; using System.Text; namespace ZenFulcrum.EmbeddedBrowser { /// /// Implements a non-generic C# promise, this is a promise that simply resolves without delivering a value. /// https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise /// /// This can also be waited on in a Unity coroutine. /// public interface IPromise { /// /// Set the name of the promise, useful for debugging. /// IPromise WithName(string name); /// /// Completes the promise. /// onResolved is called on successful completion. /// onRejected is called on error. /// void Done(Action onResolved, Action onRejected); /// /// Completes the promise. /// onResolved is called on successful completion. /// Adds a default error handler. /// void Done(Action onResolved); /// /// Complete the promise. Adds a default error handler. /// void Done(); /// /// Handle errors for the promise. /// IPromise Catch(Action onRejected); /// /// Add a resolved callback that chains a value promise (optionally converting to a different value type). /// IPromise Then(Func> onResolved); /// /// Add a resolved callback that chains a non-value promise. /// IPromise Then(Func onResolved); /// /// Add a resolved callback. /// IPromise Then(Action onResolved); /// /// Add a resolved callback and a rejected callback. /// The resolved callback chains a value promise (optionally converting to a different value type). /// IPromise Then(Func> onResolved, Action onRejected); /// /// Add a resolved callback and a rejected callback. /// The resolved callback chains a non-value promise. /// IPromise Then(Func onResolved, Action onRejected); /// /// Add a resolved callback and a rejected callback. /// IPromise Then(Action onResolved, Action onRejected); /// /// Chain an enumerable of promises, all of which must resolve. /// The resulting promise is resolved when all of the promises have resolved. /// It is rejected as soon as any of the promises have been rejected. /// IPromise ThenAll(Func> chain); /// /// Chain an enumerable of promises, all of which must resolve. /// Converts to a non-value promise. /// The resulting promise is resolved when all of the promises have resolved. /// It is rejected as soon as any of the promises have been rejected. /// IPromise> ThenAll(Func>> chain); /// /// Chain a sequence of operations using promises. /// Reutrn a collection of functions each of which starts an async operation and yields a promise. /// Each function will be called and each promise resolved in turn. /// The resulting promise is resolved after each promise is resolved in sequence. /// IPromise ThenSequence(Func>> chain); /// /// Takes a function that yields an enumerable of promises. /// Returns a promise that resolves when the first of the promises has resolved. /// IPromise ThenRace(Func> chain); /// /// Takes a function that yields an enumerable of promises. /// Converts to a value promise. /// Returns a promise that resolves when the first of the promises has resolved. /// IPromise ThenRace(Func>> chain); /// /// Returns an enumerable that yields null until the promise is settled. /// ("To WaitFor" like the WaitForXXYY functions Unity provides.) /// Suitable for use with a Unity coroutine's "yield return promise.ToWaitFor()" /// /// If throwOnFail is true, the coroutine will abort on promise rejection. /// /// IEnumerator ToWaitFor(bool abortOnFail = false); } /// /// Interface for a promise that can be rejected or resolved. /// public interface IPendingPromise : IRejectable { /// /// Resolve the promise with a particular value. /// void Resolve(); } /// /// Used to list information of pending promises. /// public interface IPromiseInfo { /// /// Id of the promise. /// int Id { get; } /// /// Human-readable name for the promise. /// string Name { get; } } /// /// Arguments to the UnhandledError event. /// public class ExceptionEventArgs : EventArgs { internal ExceptionEventArgs(Exception exception) { // Argument.NotNull(() => exception); this.Exception = exception; } public Exception Exception { get; private set; } } /// /// Represents a handler invoked when the promise is rejected. /// public struct RejectHandler { /// /// Callback fn. /// public Action callback; /// /// The promise that is rejected when there is an error while invoking the handler. /// public IRejectable rejectable; } /// /// Implements a non-generic C# promise, this is a promise that simply resolves without delivering a value. /// https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise /// public class Promise : IPromise, IPendingPromise, IPromiseInfo { static Promise() { UnhandledException += (sender, args) => { UnityEngine.Debug.LogWarning("Rejection: " + args.Exception.Message + "\n" + args.Exception.StackTrace); }; } /// /// Set to true to enable tracking of promises. /// public static bool EnablePromiseTracking = false; /// /// Event raised for unhandled errors. /// For this to work you have to complete your promises with a call to Done(). /// public static event EventHandler UnhandledException { add { unhandlerException += value; } remove { unhandlerException -= value; } } private static EventHandler unhandlerException; /// /// Id for the next promise that is created. /// internal static int nextPromiseId = 0; /// /// Information about pending promises. /// internal static HashSet pendingPromises = new HashSet(); /// /// Information about pending promises, useful for debugging. /// This is only populated when 'EnablePromiseTracking' is set to true. /// public static IEnumerable GetPendingPromises() { return pendingPromises; } /// /// The exception when the promise is rejected. /// private Exception rejectionException; /// /// Error handlers. /// private List rejectHandlers; /// /// Represents a handler invoked when the promise is resolved. /// public struct ResolveHandler { /// /// Callback fn. /// public Action callback; /// /// The promise that is rejected when there is an error while invoking the handler. /// public IRejectable rejectable; } /// /// Completed handlers that accept no value. /// private List resolveHandlers; /// /// ID of the promise, useful for debugging. /// public int Id { get; private set; } /// /// Name of the promise, when set, useful for debugging. /// public string Name { get; private set; } /// /// Tracks the current state of the promise. /// public PromiseState CurState { get; private set; } public Promise() { this.CurState = PromiseState.Pending; if (EnablePromiseTracking) { pendingPromises.Add(this); } } public Promise(Action> resolver) { this.CurState = PromiseState.Pending; if (EnablePromiseTracking) { pendingPromises.Add(this); } try { resolver( // Resolve () => Resolve(), // Reject ex => Reject(ex) ); } catch (Exception ex) { Reject(ex); } } /// /// Add a rejection handler for this promise. /// private void AddRejectHandler(Action onRejected, IRejectable rejectable) { if (rejectHandlers == null) { rejectHandlers = new List(); } rejectHandlers.Add(new RejectHandler() { callback = onRejected, rejectable = rejectable }); } /// /// Add a resolve handler for this promise. /// private void AddResolveHandler(Action onResolved, IRejectable rejectable) { if (resolveHandlers == null) { resolveHandlers = new List(); } resolveHandlers.Add(new ResolveHandler() { callback = onResolved, rejectable = rejectable }); } /// /// Invoke a single error handler. /// private void InvokeRejectHandler(Action callback, IRejectable rejectable, Exception value) { // Argument.NotNull(() => callback); // Argument.NotNull(() => rejectable); try { callback(value); } catch (Exception ex) { rejectable.Reject(ex); } } /// /// Invoke a single resolve handler. /// private void InvokeResolveHandler(Action callback, IRejectable rejectable) { // Argument.NotNull(() => callback); // Argument.NotNull(() => rejectable); try { callback(); } catch (Exception ex) { rejectable.Reject(ex); } } /// /// Helper function clear out all handlers after resolution or rejection. /// private void ClearHandlers() { rejectHandlers = null; resolveHandlers = null; } /// /// Invoke all reject handlers. /// private void InvokeRejectHandlers(Exception ex) { // Argument.NotNull(() => ex); if (rejectHandlers != null) { rejectHandlers.Each(handler => InvokeRejectHandler(handler.callback, handler.rejectable, ex)); } ClearHandlers(); } /// /// Invoke all resolve handlers. /// private void InvokeResolveHandlers() { if (resolveHandlers != null) { resolveHandlers.Each(handler => InvokeResolveHandler(handler.callback, handler.rejectable)); } ClearHandlers(); } /// /// Reject the promise with an exception. /// public void Reject(Exception ex) { // Argument.NotNull(() => ex); if (CurState != PromiseState.Pending) { throw new ApplicationException("Attempt to reject a promise that is already in state: " + CurState + ", a promise can only be rejected when it is still in state: " + PromiseState.Pending); } rejectionException = ex; CurState = PromiseState.Rejected; if (EnablePromiseTracking) { pendingPromises.Remove(this); } InvokeRejectHandlers(ex); } /// /// Resolve the promise with a particular value. /// public void Resolve() { if (CurState != PromiseState.Pending) { throw new ApplicationException("Attempt to resolve a promise that is already in state: " + CurState + ", a promise can only be resolved when it is still in state: " + PromiseState.Pending); } CurState = PromiseState.Resolved; if (EnablePromiseTracking) { pendingPromises.Remove(this); } InvokeResolveHandlers(); } /// /// Completes the promise. /// onResolved is called on successful completion. /// onRejected is called on error. /// public void Done(Action onResolved, Action onRejected) { Then(onResolved, onRejected) .Catch(ex => Promise.PropagateUnhandledException(this, ex) ); } /// /// Completes the promise. /// onResolved is called on successful completion. /// Adds a default error handler. /// public void Done(Action onResolved) { Then(onResolved) .Catch(ex => Promise.PropagateUnhandledException(this, ex) ); } /// /// Complete the promise. Adds a defualt error handler. /// public void Done() { Catch(ex => Promise.PropagateUnhandledException(this, ex) ); } /// /// Set the name of the promise, useful for debugging. /// public IPromise WithName(string name) { this.Name = name; return this; } /// /// Handle errors for the promise. /// public IPromise Catch(Action onRejected) { // Argument.NotNull(() => onRejected); var resultPromise = new Promise(); resultPromise.WithName(Name); Action resolveHandler = () => { resultPromise.Resolve(); }; Action rejectHandler = ex => { onRejected(ex); resultPromise.Reject(ex); }; ActionHandlers(resultPromise, resolveHandler, rejectHandler); return resultPromise; } /// /// Add a resolved callback that chains a value promise (optionally converting to a different value type). /// public IPromise Then(Func> onResolved) { return Then(onResolved, null); } /// /// Add a resolved callback that chains a non-value promise. /// public IPromise Then(Func onResolved) { return Then(onResolved, null); } /// /// Add a resolved callback. /// public IPromise Then(Action onResolved) { return Then(onResolved, null); } /// /// Add a resolved callback and a rejected callback. /// The resolved callback chains a value promise (optionally converting to a different value type). /// public IPromise Then(Func> onResolved, Action onRejected) { // This version of the function must supply an onResolved. // Otherwise there is now way to get the converted value to pass to the resulting promise. // Argument.NotNull(() => onResolved); var resultPromise = new Promise(); resultPromise.WithName(Name); Action resolveHandler = () => { onResolved() .Then( // Should not be necessary to specify the arg type on the next line, but Unity (mono) has an internal compiler error otherwise. (ConvertedT chainedValue) => resultPromise.Resolve(chainedValue), ex => resultPromise.Reject(ex) ); }; Action rejectHandler = ex => { if (onRejected != null) { onRejected(ex); } resultPromise.Reject(ex); }; ActionHandlers(resultPromise, resolveHandler, rejectHandler); return resultPromise; } /// /// Add a resolved callback and a rejected callback. /// The resolved callback chains a non-value promise. /// public IPromise Then(Func onResolved, Action onRejected) { var resultPromise = new Promise(); resultPromise.WithName(Name); Action resolveHandler = () => { if (onResolved != null) { onResolved() .Then( () => resultPromise.Resolve(), ex => resultPromise.Reject(ex) ); } else { resultPromise.Resolve(); } }; Action rejectHandler = ex => { if (onRejected != null) { onRejected(ex); } resultPromise.Reject(ex); }; ActionHandlers(resultPromise, resolveHandler, rejectHandler); return resultPromise; } /// /// Add a resolved callback and a rejected callback. /// public IPromise Then(Action onResolved, Action onRejected) { var resultPromise = new Promise(); resultPromise.WithName(Name); Action resolveHandler = () => { if (onResolved != null) { onResolved(); } resultPromise.Resolve(); }; Action rejectHandler = ex => { if (onRejected != null) { onRejected(ex); } resultPromise.Reject(ex); }; ActionHandlers(resultPromise, resolveHandler, rejectHandler); return resultPromise; } /// /// Helper function to invoke or register resolve/reject handlers. /// private void ActionHandlers(IRejectable resultPromise, Action resolveHandler, Action rejectHandler) { if (CurState == PromiseState.Resolved) { InvokeResolveHandler(resolveHandler, resultPromise); } else if (CurState == PromiseState.Rejected) { InvokeRejectHandler(rejectHandler, resultPromise, rejectionException); } else { AddResolveHandler(resolveHandler, resultPromise); AddRejectHandler(rejectHandler, resultPromise); } } /// /// Chain an enumerable of promises, all of which must resolve. /// The resulting promise is resolved when all of the promises have resolved. /// It is rejected as soon as any of the promises have been rejected. /// public IPromise ThenAll(Func> chain) { return Then(() => Promise.All(chain())); } /// /// Chain an enumerable of promises, all of which must resolve. /// Converts to a non-value promise. /// The resulting promise is resolved when all of the promises have resolved. /// It is rejected as soon as any of the promises have been rejected. /// public IPromise> ThenAll(Func>> chain) { return Then(() => Promise.All(chain())); } /// /// Returns a promise that resolves when all of the promises in the enumerable argument have resolved. /// Returns a promise of a collection of the resolved results. /// public static IPromise All(params IPromise[] promises) { return All((IEnumerable)promises); // Cast is required to force use of the other All function. } /// /// Returns a promise that resolves when all of the promises in the enumerable argument have resolved. /// Returns a promise of a collection of the resolved results. /// public static IPromise All(IEnumerable promises) { var promisesArray = promises.ToArray(); if (promisesArray.Length == 0) { return Promise.Resolved(); } var remainingCount = promisesArray.Length; var resultPromise = new Promise(); resultPromise.WithName("All"); promisesArray.Each((promise, index) => { promise .Catch(ex => { if (resultPromise.CurState == PromiseState.Pending) { // If a promise errorred and the result promise is still pending, reject it. resultPromise.Reject(ex); } }) .Then(() => { --remainingCount; if (remainingCount <= 0) { // This will never happen if any of the promises errorred. resultPromise.Resolve(); } }) .Done(); }); return resultPromise; } /// /// Chain a sequence of operations using promises. /// Reutrn a collection of functions each of which starts an async operation and yields a promise. /// Each function will be called and each promise resolved in turn. /// The resulting promise is resolved after each promise is resolved in sequence. /// public IPromise ThenSequence(Func>> chain) { return Then(() => Sequence(chain())); } /// /// Chain a number of operations using promises. /// Takes a number of functions each of which starts an async operation and yields a promise. /// public static IPromise Sequence(params Func[] fns) { return Sequence((IEnumerable>)fns); } /// /// Chain a sequence of operations using promises. /// Takes a collection of functions each of which starts an async operation and yields a promise. /// public static IPromise Sequence(IEnumerable> fns) { return fns.Aggregate( Promise.Resolved(), (prevPromise, fn) => { return prevPromise.Then(() => fn()); } ); } /// /// Takes a function that yields an enumerable of promises. /// Returns a promise that resolves when the first of the promises has resolved. /// public IPromise ThenRace(Func> chain) { return Then(() => Promise.Race(chain())); } /// /// Takes a function that yields an enumerable of promises. /// Converts to a value promise. /// Returns a promise that resolves when the first of the promises has resolved. /// public IPromise ThenRace(Func>> chain) { return Then(() => Promise.Race(chain())); } /// /// Returns a promise that resolves when the first of the promises in the enumerable argument have resolved. /// Returns the value from the first promise that has resolved. /// public static IPromise Race(params IPromise[] promises) { return Race((IEnumerable)promises); // Cast is required to force use of the other function. } /// /// Returns a promise that resolves when the first of the promises in the enumerable argument have resolved. /// Returns the value from the first promise that has resolved. /// public static IPromise Race(IEnumerable promises) { var promisesArray = promises.ToArray(); if (promisesArray.Length == 0) { throw new ApplicationException("At least 1 input promise must be provided for Race"); } var resultPromise = new Promise(); resultPromise.WithName("Race"); promisesArray.Each((promise, index) => { promise .Catch(ex => { if (resultPromise.CurState == PromiseState.Pending) { // If a promise errorred and the result promise is still pending, reject it. resultPromise.Reject(ex); } }) .Then(() => { if (resultPromise.CurState == PromiseState.Pending) { resultPromise.Resolve(); } }) .Done(); }); return resultPromise; } /// /// Convert a simple value directly into a resolved promise. /// public static IPromise Resolved() { var promise = new Promise(); promise.Resolve(); return promise; } /// /// Convert an exception directly into a rejected promise. /// public static IPromise Rejected(Exception ex) { // Argument.NotNull(() => ex); var promise = new Promise(); promise.Reject(ex); return promise; } /// /// Raises the UnhandledException event. /// internal static void PropagateUnhandledException(object sender, Exception ex) { if (unhandlerException != null) { unhandlerException(sender, new ExceptionEventArgs(ex)); } } class Enumerated : IEnumerator { private Promise promise; private bool abortOnFail; public Enumerated(Promise promise, bool abortOnFail) { this.promise = promise; this.abortOnFail = abortOnFail; } public bool MoveNext() { if (abortOnFail && promise.CurState == PromiseState.Rejected) { throw promise.rejectionException; } return promise.CurState == PromiseState.Pending; } public void Reset() { } public object Current { get { return null; } } } public IEnumerator ToWaitFor(bool abortOnFail = false) { var ret = new Enumerated(this, abortOnFail); //someone will poll for completion, so act like we've been terminated Done(() => {}, ex => {}); return ret; } } }