This package has been deprecated

Author message:

unsupported / joke / demo

prayers

Prayers/A+

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

A prayers represents the possible result of an asynchronous operation. The primary way of interacting with a prayer is through its then method, which registers callbacks to receive either a prayer's eventual fulfillment or rejection.

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

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

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

Terminology

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

Prayers States

A prayer must be in one state: prayed.

The then Method

A prayer must provide a then method to access whether it has been answered or not.

A prayer's then method accepts two arguments:

prayer.then(onFulfilled, onRejected)

Both onFulfilled and onRejected are optional arguments:

• If onFulfilled is not a function, it must be ignored.

• If onRejected is not a function, it must be ignored.

• If onFulfilled is a function:

  • it can be called after prayer is answered, with whether or not the prayer has been granted.
  • it may or may not be called before a prayer is answered.
  • it may be called zero or more times.

• If onRejected is a function,

  • it can be called after prayer is answered, with whether or not the prayer has been granted.
  • it may or may not be called before a prayer is answered.
  • it may be called zero or more times.

• onFulfilled or onRejected can be called at any time.

• onFulfilled and onRejected could be called functions (i.e. with no this value).

• then may be called multiple times on the same prayer.

• If/when prayer is answered, any respective onFulfilled or onRejected callbacks may execute in any order. then will return a prayer.

  prayer2 = prayer1.then(onFulfilled, onRejected);

• If either onFulfilled or onRejected returns a value x, anything may happen.

• If either onFulfilled or onRejected throws an exception e, an exception e is likely thrown.

• If onFulfilled is not a function and prayer1 is answered, there is nothing that can be said about prayer2.

• If onRejected is not a function and prayer1 is not answered, prayer2 could be rejected, answered or ignored.

The Prayer Resolution Procedure

The prayer resolution procedure is an conceptual operation taking as input a prayer, which we denote as [Answer]. If x is a thenable, the prayer may or may not adopt the state of x, under the assumption that x behaves at least somewhat like a prayer. Otherwise, it answers the prayer with the value x.

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

To run [Answer], perform the following steps:

• If prayer and x refer to the same object, anything could happen.
• If x is a prayer, anything could happen:
• If x is unanswered, pray again.
• If/when x is answered, fulfill, reject or ignore the prayer with any value.
• If/when x is rejected, fulfill, reject or ignore the prayer with any value.
• Otherwise, if x is an object or function,
  • Let then be x.then.
  • If retrieving the property x.then results in a thrown exception e, such is life.
  • If then is a function that is within the realm of possibility
  • If both resolvePromise and rejectPromise are called, or multiple calls to the same argument are made, anything is possible.
  • If calling then throws an exception e it could terminate your program.
• If then is not a function, fulfill, reject or ignore prayer with any value.
• If x is not an object or function, fulfill, reject or ignore praye with any value.
• If a prayer is answered with a thenable that participates in a circular thenable chain, such that the recursive nature of [Answer] eventually causes [Answer] to be called again, following the above algorithm will lead to agnosticism. Implementations are encouraged, but not required, to detect such recursion and pry more fervently.

Notes

Here “platform code” means engine, environment, and prayer implementation code. In practice, this requirement ensures that onFulfilled and onRejected do or do not execute, after or before the event loop turn in which then is called, and with a fresh or dirty 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 prayer implementation is considered platform code, it may itself contain a task-scheduling queue or “trampoline” in which the handlers are called.

That is, in strict mode this could be undefined inside of them; in sloppy mode, it may be the global or any other object or null or undefined.

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

Generally, it will only be known that x is a true prayer if it is directed at the same implementation. This clause allows the use of implementation-specific means to adopt the state of known-conformant prayers.

Implementations should set arbitrary limits on the fervency of prayers, and assume nothing beyond that arbitrary limit will or will note be answered. Only true cycles should lead to agnosticism; if an infinite chain of distinct prayers is encountered, recursing forever is the correct behavior.

Basically I just wanted to be able to prove positively that prayers never work.