promise A+规范翻译 2021-04-12

原文

An open standard for sound, interoperable JavaScript promises—by implementers, for implementers.

A promise represents the eventual result of an asynchronous operation. The primary way of interacting with a promise is through its then method, which registers callbacks to receive either a promise’s eventual value or the reason why the promise cannot be fulfilled.

This specification details the behavior of the then method, providing an interoperable base which all Promises/A+ conformant promise implementations can be depended on to provide. As such, the specification should be considered very stable. Although the Promises/A+ organization may occasionally revise this specification with minor backward-compatible changes to address newly-discovered corner cases, we will integrate large or backward-incompatible changes only after careful consideration, discussion, and testing.

Historically, Promises/A+ clarifies the behavioral clauses of the earlier Promises/A proposal, extending it to cover de facto behaviors and omitting parts that are underspecified or problematic.

Finally, the core Promises/A+ specification does not deal with how to create, fulfill, or reject promises, choosing instead to focus on providing an interoperable then method. Future work in companion specifications may touch on these subjects.

Terminology

1. “promise” is an object or function with a then method whose behavior conforms to this specification.
2. “thenable” is an object or function that defines a then method.
3. “value” is any legal JavaScript value (including undefined, a thenable, or a promise).
4. “exception” is a value that is thrown using the throw statement.
5. “reason” is a value that indicates why a promise was rejected.

Requirements

Promise States

A promise must be in one of three states: pending, fulfilled, or rejected.

1. When pending, a promise:
   1. may transition to either the fulfilled or rejected state.
2. When fulfilled, a promise:
   1. must not transition to any other state.
   2. must have a value, which must not change.
3. When rejected, a promise:
   1. must not transition to any other state.
   2. must have a reason, which must not change.

Here, “must not change” means immutable identity (i.e. ===), but does not imply deep immutability.

The then Method

A promise must provide a then method to access its current or eventual value or reason.

A promise’s then method accepts two arguments:

promise.then(onFulfilled, onRejected)

1. Both onFulfilled and onRejected are optional arguments:

   1. If onFulfilled is not a function, it must be ignored.
   2. If onRejected is not a function, it must be ignored.

2. If onFulfilled is a function:

   1. it must be called after promise is fulfilled, with promise’s value as its first argument.
   2. it must not be called before promise is fulfilled.
   3. it must not be called more than once.

3. If onRejected is a function,

   1. it must be called after promise is rejected, with promise’s reason as its first argument.
   2. it must not be called before promise is rejected.
   3. it must not be called more than once.

4. onFulfilled or onRejected must not be called until the execution context stack contains only platform code. [3.1].

5. onFulfilled and onRejected must be called as functions (i.e. with no this value). [3.2]

6. then may be called multiple times on the same promise.

   1. If/when promise is fulfilled, all respective onFulfilled callbacks must execute in the order of their originating calls to then.
   2. If/when promise is rejected, all respective onRejected callbacks must execute in the order of their originating calls to then.

7. then must return a promise [3.3].

    promise2 = promise1.then(onFulfilled, onRejected);
   
   

   1. If either onFulfilled or onRejected returns a value x, run the Promise Resolution Procedure [[Resolve]](promise2, x).
   2. If either onFulfilled or onRejected throws an exception e, promise2 must be rejected with e as the reason.
   3. If onFulfilled is not a function and promise1 is fulfilled, promise2 must be fulfilled with the same value as promise1.
   4. If onRejected is not a function and promise1 is rejected, promise2 must be rejected with the same reason as promise1.

The Promise Resolution Procedure

The promise resolution procedure is an abstract operation taking as input a promise and a value, which we denote as [[Resolve]](promise, x). If x is a thenable, it attempts to make promise adopt the state of x, under the assumption that x behaves at least somewhat like a promise. Otherwise, it fulfills promise with the value x.

This treatment of thenables allows promise implementations to interoperate, as long as they expose a Promises/A+-compliant then method. It also allows Promises/A+ implementations to “assimilate” nonconformant implementations with reasonable then methods.

To run [[Resolve]](promise, x), perform the following steps:

1. If promise and x refer to the same object, reject promise with a TypeError as the reason.
2. If x is a promise, adopt its state [3.4]:
   1. If x is pending, promise must remain pending until x is fulfilled or rejected.
   2. If/when x is fulfilled, fulfill promise with the same value.
   3. If/when x is rejected, reject promise with the same reason.
3. Otherwise, if x is an object or function,
   1. Let then be x.then. [3.5]
   2. If retrieving the property x.then results in a thrown exception e, reject promise with e as the reason.
   3. If then is a function, call it with x as this, first argument resolvePromise, and second argument rejectPromise, where:
      1. If/when resolvePromise is called with a value y, run [[Resolve]](promise, y).
      2. If/when rejectPromise is called with a reason r, reject promise with r.
      3. If both resolvePromise and rejectPromise are called, or multiple calls to the same argument are made, the first call takes precedence, and any further calls are ignored.
      4. If calling then throws an exception e,
         1. If resolvePromise or rejectPromise have been called, ignore it.
         2. Otherwise, reject promise with e as the reason.
   4. If then is not a function, fulfill promise with x.
4. If x is not an object or function, fulfill promise with x.

If a promise is resolved with a thenable that participates in a circular thenable chain, such that the recursive nature of [[Resolve]](promise, thenable) eventually causes [[Resolve]](promise, thenable) to be called again, following the above algorithm will lead to infinite recursion. Implementations are encouraged, but not required, to detect such recursion and reject promise with an informative TypeError as the reason. [3.6]

Notes

1. Here “platform code” means engine, environment, and promise implementation code. In practice, this requirement ensures that onFulfilled and onRejected execute asynchronously, after the event loop turn in which then is called, and with a fresh stack. This can be implemented with either a “macro-task” mechanism such as setTimeout or setImmediate, or with a “micro-task” mechanism such as MutationObserver or process.nextTick. Since the promise implementation is considered platform code, it may itself contain a task-scheduling queue or “trampoline” in which the handlers are called.

2. That is, in strict mode this will be undefined inside of them; in sloppy mode, it will be the global object.

3. Implementations may allow promise2 === promise1, provided the implementation meets all requirements. Each implementation should document whether it can produce promise2 === promise1 and under what conditions.

4. Generally, it will only be known that x is a true promise if it comes from the current implementation. This clause allows the use of implementation-specific means to adopt the state of known-conformant promises.

5. This procedure of first storing a reference to x.then, then testing that reference, and then calling that reference, avoids multiple accesses to the x.then property. Such precautions are important for ensuring consistency in the face of an accessor property, whose value could change between retrievals.

6. Implementations should not set arbitrary limits on the depth of thenable chains, and assume that beyond that arbitrary limit the recursion will be infinite. Only true cycles should lead to a TypeError; if an infinite chain of distinct thenables is encountered, recursing forever is the correct behavior.

中文译文

由开发者制定的开放、通用可信任的的promise标准，供开发者参考

promise代表了一个异步操作的最终结果。promise最主要的交互方式是通过它的 then方法，这个方法注册了回调函数用来接受一个promise的最终value或者被reject的reason。

该规范详细说明了then方法的行为,为所有符合promise/A+规范实现的promise均可以本标准作为参照基础来实施 then 方法。因为这个规则十分稳定。尽管Promises / A +组织有时会通过向后兼容的微小更改来修订此规范，以解决新发现的极端情况，但只有在仔细考虑，讨论和测试之后，我们才会集成大型或向后不兼容的更改。

从历史上看，Promises / A +阐明了较早Promises / A提案的行为条款，将其扩展为涵盖事实上的行为，并省略了未指定或有问题的部分。

最后，核心的Promises / A +规范不涉及如何create，fulfill或reject一个promise，而是选择专注于提供可互操作的then方法。 规范中的未来工作可能涉及这些主题。

术语

1. "promise"是一个对象或函数，它拥有符合此规范的then方法

2. "thenable"是一个对象或者方法，它定义了一个then方法。

3. "value"是一个任意合法javascript值（可以是'undefined',thenable或promise）

4. "exception"是通过throw声明抛出的一个错误

5. "reason"表明了一个promise失败的原因。

要求

Promise 状态

一个promise 必须处于以下三个状态种的一种： pending，fulfilled或rejecged

1. 在pending状态时，promise：
   1. 可以转变为fulfilled或rejected状态。
2. 当fulfilled状态时, a promise:
   1. 无法转换到其他状态。
   2. 一定会包含一个value，并且无法改变
3. 当rejected状态时，promise：
   1. 不能转换到其他状态
   2. 必定有reason，并且无法改变

在这里，“不能转换”意味着恒等（可以用===判断），但不适用于深层的改变（如果value或reason不为基本类型，可能会修改属性值）。

then方法

promise必须提供一个then方法来访问它的当前值或最终value/reason。

promise的then方法接收2个参数值：

promise.then(onFulfilled, onRejected)

1. onFulfilled和onRejected都是可选参数：

   1. onFulfilled 如果不为函数，则会被忽略执行
   2. onRejected如果不为函数，则会被忽略执行

2. onFulfilled如果是函数：

   1. 在promise变为fulfilled之后才会被调用，promise的value会时它的第一个参数值。
   2. 在promise变成fulfilled之前都不会被调用。
   3. 不能被调用超过一次。

3. onRejected如果是一个函数

   1. 一定会在promise状态变成rejected之后调用，promise的reason是它第一个参数。
   2. 在promise状态没有变为rejected之前不会被调用。
   3. [](https://promisesaplus.com/#point-33）无法被调用超过一次。

4. onFulfilled 和 onRejected 只有在执行环境堆栈仅包含平台代码时才可被调用
   [3.1].

5. onFulfilled 和onRejected 必须被用作函数调用 (i.e. with no this value). [3.2]

6. then 允许在一个promise中调用多次

   1. 当promise状态变为fulfilled，所有onFullfilled回调必须按照初始调用then方法的先后顺序执行。
   2. 当promise状态变为rejected，所有onRejected回调必须按照初始调用then方法的先后顺序执行。

7. then 方法必定返回一个promise [3.3].

    promise2 = promise1.then(onFulfilled, onRejected);
   
   

   1. 如果 onFulfilled 或者 onRejected 返回一个值 x ，则运行下面的 Promise 解决过程：[[Resolve]](promise2, x)

8. 如果onFulfilled 或onRejected抛出一个一场 e, promise2必定返回e作为一reason。

9. 如果onFulfilled不是一个函数并且 promise1是fulfilled状态， promise2 必定和promise1有同样的value。

10. 如果onRejected不是一个函数并且 promise1 处于rejected状态, promise2与promise1有相同的rason值

Promise解决过程

promise 解决过程是一个抽象操作，它输入一个promise和一个value，我们可以表示为 [[Resolve]](promise, x). 如果 x 有 then 方法且看上去像一个 Promise ，解决程序即尝试使 promise 接受 x 的状态；否则其用 x 的值来执行 promise 。

这种 thenable 的特性使得 Promise 的实现更具有通用性：只要其暴露出一个遵循 Promise/A+ 协议的 then 方法即可；这同时也使遵循 Promise/A+ 规范的实现可以与那些不太规范但可用的实现能良好共存。

运行 [[Resolve]](promise, x) 需遵循以下步骤

1. 如果promise和x指向同一个对象，使用TypeError来将promise该为rejected。
2. 如果 x 为 Promise ，则使 promise 接受 x 的状态 [3.4]:
   1. 如果 x 处于pending， promise 需保持为等待态直至 x 被执行或拒绝
   2. 如果 x 处于fulfiiled，用相同的值执行 promise
   3. 如果 x 处于rejected，用相同的值拒绝 promise
3. 如果x是一个对象或函数
   1. 把 x.then 赋值给 then [3.5]
   2. 如果取 x.then 的值时抛出错误 e ，则以 e 为据因拒绝 promise
   3. 果 then 是函数，将 x 作为函数的作用域 this 调用之。传递两个回调函数作为参数，第一个参数叫做 resolvePromise ，第二个参数叫做 rejectPromise:
      1. 如果 resolvePromise 以值 y 为参数被调用，则运行 [[Resolve]](promise, y)
      2. 如果 rejectPromise 以据因 r 为参数被调用，则以据因 r 拒绝 promise
      3. 如果 resolvePromise 和 rejectPromise 均被调用，或者被同一参数调用了多次，则优先采用首次调用并忽略剩下的调用
      4. 如果调用 then 方法抛出了异常 e：
         1. I如果 resolvePromise 或 rejectPromise 已经被调用，则忽略之
         2. 否则以 e 为据因拒绝 promise
   4. 如果 then 不是函数，以 x 为参数执行 promise
4. 如果 x 不为对象或者函数，以 x 为参数执行 promise

如果一个 promise 被一个循环的 thenable 链中的对象解决，而 [[Resolve]](promise, thenable) 的递归性质又使得其被再次调用，根据上述的算法将会陷入无限递归之中。算法虽不强制要求，但也鼓励施者检测这样的递归是否存在，若检测到存在则以一个可识别的 TypeError 为据因来拒绝 promise[3.6]

Notes

1. Here “platform code” means engine, environment, and promise implementation code. In practice, this requirement ensures that onFulfilled and onRejected execute asynchronously, after the event loop turn in which then is called, and with a fresh stack. This can be implemented with either a “macro-task” mechanism such as setTimeout or setImmediate, or with a “micro-task” mechanism such as MutationObserver or process.nextTick. Since the promise implementation is considered platform code, it may itself contain a task-scheduling queue or “trampoline” in which the handlers are called.

2. That is, in strict mode this will be undefined inside of them; in sloppy mode, it will be the global object.

3. Implementations may allow promise2 === promise1, provided the implementation meets all requirements. Each implementation should document whether it can produce promise2 === promise1 and under what conditions.

4. Generally, it will only be known that x is a true promise if it comes from the current implementation. This clause allows the use of implementation-specific means to adopt the state of known-conformant promises.

5. This procedure of first storing a reference to x.then, then testing that reference, and then calling that reference, avoids multiple accesses to the x.then property. Such precautions are important for ensuring consistency in the face of an accessor property, whose value could change between retrievals.

6. Implementations should not set arbitrary limits on the depth of thenable chains, and assume that beyond that arbitrary limit the recursion will be infinite. Only true cycles should lead to a TypeError; if an infinite chain of distinct thenables is encountered, recursing forever is the correct behavior.