groveco/backbone.store

A storage library for Backbone

Backbone Store

Backbone Store is a library for managing and caching data in Backbone applications.

Contributing to Backbone Store

As of v1.0.0 this package is private to Grove Collaborative. It is only published up to Github's packaging service. To declare a dependency on this package, you need to create a personal access token to fetch/publish packages from a private Github packages. I'll try to boil it down to a few steps below:

1. Create a PAT (personal access token) to fetch and publish the package. You should only need to enable the write:packages and delete:packages scopes.

2. Create or edit a ~/.npmrc configuration file to add a new registry entry. Your config should contain the following lines. Make sure to replace {TOKEN} with the PAT you just generated

   //npm.pkg.github.com/:_authToken={TOKEN}
   @groveco:registry=https://npm.pkg.github.com/

3. With the changes present to your ~/.npmrc, you should be able to install the package as a dependency as normal.

---

If you're using @groveco/backbone.store in your own project:

1. Clone this repo locally, e.g.

$> git clone https://github.com/groveco/backbone.store ~/Projects/backbone.store && cd $_
Cloning https://github.com/groveco/backbone.store into ~/Projects/backbone.store
. . .
cd ~/Projects/backbone.store
$> pwd
~/Projects/backbone.store

2. Link your work-tree as the globally installed package:

$> pwd
~/Projects/backbone.store
$> npm link
npm install...
linking @groveco/backbone.store
$> npm ls --global --depth=0
/path/to/global/node_modules
├── @groveco/[email protected] -> ~/Projects/backbone.store
├── [email protected]
└── [email protected]

3. Link the globally linked version of backbone.store in the work-tree of the project that is consuming backbone.store:

$> pwd
~/Projects/backbone.store
$> pushd ../other-project ## e.g. `groveco/grove`
~/Projects/other-project  ~/Projects/backbone.store
$> npm link @groveco/backbone.store
~/other-project/node_modules/@groveco/backbone.store -> /path/to/global/node_modules/@groveco/backbone.store -> ~/Projects/backbone.store

4. Switch back to your local clone of groveco/backbone.store and get to work!

$> pwd
~/Projects/other-project
$> popd
~/Projects/backbone.store

5. Run npm run build to recompile the library:

$> pwd
~/Projects/backbone.store
$> npm run build

> @groveco/[email protected] build ~/Projects/backbone.store
> babel src --out-dir dist

src/camelcase-dash.js -> dist/camelcase-dash.js
src/collection-proxy.js -> dist/collection-proxy.js
src/http-adapter.js -> dist/http-adapter.js
src/index.js -> dist/index.js
src/internal-model.js -> dist/internal-model.js
src/json-api-parser.js -> dist/json-api-parser.js
src/model-proxy.js -> dist/model-proxy.js
src/repository-collection.js -> dist/repository-collection.js
src/repository.js -> dist/repository.js
src/store.js -> dist/store.js

$> tree dist/
dist
├── camelcase-dash.js
├── collection-proxy.js
├── http-adapter.js
├── index.js
├── internal-model.js
├── json-api-parser.js
├── model-proxy.js
├── repository-collection.js
├── repository.js
└── store.js

0 directories, 10 files

6. Rebuild other-project to pick up the changes to backbone.store

Bonus: Run npm run build:watch to rebuild when any file updates. If your other-project build is also watching for filesystem changes, the rebuild in backbone.store will trigger it as well.

Caveat: Running npm install in other-project will destroy the link that you made in Step 3 above, so if your build process runs npm install, you'll have to rerun npm link per Step 3 after the build starts... or pass --link to npm install.

Using Backbone Store

Defining models

Backbone Store provides relational models structure. To define relations between models use relatedModels and relatedCollections fields in Backbone.Model.

For instance we have blogs with comments:

import Backbone from 'backbone'

let Blog = Backbone.Model.extend({
  relatedCollections: {
    comments: 'comment'
  }
});

let Comment = Backbone.Model.extend({
  relatedModels: {
    blog: 'blog'
  }
});

Here in relatedModels and relatedCollections objects keys are fields in model where we can find location of related model/collection (id or url). Values are types of related model.

Adapter

Adapter is a thing which knows how to manipulate with data on server (or even other sources in general). Currently there is HttpAdapter which manipulates data with server over HTTP.

Parser

Parser is class which parses data from server from specific format to Backbone Store format and vice versa. Currently there is JsonApiParser which parses data from JSON API format.

Repository

Repository is used to provide access to data and cache data on front-end to prevent same multiple requests.

That's how you create a repository with adapter and parser:

import BackboneStore from 'backbone.store'
import BlogModel from './path/to/blog-model'

let parser = new BackboneStore.JsonApiParser();
let adapter = new BackboneStore.HttpAdapter('/api/blog/', parser);
let repo = new BackboneStore.Repository(BlogModel, adapter);

backbone.store's Issues

Network should be alowed to mutate multiple resources

This one is very important, but I am having trouble articulating the issue. If this isn't clear, let me know!

The way backbone.store is currently designed, an instance of a Repository does not have any ability to update other repositories. This is wrong. I mentioned in #12 that the data API should be exposed on the Store, not the Repository, for this very reason. There are very common cases where a fetch of a single resource will lead to an update (or creation) of multiple other resources, even of various types. Here is an example, pseudo code warning:

Client fetches a customer for the first time

let customer = store.get('customer', '/api/customer/236')

Networks responds 200 OK with this payload

{
  "data": {
    "id": 236,
    "type": "customer",
    "attributes": {
      "email": "[email protected]"
    },
    "relationships": {
      "pantry": {
        "data": {"id": 241, "type": "pantry"}
      },
    }
  },
  "included": [
    {
      "id": 241,
      "type": "pantry",
      "attributes": {
        "has-valid-card": true,
        "is-active": true
      }
    }
  ]
}

Two resources are created, the customer, and the pantry. So, I can do this:

customer.then(customer => {
  customer.getRelationship('pantry').then(pantry => {
    // resolves immediately because the resource already exists

    pantry.get('has-valid-card') // true
    pantry.get('is-active') // true
  })
})

So that demonstrated that a single network response may contain various disparate resources, and they all should be managed equally by the store.

Remove or relocate demo app

Move all the actual code and tests into a lib/ folder and place all the demo files in example/. Let's make this a first class repo.

Allow fetching with includes

UMD support

@noazark Could you please take a look at how I've implemented UMD support via gulp-wrap. It's pretty hacky. Let me know if you have a better idea for UMD support.

Rename repo

Something like backbone.json-api-store or something boring! I don't really care what the name is, just something else.

Duplicated requests

When we send 1 request for a resource and then send second one before first request is completed we send 2 requests for the same resource

Use RSVP.js instead of native promises

http://caniuse.com/#feat=promises

^ Reason why.

Public data API belongs on Store, not Repository

I believe we've talked about this before, pardon me if I'm bringing up a closed matter. I do still think that we should expose the data API publicly on the instance of Store, not Repository. The primary reason for this is a cleaner API, but also I think there are some nice Architectural wins.

Proposal:

// instead of this
let repo = store.getRepository('customer')
repo.get('/api/customer/236')

// do this
store.get('customer', '/api/customer/236')

Some more examples of a fuller data API:

store.push({
  data: {
    type: 'customer',
    id: 123,
    attributes: {
     foo: 'bar'
    }
  }
})
store.create('customer', {foo: 'bar'})
store.modelFor('customer')

Architecturally I don't think a public Repository is very useful. They are simple dumb arrays of models. Where the real power of the Store comes from is it's own instance! The store marshals objects to and from the client, understands how to fetch and parse data, and synchronizes changes to models. I don't think any of these things can really be done on a single Repository instance alone. I will be making issues to address these issues.

store.build() should return a model proxy

Move type-id identifier building to one place

We have smth like model.get('_type')__model.id in several places. Move it to a module/function.

What to do about URLs

One of the strongest core concepts of JSON API is hyper linking. In all hypermedia APIs, like HTTP, the client only needs to know of a single entry point URL, and nothing else. So, it seems odd to me that our adapter treats resource links as an alternative to some predefined url. I think we should stop registering urls with the adapter, and rewrite the adapter get methods to prioritize links and accept a url as a fallback.

Here's an example of what we are currently doing:

// damn this is a lot of boilerplate!
let Customer = Model.extend()
let parser = new JsonApiParser();
let adapter = new HttpAdapter('/api/customer/', parser);
let repository = new Repository(Customer, adapter);

store.register('customer', repository);

let repo = store.getRepository('customer');
repo.get(236).then(customer => {
  // ...
})

What I think we could do to make this better:

let Customer = Model.extend()
let parser = new JsonApiParser();
let adapter = new HttpAdapter(parser);
let repository = new Repository(Customer, adapter);

store.register('customer', repository);

let repo = store.getRepository('customer');
repo.get('/api/customer/236/').then(customer => {
  // ...
})

Advantages to this, as I see them:

• Parser and Adapter are not unique instances for each model, rather they are shared instances on all models
• Encourages hyper-linking over client-side URL building
• Eliminates a whole category of configuration (the server-side API endpoints)

`Store#register(name, model)`

Store#register should take a name and a model not a repository (the store should build that).

reference:

backbone.store/src/store.js

Lines 126 to 128 in aae26e1

	register(modelName, repository) {
	this._repositories[modelName] = repository;
	}

Related: #12