AsyncCache does not invalidate cache, if invalidate is called from inside fetch

[aanelson]

Steps to reproduce

    final cache = AsyncCache<void>(const Duration(seconds: 1));
    Future<void> function() async {
      debugPrint('called function');
      cache.invalidate();
    }

    await cache.fetch(function);
    await cache.fetch(function);
    await cache.fetch(function);

Expected results

It should clear results. It would print 'called function' three times.

At the very least the documentation should mention this behavior.

Actual results

It caches based on the timer. In the above code it would print a single 'called function'.

[lrhn]

That behavior looks correct and expected.

The function here calls cache.invalidate(); synchronously, before returning a Future.

The cache value is not set until the function has returned a value. Before that, there is no value to set the cache to.
Invalidating the cache before function returns does nothing, since it's already invalidated, otherwise it wouldn't have called function to begin with.

Not sure where to document that, other than saying "calling invalidate has no effect if there is no current value", which should be obvious.

If you want a cache that is immediately invalidated after its future has completed, use an ephemeral cache.

[aanelson]

That makes sense why it is happening, but still feels like a trap.

The example provided in the documentation is the following

final _usersCache = new AsyncCache<List<String>>(const Duration(hours: 1));

/// Uses the cache if it exists, otherwise calls the closure:
Future<List<String>> get onlineUsers => _usersCache.fetch(() {
  // Actually fetch online users here.
});

Most developers, myself included, would follow that code then realize that they do not want to cache a failed request for a hour. Thereafter modifying it to be the following, which would hit this issue.

final _usersCache = new AsyncCache<List<String>>(const Duration(hours: 1));

/// Uses the cache if it exists, otherwise calls the closure:
Future<List<String>> get onlineUsers => _usersCache.fetch(() {
try {
  // Actually fetch online users here.
} catch (e) {
 _userCache.invalidate();
rethrow;
}
});

Having an example of proper usage there would probably help.

final _usersCache = new AsyncCache<List<String>>(const Duration(hours: 1));

/// Uses the cache if it exists, otherwise calls the closure:
  Future<List<String>> get onlineUsers {
    try {
      return await _usersCache.fetch(() {
        // Actually fetch online users here.
      });
    } catch (e) {
      _usersCache.invalidate();
      rethrow;
    }
  }

or

Future<List<String>> get onlineUsers => _usersCache.fetch(() {
  // Actually fetch online users here.
}) ..onError((e, s) {
              _usersCache.invalidate();
              throw e as Exception;
            });