These are the configuration options available for customizing each instance of AngularCache. They can be used in three places:

Setting the default options for all caches

$angularCacheFactoryProvider.setCacheDefaults({
    // configuration options
});

See $angularCacheFactoryProvider.setCacheDefaults(options)

Creating a cache

$angularCacheFactory('newCache', {
    // configuration options
});

See $angularCacheFactory(cacheId, options)

Dynamically configuring a cache

newCache.setOptions({
    // configuration options
});

See AngularCache.setOptions(options, strict)

Type: number (milliseconds)

Default: null

Description: Set a default maximum lifetime on all items added to the cache. They will be removed aggressively or passively or not at all depending on the value of deleteOnExpire (see below). Can be configured on a per-item basis for greater specificity.

Usage:

$angularCacheFactory('newCache', {
    maxAge: 3600000
});

Can be configured on a per-item basis:

newCache.put('someKey', 'someValue', {
    maxAge: 90000 // overrides the maxAge for "newCache"
});

Type: string

Default: "none"

Description: Specifies what should happen when an item expires. maxAge must be set in order for "passive" or "aggressive" to have any effect. Can be configured on a per-item basis for greater specificity.

Possible Values:

• "none" - Items will not be removed from the cache even if they have expired.

• "passive" - Items will be deleted if they are requested after they have expired, resulting in a miss.

• "aggressive" - Items will be deleted as soon as they expire.

Usage:

$angularCacheFactory('newCache', {
    maxAge: 3600000,
    deleteOnExpire: 'aggressive'
});

Can be configured on a per-item basis:

newCache.put('someKey', 'someValue', {
    maxAge: 90000,
    deleteOnExpire: 'passive' // overrides the maxAge for "newCache"
});

Type: number (milliseconds)

Default: 1000

Description: How often the cache should check for expired items. Only used when maxAge is set.

Usage:

$angularCacheFactory('newCache', {
    maxAge: 3600000,
    recycleFreq: 10000 // check for expired items every 10 seconds
});

Type: function

Default: null

Description: A callback function to be executed when an item expires.

Usage:

Using 'onExpire' in passive delete mode

In passive delete mode the cache doesn't know if an item has expired until the item is requested, at which point the cache checks to see if the item has expired. If the item has expired then it is immediately removed from the cache, resulting in a "miss".

If you specify a global "onExpire" callback function, the cache will execute this function when it is discovered the item has expired, passing to the callback the key and value of the expired item.

When you actually request the expired item via myCache.get('someKey') you can also pass a second argument to get() specifying a callback that your cache's "onExpire" callback can execute when it finishes. For example:

var newCache = $angularCacheFactory('newCache', {
    maxAge: 1000, // Items expire after 1 second, but we don't know it until the item is requested
    onExpire: function (key, value, done) {
        // "onExpire" callback for the cache.
        // The third optional parameter "done", is the second argument passed to `get()` as described above

        console.log(key + ' expired!');
        // Retrieve fresh value for "key" from server, of course you'll need to figure out
        // what the url is if key != url
        $http.get(key).success(function (data) {
            $angularCacheFactory.get('newCache').put(key, data);
            done(key, data); // Execute the "done" callback specified in the `get()` call
        });
    });
});

newCache.put('denver', 'broncos');

// wait a few seconds

var value = newCache.get('denver', {
    onExpire: function (key, value) {
        // here value is defined, because the global onExpire callback just retrieved it from the server
    }
});
// here value is undefined because the item withx
// the key "denver" has expired and was deleted from the
// cache when we requested it. The callback passed to
// "get()" will receive the new value for 'denver' which
// will be retrieved from the server. This callback
// is the "done" callback executed by the "onExpire"
// callback specified when we created the cache.

Another example:

// We don't specify an "onExpire" callback for this cache
var newCache = $angularCacheFactory('newCache', {
    maxAge: 1000, // Items expire after 1 second, but we don't know it until the item is requested
});

newCache.put('denver', 'broncos');

// wait a few seconds

// In this cache the callback is immediately executed when
// the cache discovers that 'denver' has expired, and the
// callback is passed the key and value of the expired item.
// Here you could retrieve a new value for 'denver' from
// the server or decide to keep the old value and re-insert
// it into the cache. Specifying an "onExpire" callback for
// the cache is a good way to stay DRY.
var value = newCache.get('denver', {
    onExpire: function (key, value) {
        if (isGoodThisYear(key, value)) {
            newCache.put(key, value);
        } else {
            $http.get(key).success(function (data) {
                newCache.put(key, data);
            });
        }
    }
});

Using 'onExpire' in aggressive delete mode

In aggressive delete mode you can't pass a second parameter to get() because your "onExpire" callback for the cache has already been executed for expired items.

Usage:

var newCache = $angularCacheFactory('newCache', {
    maxAge: 1000, // Items expire after 1 second and are immediately deleted
    onExpire: function (key, value) {
        // "onExpire" callback for the cache.
        // The third optional parameter "done", is the second argument passed to `get()` as described above

        console.log(key + ' expired!');
        // Retrieve fresh value for "key" from server, of course you'll need to figure out
        // what the url is if key != url
        $http.get(key).success(function (data) {
            $angularCacheFactory.get('newCache').put(key, data);
        });
    });
});

newCache.put('denver', 'broncos');

// wait a few seconds, during which time the "onExpire" callback is automatically executed

newCache.get('denver'); // 'broncos' or whatever was returned by the server in the "onExpire" callback

Type: number (milliseconds)

Default: null

Description: Set the cache to periodically clear itself.

Usage:

$angularCacheFactory('newCache', { cacheFlushInterval: 3600000 }); // clear the cache every hour

Type: string

Default: "none"

Description: Configure the cache to sync itself with localStorage or sessionStorage. The cache will re-initialize itself from localStorage or sessionStorage on page refresh. See Using angular-cache with localStorage.

Possible Values:

• "none" - The cache will not sync itself with web storage.

• "localStorage" - Sync with localStorage

• "sessionStorage" - Sync with sessionStorage

Usage:

$angularCacheFactory('newCache', {
    storageMode: 'localStorage', // this cache will sync itself to localStorage
    verifyIntegrity: true
});

Type: object

Default: null

Description: When storageMode is set to "localStorage" or "sessionStorage" angular-cache will default to using the global localStorage or sessionStorage object.

storageImpl provides angular-cache an implementation of localStorage or sessionStorage. This is useful when you don't want to override the global storage objects or when using angular-cache in a browser that doesn't support localStorage or sessionStorage.

Note: If angular-cache doesn't detect a global localStorage or sessionStorage and you don't provide a polyfill, then syncing with web storage will be disabled. It is up to the developer to provide a polyfill for browsers that don't support localStorage and sessionStorage. Any implementation of localStorage and sessionStorage provided to angular-cache must implement at least the setItem, getItem, and removeItem methods.

See Using angular-cache with localStorage.

Usage:

$angularCacheFactory('newCache', {
    storageImpl: mystorageImplementation,
    storageMode: 'localStorage'
});

$angularCacheFactory('otherCache', {
    storageImpl: mySessionStorageImplementation,
    storageMode: 'sessionStorage'
});

Type: boolean

Default: true

Description: Specify whether to verify integrity of data saved in localStorage on every operation. If true, angular-cache will perform a full sync with localStorage on every operation. Increases reliability of data synchronization, but may incur a performance penalty. Has no effect if storageMode is set to "none".

Usage:

$angularCacheFactory('newCache', {
    storageMode: 'localStorage',
    verifyIntegrity: true
});

Type: boolean

Default: false

Description: Disabled the cache. The cache will continue to function as normal, aside from the fact that any calls to AngularCache#put(key, value[, options]) or AngularCache#get(key[, options]) will have no effect whatsoever.

Usage:

var newCache = $angularCacheFactory('newCache', { disabled: true }); // This cache starts disabled

newCache.put('4', 'thing');

newCache.get('4'); // undefined, because the cache is disabled