using ZenFulcrum.EmbeddedBrowser.Promises; using System; using System.Collections; using System.Collections.Generic; using System.Linq; using System.Text; namespace ZenFulcrum.EmbeddedBrowser { /// /// Implements a C# promise. /// https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise /// /// This can also be waited on in a Unity coroutine and queried for its value. /// 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); /// /// Return a new promise with a different value. /// May also change the type of the value. /// IPromise Then(Func transform); /// /// Return a new promise with a different value. /// May also change the type of the value. /// [Obsolete("Use Then instead")] IPromise Transform(Func transform); /// /// Chain an enumerable of promises, all of which must resolve. /// Returns a promise for a collection of the resolved results. /// 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); /// /// Takes a function that yields an enumerable of promises. /// Returns a promise that resolves when the first of the promises has resolved. /// Yields the value from the first promise that has resolved. /// IPromise ThenRace(Func>> chain); /// /// Takes a function that yields an enumerable of promises. /// Converts to a non-value promise. /// Returns a promise that resolves when the first of the promises has resolved. /// Yields the value from the first promise that has resolved. /// IPromise ThenRace(Func> chain); /// /// Returns the resulting value if resolved. /// Throws the rejection if rejected. /// Throws an exception if not settled. /// PromisedT Value { get; } /// /// 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()" /// Once it finishes, use promise.Value to retrieve the value/error. /// /// If throwOnFail is true, the coroutine will abort on promise rejection. /// /// IEnumerator ToWaitFor(bool abortOnFail = false); } /// /// Interface for a promise that can be rejected. /// public interface IRejectable { /// /// Reject the promise with an exception. /// void Reject(Exception ex); } /// /// Interface for a promise that can be rejected or resolved. /// public interface IPendingPromise : IRejectable { /// /// Resolve the promise with a particular value. /// void Resolve(PromisedT value); } /// /// Specifies the state of a promise. /// public enum PromiseState { Pending, // The promise is in-flight. Rejected, // The promise has been rejected. Resolved // The promise has been resolved. }; /// /// Implements a C# promise. /// https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise /// public class Promise : IPromise, IPendingPromise, IPromiseInfo { /// /// The exception when the promise is rejected. /// private Exception rejectionException; /// /// The value when the promises is resolved. /// private PromisedT resolveValue; /// /// Error handler. /// private List rejectHandlers; /// /// Completed handlers that accept a value. /// private List> resolveCallbacks; private List resolveRejectables; /// /// 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; this.Id = ++Promise.nextPromiseId; if (Promise.EnablePromiseTracking) { Promise.pendingPromises.Add(this); } } public Promise(Action, Action> resolver) { this.CurState = PromiseState.Pending; this.Id = ++Promise.nextPromiseId; if (Promise.EnablePromiseTracking) { Promise.pendingPromises.Add(this); } try { resolver( // Resolve value => Resolve(value), // 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 (resolveCallbacks == null) { resolveCallbacks = new List>(); } if (resolveRejectables == null) { resolveRejectables = new List(); } resolveCallbacks.Add(onResolved); resolveRejectables.Add(rejectable); } /// /// Invoke a single handler. /// private void InvokeHandler(Action callback, IRejectable rejectable, T value) { // Argument.NotNull(() => callback); // Argument.NotNull(() => rejectable); try { callback(value); } catch (Exception ex) { rejectable.Reject(ex); } } /// /// Helper function clear out all handlers after resolution or rejection. /// private void ClearHandlers() { rejectHandlers = null; resolveCallbacks = null; resolveRejectables = null; } /// /// Invoke all reject handlers. /// private void InvokeRejectHandlers(Exception ex) { // Argument.NotNull(() => ex); if (rejectHandlers != null) { rejectHandlers.Each(handler => InvokeHandler(handler.callback, handler.rejectable, ex)); } ClearHandlers(); } /// /// Invoke all resolve handlers. /// private void InvokeResolveHandlers(PromisedT value) { if (resolveCallbacks != null) { for (int i = 0, maxI = resolveCallbacks.Count; i < maxI; i++) { InvokeHandler(resolveCallbacks[i], resolveRejectables[i], value); } } 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 (Promise.EnablePromiseTracking) { Promise.pendingPromises.Remove(this); } InvokeRejectHandlers(ex); } /// /// Resolve the promise with a particular value. /// public void Resolve(PromisedT value) { 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); } resolveValue = value; CurState = PromiseState.Resolved; if (Promise.EnablePromiseTracking) { Promise.pendingPromises.Remove(this); } InvokeResolveHandlers(value); } /// /// 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 default 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 = v => { resultPromise.Resolve(v); }; 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 = v => { onResolved(v) .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 = v => { if (onResolved != null) { onResolved(v) .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 = v => { if (onResolved != null) { onResolved(v); } resultPromise.Resolve(v); }; Action rejectHandler = ex => { if (onRejected != null) { onRejected(ex); } resultPromise.Reject(ex); }; ActionHandlers(resultPromise, resolveHandler, rejectHandler); return resultPromise; } /// /// Return a new promise with a different value. /// May also change the type of the value. /// public IPromise Then(Func transform) { // Argument.NotNull(() => transform); return Then(value => Promise.Resolved(transform(value))); } /// /// Return a new promise with a different value. /// May also change the type of the value. /// [Obsolete("Use Then instead")] public IPromise Transform(Func transform) { // Argument.NotNull(() => transform); return Then(value => Promise.Resolved(transform(value))); } /// /// Helper function to invoke or register resolve/reject handlers. /// private void ActionHandlers(IRejectable resultPromise, Action resolveHandler, Action rejectHandler) { if (CurState == PromiseState.Resolved) { InvokeHandler(resolveHandler, resultPromise, resolveValue); } else if (CurState == PromiseState.Rejected) { InvokeHandler(rejectHandler, resultPromise, rejectionException); } else { AddResolveHandler(resolveHandler, resultPromise); AddRejectHandler(rejectHandler, resultPromise); } } /// /// Chain an enumerable of promises, all of which must resolve. /// Returns a promise for a collection of the resolved results. /// 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(value => Promise.All(chain(value))); } /// /// 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(value => Promise.All(chain(value))); } /// /// 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(EnumerableExt.Empty()); } var remainingCount = promisesArray.Length; var results = new PromisedT[remainingCount]; 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(result => { results[index] = result; --remainingCount; if (remainingCount <= 0) { // This will never happen if any of the promises errorred. resultPromise.Resolve(results); } }) .Done(); }); return resultPromise; } /// /// Takes a function that yields an enumerable of promises. /// Returns a promise that resolves when the first of the promises has resolved. /// Yields the value from the first promise that has resolved. /// public IPromise ThenRace(Func>> chain) { return Then(value => Promise.Race(chain(value))); } /// /// Takes a function that yields an enumerable of promises. /// Converts to a non-value promise. /// Returns a promise that resolves when the first of the promises has resolved. /// Yields the value from the first promise that has resolved. /// public IPromise ThenRace(Func> chain) { return Then(value => Promise.Race(chain(value))); } public PromisedT Value { get { if (CurState == PromiseState.Pending) throw new InvalidOperationException("Promise not settled"); else if (CurState == PromiseState.Rejected) throw rejectionException; return resolveValue; } } 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) { var ret = new Enumerated(this, abortOnFail); //someone will poll for completion, so act like we've been terminated Done(x => {}, ex => {}); return ret; } /// /// 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(result => { if (resultPromise.CurState == PromiseState.Pending) { resultPromise.Resolve(result); } }) .Done(); }); return resultPromise; } /// /// Convert a simple value directly into a resolved promise. /// public static IPromise Resolved(PromisedT promisedValue) { var promise = new Promise(); promise.Resolve(promisedValue); 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; } } }