{"id":18088726,"url":"https://github.com/beauby/jsonapi-datastore","last_synced_at":"2025-04-04T20:15:14.925Z","repository":{"id":36523703,"uuid":"40829457","full_name":"beauby/jsonapi-datastore","owner":"beauby","description":"JavaScript client-side JSON API data handling made easy.","archived":false,"fork":false,"pushed_at":"2017-11-10T12:51:56.000Z","size":181,"stargazers_count":198,"open_issues_count":14,"forks_count":40,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-28T19:11:55.533Z","etag":null,"topics":["json-api"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beauby.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-08-16T17:10:10.000Z","updated_at":"2024-11-24T22:05:06.000Z","dependencies_parsed_at":"2022-08-31T00:00:17.233Z","dependency_job_id":null,"html_url":"https://github.com/beauby/jsonapi-datastore","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beauby%2Fjsonapi-datastore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beauby%2Fjsonapi-datastore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beauby%2Fjsonapi-datastore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beauby%2Fjsonapi-datastore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beauby","download_url":"https://codeload.github.com/beauby/jsonapi-datastore/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247242681,"owners_count":20907134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-api"],"created_at":"2024-10-31T17:14:16.006Z","updated_at":"2025-04-04T20:15:14.907Z","avatar_url":"https://github.com/beauby.png","language":"JavaScript","readme":"# jsonapi-datastore\n[![Build Status](https://travis-ci.org/beauby/jsonapi-datastore.svg)](https://travis-ci.org/beauby/jsonapi-datastore)\n\nJavaScript client-side [JSON API](http://jsonapi.org) data handling made easy.\n\nCurrent version is v0.4.0-beta. It is still a work in progress, but should do what it says.\n\n## Description\n\nThe [JSONAPI](http://jsonapi.org) standard is great for exchanging data (which is its purpose), but the format is not ideal to work directly with in an application.\njsonapi-datastore is a JavaScript framework-agnostic library (but an [AngularJS version](#angularjs) is provided for convenience) that takes away the burden of handling [JSONAPI](http://jsonapi.org) data on the client side.\n\nWhat it does:\n- read JSONAPI payloads,\n- rebuild the underlying data graph,\n- allows you to query models and access their relationships directly,\n- create new models,\n- serialize models for creation/update.\n\nWhat it does not do:\n- make requests to your API. You design your endpoints URLs, the way you handle authentication, caching, etc. is totally up to you.\n\n## Installing\n\nInstall jsonapi-datastore with `bower` by running:\n```\n$ bower install jsonapi-datastore\n```\nor with `npm` by running:\n```\n$ npm install jsonapi-datastore\n```\n\n## Parsing data\n\nJust call the `.sync()` method of your store.\n```javascript\nvar store = new JsonApiDataStore();\nstore.sync(data);\n```\nThis parses the data and incorporates it in the store, taking care of already existing records (by updating them) and relationships.\n\n## Parsing with meta data\n\nIf you have meta data in your payload use the `.syncWithMeta` method of your store.\n```javascript\nvar store = new JsonApiDataStore();\nstore.syncWithMeta(data);\n```\nThis does everything that `.sync()` does, but returns an object with data and meta split.\n\n## Retrieving models\n\nJust call the `.find(type, id)` method of your store.\n```javascript\nvar article = store.find('article', 123);\n```\nor call the `.findAll(type)` method of your store to get all the models of that type.\n```javascript\nvar articles = store.findAll('article');\n```\nAll the attributes *and* relationships are accessible through the model as object properties.\n```javascript\nconsole.log(article.author.name);\n```\nIn case a related resource has not been fetched yet (either as a primary resource or as an included resource), the corresponding property on the model will contain only the `type` and `id` (and the `._placeHolder` property will be set to `true`). However, the models are *updated in place*, so you can fetch a related resource later, and your data will remain consistent.\n\n## Serializing data\n\nJust call the `.serialize()` method on the model.\n```javascript\nconsole.log(article.serialize());\n```\n\n## Examples\n\n```javascript\n// Create a store:\nvar store = new JsonApiDataStore();\n\n// Then, given the following payload, containing two `articles`, with a related `user` who is the author of both:\nvar payload = {\n  data: [{\n    type: 'article',\n    id: 1337,\n    attributes: {\n      title: 'Cool article'\n    },\n    relationships: {\n      author: {\n        data: {\n          type: 'user',\n          id: 1\n        }\n      }\n    }\n  }, {\n    type: 'article',\n    id: 300,\n    attributes: {\n      title: 'Even cooler article'\n    },\n    relationships: {\n      author: {\n        data: {\n          type: 'user',\n          id: 1\n        }\n      }\n    }\n  }]\n};\n\n// we can sync it:\nvar articles = store.sync(payload);\n\n// which will return the list of synced articles.\n\n// Later, we can retrieve one of those:\nvar article = store.find('article', 1337);\n\n// If the author resource has not been synced yet, we can only access its id and its type:\nconsole.log(article.author);\n// { id: 1, _type: 'article' }\n\n// If we do sync the author resource later:\nvar authorPayload = {\n  data: {\n    type: 'user',\n    id: 1,\n    attributes: {\n      name: 'Lucas'\n    }\n  }\n};\n\nstore.sync(authorPayload);\n\n// we can then access the author's name through our old `article` reference:\nconsole.log(article.author.name);\n// 'Lucas'\n\n// We can also serialize any whole model in a JSONAPI-compliant way:\nconsole.log(article.serialize());\n// ...\n// or just a subset of its attributes/relationships:\nconsole.log(article.serialize({ attributes: ['title'], relationships: []}));\n// ...\n```\n\n## Documentation\n\nSee [DOCUMENTATION.md](DOCUMENTATION.md).\n\n## What's missing\n\nCurrently, the store does not handle `links` attributes or resource-level or relationship-level meta.\n\n## Notes\n\n### AngularJS\n\njsonapi-datastore is bundled with an AngularJs wrapper. Just include `ng-jsonapi-datastore.js` in your `index.html` and require the module `beauby.jsonApiDataStore` in your application.\nYou can then use the `JsonApiDataStore` factory, which is essentially defined as follows:\n```javascript\n{\n  store: new JsonApiDataStore(),\n  Model: JsonApiDataStoreModel\n}\n```\nso that you can use it as follows:\n\n```javascript\nangular\n  .module('myApp')\n  .controller('myController', function(JsonApiDataStore) {\n    var article = JsonApiDataStore.store.find('article', 1337);\n    var newArticle = new JsonApiDataStore.Model('article');\n    newArticle.setAttribute('title', 'My cool article');\n    console.log(newArticle.serialize());\n  });\n```\n\n\n## Contributing\n\nAll pull-requests welcome!\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeauby%2Fjsonapi-datastore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeauby%2Fjsonapi-datastore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeauby%2Fjsonapi-datastore/lists"}