Changes between Initial Version and Version 1 of Ticket #14615

Apr 1, 2012, 10:54:49 PM (8 years ago)
Mark Wubben


  • Ticket #14615 – Description

    initial v1  
    1 For 1.8 I'm looking to introduce a new Deferred API under `dojo/Deferred`, with a backwards compatible wrapper under `dojo/_base/Deferred`.
     1Dojo 1.8 will have a new Deferred API available under `dojo/Deferred`, with a `when()` implementation under `dojo/when`. `dojo.Deferred` will remain `dojo/_base/Deferred`. `dojo/_base/Deferred` also sets `dojo.when`, which *is` the same as `dojo/when`. Instances of `dojo/_base/Deferred` have a `promise` object that is an instance of `dojo/promise/Promise`, i.e. a new promise object.
    3 Ideally you can use Dojo without ever loading the backwards compatible layer. The most elegant solution is to only include `dojo/_base/Deferred` when `dojo` itself is included. Internal code should never require `dojo` directly and external code can be written in a similar manner.
     3Notable changes:
    5 `dojo/Deferred` should be the minimal promise API. It'd be good however if we allow a configuration option to swap out its implementation. E.g. `dojo/Deferred` would by default load and return `dojo/promise/Deferred` but this can be changed to `promised-io/promise/Deferred`.
     5* Based on Promises/A, ergo no support for `addCallback`, `callback` etc.
     6* You can `resolve`/`reject`/`progress`/`cancel` a deferred multiple times without errors being thrown, unless a "strict" flag is set.
     7* `resolve`/`reject`/`progress` return the promise.
     8* a reason can be passed to `cancel()` for communicating to the canceler why the deferred needs to be canceled.
     9* `when()` without callbacks always returns a promise.
    7 Which brings us to the work I'm doing on a Promised-IO rewrite, code for which can be found at <>. This code differs from the CommonJS proposals and the current Dojo implementation in a few ways:
     11Additional changes:
    9 * A reason can be passed to `cancel()` which is then sent to the canceler, allowing for upstream signaling
    10 * `resolve()`, `reject()`, `progress()` and `cancel()` are no-ops on fulfilled promises, unless a second parameter, a `strict` flag, is set to `true`, in which case an error will be thrown
    11 * `resolve()`, `reject()`, `progress()`, `cancel()` and `then()` are bound via closure to the deferred / promise, meaning they can be called without a scope and still work correctly
    12 * Anything is allowed to be an error, even `undefined`, as long as its passed with `reject()` or thrown by a callback
    13 * A custom error class is used for cancel errors
    14 * `promised-io/promise/when` **always** returns a promise and converts foreign promises into "native" promises
    16 I've also added various sugary methods that do not need to be included in Dojo Core.
    18 While I intend to copy the logic from my Promised-IO code into Dojo I'm not sure about some of the behavior changes. Especially if we want to make the logic swappable Dojo Core should assume a lowest common denominator.
    20 To what extend do we need to support older behavior? There are subtle differences between 1.4 and 1.7, which should it meet? What about the error objects when a promise is canceled? What do we do about `dojo/xhr` who's behavior relies on the old deferred logic?
    22 Similarly, `dojo/DeferredList` is just horrible and should be replaced. Perhaps `dojo/promise/all` analogous to `promised-io/promise/all`.
    24 Feedback appreciated.
     13* `when()` converts foreign promises.
     14* `isResolved`/`isRejected`/`isCanceled`/`isFulfilled` helpers on deferreds and promises.
     15* `fail`/`both` helpers on promises.
     16* custom `CancelError` subclass of `Error`.
     17* To detect errors (or generally observe the behavior of promises) a tracing mechanism has been added. This replaces logging errors to the console in `dojo/_base/Deferred`.
     18* Introduces `dojo/promise/first` and `dojo/promise/all` as a replacement for `dojo/DeferredList`. The later is unmodified.