feat(relations): allow filtering on existence of nullable relation node (#90)

Author: mattbretl

README.md

@@ -367,6 +367,24 @@ query {
 }
 ```
 
+A node passes the filter if a related node exists *and* the filter criteria for the related node are satisfied. (If a related node does not exist, the check fails.)
+
+The `*Exists` Boolean field can be used to filter on the existence of a related node:
+
+```graphql
+query {
+  allPosts(filter: {
+    personByAuthorIdExists: true
+  }) {
+    nodes {
+      id
+    }
+  }
+}
+```
+
+The `*Exists` Boolean field is only exposed on nullable relations. For example, if the `post.author_id` column is defined as `not null`, a related `person` always exists, so the `personByAuthorIdExists` field is not exposed.
+
 </details>
 
 <details>
@@ -378,13 +396,31 @@ query {
 ```graphql
 query {
   allPeople(filter: {
-    accountByPersonId: { status: { equalTo: ACTIVE } }
+    accountByAccountId: { status: { equalTo: ACTIVE } }
   }) {
     ...
   }
 }
 ```
 
+A node passes the filter if a related node exists *and* the filter criteria for the related node are satisfied. (If a related node does not exist, the check fails.)
+
+The `*Exists` Boolean field can be used to filter on the existence of a related node:
+
+```graphql
+query {
+  allPeople(filter: {
+    accountByAccountId: true
+  }) {
+    nodes {
+      id
+    }
+  }
+}
+```
+
+The `*Exists` Boolean field is only exposed on nullable relations. For example, if the `person.account_id` column is defined as `not null`, a related `account` always exists, so the `accountByAccountIdExists` field is not exposed.
+
 </details>
 
 <details>
@@ -406,32 +442,28 @@ query {
   }) {
     nodes {
       id
-      createdAt
     }
   }
 }
 ```
 
-There is also an `exist` Boolean field for evaluating whether any related objects exist.
+The `*Exist` Boolean field can be used to filter on the existence of related records:
 
 ```graphql
 query {
   allPeople(filter: {
-    postsByAuthorId: {
-      exist: true
-    }
+    postsByAuthorIdExist: true
   }) {
     nodes {
       id
-      createdAt
     }
   }
 }
 ```
 
 </details>
 
-For additional examples, see the [tests](https://github.com/graphile-contrib/postgraphile-plugin-connection-filter/blob/master/__tests__/fixtures/queries/filters.graphql).
+For additional examples, see the [tests](https://github.com/graphile-contrib/postgraphile-plugin-connection-filter/blob/master/__tests__/fixtures/queries/).
 
 ## Plugin Options
 

__tests__/fixtures/queries/relations.graphql

@@ -1,25 +1,37 @@
 query {
-  allSideAs_junctionsBySideAId_exist_true: allSideAs(filter: {junctionsBySideAId: {exist: true}}) { nodes { aId } }
-  allSideBs_junctionsBySideBId_exist_true: allSideBs(filter: {junctionsBySideBId: {exist: true}}) { nodes { bId } }
+  allSideAs_junctionsBySideAIdExist_false: allSideAs(filter: {junctionsBySideAIdExist: false}) { nodes { aId } }
+  allSideAs_junctionsBySideAIdExist_true: allSideAs(filter: {junctionsBySideAIdExist: true}) { nodes { aId } }
+  allSideBs_junctionsBySideBIdExist_false: allSideBs(filter: {junctionsBySideBIdExist: false}) { nodes { bId } }
+  allSideBs_junctionsBySideBIdExist_true: allSideBs(filter: {junctionsBySideBIdExist: true}) { nodes { bId } }
   backwardCompound_name_equalTo_backwardCompound12: allFilterables(filter: {backwardCompoundByBackwardCompound1AndBackwardCompound2: {name: {equalTo: "backwardCompound12"}}}) { ...textConnection }
+  backwardCompoundExists_false: allFilterables(filter: {backwardCompoundByBackwardCompound1AndBackwardCompound2Exists: false}) { ...textConnection }
+  backwardCompoundExists_true: allFilterables(filter: {backwardCompoundByBackwardCompound1AndBackwardCompound2Exists: true}) { ...textConnection }
   backward_name_equalTo_backward2: allFilterables(filter: {backwardByFilterableId: {name: {equalTo: "backward2"}}}) { ...textConnection }
+  backwardExists_false: allFilterables(filter: {backwardByFilterableIdExists: false}) { ...textConnection }
+  backwardExists_true: allFilterables(filter: {backwardByFilterableIdExists: true}) { ...textConnection }
   children_every_name_equalTo_child2: allFilterables(filter: {childrenByFilterableId: {every: {name: {equalTo: "child2"}}}}) { ...childrenConnection }
   children_every_name_startsWith_c: allFilterables(filter: {childrenByFilterableId: {every: {name: {startsWith: "c"}}}}) { ...childrenConnection }
-  children_every_name_startsWith_c_and_exist_true: allFilterables(filter: {childrenByFilterableId: {every: {name: {startsWith: "c"}}, exist: true}}) { ...childrenConnection }
-  children_every_name_startsWith_c_and_exist_false: allFilterables(filter: {childrenByFilterableId: {every: {name: {startsWith: "c"}}, exist: false}}) { ...childrenConnection }
-  children_exist_true: allFilterables(filter: {childrenByFilterableId: {exist: true}}) { ...childrenConnection }
-  children_exist_false: allFilterables(filter: {childrenByFilterableId: {exist: false}}) { ...childrenConnection }
+  children_every_name_startsWith_c_and_childrenExist_true: allFilterables(filter: {childrenByFilterableId: {every: {name: {startsWith: "c"}}}, childrenByFilterableIdExist: true}) { ...childrenConnection }
+  children_every_name_startsWith_c_and_childrenExist_false: allFilterables(filter: {childrenByFilterableId: {every: {name: {startsWith: "c"}}}, childrenByFilterableIdExist: false}) { ...childrenConnection }
   children_some_name_equalTo_child2: allFilterables(filter: {childrenByFilterableId: {some: {name: {equalTo: "child2"}}}}) { ...childrenConnection }
   children_some_name_startsWith_c: allFilterables(filter: {childrenByFilterableId: {some: {name: {startsWith: "c"}}}}) { ...childrenConnection }
-  children_some_name_startsWith_c_and_exist_true: allFilterables(filter: {childrenByFilterableId: {some: {name: {startsWith: "c"}}, exist: true}}) { ...childrenConnection }
-  children_some_name_startsWith_c_and_exist_false: allFilterables(filter: {childrenByFilterableId: {some: {name: {startsWith: "c"}}, exist: false}}) { ...childrenConnection }
+  children_some_name_startsWith_c_and_childrenExist_true: allFilterables(filter: {childrenByFilterableId: {some: {name: {startsWith: "c"}}}, childrenByFilterableIdExist: true}) { ...childrenConnection }
+  children_some_name_startsWith_c_and_childrenExist_false: allFilterables(filter: {childrenByFilterableId: {some: {name: {startsWith: "c"}}}, childrenByFilterableIdExist: false}) { ...childrenConnection }
   children_none_name_equalTo_child2: allFilterables(filter: {childrenByFilterableId: {none: {name: {equalTo: "child2"}}}}) { ...childrenConnection }
   children_none_name_startsWith_c: allFilterables(filter: {childrenByFilterableId: {none: {name: {startsWith: "c"}}}}) { ...childrenConnection }
-  children_none_name_startsWith_c_and_exist_true: allFilterables(filter: {childrenByFilterableId: {none: {name: {startsWith: "c"}}, exist: true}}) { ...childrenConnection }
-  children_none_name_startsWith_c_and_exist_false: allFilterables(filter: {childrenByFilterableId: {none: {name: {startsWith: "c"}}, exist: false}}) { ...childrenConnection }
+  children_none_name_startsWith_c_and_childrenExist_true: allFilterables(filter: {childrenByFilterableId: {none: {name: {startsWith: "c"}}}, childrenByFilterableIdExist: true}) { ...childrenConnection }
+  children_none_name_startsWith_c_and_childrenExist_false: allFilterables(filter: {childrenByFilterableId: {none: {name: {startsWith: "c"}}}, childrenByFilterableIdExist: false}) { ...childrenConnection }
+  childrenExist_false: allFilterables(filter: {childrenByFilterableIdExist: false}) { ...childrenConnection }
+  childrenExist_true: allFilterables(filter: {childrenByFilterableIdExist: true}) { ...childrenConnection }
   forwardCompound_name_equalTo_forwardCompound12: allFilterables(filter: {forwardCompoundByForwardCompound1AndForwardCompound2: {name: {equalTo: "forwardCompound12"}}}) { ...textConnection }
+  forwardCompoundExists_false: allFilterables(filter: {forwardCompoundByForwardCompound1AndForwardCompound2Exists: false}) { ...textConnection }
+  forwardCompoundExists_true: allFilterables(filter: {forwardCompoundByForwardCompound1AndForwardCompound2Exists: true}) { ...textConnection }
   forward_name_equalTo_forward2: allFilterables(filter: {forwardByForwardId: {name: {equalTo: "forward2"}}}) { ...textConnection }
+  forwardExists_false: allFilterables(filter: {forwardByForwardIdExists: false}) { ...textConnection }
+  forwardExists_true: allFilterables(filter: {forwardByForwardIdExists: true}) { ...textConnection }
   parent_name_equalTo_parent2: allFilterables(filter: {parentByParentId: {name: {equalTo: "parent2"}}}) { ...textConnection }
+  parentExists_false: allFilterables(filter: {parentByParentIdExists: false}) { ...textConnection }
+  parentExists_true: allFilterables(filter: {parentByParentIdExists: true}) { ...textConnection }
   # the following should all fail due to null and empty object checks:
   x_backward_name_equalTo_null: allFilterables(filter: {backwardByFilterableId: {name: {equalTo: null}}}) { ...textConnection }
   x_backward_name_null: allFilterables(filter: {backwardByFilterableId: {name: null}}) { ...textConnection }
@@ -33,7 +45,7 @@ query {
   x_children_every_empty: allFilterables(filter: {childrenByFilterableId: {every: {}}}) { ...childrenConnection }
   x_children_null: allFilterables(filter: {childrenByFilterableId: null}) { ...childrenConnection }
   x_children_empty: allFilterables(filter: {childrenByFilterableId: {}}) { ...childrenConnection }
-  x_children_exist_null: allFilterables(filter: {childrenByFilterableId: {exist: null}}) { ...childrenConnection }
+  x_childrenExist_null: allFilterables(filter: {childrenByFilterableIdExist: null}) { ...childrenConnection }
   x_forward_name_equalTo_null: allFilterables(filter: {forwardByForwardId: {name: {equalTo: null}}}) { ...textConnection }
   x_forward_name_null: allFilterables(filter: {forwardByForwardId: {name: null}}) { ...textConnection }
   x_forward_name_empty: allFilterables(filter: {forwardByForwardId: {name: {}}}) { ...textConnection }