Document equality operators and prepare release (#281)

* Document equality operators and prepare release

* Apply suggestions from code review

Co-authored-by: Sigurd Meldgaard <[email protected]>

---------

Co-authored-by: Sigurd Meldgaard <[email protected]>

Author: jonasfj

typed_sql/CHANGELOG.md

@@ -1,4 +1,4 @@
-## 0.1.2-wip
+## 0.1.2
  * Support for _composite foreign keys_ using the `@ForeignKey` annotation.
  * Extension methods for joining table using _foreign keys_.
 

typed_sql/doc/03_writing_queries.md

@@ -644,12 +644,15 @@ The following is a high-level reference of _some_ of the available
 _extension methods_:
 
  * `Expr<T?>`, when `T` is one of `bool`, `int`, `double`, `String`, `DateTime`, has:
-    * `.equals(Expr<T?> other) -> Expr<bool>`
-    * `.notEquals(Expr<T?> other) -> Expr<bool>`
+    * `.equals(Expr<T> other) -> Expr<bool>`
+    * `.equalsUnlessNull(Expr<T?> other) -> Expr<bool?>`
+    * `.isNotDistinctFrom(Expr<T?> other) -> Expr<bool>`
     * `.isNull() -> Expr<bool>`
     * `.isNotNull() -> Expr<bool>`
     * `.orElse(Expr<T> other) -> Expr<T>`
     * `.asNotNull() -> Expr<T>`
+ * `Expr<T>`, when `T` is one of `bool`, `int`, `double`, `String`, `DateTime`, has:
+    * `.equals(Expr<T?> other) -> Expr<bool>`
  * `Expr<bool>`, has:
     * `.not() -> Expr<bool>` (also available as operator `~`)
     * `.and(Expr<bool> other) -> Expr<bool>` (also available as operator `&`)
@@ -694,6 +697,58 @@ The reference above, deliberately omits variations such as
 `.<method>Value(...)` and `.not<method>(...)` because they are merely
 convinience functions.
 
+### Equality operators
+In the previous reference there are 3 equality operators:
+
+| `package:typed_sql`      | Return type   | SQL equivalent             | `NULL` compared to `NULL`? |
+|--------------------------|---------------|:--------------------------:|:--------------------------:|
+| `a.equals(b)`            | `Expr<bool>`  | `a = b`                    | N/A                        |
+| `a.equalsUnlessNull(b)`  | `Expr<bool?>` | `a = b`                    | `NULL`                     |
+| `a.isNotDistinctFrom(b)` | `Expr<bool>`  | `a IS NOT DISTINCT FROM b` | `TRUE`                     |
+
+The difference between these operators is what arguments they take, and how they
+behave when comparing to `NULL`. In SQL `NULL = NULL` yields `UNKNOWN`
+represented by `NULL`. Meaning that when we compare two expressions in SQL using
+the `=` operator, the result cannot be `TRUE` if one of the expressions is `NULL`.
+This is very different from Dart. Thus, to avoid any confusion the SQL `=`
+operator is exposed using the `.equalsUnlessNull` extension method.
+
+The `.equalsUnlessNull` extension method will return `NULL` if any of the two
+operands are `NULL`, thus, the return type for `.equalsUnlessNull` is
+`Expr<bool?>`. This isn't very convenient, but if you're comparing two
+expressions where one of them is not nullable, you can use the `.equals`
+extension method.
+
+The `.equals` extension method requires that at least one of the two operands
+are not nullable. This is implemented by having two variants:
+ * `Expr<T>.equals(Expr<T?> other) -> Expr<bool>`, and,
+ * `Expr<T?>.equals(Expr<T> other) -> Expr<bool>`.
+
+Thus, when using the `.equals` extension method the return type is `Expr<bool>`,
+and the SQL operator used is `=`. The downside is that you cannot compare two
+nullable expressions. If you wish to compare two nullable expressions you can use
+`.isNotDistinctFrom` which has the same semantics as Dart, meaning that
+`NULL IS NOT DISTINCT FROM NULL` evaluates to `TRUE`. Or you can use
+`.equalsUnlessNull` if you want SQL semantics, where `NULL = NULL` evaluates to
+`NULL`.
+
+If you wish to compare two nullable expressions in manner where `NULL = NULL`
+evaluates to `FALSE`, you can use `a.equalsUnlessNull(b).orElseValue(false)`.
+Or you can do `a.isNotDistinctFrom(b) & a.isNotNull()`.
+
+> [!TIP]
+> While it is tempting to always use `.isNotDistinctFrom`, which has the same
+> comparison semantics as equality in Dart, there are many scenarios where
+> database engines are optimized for the `=` operator in SQL.
+> And if you are joining tables you'll
+> often find that you do not want to join two rows when the key in both tables
+> is `NULL`.
+>
+> Thus, whenever you find that the `.equals` extension method doesn't work,
+> because you are comparing two nullable expressions, do consider if you want
+> the `NULL = NULL` to be `TRUE` or `FALSE`, before resorting to use
+> `.isNotDistinctFrom`.
+
 
 ## Query reference
 The following is a high-level overview of the most important extension methods

typed_sql/pubspec.yaml

@@ -1,5 +1,5 @@
 name: typed_sql
-version: 0.1.1
+version: 0.1.2
 description: Package for doing SQL with some type safety.
 homepage: https://github.com/google/dart-neats/tree/master/typed_sql
 repository: https://github.com/google/dart-neats.git