{"__v":1,"_id":"57804064827bd50e006b0503","category":{"version":"57804064827bd50e006b04fc","project":"54344d89bfaa3d0800c4d7fa","_id":"57804064827bd50e006b04fd","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-07T22:53:45.315Z","from_sync":false,"order":0,"slug":"guides","title":"Guides"},"project":"54344d89bfaa3d0800c4d7fa","user":"54344d6cbfaa3d0800c4d7f7","version":{"__v":1,"_id":"57804064827bd50e006b04fc","project":"54344d89bfaa3d0800c4d7fa","createdAt":"2016-07-09T00:08:04.866Z","releaseDate":"2016-07-09T00:08:04.866Z","categories":["57804064827bd50e006b04fd","57804064827bd50e006b04fe","57804064827bd50e006b04ff","57804064827bd50e006b0500","57804064827bd50e006b0501"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.9.0","version":"2.9"},"updates":["54dbc332e776882100abd40d","5593032f6bf22f170075b957","55dc8aba6f16451700843e65","577134a12659e20e00c90bb9","57d08cfa6b4de029009583f9"],"next":{"pages":[],"description":""},"createdAt":"2014-10-07T20:31:05.450Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"never","params":[],"url":""},"isReference":false,"order":1,"body":"## js-data  [![Slack Status](http://slack.js-data.io/badge.svg)](http://slack.js-data.io) [![npm version](https://img.shields.io/npm/v/js-data.svg?style=flat)](https://www.npmjs.org/package/js-data) [![Circle CI](https://img.shields.io/circleci/project/js-data/js-data/master.svg?style=flat)](https://circleci.com/gh/js-data/js-data/tree/master) [![npm downloads](https://img.shields.io/npm/dm/js-data.svg?style=flat)](https://www.npmjs.org/package/js-data) [![Coverage Status](https://img.shields.io/coveralls/js-data/js-data/master.svg?style=flat)](https://coveralls.io/github/js-data/js-data?branch=master) [![Codacy](https://img.shields.io/codacy/88b55f71c45a47838d24ed1e5fd2476c.svg)](https://www.codacy.com/app/jasondobry/js-data/dashboard)\n\nInspired by [Ember Data](https://github.com/emberjs/data), __JSData__ is the model layer you've been craving. It consists of a convenient __framework-agnostic__, __in-memory store__ for managing your data, which uses __adapters__ to communicate with various __persistence layers__.\n\nThe most commonly used adapter is the [http adapter](dshttpadapter), which is perfect for communicating with your RESTful backend. [localStorage](dslocalstorageadapter), [localForage](dslocalforageadapter), [firebase](dsfirebaseadapter) and [other adapters](working-with-adapters) are already available. On the server you could hook up to the [SQL adapter (Postgres/MySQL/MariaDB/SQLite3)](dssqladapter) and add in the [Redis adapter](dsredisadapter) as a caching layer for your read endpoints. More adapters are coming, and you're free to implement your own. See [Adapters](working-with-adapters). \n\nUnlike some libraries, JSData does not require the use of getters and setters, and doesn't decorate your data with a bunch of cruft. JSData's internal change detection (via [observe-js](https://github.com/Polymer/observe-js) or `Object.observe` in supporting browsers) allows for powerful use cases and an easy avenue for implementing your own [3-way data-binding](https://www.firebase.com/blog/2013-10-04-firebase-angular-data-binding.html).\n\nSupporting relations, computed properties, support for Node and the Browser, model lifecycle control and a slew of other features, JSData is the tool for [giving your data the respect it deserves](http://confreaks.tv/videos/mwjs2015-give-your-data-the-respect-it-deserves).\n\nWritten in ES6 and built for modern web development, JSData will save you thousands of lines of code _and_ make you cooler.\n\nSupport is handled via the [Slack channel](http://slack.js-data.io) or the [Mailing List](https://groups.io/org/groupsio/jsdata).\n\n##### Looking for contributors!\n\nJSData is getting popular and becoming a lot of work for me. I could use help with tests, documentation, demos/examples, and adapters. Contact me if you want to help! jason dot dobry at gmail dot com\n[block:embed]\n{\n  \"html\": \"<iframe class=\\\"embedly-embed\\\" src=\\\"//cdn.embedly.com/widgets/media.html?src=http%3A%2F%2Fwww.youtube.com%2Fembed%2F8wxnnJA9FKw%3Ffeature%3Doembed&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D8wxnnJA9FKw&image=http%3A%2F%2Fi.ytimg.com%2Fvi%2F8wxnnJA9FKw%2Fhqdefault.jpg&key=02466f963b9b4bb8845a05b53d3235d7&type=text%2Fhtml&schema=youtube\\\" width=\\\"854\\\" height=\\\"480\\\" scrolling=\\\"no\\\" frameborder=\\\"0\\\" allowfullscreen></iframe>\",\n  \"url\": \"https://www.youtube.com/watch?v=8wxnnJA9FKw\",\n  \"title\": \"MountainWest JavaScript 2015 - Give your Data the Respect it Deserves by Jason Dobry\",\n  \"favicon\": \"https://www.youtube.com/favicon.ico\",\n  \"image\": \"http://i.ytimg.com/vi/8wxnnJA9FKw/hqdefault.jpg\"\n}\n[/block]\n##### Documentation TODOs\n- offline/multi-adapter guide\n- example pagination solution\n- what else do you want to know?\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Quick Start\"\n}\n[/block]\nRead the [Installation Guide](/docs/installation).\n\n##### Bower\n\n`bower install --save js-data js-data-http`\n\nLoad `js-data-http.js` after `js-data.js`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// you can also require \\\"js-data\\\" if you're using AMD/CommonJS\\n// e.g. var JSData = require('js-data'); var DSHttpAdapter = require('js-data-http');\\nvar store = new JSData.DS();\\n\\n// register and use http by default for async operations\\nstore.registerAdapter('http', new DSHttpAdapter(), { default: true });\\n\\n// simplest model definition, just pass the name instead of an options hash\\n// this is the same as \\\"store.defineResource({ name: 'user' })\\\"\\nvar User = store.defineResource('user');\\n\\n\\n// Usually you'll define a resource by passing options\\nvar Comment = store.defineResource({\\n  name: 'comment',\\n  relations: {\\n    belongsTo: {\\n      user: {\\n        // \\\"join\\\" field, name of field on a comment\\n        // that is the primary key of the parent user\\n        localKey: 'userId',\\n        \\n        // name of the field on the comment where the \\n        // parent user will be attached to the comment\\n        // by js-data\\n        localField: 'user' \\n      }\\n    }\\n  }\\n});\\n\\nvar user;\\n\\n// Example CRUD operations with default configuration\\n// See http://www.js-data.io/docs/dsfind\\nUser.find(1)\\n  .then(function (_user) {\\n    _user; // { id: 1, name: 'John' }\\n\\n    // See http://www.js-data.io/docs/dsis\\n    User.is(_user); // true\\n    Comment.is(_user); // false\\n\\n    // The user is in the store now\\n    // See http://www.js-data.io/docs/dsget\\n    User.get(_user.id); // { id: 1, name: 'John' }\\n\\n    user = _user;\\n\\n    // No need for another GET request, will resolve immediately\\n    // See http://www.js-data.io/docs/dsfind\\n    return User.find(1);\\n  })\\n  .then(function (_user) {\\n    user === _user; // true\\n\\n    // PUT /user/1 {name:\\\"Johnny\\\"}\\n    // See http://www.js-data.io/docs/dsupdate\\n    return User.update(user.id, { name: 'Johnny' });\\n  })\\n  .then(function (_user) {\\n    // identity mapping at play\\n    user === _user; // true\\n    user === User.get(_user.id); // true\\n\\n    user; // { id: 1, name: 'Johnny' }\\n\\n    user.name = 'Billy';\\n\\n    // PUT /user/1 {id:1,name:\\\"Billy\\\"}\\n    // See http://www.js-data.io/docs/dssave\\n    return User.save(1);\\n  })\\n  .then(function (_user) {\\n    // identity mapping at play\\n    user === _user; // true\\n    user === User.get(_user.id); // true\\n\\n    user; // { id: 1, name: 'Billy' }\\n\\n    // DELETE /user/1\\n    // See http://www.js-data.io/docs/dsdestroy\\n    return User.destroy(1);\\n  })\\n  .then(function () {\\n    // The user has also been removed from the in-memory store\\n    User.get(1); // undefined\\n  });\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n##### Node.js\n\n`npm install --save js-data js-data-redis` (Using the [redis adapter](dsredisadapter) in the example.)\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var JSData = require('js-data');\\nvar DSRedisAdapter = require('js-data-redis')\\nvar store = new JSData.DS();\\n\\n// register and use http by default for async operations\\nstore.registerAdapter('redis', new DSRedisAdapter(), { default: true });\\n\\n// simplest model definition\\nvar User = store.defineResource('user');\\n\\nUser.find(1).then(function (user) {\\n  user; // { id: 1, name: 'John' }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API\"\n}\n[/block]\n- [DS](ds)\n- [DSFirebaseAdapter](dsfirebaseadapter)\n- [DSHttpAdapter](dshttpadapter)\n- [DSLocalForageAdapter](dslocalforageadapter)\n- [DSLocalStorageAdapter](dslocalstorageadapter)\n- [DSMongoDBAdapter](dsmongodbadapter)\n- [DSRedisAdapter](dsredisadapter)\n- [DSRethinkDBAdapter](dsrethinkdbadapter)\n- [DSSqlAdapter](dssqladapter)\n- [js-data-schema](js-data-schema)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Community & Links\"\n}\n[/block]\n- [Slack Channel](http://slack.js-data.io) \n- [Mailing List](https://groups.io/org/groupsio/jsdata) - Ask your questions!\n- [Announcements](/blog)\n- [Issues](https://github.com/js-data/js-data/issues) - Found a bug? Feature request? Submit an issue!\n- [GitHub](https://github.com/js-data/js-data) - View the source code for js-data.\n- [Contributing Guide](https://github.com/js-data/js-data/blob/master/CONTRIBUTING.md)\n- [CHANGELOG.md](https://github.com/js-data/js-data/blob/master/CHANGELOG.md)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Contributing\"\n}\n[/block]\nFirst, support is handled via the [Mailing List](https://groups.io/org/groupsio/jsdata). Ask your questions there.\n\nWhen submitting issues on GitHub, please include as much detail as possible to make debugging quick and easy.\n\n- good - Your versions of Angular, JSData, etc, relevant console logs/error, code examples that revealed the issue\n- better - A [plnkr](http://plnkr.co/), [fiddle](http://jsfiddle.net/), or [bin](http://jsbin.com/?html,output) that demonstrates the issue\n- best - A Pull Request that fixes the issue, including test coverage for the issue and the fix\n\n[Github Issues](https://github.com/js-data/js-data/issues).\n\n#### Pull Requests\n\n1. Contribute to the issue that is the reason you'll be developing in the first place\n1. Fork js-data\n1. `git clone https://github.com/<you>/js-data.git`\n1. `cd js-data; npm install; bower install;`\n1. `npm run all`\n1. Write your code, including relevant documentation and tests\n1. Submit a PR and we'll review\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"License\",\n  \"body\": \"The MIT License (MIT)\\n\\nCopyright (c) 2014-2015 Jason Dobry\\n\\nPermission is hereby granted, free of charge, to any person obtaining a copy\\nof this software and associated documentation files (the \\\"Software\\\"), to deal\\nin the Software without restriction, including without limitation the rights\\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\\ncopies of the Software, and to permit persons to whom the Software is\\nfurnished to do so, subject to the following conditions:\\n\\nThe above copyright notice and this permission notice shall be included in all\\ncopies or substantial portions of the Software.\\n\\nTHE SOFTWARE IS PROVIDED \\\"AS IS\\\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\\nSOFTWARE.\"\n}\n[/block]","excerpt":"What is this library for anyway?","slug":"home","type":"basic","title":"Getting Started with JSData"}

Getting Started with JSData

What is this library for anyway?

## js-data [![Slack Status](http://slack.js-data.io/badge.svg)](http://slack.js-data.io) [![npm version](https://img.shields.io/npm/v/js-data.svg?style=flat)](https://www.npmjs.org/package/js-data) [![Circle CI](https://img.shields.io/circleci/project/js-data/js-data/master.svg?style=flat)](https://circleci.com/gh/js-data/js-data/tree/master) [![npm downloads](https://img.shields.io/npm/dm/js-data.svg?style=flat)](https://www.npmjs.org/package/js-data) [![Coverage Status](https://img.shields.io/coveralls/js-data/js-data/master.svg?style=flat)](https://coveralls.io/github/js-data/js-data?branch=master) [![Codacy](https://img.shields.io/codacy/88b55f71c45a47838d24ed1e5fd2476c.svg)](https://www.codacy.com/app/jasondobry/js-data/dashboard) Inspired by [Ember Data](https://github.com/emberjs/data), __JSData__ is the model layer you've been craving. It consists of a convenient __framework-agnostic__, __in-memory store__ for managing your data, which uses __adapters__ to communicate with various __persistence layers__. The most commonly used adapter is the [http adapter](dshttpadapter), which is perfect for communicating with your RESTful backend. [localStorage](dslocalstorageadapter), [localForage](dslocalforageadapter), [firebase](dsfirebaseadapter) and [other adapters](working-with-adapters) are already available. On the server you could hook up to the [SQL adapter (Postgres/MySQL/MariaDB/SQLite3)](dssqladapter) and add in the [Redis adapter](dsredisadapter) as a caching layer for your read endpoints. More adapters are coming, and you're free to implement your own. See [Adapters](working-with-adapters). Unlike some libraries, JSData does not require the use of getters and setters, and doesn't decorate your data with a bunch of cruft. JSData's internal change detection (via [observe-js](https://github.com/Polymer/observe-js) or `Object.observe` in supporting browsers) allows for powerful use cases and an easy avenue for implementing your own [3-way data-binding](https://www.firebase.com/blog/2013-10-04-firebase-angular-data-binding.html). Supporting relations, computed properties, support for Node and the Browser, model lifecycle control and a slew of other features, JSData is the tool for [giving your data the respect it deserves](http://confreaks.tv/videos/mwjs2015-give-your-data-the-respect-it-deserves). Written in ES6 and built for modern web development, JSData will save you thousands of lines of code _and_ make you cooler. Support is handled via the [Slack channel](http://slack.js-data.io) or the [Mailing List](https://groups.io/org/groupsio/jsdata). ##### Looking for contributors! JSData is getting popular and becoming a lot of work for me. I could use help with tests, documentation, demos/examples, and adapters. Contact me if you want to help! jason dot dobry at gmail dot com [block:embed] { "html": "<iframe class=\"embedly-embed\" src=\"//cdn.embedly.com/widgets/media.html?src=http%3A%2F%2Fwww.youtube.com%2Fembed%2F8wxnnJA9FKw%3Ffeature%3Doembed&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D8wxnnJA9FKw&image=http%3A%2F%2Fi.ytimg.com%2Fvi%2F8wxnnJA9FKw%2Fhqdefault.jpg&key=02466f963b9b4bb8845a05b53d3235d7&type=text%2Fhtml&schema=youtube\" width=\"854\" height=\"480\" scrolling=\"no\" frameborder=\"0\" allowfullscreen></iframe>", "url": "https://www.youtube.com/watch?v=8wxnnJA9FKw", "title": "MountainWest JavaScript 2015 - Give your Data the Respect it Deserves by Jason Dobry", "favicon": "https://www.youtube.com/favicon.ico", "image": "http://i.ytimg.com/vi/8wxnnJA9FKw/hqdefault.jpg" } [/block] ##### Documentation TODOs - offline/multi-adapter guide - example pagination solution - what else do you want to know? [block:api-header] { "type": "basic", "title": "Quick Start" } [/block] Read the [Installation Guide](/docs/installation). ##### Bower `bower install --save js-data js-data-http` Load `js-data-http.js` after `js-data.js`. [block:code] { "codes": [ { "code": "// you can also require \"js-data\" if you're using AMD/CommonJS\n// e.g. var JSData = require('js-data'); var DSHttpAdapter = require('js-data-http');\nvar store = new JSData.DS();\n\n// register and use http by default for async operations\nstore.registerAdapter('http', new DSHttpAdapter(), { default: true });\n\n// simplest model definition, just pass the name instead of an options hash\n// this is the same as \"store.defineResource({ name: 'user' })\"\nvar User = store.defineResource('user');\n\n\n// Usually you'll define a resource by passing options\nvar Comment = store.defineResource({\n name: 'comment',\n relations: {\n belongsTo: {\n user: {\n // \"join\" field, name of field on a comment\n // that is the primary key of the parent user\n localKey: 'userId',\n \n // name of the field on the comment where the \n // parent user will be attached to the comment\n // by js-data\n localField: 'user' \n }\n }\n }\n});\n\nvar user;\n\n// Example CRUD operations with default configuration\n// See http://www.js-data.io/docs/dsfind\nUser.find(1)\n .then(function (_user) {\n _user; // { id: 1, name: 'John' }\n\n // See http://www.js-data.io/docs/dsis\n User.is(_user); // true\n Comment.is(_user); // false\n\n // The user is in the store now\n // See http://www.js-data.io/docs/dsget\n User.get(_user.id); // { id: 1, name: 'John' }\n\n user = _user;\n\n // No need for another GET request, will resolve immediately\n // See http://www.js-data.io/docs/dsfind\n return User.find(1);\n })\n .then(function (_user) {\n user === _user; // true\n\n // PUT /user/1 {name:\"Johnny\"}\n // See http://www.js-data.io/docs/dsupdate\n return User.update(user.id, { name: 'Johnny' });\n })\n .then(function (_user) {\n // identity mapping at play\n user === _user; // true\n user === User.get(_user.id); // true\n\n user; // { id: 1, name: 'Johnny' }\n\n user.name = 'Billy';\n\n // PUT /user/1 {id:1,name:\"Billy\"}\n // See http://www.js-data.io/docs/dssave\n return User.save(1);\n })\n .then(function (_user) {\n // identity mapping at play\n user === _user; // true\n user === User.get(_user.id); // true\n\n user; // { id: 1, name: 'Billy' }\n\n // DELETE /user/1\n // See http://www.js-data.io/docs/dsdestroy\n return User.destroy(1);\n })\n .then(function () {\n // The user has also been removed from the in-memory store\n User.get(1); // undefined\n });", "language": "javascript" } ] } [/block] ##### Node.js `npm install --save js-data js-data-redis` (Using the [redis adapter](dsredisadapter) in the example.) [block:code] { "codes": [ { "code": "var JSData = require('js-data');\nvar DSRedisAdapter = require('js-data-redis')\nvar store = new JSData.DS();\n\n// register and use http by default for async operations\nstore.registerAdapter('redis', new DSRedisAdapter(), { default: true });\n\n// simplest model definition\nvar User = store.defineResource('user');\n\nUser.find(1).then(function (user) {\n user; // { id: 1, name: 'John' }\n});", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "API" } [/block] - [DS](ds) - [DSFirebaseAdapter](dsfirebaseadapter) - [DSHttpAdapter](dshttpadapter) - [DSLocalForageAdapter](dslocalforageadapter) - [DSLocalStorageAdapter](dslocalstorageadapter) - [DSMongoDBAdapter](dsmongodbadapter) - [DSRedisAdapter](dsredisadapter) - [DSRethinkDBAdapter](dsrethinkdbadapter) - [DSSqlAdapter](dssqladapter) - [js-data-schema](js-data-schema) [block:api-header] { "type": "basic", "title": "Community & Links" } [/block] - [Slack Channel](http://slack.js-data.io) - [Mailing List](https://groups.io/org/groupsio/jsdata) - Ask your questions! - [Announcements](/blog) - [Issues](https://github.com/js-data/js-data/issues) - Found a bug? Feature request? Submit an issue! - [GitHub](https://github.com/js-data/js-data) - View the source code for js-data. - [Contributing Guide](https://github.com/js-data/js-data/blob/master/CONTRIBUTING.md) - [CHANGELOG.md](https://github.com/js-data/js-data/blob/master/CHANGELOG.md) [block:api-header] { "type": "basic", "title": "Contributing" } [/block] First, support is handled via the [Mailing List](https://groups.io/org/groupsio/jsdata). Ask your questions there. When submitting issues on GitHub, please include as much detail as possible to make debugging quick and easy. - good - Your versions of Angular, JSData, etc, relevant console logs/error, code examples that revealed the issue - better - A [plnkr](http://plnkr.co/), [fiddle](http://jsfiddle.net/), or [bin](http://jsbin.com/?html,output) that demonstrates the issue - best - A Pull Request that fixes the issue, including test coverage for the issue and the fix [Github Issues](https://github.com/js-data/js-data/issues). #### Pull Requests 1. Contribute to the issue that is the reason you'll be developing in the first place 1. Fork js-data 1. `git clone https://github.com/<you>/js-data.git` 1. `cd js-data; npm install; bower install;` 1. `npm run all` 1. Write your code, including relevant documentation and tests 1. Submit a PR and we'll review [block:callout] { "type": "info", "title": "License", "body": "The MIT License (MIT)\n\nCopyright (c) 2014-2015 Jason Dobry\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE." } [/block]