v2 usage

Hi raix, I'm looking at your current grounddb-caching-2016 branch and hoping to come up with a recommendation for the Guide for offline data with Meteor 1.3.

Common use cases

Are these the two most common reasons why a dev might want to persist data?

1. Ability to load page while offline and still read data
2. Ability to change the data while offline and sync up when online
3. Ability to render a data-filled page sooner during an online pageload (instead of waiting for a subscription to be ready)

For 2, Meteor sends outstanding methods on reconnect, but this package no longer persists them across reloads. There is also no direct syncing of changes from the cached collection to the server collection on reconnect. You can call update on a Ground.Collection, but you'd have to either do your own syncing logic, or be building an app that didn't need syncing, eg an account-less todo list app that only saves data on your browser.

Offline reading

For 1 and 3, I think the easiest and most generally-applicable method would be for entire normal collections to just work / appear to have data. For 1, you'd use the appcache package and the below?

const Lists = new Mongo.Collection('Lists');
const ListsCache = new Ground.Collection('ListsCache');

// Cache Lists
ListsCache.observeSource(Lists.find()); 

Meteor.subscribe('lists.public')

Lists.find = function(...args) {
  return ListsCache.find(...args);
};

Lists.findOne = function(...args) {
  return ListsCache.findOne(...args);
};

// reload page, and Lists.find() returns data even though the Mongo.Collection 
// is empty, and doesn't hydrate

Jumpstart template rendering

And for 3, instead of Template.subscriptionsReady:

{{#if Template.subscriptionsReady}}
  {{> Template.dynamic template=main}}
{{else}}
  {{> App_loading}}
{{/if}}

https://guide.meteor.com/ui-ux.html#subscription-readiness

we'd need a different helper, like listsDataReady:

Template.foo.helpers({
  listsDataReady() {
    const cachedDataAvailable = !! Lists.findOne()
    return cachedDataAvailable || Template.subscriptionsReady()
  }
})

Cache size

When should we recommend trimming the cache?

At some point you'll hit quota, but there's not a good way to tell in advance (see this localForage issue). Perhaps we could listen for quota exceeded errors and call a user-provided a hook?

Ground.onQuotaExceeded(() => {
  ListsCache.keep(Lists.find());
});

Is hitting quota at all likely? How many moderate-size docs would it take to fill eg 10MB? (quotas are dynamic and across the board, but 10MB seems on the low end)

Are there other drawbacks to a large cache size? I'd guess for IndexedDB and SQL, queries wouldn't slow down much with data size like they do with minimongo?

The conservative approach would be trimming on subscription ready:

Meteor.subscribe('lists.public', () => {
  ListsCache.keep(Lists.find())
});

Start by reviewing Ground.Collection, observeSource, Meteor.subscribe, and the Template helper examples in the issue. Define the intended v2 behavior for offline reads, reconnect syncing, cache quota handling, and subscription readiness before identifying implementation and test locations; the issue is complete only when those recommendations and behaviors are settled.