Promise

public struct Promise<Value, Error>

extension Promise: Equatable

A Promise is a construct that will eventually hold a value or error, and can invoke callbacks when that happens.

Example usage:

Promise(on: .utility) { resolver in
    let value = try someLongComputation()
    resolver.fulfill(with: value)
}.then(on: main) { value in
    self.updateUI(with: value)
}.catch(on: .main) { error in
    self.handleError(error)
}

Promises can also be cancelled. With a Promise object you can invoke .requestCancel(), which is merely advisory; the promise does not have to actually implement cancellation and may resolve anyway. But if a promise does implement cancellation, it can then call resolver.cancel(). Note that even if the promise supports cancellation, calling .requestCancel() on an unresolved promise does not guarantee that it will cancel, as the promise may be in the process of resolving when that method is invoked. Make sure to use the invalidation token support if you need to ensure your registered callbacks aren’t invoked past a certain point.

Note

If a registered callback is invoked (or would have been invoked if no token was provided) it is guaranteed to be released on the context. This is important if the callback captures a value whose deallocation must occur on a specific thread (such as the main thread). If the callback is not invoked (ignoring tokens) it will be released on whatever thread the promise was resolved on. For example, if a promise is fulfilled, any callback registered with .then(on:token:_:) will be released on the context, but callbacks registered with .catch(on:token:_:) will not. If you need to guarantee the thread that the callback is released on, you should use .always(on:token:_:) or one of the .mapResult(on:token:_:) variants.

Resolver
A Resolver is used to fulfill, reject, or cancel its associated Promise.
See more
Declaration
Swift

public struct Resolver
result
Returns the result of the promise.

Once this value becomes non-nil it will never change.
Declaration
Swift

public var result: PromiseResult<Value, Error>? { get }
makeWithResolver()
Returns a Promise and a Promise.Resolver that can be used to fulfill that promise.

Note
In most cases you want to use Promise(on:_:) instead.
Declaration
Swift

public static func makeWithResolver() -> (Promise<Value, Error>, Promise<Value, Error>.Resolver)


                    
                    
                    init(on:_:)

Returns a new Promise that will be resolved using the given block.

Declaration

Swift

public init(on context: PromiseContext, _ handler: @escaping (_ resolver: Resolver) -> Void)

Parameters

`context`	The context to execute the handler on.
`handler`	A block that is executed in order to fulfill the promise.
`resolver`	The `Resolver` used to resolve the promise.

init(fulfilled:)
Returns a Promise that is already fulfilled with the given value.
Declaration
Swift

public init(fulfilled value: Value)
init(rejected:)
Returns a Promise that is already rejected with the given error.
Declaration
Swift

public init(rejected error: Error)
init(with:)
Returns a Promise that is already resolved with the given result.
Declaration
Swift

public init(with result: PromiseResult<Value, Error>)


                    
                    
                    then(on:token:_:)

Registers a callback that is invoked when the promise is fulfilled.

Declaration

Swift

public func then(on context: PromiseContext = .auto, token: PromiseInvalidationToken? = nil, _ onSuccess: @escaping (Value) -> Void) -> Promise<Value, Error>

Parameters

`context`	The context to invoke the callback on. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onSuccess` from being invoked.
`onSuccess`	The callback that is invoked with the fulfilled value.

Return Value

A new promise that will resolve to the same value as the receiver. You may safely ignore this value.


                    
                    
                    map(on:token:_:)

Registers a callback that is invoked when the promise is fulfilled.

Declaration

Swift

public func map<U>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onSuccess: @escaping (Value) -> U) -> Promise<U, Error>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onSuccess` from being invoked. If the promise is fulfilled and the token is invalidated, the returned promise will be cancelled.
`onSuccess`	The callback that is invoked with the fulfilled value.

Return Value

A new promise that will be fulfilled with the return value of onSuccess. If the receiver is rejected or cancelled, the returned promise will also be rejected or cancelled.


                    
                    
                    flatMap(on:token:_:)

Registers a callback that is invoked when the promise is fulfilled.

Declaration

Swift

public func flatMap<U>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onSuccess: @escaping (Value) -> Promise<U, Error>) -> Promise<U, Error>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onSuccess` from being invoked. If the promise is fulfilled and the token is invalidated, the returned promise will be cancelled.
`onSuccess`	The callback that is invoked with the fulfilled value.

Return Value

A new promise that will be eventually resolved using the promise returned from onSuccess. If the receiver is rejected or cancelled, the returned promise will also be rejected or cancelled.


                    
                    
                    catch(on:token:_:)

Registers a callback that is invoked when the promise is rejected.

This method (or always) should be used to terminate a promise chain.

Declaration

Swift

@discardableResult
public func `catch`(on context: PromiseContext = .auto, token: PromiseInvalidationToken? = nil, _ onError: @escaping (Error) -> Void) -> Promise<Value, Error>

Parameters

`context`	The context to invoke the callback on. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onError` from being invoked.
`onError`	The callback that is invoked with the rejected error.

Return Value

A new promise that will resolve to the same value as the receiver. You may safely ignore this value.


                    
                    
                    recover(on:token:_:)

Declaration

Swift

public func recover(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onError: @escaping (Error) -> Value) -> Promise<Value, NoError>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onError` from being invoked. If the promise is rejected and the token is invalidated, the returned promise will be cancelled.
`onError`	The callback that is invoked with the rejected error.

Return Value

A new promise that will be fulfilled with the return value of onError. If the receiver is fulfilled or cancelled, the returned promise will also be fulfilled or cancelled.


                    
                    
                    mapError(on:token:_:)

Declaration

Swift

public func mapError<E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onError: @escaping (Error) -> E) -> Promise<Value, E>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onError` from being invoked. If the promise is rejected and the token is invalidated, the returned promise will be cancelled.
`onError`	The callback that is invoked with the rejected error.

Return Value

A new promise that will be rejected with the return value of onError. If the receiver is fulfilled or cancelled, the returned promise will also be fulfilled or cancelled.


                    
                    
                    flatMapError(on:token:_:)

Declaration

Swift

public func flatMapError<E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onError: @escaping (Error) -> Promise<Value, E>) -> Promise<Value, E>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onError` from being invoked. If the promise is rejected and the token is invalidated, the returned promise will be cancelled.
`onError`	The callback that is invoked with the rejected error.

Return Value

A new promise that will be eventually resolved using the promise returned from onError. If the receiver is fulfilled or cancelled, the returned promise will also be fulfilled or cancelled.


                    
                    
                    tryMapError(on:token:_:)

Declaration

Swift

public func tryMapError<E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onError: @escaping (Error) throws -> E) -> Promise<Value, Swift.Error> where E : Error

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onError` from being invoked. If the promise is rejected and the token is invalidated, the returned promise will be cancelled.
`onError`	The callback that is invoked with the rejected error.

Return Value

A new promise that will be rejected with the return value of onError, or is rejected if onError throws an error. If the receiver is fulfilled or cancelled, the returned promise will also be fulfilled or cancelled.


                    
                    
                    tryFlatMapError(on:token:_:)

Declaration

Swift

public func tryFlatMapError<E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onError: @escaping (Error) throws -> Promise<Value, E>) -> Promise<Value, Swift.Error> where E : Error

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onError` from being invoked. If the promise is rejected and the token is invalidated, the returned promise will be cancelled.
`onError`	The callback that is invoked with the rejected error.

Return Value

A new promise that will be eventually resolved using the promise returned from onError, or is rejected if onError throws an error. If the receiver is fulfilled or cancelled, the returned promise will also be fulfilled or cancelled.

tryMapError(on:token:_:)
tryFlatMapError(on:token:_:)


                    
                    
                    always(on:token:_:)

Registers a callback that will be invoked with the promise result, no matter what it is.

Declaration

Swift

@discardableResult
public func always(on context: PromiseContext = .auto, token: PromiseInvalidationToken? = nil, _ onComplete: @escaping (PromiseResult<Value, Error>) -> Void) -> Promise<Value, Error>

Parameters

`context`	The context to invoke the callback on. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onComplete` from being invoked.
`onComplete`	The callback that is invoked with the promise’s value.

Return Value

A new promise that will resolve to the same value as the receiver. You may safely ignore this value.


                    
                    
                    mapResult(on:token:_:)

Registers a callback that will be invoked with the promise result, no matter what it is, and returns a new result.

Declaration

Swift

public func mapResult<T, E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onComplete: @escaping (PromiseResult<Value, Error>) -> PromiseResult<T, E>) -> Promise<T, E>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onComplete` from being invoked and will cause the returned `Promise` to be cancelled.
`onComplete`	The callback that is invoked with the promise’s value. This callback returns a new result, which the returned promise will adopt the value of.

Return Value

A new Promise that adopts the result returned by onComplete.


                    
                    
                    flatMapResult(on:token:_:)

Registers a callback that will be invoked with the promise result, no matter what it is, and returns a new promise to wait on.

Declaration

Swift

public func flatMapResult<T, E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onComplete: @escaping (PromiseResult<Value, Error>) -> Promise<T, E>) -> Promise<T, E>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onComplete` from being invoked and will cause the returned `Promise` to be cancelled.
`onComplete`	The callback that is invoked with the promise’s value. This callback returns a new promise, which the returned promise will adopt the value of.

Return Value

A new Promise that adopts the same value that the promise returned by onComplete does.


                    
                    
                    tryMapResult(on:token:_:)

Registers a callback that will be invoked with the promise result, no matter what it is, and returns a new result.

Declaration

Swift

public func tryMapResult<T, E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onComplete: @escaping (PromiseResult<Value, Error>) throws -> PromiseResult<T, E>) -> Promise<T, Swift.Error> where E : Error

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onComplete` from being invoked and will cause the returned `Promise` to be cancelled.
`onComplete`	The callback that is invoked with the promise’s value. This callback returns a new result, which the returned promise will adopt the value of.

Return Value

A new Promise that adopts the result returned by onComplete, or is rejected if onComplete throws an error.


                    
                    
                    tryFlatMapResult(on:token:_:)

Registers a callback that will be invoked with the promise result, no matter what it is, and returns a new promise to wait on.

Declaration

Swift

public func tryFlatMapResult<T, E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onComplete: @escaping (PromiseResult<Value, Error>) throws -> Promise<T, E>) -> Promise<T, Swift.Error> where E : Error

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onComplete` from being invoked and will cause the returned `Promise` to be cancelled.
`onComplete`	The callback that is invoked with the promise’s value. This callback returns a new promise, which the returned promise will adopt the value of.

Return Value

A new Promise that adopts the same value that the promise returned by onComplete does, or is rejected if onComplete throws an error.

tryMapResult(on:token:_:)

Registers a callback that will be invoked with the promise result, no matter what it is, and returns a new result.
tryFlatMapResult(on:token:_:)

Registers a callback that will be invoked with the promise result, no matter what it is, and returns a new promise to wait on.


                    
                    
                    tap(on:token:_:)

Registers a callback that will be invoked when the promise is resolved without affecting behavior.

This is similar to an always callback except it doesn’t create a new Promise and instead returns its receiver. This means it won’t delay any chained callbacks and it won’t affect automatic cancellation propagation behavior.

This is similar to tap().always(on:token:_:) except it can be inserted into any promise chain without affecting the chain.

Note

This method is intended for inserting into the middle of a promise chain without affecting existing behavior (in particular, cancellation propagation). If you are not inserting this into the middle of a promise chain, you probably want to use then(on:token:_:), map(on:token:_:), catch(on:token:_:), or always(on:token:_:) instead.

Declaration

Swift

@discardableResult
public func tap(on context: PromiseContext = .auto, token: PromiseInvalidationToken? = nil, _ onComplete: @escaping (PromiseResult<Value, Error>) -> Void) -> Promise<Value, Error>

Parameters

`context`	The context to invoke the callback on. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onComplete` from being invoked.
`onComplete`	The callback that is invoked with the promise’s value.

Return Value

The receiver.

tap()
Returns a new Promise that adopts the result of the receiver without affecting its behavior.

The returned Promise will always resolve with the same value that its receiver does, but it won’t affect the timing of any of the receiver’s other observers and it won’t affect automatic cancellation propagation behavior. Requesting cancellation of the returned Promise does nothing.

tap().always(on:token:_:) behaves the same as tap(on:token:_:) except it returns a new Promise whereas tap(on:token:_:) returns the receiver and can be inserted into any promise chain without affecting the chain.

Note

This method is intended for inserting into the middle of a promise chain without affecting existing behavior (in particular, cancellation propagation). If you are not inserting this into the middle of a promise chain, you probably want to use then(on:token:_:), map(on:token:_:), catch(on:token:_:), or always(on:token:_:) instead.

See also

tap(on:token:_:), ignoringCancel()
Declaration
Swift

public func tap() -> Promise<Value, Error>
Return Value

A new Promise that adopts the same result as the receiver. Requesting this new promise to cancel does nothing.


                    
                    
                    onCancel(on:token:_:)

Registers a callback that will be invoked when the promise is cancelled.

Note

Like tap, onCancel does not prevent automatic cancellation propagation if the parent has multiple children and all other children have requested cancellation. Unlike tap, requesting cancellation of onCancel will cancel the parent if the parent has no other children. onCancel‘s behavior differs from the other standard obsrevers here as attaching an onCancel observer to a promise that would otherwise be cancelled should not prevent the cancellation.

Declaration

Swift

@discardableResult
public func onCancel(on context: PromiseContext = .auto, token: PromiseInvalidationToken? = nil, _ onCancel: @escaping () -> Void) -> Promise<Value, Error>

Parameters

`context`	The context to invoke the callback on. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onCancel` from being invoked.
`onCancel`	The callback that is invoked when the promise is cancelled.

Return Value

A new promise that will resolve to the same value as the receiver. You may safely ignore this value.


                    
                    
                    propagatingCancellation(on:cancelRequested:)

Returns a promise that adopts the same value as the receiver, and propagates cancellation from its children upwards even when it still exists.

Normally cancellation is only propagated from children upwards when the parent promise is no longer held on to directly. This allows more children to be attached to the parent later, and only after the parent has been dropped will cancellation requests from its children propagate up to its own parent.

This method returns a promise that ignores that logic and propagates cancellation upwards even while it still exists. As soon as all existing children have requested cancellation, the cancellation request will propagate to the receiver. A callback is provided to allow you to drop the returned promise at that point, so you don’t try to attach new children.

The intent of this method is to allow you to deduplicate requests for a long-lived resource (such as a network load) without preventing cancellation of the load in the event that no children care about it anymore.

Important

Do not give the returned promise directly to callers. Instead always hand back a child, such as returned from makeChild. Otherwise automatic cancellation propagation won’t work as expected.

Declaration

Swift

public func propagatingCancellation(on context: PromiseContext, cancelRequested: @escaping (_ promise: Promise<Value, Error>) -> Void) -> Promise<Value, Error>

Parameters

`context`	The context to invoke the callback on.
`cancelRequested`	The callback that is invoked when the promise is requested to cancel, either because `.requestCancel()` was invoked on it directly or because all children have requested cancellation. This callback is executed immediately prior to the cancellation request being propagated to the receiver.
`promise`	The same promise that’s returned from this method.

Return Value

A new promise that will resolve to the same value as the receiver.

makeChild()
Returns a promise that adopts the same value as the receiver.

This method is used in order to hand back child promises to callers so that they cannot directly request cancellation of a shared parent promise. This is most useful in conjunction with propagatingCancellation(on:cancelRequested:) but could also be used any time a shared promise is given to multiple callers.
Declaration
Swift

public func makeChild() -> Promise<Value, Error>
Return Value

A new promise that will resolve to the same value as the receiver.
fork(_:)
Passes the Promise to a block and then returns the Promise for further chaining.

This method exists to make it easy to add multiple children to the same Promise in a promise chain.

Note
Having multiple children on a single Promise can interfere with automatic cancellation propagation. You may want to use tap(on:token:_:) or tap() for your sibling children if you’re returning the result of the promise chain to a caller that may wish to cancel the chain.

Example:
```
return urlSession.dataTaskAsPromise(for: url)
    .fork({ $0.tap().then(on: .main, { analytics.recordNetworkLoad($0.response, for: url) }) })
    .tryMap(on: .utility, { try JSONDecoder().decode(Model.self, from: $0.data) })
```
Declaration
Swift

public func fork(_ handler: (Promise) throws -> Void) rethrows -> Promise
requestCancel()
Requests that the Promise should be cancelled.

If the promise is already resolved, this does nothing. Otherwise, if the Promise registers any onRequestCancel handlers, those handlers will be called.

Note
Requesting that a Promise should be cancelled doesn’t guarantee it will be. If you need to ensure your then block isn’t invoked, also use a PromiseInvalidationToken and call .invalidate() on it.
Declaration
Swift

public func requestCancel()


                    
                    
                    requestCancelOnInvalidate(_:)

Requests that the Promise should be cancelled when the token is invalidated.

This is equivalent to calling token.requestCancelOnInvalidate(promise) and is intended to be used to terminate a promise chain. For example:

urlSession.promiseDataTask(for: url).then(token: token, { (data) in
    …
}).catch(token: token, { (error) in
    …
}).requestCancelOnInvalidate(token)

Declaration

Swift

@discardableResult
public func requestCancelOnInvalidate(_ token: PromiseInvalidationToken) -> Promise<Value, Error>

Parameters


                                token

A PromiseInvalidationToken. When the token is invalidated the receiver will be requested to cancel.

Return Value

The receiver. This value can be ignored.

ignoringCancel()
Returns a new Promise that adopts the value of the receiver but ignores cancel requests.

This is primarily useful when returning a nested promise in a callback handler in order to unlink cancellation of the outer promise with the inner one. It can also be used to stop propagating cancel requests up the chain, e.g. if you want to implement something similar to tap(on:token:_:).

Note

This is similar to tap() except it prevents the parent promise from being automatically cancelled due to cancel propagation from any observer.

Note

The returned Promise will still be cancelled if its parent promise is cancelled.

See also

tap()
Declaration
Swift

public func ignoringCancel() -> Promise<Value, Error>
init(result:)
Returns a Promise that is already resolved with the given result.

Note
This initializer has been renamed to init(with:).

See also
Promise.init(with:).
Declaration
Swift

@available(*, deprecated, renamed: "init(with:﹚") init(result: PromiseResult<Value, Error>)
init(on:result:after:)
Returns a Promise that resolves with the given result after a delay.

Note
This initializer has been renamed to init(on:with:after:).

See also
Promise.init(on:with:after:).
Declaration
Swift

@available(*, deprecated, renamed: "init(on:with:after:﹚") init(on context: PromiseContext = .auto, result: PromiseResult<Value, Error>, after delay: TimeInterval)


                    
                    
                    requestCancelOnDeinit(_:)

Requests that the Promise should be cancelled when the object deinits.

This is equivalent to having the object hold a PromiseInvalidationToken in a property (configured to invalidate on deinit) and requesting the promise cancel on that token.

Declaration

Swift

@discardableResult
public func requestCancelOnDeinit(_ object: AnyObject) -> Promise<Value, Error>

Parameters


                                object

Any object. When the object deinits the receiver will be requested to cancel.

Return Value

The receiver. This value can be ignored.

Equatable

==(_:_:)
Two Promises compare as equal if they represent the same promise.

Two distinct Promises that are resolved to the same value compare as unequal.
Declaration
Swift

public static func == (lhs: Promise, rhs: Promise) -> Bool

cancellable
Returns a value that can be used to cancel this promise without holding onto the full promise.

In particular, this acts like a weak reference, allowing for cancelling the promise without creating a retain cycle. Promise retain cycles normally break themselves anyway when the promise is resolved, but a misbehaving promise body may drop the resolver without ever resolving the promise. If the Promise has no more references to it this automatically cancels the promise, but a retain cycle prevents this.

If you trust the promise provider to always resolve the promise, you can safely ignore this.
Declaration
Swift

public var cancellable: PromiseCancellable { get }


                    
                    
                    withToken(_:)

Returns a new TokenPromise that wraps the receiver.

A TokenPromise is an adapter that allows you to call methods on the wrapped Promise while automatically applying the given PromiseInvalidationToken.

Important

TokenPromise automatically cancels any returned child Promises when the PromiseInvalidationToken is invalidated. If you do not want child Promises to be cancelled, pass the token to the Promise methods manually instead of using .withToken(_:). See TokenPromise for details.

Declaration

Swift

public func withToken(_ token: PromiseInvalidationToken) -> TokenPromise<Value, Error>

Parameters


                                token

The PromiseInvalidationToken to use when calling methods on the receiver using the returned TokenPromise.

Return Value

A TokenPromise.


                    
                    
                    init(on:fulfilled:after:)

Returns a Promise that fulfills with the given value after a delay.

Requesting that the promise be cancelled prior to it resolving will immediately cancel the promise.

This can be used as a sort of cancellable timer. It can also be used in conjunction with when(first:cancelRemaining:) to implement a timeout that fulfills with a given value on timeout instead of rejecting with a PromiseTimeoutError.

Declaration

Swift

public init(on context: PromiseContext = .auto, fulfilled value: Value, after delay: TimeInterval)

Parameters

`context`	The context to resolve the `Promise` on. This is generally only important when using callbacks registered with `.immediate`. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`. If provided as `.immediate`, behaves the same as `.auto`. If provided as `.operationQueue` it enqueues an operation on the operation queue immediately that becomes ready once the delay has elapsed.
`value`	The value the promise will be fulfilled with.
`delay`	The number of seconds to delay the promise by.


                    
                    
                    init(on:rejected:after:)

Returns a Promise that rejects with the given error after a delay.

Requesting that the promise be cancelled prior to it resolving will immediately cancel the promise.

Declaration

Swift

public init(on context: PromiseContext = .auto, rejected error: Error, after delay: TimeInterval)

Parameters

`context`	The context to resolve the `Promise` on. This is generally only important when using callbacks registered with `.immediate`. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`. If provided as `.immediate`, behaves the same as `.auto`. If provided as `.operationQueue` it enqueues an operation on the operation queue immediately that becomes ready once the delay has elapsed.
`error`	The error the promise will be rejected with.
`delay`	The number of seconds to delay the promise by.


                    
                    
                    init(on:with:after:)

Returns a Promise that resolves with the given result after a delay.

Requesting that the promise be cancelled prior to it resolving will immediately cancel the promise.

Declaration

Swift

public init(on context: PromiseContext = .auto, with result: PromiseResult<Value, Error>, after delay: TimeInterval)

Parameters

`context`	The context to resolve the `Promise` on. This is generally only important when using callbacks registered with `.immediate`. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`. If provided as `.immediate`, behaves the same as `.auto`. If provided as `.operationQueue` it enqueues an operation on the operation queue immediately that becomes ready once the delay has elapsed.
`result`	The result the promise will be resolved with.
`delay`	The number of seconds to delay the promise by.


                    
                    
                    delay(on:_:)

Returns a new Promise that adopts the receiver’s result after a delay.

Declaration

Swift

public func delay(on context: PromiseContext = .auto, _ delay: TimeInterval) -> Promise<Value, Error>

Parameters


                                context

The context to resolve the new Promise on. This is generally only important when using callbacks registered with .immediate. If not provided, defaults to .auto, which evaluates to .main when invoked on the main thread, otherwise .default. If provided as .immediate, behaves the same as .auto. If provided as .operationQueue it enqueues an operation on the operation queue immediately that becomes ready once the delay has elapsed.


                                delay

The number of seconds to delay the resulting promise by.

Return Value

A Promise that adopts the same result as the receiver after a delay.


                    
                    
                    timeout(on:delay:)

Returns a Promise that is rejected with an error if the receiver does not resolve within the given interval.

The returned Promise will adopt the receiver’s value if it resolves within the given interval. Otherwise it will be rejected with the error PromiseTimeoutError.timedOut. If the receiver is rejected, the returned promise will be rejected with PromiseTimeoutError.rejected(error).

If the promise times out, the returned promise will be rejected using the same context. In this event, .immediate is treated the same as .auto. If provided as .operationQueue it enqueues an operation on the operation queue immediately that becomes ready when the promise times out.

Note

If the delay is less than or equal to zero and the context is .immediate or .nowOr(_:) then the returned promise will already be resolved; if the receiver is already resolved the returned promise will adopt the same result, otherwise it will be rejected with .timedOut.

Declaration

Swift

public func timeout(on context: PromiseContext = .nowOr(.auto), delay: TimeInterval) -> Promise<Value, PromiseTimeoutError<Error>>

Parameters


                                context

The context to invoke the callback on. If not provided, defaults to .nowOr(.auto), which evaluates to .nowOr(.main) when invoked on the main thread, otherwise .nowOr(.default). The usage of .nowOr here means that if the receiver has already been resolved when this method is called, the returned promise will likewise already be resolved. If the receiver has not already resolved then this behaves the same as passing .auto.


                                delay

The delay before the returned promise times out. If less than or equal to zero, the returned Promise will be timed out at once unless the receiver is already resolved.

Return Value

A new Promise.

Available where `Error`: `Swift.Error`

upcast
Returns a new promise with an error type of Swift.Error.

The new promise adopts the exact same result as the receiver, but if the promise resolves to an error, it’s upcast to Swift.Error.
Declaration
Swift

public var upcast: Promise<Value, Swift.Error> { get }

Available where `Error` == `NoError`

upcast
Returns a new promise with an error type of Swift.Error.

The new promise adopts the exact same result as the receiver. As the receiver’s error type is NoError, the receiver cannot ever be rejected, but this upcast allows the promise to compose better with other promises.
Declaration
Swift

public var upcast: Promise<Value, Swift.Error> { get }

Available where `Error` == `Swift.Error`


                    
                    
                    init(on:_:)

Returns a new Promise that will be resolved using the given block.

Declaration

Swift

public init(on context: PromiseContext, _ handler: @escaping (_ resolver: Resolver) throws -> Void)

Parameters

`context`	The context to execute the handler on.
`handler`	A block that is executed in order to fulfill the promise. If the block throws an error the promise will be rejected (unless it was already resolved first).
`resolver`	The `Resolver` used to resolve the promise.


                    
                    
                    tryThen(on:token:_:)

Registers a callback that is invoked when the promise is fulfilled.

Declaration

Swift

public func tryThen(on context: PromiseContext = .auto, token: PromiseInvalidationToken? = nil, _ onSuccess: @escaping (Value) throws -> Void) -> Promise<Value, Error>

Parameters

`context`	The context to invoke the callback on. If not provided, defaults to `.auto`, which evaluates to `.main` when invoked on the main thread, otherwise `.default`.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onSuccess` from being invoked.
`onSuccess`	The callback that is invoked with the fulfilled value.

Return Value

A new promise that will resolve to the same value as the receiver, or rejected if onSuccess throws an error. If the receiver is rejected or cancelled, the returned promise will also be rejected or cancelled.


                    
                    
                    tryMap(on:token:_:)

Registers a callback that is invoked when the promise is fulfilled.

Declaration

Swift

public func tryMap<U>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onSuccess: @escaping (Value) throws -> U) -> Promise<U, Error>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onSuccess` from being invoked. If the promise is fulfilled and the token is invalidated, the returned promise will be cancelled.
`onSuccess`	The callback that is invoked with the fulfilled value.

Return Value

A new promise that will be fulfilled with the return value of onSuccess, or rejected if onSuccess throws an error. If the receiver is rejected or cancelled, the returned promise will also be rejected or cancelled.

tryFlatMap(on:token:_:)

Registers a callback that is invoked when the promise is fulfilled.


                    
                    
                    tryFlatMap(on:token:_:)

Registers a callback that is invoked when the promise is fulfilled.

Declaration

Swift

public func tryFlatMap<U, E>(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onSuccess: @escaping (Value) throws -> Promise<U, E>) -> Promise<U, Error> where E : Error

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onSuccess` from being invoked. If the promise is fulfilled and the token is invalidated, the returned promise will be cancelled.
`onSuccess`	The callback that is invoked with the fulfilled value.

Return Value

A new promise that will be eventually resolved using the promise returned from onSuccess, or rejected if onSuccess throws an error. If the receiver is rejected or cancelled, the returned promise will also be rejected or cancelled.


                    
                    
                    tryRecover(on:token:_:)

Registers a callback that is invoked when the promise is rejected.

Unlike catch(on:_:) this callback can recover from the error and return a new value.

Declaration

Swift

public func tryRecover(on context: PromiseContext, token: PromiseInvalidationToken? = nil, _ onError: @escaping (Error) throws -> Value) -> Promise<Value, Error>

Parameters

`context`	The context to invoke the callback on.
`token`	An optional `PromiseInvalidatonToken`. If provided, calling `invalidate()` on the token will prevent `onError` from being invoked. If the promise is fulfilled and the token is invalidated, the returned promise will be cancelled.
`onError`	The callback that is invoked with the rejected error.

Return Value

A new promise that will be fulfilled with the return value of onError, or rejected if onError throws an error. If the receiver is rejected or cancelled, the returned promise will also be rejected or cancelled.

Available where `Error`: `Swift.Error`

init(with:)
Returns a Promise that is already resolved with the given result.
Declaration
Swift

public init(with result: Result<Value, Error>)

Available where `Error` == `Swift.Error`


                    
                    
                    timeout(on:delay:)

Returns a Promise that is rejected with an error if the receiver does not resolve within the given interval.

The returned Promise will adopt the receiver’s value if it resolves within the given interval. Otherwise it will be rejected with the error PromiseTimeoutError<Error>.timedOut. If the receiver is rejected, the returned promise will be rejected with the same error.

Note

Declaration

Swift

public func timeout(on context: PromiseContext = .nowOr(.auto), delay: TimeInterval) -> Promise<Value, Swift.Error>

Parameters


                                context


                                delay

The delay before the returned promise times out. If less than or equal to zero, the returned Promise will be timed out at once unless the receiver is already resolved.

Return Value

A new Promise.