{"id":21326227,"url":"https://github.com/masylum/mobx-rest","last_synced_at":"2025-04-04T13:13:57.716Z","repository":{"id":9720383,"uuid":"63106873","full_name":"masylum/mobx-rest","owner":"masylum","description":"REST conventions for Mobx","archived":false,"fork":false,"pushed_at":"2023-03-04T03:39:57.000Z","size":922,"stargazers_count":187,"open_issues_count":10,"forks_count":43,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-28T12:05:04.437Z","etag":null,"topics":["api","api-client","api-rest","mobx","reactive","rest","state","state-management"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/masylum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-07-11T22:32:34.000Z","updated_at":"2025-01-06T12:49:28.000Z","dependencies_parsed_at":"2023-01-13T15:31:59.873Z","dependency_job_id":"6860772c-46aa-497d-9106-af6cdf3bb41f","html_url":"https://github.com/masylum/mobx-rest","commit_stats":{"total_commits":246,"total_committers":21,"mean_commits":"11.714285714285714","dds":0.6666666666666667,"last_synced_commit":"91be935368fe837cefd2ca104bb81f7dcd7231b2"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masylum%2Fmobx-rest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masylum%2Fmobx-rest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masylum%2Fmobx-rest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/masylum%2Fmobx-rest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/masylum","download_url":"https://codeload.github.com/masylum/mobx-rest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247181350,"owners_count":20897368,"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":["api","api-client","api-rest","mobx","reactive","rest","state","state-management"],"created_at":"2024-11-21T21:08:51.296Z","updated_at":"2025-04-04T13:13:57.687Z","avatar_url":"https://github.com/masylum.png","language":"TypeScript","funding_links":[],"categories":["Awesome MobX"],"sub_categories":["Related projects and utilities"],"readme":"# mobx-rest\n\nREST conventions for mobx.\n\n[![Build Status](https://travis-ci.org/masylum/mobx-rest.svg?branch=master)](https://travis-ci.org/masylum/mobx-rest)\n[![js-standard-style](https://cdn.rawgit.com/feross/standard/master/badge.svg)](http://standardjs.com)\n\n![](https://media.giphy.com/media/b9QBHfcNpvqDK/giphy.gif)\n\n**Table of Contents**\n\n- [Installation](#installation)\n- [What is it?](#what-is-it)\n- [Full React example](#full-react-example)\n- [Documentation](#documentation)\n  - [Model](#model)\n  - [Collection](#collection)\n  - [apiClient](#apiclient)\n- [Simple Example](#simple-example)\n- [State shape](#state-shape)\n- [FAQ](#faq)\n- [Where is it used?](#where-is-it-used)\n- [License](#license)\n\n## Installation\n\n```\nnpm install mobx-rest --save\n```\n\n## What is it?\n\nAn application state is usually divided into three realms:\n\n  - **Component state**: Each component can have their own state, like a button\n  being pressed, a text input value, etc.\n  - **Application state**: Sometimes we need components to share state between them and\n  they are too far away to actually make them talk each other through props.\n  - **Resources state**: Other times, state is persisted in the server. We synchronize\n  that state through APIs that consume *resources*. One way to synchronize this state\n  is through REST.\n\nMobX is an excellent state management choice to deal with those three realms:\nIt allows you to represent your state as a graph while other solutions,\nlike Redux for instance, force you to represent your state as a tree.\n\nWith `mobx-rest` resources are implemented with all their REST\nactions built in (`create`, `fetch`, `save`, `destroy`, ...) so instead\nof writing, over and over, hundreds of lines of boilerplate we can leverage\nREST conventions to minimize the code needed for your API interactions.\n\n## Full React example\n\nIf you want to see a full example with React you\ncan check out the [mobx-rest-example repo](https://github.com/masylum/mobx-rest-example).\nThe demo is deployed [here](https://demo-wiimsnkpdy.now.sh/).\n\n## Documentation\n\n`mobx-rest` is fairly simple and its source code could be read in 5 minutes.\n\n### `Model`\n\nA `Model` represents one resource. It's identified by a primary key (mandatory) and holds\nits attributes. You can create, update and destroy models in the client and then sync\nthem with the server. Apart from its attributes, a `Model` also holds the state of\nthe interactions with the server so you can react to those easily (showing loading states\nfor instance).\n\n#### `constructor(attributes: Object)`\n\nInitialize the model with the given attributes.\n\n#### `defaultAttributes: Object`\n\nAn object literal that holds the default attributes of the model. {} by default.\n\n#### `attributes: ObservableMap`\n\nAn `ObservableMap` that holds the attributes of the model in the client.\n\n#### `commitedAttributes: ObservableMap`\n\nAn `ObservableMap` that holds the attributes of the model in the server.\n\n#### `collection: ?Collection`\n\nA pointer to a `Collection`. By having models\n\"belong to\" a collection you can take the most out\nof `mobx-rest`.\n\n#### `toJS(): Object`\n\nReturn the object version of the attributes.\n\n#### `primaryKey: string`\n\nImplement this abstract method so `mobx-rest` knows what to\nuse as a primary key. It defaults to `'id'` but if you use\nsomething like mongodb you can change it to `'_id'`.\n\n#### `urlRoot(): string`\n\nImplement this abstract method so `mobx-rest` knows where\nits API points to. If the model belongs to a `Collection`\n(setting the `collection` attribute) this method does\nnot need to be implemented.\n\n#### `url(): string`\n\nReturn the url for that given resource. Will leverage the\ncollection's base url (if any) or `urlRoot`. It uses the\nprimary id since that's REST convention.\n\nExample: `tasks.get(34).url() // =\u003e \"/tasks/34\"`\n\n#### changedAttributes: Array\u003cstring\u003e\n\nGet an array with the attributes names that have changed.\n\nExample:\n```js\nmodel.set({ name: 'Pau'})\n\nmodel.changedAttributes // =\u003e ['name']\n```\n\n#### changes: { [string]: any }\n\nGets the current changes.\n\nExample:\n```js\nmodel.set({ name: 'Pau'})\n\nmodel.changes // =\u003e { name: 'Pau' }\n```\n\n#### hasChanges(attribute?: string): boolean\n\nIf an attribute is specified, returns true if it has changes.\nIf no attribute is specified, returns true if any attribute has changes.\n\nExample:\n```js\nmodel.set({ name: 'Pau'})\n\n// with attribute\nmodel.hasChanges('name') // =\u003e true\n\n// without attribute\nmodel.hasChanges() // =\u003e true\n```\n\n#### commitChanges(): void\n\nCommit attributes to model.\n\nExample:\n```js\nmodel.set({ name: 'Pau' })\nmodel.hasChanges // =\u003e true\n\nmodel.commitChanges()\nmodel.hasChanges // =\u003e false\n```\n\n#### discardChanges(): void\n\nThis will reset the model attributes to the last committed ones.\n\nExample:\n```js\nconst model = new Model({ name: 'Foo' })\nmodel.set({ name: 'Pau' })\nmodel.get('name') // =\u003e Pau\n\nmodel.discardChanges()\nmodel.get('name') // =\u003e 'Foo'\n```\n\n#### `isNew: boolean`\n\nReturn whether that model has been synchronized with the server or not.\nResources created in the client side (optimistically) don't have\nan `id` attribute yet (that's given by the server)\n\nExample:\n\n```js\nconst user = new User({ name : 'Pau' })\nuser.isNew // =\u003e true\nuser.save()\nuser.isNew // =\u003e false\nuser.get('id') // =\u003e 1\n```\n\n#### `get(attribute: string): any`\n\nGet the given attribute. If the attribute does not exist, it will throw an error.\n\nIf different resources have different schemas you can\nalways use `has` to check whether a given attribute exists or not.\n\nExample:\n\n```js\nif (user.has('role')) {\n  return user.get('role')\n} else {\n  return 'basic'\n}\n```\n\n#### `has(attribute: string): boolean`\n\nCheck that the given attribute exists.\n\n#### `set(data: Object): void`\n\nUpdate the attributes in the client.\n\nExample:\n\n```js\nconst folder = new Folder({ name : 'Trash' })\nfolder.get('name') // =\u003e 'Trash'\nfolder.set({ name: 'Rubbish' })\nfolder.get('name') // =\u003e 'Rubbish'\n```\n\n#### `fetch(options): Promise`\n\nFetches this resource's data from the server.\n\nExample:\n\n```js\nconst task = new Task({ id: 3 })\nconst promise = task.fetch()\nawait promise\ntask.get('name') // =\u003e 'Do the laundry'\n```\n\n#### `save(attributes: Object, options: Object): Promise`\n\nThe opposite of `fetch`. It takes the resource from the client and\npersists it in the server through the API. It accepts some attributes\nas the first argument so you can use it as a `set` + `save`.\nIt tracks the state of the request using the label `saving`.\nIf the model has a collection associated, it will be added into it.\n\nOptions:\n\n  - `optimistic = true` Whether we want to update the resource in the client\n  first or wait for the server's response.\n  - `patch = true` Whether we want to use the `PATCH` verb and semantics, sending\n  only the changed attributes instead of the whole resource down the wire.\n  - `keepChanges = false` Whether we want to keep the changes after the response from the API.\n  - `path` (Optional) Target API path where we want perform the save action. It\n      has preference over `url()`.\n\nExample:\n\n```js\nconst company = new Company({ name: 'Teambox' })\nconst promise = company.save({ name: 'Redbooth' }, { optimistic: false })\ncompany.get('name') // =\u003e 'Teambox'\nawait promise\ncompany.get('name') // =\u003e 'Redbooth'\n```\n\n#### `destroy(options: Object): Promise`\n\nTells the API to destroy this resource.\n\nOptions:\n\n  - `optimistic = true` Whether we want to delete the resource in the client\n  first or wait for the server's response.\n  - `path` (Optional) Target API path where we want perform the save action. It\n      has preference over `url()`.\n\n#### `rpc(method: 'string', body?: {},  label?: 'fetching'): Promise`\n\nWhen dealing with REST there are always cases when we have some actions beyond\nthe conventions. Those are represented as `rpc` calls and are not opinionated.\n\nExample:\n\n```js\nconst response = await task.rpc('resolveSubtasks', { all: true })\nif (response.ok) {\n  task.subTasks.fetch()\n}\n```\n\n### `Collection`\n\nA `Collection` represents a group of resources. Each element of a `Collection` is a `Model`.\nLikewise, a collection tracks also the state of the interactions with the server so you\ncan react accordingly.\n\n#### `models: ObservableArray`\n\nAn `ObservableArray` that holds the collection of models.\n\n#### `indexes: Array\u003cString\u003e`\n\nIndexes allow you to determine which attributes you want to index your collection by.\nThis allows you to trade-off memory for speed. By default we index all the models by\n`primaryKey` but you can add more indexes that will be used automatically when using `filter` and `find` with the object form.\n\n```js\nusers.find({ id: 123 }) // This will hit the index. Fast!\nusers.find(user =\u003e user.get('id') === 123) // This will do a full scan of the table. Slow.\n```\n\nYou can query your collection by a combination of attributes that are indexed and others\nthat are not indexed. `mobx-rest` will take care to sort your query in order to scan the least\nnumber of models.\n\n#### `constructor(data: Array\u003cObject\u003e)`\n\nInitializes the collection with the given resources.\n\n#### `url(): string`\n\nAbstract method that must be implemented if you want your collection\nand it's models to be able to interact with the API.\n\n#### `model(): Model`\n\nAbstract method that tells which kind of `Model` objects this collection\nholds. This is used, for instance, when doing a `collection.create` so\nwe know which object to instantiate.\n\n#### `toJS(): Array\u003cObject\u003e`\n\nReturn a plain data structure representing the collection of resources\nwithout all the observable layer.\n\n#### `toArray(): Array\u003cObservableMap\u003e`\n\nReturn an array with the observable resources.\n\n#### `isEmpty: boolean`\n\nHelper method that asks the collection whether there is any\nmodel in it.\n\nExample:\n\n```js\nconst promise = usersCollection.fetch()\nusersCollection.isEmpty // =\u003e true\nawait promise\nusersCollection.isEmpty // =\u003e false\nusersCollection.models.length // =\u003e 10\n```\n\n#### `at(index: number): ?Model`\n\nFind a model at the given position.\n\n#### `get(id: number, { required?: boolean = false }): ?Model`\n\nFind a model (or not) with the given id. If `required` it will raise an error if not found.\n\n#### `filter(query: Object | Function): Array\u003cModel\u003e`\n\nHelper method that filters the collection by the given conditions represented\nas a key value.\n\nExample:\n\n```js\n// using a query object\nconst resolvedTasks = tasksCollection.filter({ resolved: true })\nresolvedTasks.length // =\u003e 3\n\n// using a query function\nconst resolvedTasks = tasksCollection.filter(model =\u003e model.resolved)\nresolvedTasks.length // =\u003e 3\n```\n\nIt's important to notice that using the object API we can optimize\nthe filtering using indexes.\n\n#### `find(query: Object | Function, { required?: boolean = false }): ?Model`\n\nSame as `filter` but it will halt and return when the first model matches\nthe conditions. If `required` it will raise an error if not found.\n\nExample:\n\n```js\n// using a query object\nconst user = usersCollection.find({ name: 'paco' })\nuser.get('name') // =\u003e 'paco'\n\n// using a query function\nconst user = usersCollection.find(model =\u003e model.name === 'paco')\nuser.get('name') // =\u003e 'paco'\n\nusersCollection.find({ name: 'foo'}) // =\u003e Error(`Invariant: Model must be found`)\n```\n\n#### `last(): ?Model`\n\nReturns the last model of the collection. If the collection is empty, it returns `null`\n\n#### `add(data: Array\u003cObject|T\u003e|T|Object): Array\u003cModel\u003e`\n\nAdds models with the given array of attributes.\n\n```js\nusersCollection.add([{id: 1, name: 'foo'}])\n```\n\n#### `reset(data: Array\u003cObject|T\u003e): Array\u003cModel\u003e`\n\nResets the collection with the given models.\n\n```js\nusersCollection.reset([{id: 1, name: 'foo'}])\n```\n\n#### `remove(ids: Array\u003cnumber|T\u003e|number|T): void`\n\nRemove any model with the given ids.\n\nExample:\n\n```js\nusersCollection.remove([1, 2, 3])\n```\n\n#### `set(models: Array\u003cObject | Model\u003e, options: Object): void`\n\nMerge the given models smartly the current ones in the collection.\nIt detects what to add, remove and change.\n\nOptions:\n\n  - `add = true` Change to disable adding models\n  - `change = true` Change to disable updating models\n  - `remove = true` Change to disable removing models\n\n```js\nconst companiesCollection = new CompaniesCollection([\n  { id: 1, name: 'Teambox' }\n  { id: 3, name: 'Zpeaker' }\n])\ncompaniesCollection.set([\n  { id: 1, name: 'Redbooth' },\n  { id: 2, name: 'Factorial' }\n])\ncompaniesCollection.get(1).get('name') // =\u003e 'Redbooth'\ncompaniesCollection.get(2).get('name') // =\u003e 'Factorial'\ncompaniesCollection.get(3) // =\u003e null\n```\n\n#### `build(attributes: Object|T): Model`\n\nInstantiates and links a model to the current collection.\n\n```js\nconst factorial = companiesCollection.build({ name: 'Factorial' })\nfactorial.collection === companiesCollection // =\u003e true\nfactorial.get('name') // 'Factorial'\n```\n\n#### `create(target: Object | Model, options: Object)`\n\nAdd and save to the server the given model. If attributes are given,\nalso it builds the model for you. It tracks the state of the request\nusing the label `creating`.\n\nOptions:\n\n  - `optimistic = true` Whether we want to create the resource in the client\n  first or wait for the server's response.\n  - `path` (Optional) Target API path where we want perform the save action. It\n      has preference over `url()`.\n\n```js\nconst promise = tasksCollection.create({ name: 'Do laundry' })\nawait promise\ntasksCollection.at(0).get('name') // =\u003e 'Do laundry'\n```\n\n#### `fetch(options: Object)`\n\nFetch the date from the server and then calls `set` to update the current\nmodels. Accepts any option from the `set` method.\n\n```js\nconst promise = tasksCollection.fetch()\ntasksCollection.isEmpty // =\u003e true\nawait promise\ntasksCollection.isEmpty // =\u003e false\n```\n\n#### `rpc(method: 'string', body: {}): Promise`\n\nExactly the same as the model one, but at the collection level.\n\n### forEach (callback: (model: T) =\u003e void): void\n\nAlias for models.forEach\n\nExample: `collection.forEach(model =\u003e console.log(model.get('id')))`\n\n### map\u003cP\u003e (callback: (model: T) =\u003e P): Array\u003cP\u003e\n\nAlias for models.map\n\nExample: `collection.map(model =\u003e model.get('id')) // =\u003e [1,2,3...]`\n\n### peek (): Array\u003cT: Model\u003e\n\nReturns a shallow array representation of the collection\n\n### slice (): Array\u003cT: Model\u003e\n\nReturns a defensive shallow array representation of the collection\n\n### `apiClient`\n\nThis is the object that is going to make the `xhr` requests to interact with your API.\nThere are currently three implementations:\n\n  - One using `jQuery` in the [mobx-rest-jquery-adapter](https://github.com/masylum/mobx-rest-jquery-adapter) package.\n  - One using `fetch` in the [mobx-rest-fetch-adapter](https://github.com/masylum/mobx-rest-fetch-adapter) package.\n  - One Using `axios` in the [mobx-rest-axios-adapter](https://github.com/IranTIP/mobx-rest-axios-adapter) package.\n\nInitially you need to configure `apiClient()` with an adapter and the `apiPath`. You can also set additional options, like headers to send with all requests.\n\nFor example, if you're using JWT and need to send it using the Authorization header, it could look like this:\n```\nconst options = {\n  apiPath: window.env.apiUrl,\n}\nif (token) {\n  options.commonOptions = {\n    headers: {\n      Authorization: `Bearer ${token}`\n    }\n  }\n}\napiClient(adapter, options)\n```\n\nAll options:\n* **apiPath** (required): what do prepend for all model and collections URLs\n* **commonOptions**: settings to use for all requests\n  * **headers**: Additional request headers, like `Authorization`\n  * **tbd.**\n\n## Simple Example\n\nA collection looks like this:\n\n```js\n// TasksCollection.js\nconst apiPath = '/api'\nimport adapter from 'mobx-rest-fetch-adapter'\nimport { apiClient, Collection, Model } from 'mobx-rest'\n\n// We will use the adapter to make the `xhr` calls\napiClient(adapter, { apiPath })\n\nclass Task extends Model { }\nclass Tasks extends Collection {\n  url ()  { return `/tasks` }\n  model () { return Task }\n}\n\n// We instantiate the collection and export it as a singleton\nexport default new Tasks()\n```\n\nAnd here an example of how to use React with it:\n\n```js\nimport tasksCollection from './TasksCollection'\nimport { computed } from 'mobx'\nimport { observer } from 'mobx-react'\n\n@observer\nclass Task extends React.Component {\n  onClick () {\n    this.props.task.save({ resolved: true })\n  }\n\n  render () {\n    return (\n      \u003cli key={task.id}\u003e\n        \u003cbutton onClick={this.onClick.bind(this)}\u003e\n          resolve\n        \u003c/button\u003e\n        {this.props.task.get('name')}\n      \u003c/li\u003e\n    )\n  }\n}\n\n@observer\nclass Tasks extends React.Component {\n  componentDidMount () {\n    // This will call `/api/tasks?all=true`\n    tasksCollection.fetch({ data: { all: true } })\n  }\n\n  @computed\n  get activeTasks () {\n    return tasksCollection.filter({ resolved: false })\n  }\n\n  render () {\n    return (\n      \u003cdiv\u003e\n        \u003cspan\u003e{this.activeTasks.length} tasks\u003c/span\u003e\n        \u003cul\u003e{activeTasks.map((task) =\u003e \u003cTask task={task} /\u003e)}\u003c/ul\u003e\n      \u003c/div\u003e\n    )\n  }\n}\n\n```\n\n## State shape\n\nYour collections and models will have the following state shape:\n\n### Collection\n\n```js\nmodels: Array\u003cModel\u003e      // This is where the models live\n```\n\n### Model\n\n```js\nattributes: Object    // The resource attributes\noptimisticId: string, // Client side id. Used for optimistic updates\n```\n\n## FAQ\n\n### How do I create relations between the models?\n\nThis is something that mobx makes really easy to achieve:\n\n```js\nimport users from './UsersCollections'\nimport comments from './CommentsCollections'\nimport { computed } from 'mobx'\n\nclass Task extends Model {\n  @computed\n  author () {\n    return users.get(this.get('user_id'))\n  }\n\n  @computed\n  comments () {\n    return comments.filter({ task_id: this.get('id') })\n  }\n}\n```\n\n## Where is it used?\n\nDeveloped and battle tested in production in [Factorial](https://factorialhr.com)\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2022 Pau Ramon \u003cmasylum@gmail.com\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies 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 SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasylum%2Fmobx-rest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmasylum%2Fmobx-rest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmasylum%2Fmobx-rest/lists"}