Document handling of `null` literals

I’d like to add something like the following to README.md. Feedback on the language (or the design decision itself) would be much appreciated.

tl;dr This plugin ignores all null literals and empty objects passed via GraphQL queries. Queries such as filter: { field: null } and filter: { field: { equalTo: null } } will not filter the dataset.

GraphQL draws a distinction between including a field with a null literal value and omitting the field (see Section 2.9.5 of the spec). Servers must be prepared to handle either type of input, and can decide whether to process them differently.

In the context of a traditional CRUD update mutation, the semantics of the null literal are well understood: null clears the value in the database.

In the context of this plugin, a case could be made for inputs such as { field: null } to be interpreted as a where clause of field IS NULL. But equating null with SQL NULL quickly breaks down. Should filter: { field: { equalTo: null } } resolve to field = NULL or field IS NULL, or should it be ignored?

It gets more complicated when filtering across relations. Should { account: null } Where there is a related table named account, should { account: null } check that no related rows exist in the account table, or should it be ignored?

Rather than relying on documenting these clever uses of null, this plugin keeps it simple: null-valued fields are ignored. (Use the isNull operator for null value checks.)

The same goes for passing empty objects to input object fields: they are ignored.

See the tests for examples.

As a nice side effect of this approach, you never have to worry about null vs. undefined (or {} vs. null vs. undefined for input object fields) when building your GraphQL query variables in client-side code.

[mattbretl]

As a superficial comment (not considered this deeply), all of the above should return an unfiltered collection - they should be equivalent to not specifying a filter.

https://github.com/graphile-contrib/postgraphile-plugin-connection-filter/blob/071b096a4d254fa8fc6f196f034821806cbe4511/__tests__/fixtures/queries/connections-filter.null-and-empty.graphql#L1 😉

I would still prefer a server side error than it being silently ignored

Fair enough. There’s a valid case for both “throw” and “ignore”, so I’ll expose it as an option. Regarding the default:

• With “throw”, it will feel broken to users accustomed to passing null inputs that are ignored.

• With “ignore”, the queries will succeed but the result may not be what the user expected.

I’m leaning toward “throw”, so that anyone passing null/{} hits a wall and has to decide how to handle it. They can either stop using null/{}, or opt-in to the “ignore all null/{}” behavior.

[syndesis]

Perhaps mention the new options in the error message?