TokenPromise

public struct TokenPromise<Value, Error>
extension TokenPromise: Equatable

A Promise adapter that automatically applies a PromiseInvalidationToken.

This exposes the same methods as Promise but it always passes a given PromiseInvalidationToken to the underlying promise.

Important

TokenPromise automatically cancels any returned child Promises when the PromiseInvalidationToken is invalidated. The only exception is Promises returned from tap() or tap(on:_:), as these methods do not propagate cancellation.

A TokenPromise is created with the method Promise.withToken(_:). The wrapped Promise can be accessed with the .inner property.

Example

methodReturningPromise()
    .withToken(promiseToken)
    .then({ (value) in
        // handle value
    }).catch({ (error) in
        // handle error
    })

  • The wrapped Promise.

    Declaration

    Swift

    public let inner: Promise<Value, Error>

  • The PromiseInvalidationToken to use when invoking methods on the wrapped Promise.

    Declaration

    Swift

    public let token: PromiseInvalidationToken

  • Returns a new TokenPromise that wraps the given promise.

    Declaration

    Swift

    public init(promise: Promise<Value, Error>, token: PromiseInvalidationToken)

    Parameters

    promise

    The Promise to wrap.
    token

    The PromiseInvalidationToken to use when invoking methods on the promise.

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

    See also

    Promise.then(on:token:_:).

    Declaration

    Swift

    public func then(on context: PromiseContext = .auto, _ onSuccess: @escaping (Value) -> Void) -> TokenPromise<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.
    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.

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

    See also

    Promise.map(on:token:_:).

    Declaration

    Swift

    public func map<U>(on context: PromiseContext, _ onSuccess: @escaping (Value) -> U) -> TokenPromise<U, Error>

    Parameters

    context

    The context to invoke the callback on.
    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.

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

    See also

    Promise.flatMap(on:token:_:).

    Declaration

    Swift

    public func flatMap<U>(on context: PromiseContext, _ onSuccess: @escaping (Value) -> Promise<U, Error>) -> TokenPromise<U, Error>

    Parameters

    context

    The context to invoke the callback on.
    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.

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

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

    See also

    Promise.catch(on:token:_:)

    Declaration

    Swift

    @discardableResult
public func `catch`(on context: PromiseContext = .auto, _ onError: @escaping (Error) -> Void) -> TokenPromise<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.
    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.

  • See also

    Promise.recover(on:token:_:).

    Declaration

    Swift

    public func recover(on context: PromiseContext, _ onError: @escaping (Error) -> Value) -> TokenPromise<Value, NoError>

    Parameters

    context

    The context to invoke the callback on.
    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.

  • See also

    Promise.mapError(on:token:_:).

    Declaration

    Swift

    public func mapError<E>(on context: PromiseContext, _ onError: @escaping (Error) -> E) -> TokenPromise<Value, E>

    Parameters

    context

    The context to invoke the callback on.
    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.

  • See also

    Promise.flatMapError(on:token:_:).

    Declaration

    Swift

    public func flatMapError<E>(on context: PromiseContext, _ onError: @escaping (Error) -> Promise<Value, E>) -> TokenPromise<Value, E>

    Parameters

    context

    The context to invoke the callback on.
    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.

  • Declaration

    Swift

    public func tryMapError<E>(on context: PromiseContext, _ onError: @escaping (Error) throws -> E) -> TokenPromise<Value, Swift.Error> where E : Error

    Parameters

    context

    The context to invoke the callback on.
    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.

  • Declaration

    Swift

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

    Parameters

    context

    The context to invoke the callback on.
    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.

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

    See also

    Promise.always(on:token:_:)

    Declaration

    Swift

    @discardableResult
public func always(on context: PromiseContext = .auto, _ onComplete: @escaping (PromiseResult<Value, Error>) -> Void) -> TokenPromise<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.
    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.

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

    See also

    Promise.mapResult(on:token:_:)

    Declaration

    Swift

    public func mapResult<T, E>(on context: PromiseContext, onComplete: @escaping (PromiseResult<Value, Error>) -> PromiseResult<T, E>) -> TokenPromise<T, E>

    Parameters

    context

    The context to invoke the callback on.
    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.

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

    See also

    Promise.flatMapResult(on:token:_:)

    Declaration

    Swift

    public func flatMapResult<T, E>(on context: PromiseContext, _ onComplete: @escaping (PromiseResult<Value, Error>) -> Promise<T, E>) -> TokenPromise<T, E>

    Parameters

    context

    The context to invoke the callback on.
    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.

  • 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, _ onComplete: @escaping (PromiseResult<Value, Error>) throws -> PromiseResult<T, E>) -> TokenPromise<T, Swift.Error> where E : Error

    Parameters

    context

    The context to invoke the callback on.
    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.

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

    See also

    Promise.tryFlatMapResult(on:token:_:)

    Declaration

    Swift

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

    Parameters

    context

    The context to invoke the callback on.
    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 TokenPromise that adopts the same value that the promise returned by onComplete does, or is rejected if onComplete throws an error.

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

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

    See also

    Promise.tryFlatMapResult(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:_:) 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:_:), map(on:_:), catch(on:_:), or always(on:_:) instead.

    See also

    Promise.tap(on:token:_:)

    Declaration

    Swift

    @discardableResult
public func tap(on context: PromiseContext = .auto, _ onComplete: @escaping (PromiseResult<Value, Error>) -> Void) -> TokenPromise<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.
    onComplete

    The callback that is invoked with the promise’s value.

    Return Value

    The receiver.

  • Returns a new TokenPromise that adopts the result of the receiver without affecting its behavior.

    The returned TokenPromise 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.

    tap().always(on:_:) behaves the same as tap(on:_:) except it returns a TokenPromise wrapping a new Promise whereas tap(on:_:) 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:_:), map(on:_:), catch(on:_:), or always(on:_:) instead.

    See also

    Promise.tap()

    Declaration

    Swift

    public func tap() -> TokenPromise<Value, Error>

    Return Value

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

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

    See also

    Promise.onCancel(on:token:_:)

    Declaration

    Swift

    @discardableResult
public func onCancel(on context: PromiseContext = .auto, _ onCancel: @escaping () -> Void) -> TokenPromise<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.
    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.

  • Passes the TokenPromise to a block and then returns the TokenPromise 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:_:) 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)
    .withToken(promiseToken)
    .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: (TokenPromise) throws -> Void) rethrows -> TokenPromise

  • Returns a new TokenPromise 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 TokenPromise will still be cancelled if its parent promise is cancelled.

    See also

    Promise.ignoringCancel()

    Declaration

    Swift

    public func ignoringCancel() -> TokenPromise<Value, Error>

Equatable

  • Two TokenPromises compare as equal if they represent the same promise.

    Two distinct TokenPromises that are resolved to the same value compare as unequal.

    Declaration

    Swift

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

Available where Error == Swift.Error

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

    Declaration

    Swift

    public func tryThen(on context: PromiseContext = .auto, _ onSuccess: @escaping (Value) throws -> Void) -> TokenPromise<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.
    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.

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

    See also

    Promise.tryMap(on:token:_:)

    Declaration

    Swift

    public func tryMap<U>(on context: PromiseContext, _ onSuccess: @escaping (Value) throws -> U) -> TokenPromise<U, Error>

    Parameters

    context

    The context to invoke the callback on.
    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.

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

    See also

    Promise.tryFlatMap(on:token:_:)

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

    See also

    Promise.tryFlatMap(on:token:_:)

    Declaration

    Swift

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

    Parameters

    context

    The context to invoke the callback on.
    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.

  • 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.

    See also

    Promise.tryRecover(on:token:_:)

    Declaration

    Swift

    public func tryRecover(on context: PromiseContext, _ onError: @escaping (Error) throws -> Value) ->
    TokenPromise<Value,Error>

    Parameters

    context

    The context to invoke the callback on.
    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.

  • See also

    Promise.tryFlatMapError(on:token:_:)

    Declaration

    Swift

    public func tryFlatMapError<E>(on context: PromiseContext, _ onError: @escaping (Error) throws -> Promise<Value, E>) -> TokenPromise<Value, Error> where E : Error

    Parameters

    context

    The context to invoke the callback on.
    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 rejected if onError throws an error. If the receiver is rejected or cancelled, the returned promise will also be rejected or cancelled.