readme: replace problematic definition of promise equivalence

[davidchambers]

I've listed @safareli as co-author since he suggested this change in #211 (comment) back in 2016!

[paldepind]

I'm not sure how helpful the Wikipedia link is. The text in the readme say "Two values are equivalent if they are referentially transparent" but the definition in the Wikipedia article defines referential transparency as a property that an expression can have.

[davidchambers]

Simon, how do you suggest we proceed?

[Avaq]

2. "equivalent" is an appropriate definition of equivalence for the given value.
                                                                          ^^^^^
                                                                            1a

    The definition should ensure that the two values can be safely swapped out in a program that respects abstractions. For example:
                                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                                                                      2a

    - Two lists are equivalent if they are equivalent at all indices.
    - Two plain old JavaScript objects, interpreted as dictionaries, are equivalent when they are equivalent for all keys.
    - Two values are equivalent if they are [referentially transparent](https://en.wikipedia.org/wiki/Referential_transparency).
          ^^^^^^                             ^^^^^^^^^^^^^^^^^^^^^^^^^
            1b                                          2b

    - Two functions are equivalent if they yield equivalent outputs for equivalent inputs.

I feel like we are using a circular definition of equivalence (the examples depend on the definition, and the definition depends on the examples):

1. At a we talk about "value", and then proceed to give a list of examples of values. Yet in the examples we include a definition (at b) of arbitrary "values".
2. To my understanding, the sentence at a describes referential transparency. Yet in one of the examples of this (at b), we refer back to referential transparency.

[paldepind]

I am not familiar with referential transparency as a term that defines equality between two values? The definition I'm familiar with is one similar to the one in the Wikipedia link which defines referential transparency as a property of purely functional programs. Can anyone point towards a definition of referential transparency that fits with how we're using the term here?

Here is an alternative that is precise and which doesn't use any jargon:

"equivalent" means that two values can be safely swapped out in a program. Two values a and b are equivalent if for any pure predicate function p it is the case that p(a) evaluates to true if and only if p(b) evaluates to true. For example:

• Two arrays are equivalent if they are equivalent at all indices.
• Two plain old JavaScript objects are equivalent when they are equivalent for all keys.
• Two promises are equivalent when they yield equivalent values at the same point in time.
• Two functions are equivalent if return equivalent values for equivalent arguments.

The definition of equality I've formulated above is just Liebniz equality which is both a very precise notion of equality and, in my opinion, one that is very intuitive and easy to understand.

[davidchambers]

This pull request has proven controversial, and I'm not currently inclined to spend time and energy resolving the controversy. Feel free to submit a pull request if you believe you can satisfy all parties. :)