Require Cache.EvictOptions when calling cache.evict.

[benjamn]

We've been finding lately that named options APIs are much easier to work with (and later to extend), because you can think about the different options independently, and future additions of new named options tend to be much less disruptive for existing code.

Since we're approaching a major new version of Apollo Client (3.0), and the cache.evict method did nothing in AC2 anyway, there's no sense preserving the alternate API with positional arguments, now that we support Cache.EvictOptions.

In other words, this is definitely a breaking change, but only for those who have been using using the @apollo/client betas. Thank you for your patience and understanding; we know changes like this can be annoying if you were using cache.evict heavily, but we think the uniformity of always requiring Cache.EvictOptions will be simpler and more flexible in the long run.

Here's a cheatsheet for updating your code:

// Old:
cache.evict(id);
cache.evict(cache.identify(obj));
// New:
cache.evict({ id });
cache.evict({ id: cache.identify(obj) });

// Old:
cache.evict(cache.identify(obj), fieldName);
// New:
cache.evict({
  id: cache.identify(obj),
  fieldName,
});

// Old:
cache.evict("ROOT_QUERY", fieldName);
// New (either way works):
cache.evict({ id: "ROOT_QUERY", fieldName });
cache.evict({ fieldName });

// Old:
cache.evict(id, fieldName, args);
// New:
cache.evict({ id, fieldName, args });

[benjamn]

This comment was a bit of a tell, in hindsight.

[benjamn]

This is important now that options.id can be omitted as a way to default to the ROOT_QUERY ID.

Here's the equivalent logic from cache.modify:

  public modify(options: ModifyOptions): boolean {
    if (hasOwn.call(options, "id") && !options.id) {
      // To my knowledge, TypeScript does not currently provide a way to
      // enforce that an optional property?:type must *not* be undefined
      // when present. That ability would be useful here, because we want
      // options.id to default to ROOT_QUERY only when no options.id was
      // provided. If the caller attempts to pass options.id with a
      // falsy/undefined value (perhaps because cache.identify failed), we
      // should not assume the goal was to modify the ROOT_QUERY object.
      // We could throw, but it seems natural to return false to indicate
      // that nothing was modified.
      return false;
    }

[hwillson]

Awesome @benjamn 👍!