Backbone.Store

A store for keeping unique instances of Backbone models with ease.

Usage

Instantiating models

When creating a new model, if that model is already being tracked, you will be returned the original model instance.

var StoredUser = Backbone.Store(User);

var first  = new StoredUser({ id: 1, name: 'Jean Grey' });
var second = new StoredUser({ id: 1, name: 'Jean Summers' });

first === second; // true
first.get('name') === 'Jean Summers'; // true

Store will also update the attributes of the instance to reflect the latest state.

Working with collections

Backbone.Store also guarantees that instances created through a collection (e.g. via fetch) are also unique.

var UserCollection = Backbone.Collection.extend({
  model: StoredUser
});

var users = new UserCollection([
  { id: 2, name: 'Henry McCoy' },
  { id: 3, name: 'Bobby Drake' }
]);

var user = new StoredUser({ id: 2, name: 'Henry McCoy' });
user === users.get(2); // true

API

If you need additional control, Store exposes additional API and events.

Store

Store contains only static methods as has no instance methods or constructor.

Store(Model, [modelName])

Returns a Stored Model defintion. If modelName is not given a unique generate name will be used.

Store.ModelCache

ModelCache definition used internally. Useful for overriding and extending.

Store.add(Model, modelName)

Adds a ModelCache for the Model definition by modelName to the store. Returns the ModelCache for the Model definition.

Store.getCache(modelName)

Returns a ModelCache by name.

Store.getAllCache()

Returns all ModelCache instances by name.

Store.get(modelName)

Returns a Model definition by name.

Store.find(modelName, id)

Returns a cached model instance by id, or undefined if the model is not cached. The id is normalized with String(id), so 1 and "1" resolve to the same cached model. null and undefined ids return undefined.

Store.has(modelName, id)

Returns true when a model instance is cached by id. null and undefined ids return false.

Store.patch(modelName, id, attrs, [options])

Updates an existing cached model with model.set(attrs, options). Returns the patched model, or undefined when the id is not cached. This is the option-aware update API; duplicate construction still preserves the original behavior and calls set(attrs) without options.

Store.evict(modelName, id)

Removes one cached model without destroying it. Returns the evicted model, or undefined when the id is not cached. This triggers the Store remove event for the evicted model.

Store.inspect(modelName, id)

Returns { modelName, id, key, cached, model }. id is the caller-supplied id, key is the normalized cache key, and model is the live Backbone model reference or undefined. For null and undefined ids, key is undefined, cached is false, and model is undefined. When called by object-formatting tools as .inspect(depth, options), returns a short Store label instead of treating depth as a model name.

Store.getAll()

Returns all Model definitions by name.

Store.reset(modelName)

Clears all cached and pending models for one modelName while keeping the registered Model definition. This detaches Store-owned listeners and does not trigger remove or reset events.

Store.resetAll()

Clears all cached and pending models for every registered Model definition. This keeps the registered Model definitions and does not trigger remove or reset events.

Store.remove(modelName)

Removes a ModelCache from Store by name. This detaches Store-owned listeners and does not trigger remove or reset events.

Store.removeAll()

Removes the entire cache. This detaches Store-owned listeners and does not trigger remove or reset events.

Store examples

import Store from `backbone.store`;

const StoredModel = Store(Backbone.Model, 'myModel');

const StoredMyModel = Store.get('myModel');

console.log(StoredModel === StoredMyModel); // true

const MyModelCache = Store.getCache('myModel');

console.log(StoredModel ===  MyModelCache.ModelConstructor); // true

const Models = Store.getAll();

console.log(StoredModel === Models.myModel.modelConstructor);

All APIs that take modelName throw the same error as Store.getCache(modelName) when the model name is not recognized. Calling StoredModel.extend(...) still delegates to Backbone's inherited extend; the returned child constructor is not automatically registered with Store unless it is passed through Store(childModel, modelName).

Store Events

add

Triggered when a new instance is added to a ModelCache This event gets the instance and the ModelCache instance passed to it.

// Clean cache
Store.removeAll();

Store.on('add', function(instance, ModelCache) {
  console.log('model added');
});

// logs "model added"
new StoredUser({ id: 1 });

const newUser = new StoredUser();

// logs "model added"
newUser.set({ id: 5 });

update

Triggered when a cached instance is returned. Any data instantiated updates the cached instance. This event gets the instance and the ModelCache instance passed to it.

// Clean cache
Store.removeAll();

Store.on('update', function(instance, ModelCache) {
  console.log('model updated: ' + instance.get('name'));
});

const user = new StoredUser({ id: 1 });

// logs "model updated: bob"
const user2 = new StoredUser({ id: 1, name: 'bob' });

remove

Triggered when an instance is removed from a ModelCache. This event gets the instance and the ModelCache instance passed to it.

// Clean cache
Store.removeAll();

Store.on('remove', function(instance, ModelCache) {
  console.log('model removed');
});

const user = new StoredUser({ id: 1 });

// logs "model removed"
user.destroy();

ModelCache

ModelCache instances will be created for each Model added to the Store. When a model instance is destroyed it will be removed automatically.

Instances will have four properties:

• instances - an object with each instance of the cache's Model
• Model - the original model defintion of the cache.
• modelName - the name the cache is stored as on the Store.
• ModelConstructor - the unique model definition return by the store.

get(attrs, options)

If the instance by index is not cached it is instantiated, cached, and returned. Otherwise it returns the cached instance and sets the attrs on the model. The options passed to this method will pass through only when a new model is instantiated. Use patch(id, attrs, options) when cached updates need set options.

remove(instance)

Removes the model instance from the cache.

find(id), has(id), patch(id, attrs, [options]), evict(id), inspect(id), reset()

ModelCache-level primitives backing the Store APIs of the same names.

Acknowledgments

Backbone.Store is heavily inspired by Backbone.UniqueModel written by Ben Vinegar

===

This library is © 2020 RoundingWell. Distributed under MIT license.