DataStore.AUTO.js

// SUMMARY
// 1. New DataStore type will replace the problematic DataStoreType.CACHE
// 2. DataStoreType.CACHE will be deprecated
// 3. The new DataStore type will be called DataStore.AUTO
// 4. DataStoreType.AUTO will be the new default

// AUTO data store creation
// The AUTO data store will favor operations on the network first
// It will only resolve to use the local data store if the network operation cannot complete successfully
var store = DataStore.Collection("workorders", DataStoreType.AUTO, KinveyClient.SharedClient);

// AUTO data store find() operation
// find() operation will attempt to read from the network:
    // If successful, local database is updated with response data
    // If failure, local database find() will be performed to return data to the caller (subject to TTL)
store.find(query);

// AUTO data store save() operation
// save() operation will attempt to write to the network:
    // If successful, local database is updated with response data
    // If failure, local database save() will be performed, and a sync queue entry will be made to represent the failed request
store.save(entity);

// AUTO data store remove() will follow the same pattern as save(), as they are both write operations
store.remove(entity.id);

// Read request
find(query) {
    if (DataStoreType == AUTO) {
        // Build read request
        var networkrequest = buildRequest(query);
        networkrequest.execute() {
            onSuccess(results) {
                localDB.save(results);
            }
            onFailure(error) {
                return localDB.find(query);
            }
        }
    }
}

// Write request
save(entity) {
    if (DataStoreType == AUTO) {
        // Build write request
        var networkrequest = buildWriteRequest(entity);
        networkrequest.execute() {
            onSuccess(result) {
                localDB.save(result);
            }
            onFailure(error) {
                localDB.save(entity);
                syncQueue.save(request);
            }
        }
    }
}

// Caching
// It is possible for a read operation to optionally first look for data in the local database.
// This is subject to a time-to-live number (TTL), which is specified in minutes
// If a TTL is specified (default is to have this value be 0, meaning that the data is considered immediately stale),
// then if the time that the entity is being requested falls within the TTL timeline, it is fetched from the local database.
// Else, it is considered stale (dirty), and a network request is made to retrieve fresh data with which to re-seed the cache.
// TTL is a parameter that exists at the data store level, meaning that each collection can have a separate TTL.
// TTL is a completely client-side concept in this case.

store.setTTL(3600);

// Read request with TTL set
// Read request
find(query) {
    if (DataStoreType == AUTO) {
        // Build read request
        if (isCacheHit()) {
            // entity is still fresh, becuase the last modified time is within the range of current time and TTL
            localDB.find(query);
        } else {
            // entities are considered stale, so fetch from network
            var networkrequest = buildRequest(query);
            networkrequest.execute() {
                onSuccess(results) {
                    localDB.save(results);
                }
                onFailure(error) {
                    return localDB.find(query);
                }
            }
        }
    }
}