js-data

js-data

js-data is a framework-agnostic, datastore-agnostic ORM/ODM for Node.js and the Browser.

Adapters allow js-data to connect to various data sources such as Firebase, MySql, RethinkDB, MongoDB, localStorage, Redis, a REST API, etc. With js-data you can re-use your data modeling code between environments, keep your data layer intact when transitioning between app frameworks, and work with a unified data API on the server and the client. js-data employs conventions for rapid development, but allows for endless customization in order to meet your particular needs.

To get started, visit http://js-data.io.

Table of contents

• Quick start
• Background
• Dependencies
• Guides and Tutorials
• API Reference Docs
• Community
• Support
• Contributing
• License

Quick Start

This example shows setting up js-data to use the Http adapter in the browser:

npm i --save js-data js-data-http

See installation instructions for more information.

import {DataStore} from 'js-data'
import HttpAdapter from 'js-data-http'

// Create an empty data store
const store = new DataStore()

// "store" will use an http adapter by default
store.registerAdapter('http', new HttpAdapter(), { 'default': true })

// Define a Mapper for a "user" resource
store.defineMapper('user')

// GET /user/1
let user = await store.find('user', 1)

console.log(user) // { id: 1, name: 'John' }

// The user record is now stored in Users
console.log(store.get('user', user.id)) // { id: 1, name: 'John' }
console.log(user === store.get('user', user.id)) // true

// PUT /user/1 {name:"Johnny"}
user = await store.update('user', user.id, { name: 'Johnny' })

// The user record has been updated, and the change synced to the store
console.log(store.get('user', user.id)) // { id: 1, name: 'Johnny' }
console.log(user === store.get('user', user.id)) // true

// DELETE /user/1
await store.destroy('user', user.id)

// The user instance no longer in the store
console.log(store.get('user', 1)) // undefined

ES5:

// Create an empty data store
var store = new JSData.DataStore()

// "store" will use an http adapter by default
store.registerAdapter('http', new HttpAdapter(), { default: true })

// Define a Mapper for a "user" resource
store.defineMapper('user')

// GET /user/1
store.find('user', 1)
  .then(function (user) {
    console.log(user) // { id: 1, name: 'John' }

    // The user record is now stored in Users
    console.log(store.get('user', user.id)) // { id: 1, name: 'John' }
    console.log(user === store.get('user', user.id)) // true

    // PUT /user/1 {name:"Johnny"}
    return await store.update('user', user.id, { name: 'Johnny' })
  })
  .then(function (user) {
    // The user record has been updated, and the change synced to the store
    console.log(store.get('user', user.id)) // { id: 1, name: 'Johnny' }
    console.log(user === store.get('user', user.id)) // true

    // DELETE /user/1
    return store.destroy('user', user.id)
  })
  .then(function () {
    // The user instance no longer in the store
    console.log(store.get('user', 1)) // undefined
  })

Background

Most ORMs/ODMs only work with a single datastore, and most JavaScript ORMs only work in Node.js or the Browser. Wouldn't it be nice if you could use the same ORM/ODM on the client as you do on the backend? Wouldn't it be nice if you could switch databases without having to switch out your data layer code? Enter js-data.

Originally inspired by the desire to have something like Ember Data that worked in Angular.js and other frameworks, js-data was created. Turns out, js-data works in Node.js, so server-side adapters were written. js-data is the Model layer you've been craving. It consists of a convenient framework-agnostic, datastore-agnostic ORM for managing your data, which uses adapters to connect to various persistence layers.

The most commonly used adapter is the http adapter, which is perfect for connecting your frontend to your backend. localStorage, localForage, Firebase and other adapters are available for the browser. On the server you could hook up to the SQL adapter (Postgres/MySQL/MariaDB/SQLite3) or the MongoDB adapter. More adapters are coming, and you're free to implement your own. See Adapters.

Dependencies

js-data and its adapters depend on a global ES2015 Promise constructor. In the browser, window.Promise must be available. In Node.js, global.Promise must be available. Here is a handy ES2015 Promise polyfill if you need it.

js-data and its adapters require full ES5 support from the runtime. Here is a handy ES5 polyfill if you need it.

Guides and Tutorials

Get started at http://js-data.io

API Reference Docs

Visit http://api.js-data.io.

Community

Explore the Community.

Support

Find out how to Get Support.

Contributing

Read the Contributing Guide.

License

The MIT License (MIT)

Copyright (c) 2014-2016 js-data project authors

• LICENSE
• AUTHORS
• CONTRIBUTORS

Changelog

3.0.0-alpha.20 - 18 March 2016

Breaking API changes

• Switched Record#changes and Record#hasChanges to using an options argument

Backwards compatible API changes

• Passive change detection now possible with changes to Record#changes() and Record#hasChanges(), see #313
• #283 - Added sum and count methods

Backwards compatible big fixes

• Container and DataStore now proxy all Mapper methods