REST conventions for mobx.
Table of Contents
npm install mobx-rest --save
An application state is usually divided into three realms:
MobX is an excellent state management choice to deal with those three realms: It allows you to represent your state as a graph while other solutions, like Redux for instance, force you to represent your state as a tree.
With mobx-rest resources are implemented with all their REST
actions built in (create, fetch, save, destroy, ...) so instead
of writing, over and over, hundreds of lines of boilerplate we can leverage
REST conventions to minimize the code needed for your API interactions.
If you want to see a full example with React you can check out the mobx-rest-example repo. The demo is deployed here.
mobx-rest is fairly simple and its source code could be read in 5 minutes.
ModelA Model represents one resource. It's identified by a primary key (mandatory) and holds
its attributes. You can create, update and destroy models in the client and then sync
them with the server. Apart from its attributes, a Model also holds the state of
the interactions with the server so you can react to those easily (showing loading states
for instance).
constructor(attributes: Object)Initialize the model with the given attributes.
defaultAttributes: ObjectAn object literal that holds the default attributes of the model. {} by default.
attributes: ObservableMapAn ObservableMap that holds the attributes of the model in the client.
commitedAttributes: ObservableMapAn ObservableMap that holds the attributes of the model in the server.
collection: ?CollectionA pointer to a Collection. By having models
"belong to" a collection you can take the most out
of mobx-rest.
requestA Request object that represents the state of the ongoing request, if any.
errorAn Error object that represents the state of the failed request, if any.
toJS(): ObjectReturn the object version of the attributes.
primaryKey: stringImplement this abstract method so mobx-rest knows what to
use as a primary key. It defaults to 'id' but if you use
something like mongodb you can change it to '_id'.
urlRoot(): stringImplement this abstract method so mobx-rest knows where
its API points to. If the model belongs to a Collection
(setting the collection attribute) this method does
not need to be implemented.
url(): stringReturn the url for that given resource. Will leverage the
collection's base url (if any) or urlRoot. It uses the
primary id since that's REST convention.
Example: tasks.get(34).url() // => "/tasks/34"
isRequest(label: string): booleanHelper method that asks the model whether there is an ongoing request with the given label.
Example: file.isRequest('saving')
Get an array with the attributes names that have changed.
Example:
model.set({ name: 'Pau'})
model.changedAttributes // => ['name']
Gets the current changes.
Example:
model.set({ name: 'Pau'})
model.changes // => { name: 'Pau' }
If an attribute is specified, returns true if it has changes. If no attribute is specified, returns true if any attribute has changes.
Example:
model.set({ name: 'Pau'})
// with attribute
model.hasChanges('name') // => true
// without attribute
model.hasChanges() // => true
Commit attributes to model.
Example:
model.set({ name: 'Pau' })
model.hasChanges // => true
model.commitChanges()
model.hasChanges // => false
This will reset the model attributes to the last committed ones.
Example:
const model = new Model({ name: 'Foo' })
model.set({ name: 'Pau' })
model.get('name') // => Pau
model.discardChanges()
model.get('name') // => 'Foo'
isNew: booleanReturn whether that model has been synchronized with the server or not.
Resources created in the client side (optimistically) don't have
an id attribute yet (that's given by the server)
Example:
const user = new User({ name : 'Pau' })
user.isNew // => true
user.save()
user.isNew // => false
user.get('id') // => 1
get(attribute: string): anyGet the given attribute. If the attribute does not exist, it will throw an error.
If different resources have different schemas you can
always use has to check whether a given attribute exists or not.
Example:
if (user.has('role')) {
return user.get('role')
} else {
return 'basic'
}
has(attribute: string): booleanCheck that the given attribute exists.
set(data: Object): voidUpdate the attributes in the client.
Example:
const folder = new Folder({ name : 'Trash' })
folder.get('name') // => 'Trash'
folder.set({ name: 'Rubbish' })
folder.get('name') // => 'Rubbish'
fetch(options): PromiseRequest this resource's data from the server. It tracks the state
of the request using the label fetching and updates the resource when
the data is back from the API.
Example:
const task = new Task({ id: 3 })
const promise = task.fetch()
task.isRequest('fetching') // => true
await promise
task.get('name') // => 'Do the laundry'
save(attributes: Object, options: Object): PromiseThe opposite of fetch. It takes the resource from the client and
persists it in the server through the API. It accepts some attributes
as the first argument so you can use it as a set + save.
It tracks the state of the request using the label saving.
If the model has a collection associated, it will be added into it.
Options:
optimistic = true Whether we want to update the resource in the client
first or wait for the server's response.patch = true Whether we want to use the PATCH verb and semantics, sending
only the changed attributes instead of the whole resource down the wire.keepChanges = false Whether we want to keep the changes after the response from the API.path (Optional) Target API path where we want perform the save action. It
has preference over url().Example:
const company = new Company({ name: 'Teambox' })
const promise = company.save({ name: 'Redbooth' }, { optimistic: false })
company.isRequest('saving') // => true
company.get('name') // => 'Teambox'
await promise
company.get('name') // => 'Redbooth'
destroy(options: Object): PromiseTells the API to destroy this resource.
Options:
optimistic = true Whether we want to delete the resource in the client
first or wait for the server's response.path (Optional) Target API path where we want perform the save action. It
has preference over url().rpc(method: 'string', body?: {}, label?: 'fetching'): PromiseWhen dealing with REST there are always cases when we have some actions beyond
the conventions. Those are represented as rpc calls and are not opinionated.
Example:
const response = await task.rpc('resolveSubtasks', { all: true })
if (response.ok) {
task.subTasks.fetch()
}
CollectionA Collection represents a group of resources. Each element of a Collection is a Model.
Likewise, a collection tracks also the state of the interactions with the server so you
can react accordingly.
models: ObservableArrayAn ObservableArray that holds the collection of models.
indexes: Array<String>Indexes allow you to determine which attributes you want to index your collection by.
This allows you to trade-off memory for speed. By default we index all the models by
primaryKey but you can add more indexes that will be used automatically when using filter and find with the object form.
users.find({ id: 123 }) // This will hit the index. Fast!
users.find(user => user.get('id') === 123) // This will do a full scan of the table. Slow.
You can query your collection by a combination of attributes that are indexed and others
that are not indexed. mobx-rest will take care to sort your query in order to scan the least
number of models.
request: ?RequestA Request object that represents the state of the ongoing request, if any.
error: ?ErrorObjectAn Error object that represents the state of the failed request, if any.
constructor(data: Array<Object>)Initializes the collection with the given resources.
url(): stringAbstract method that must be implemented if you want your collection and it's models to be able to interact with the API.
model(): ModelAbstract method that tells which kind of Model objects this collection
holds. This is used, for instance, when doing a collection.create so
we know which object to instantiate.
toJS(): Array<Object>Return a plain data structure representing the collection of resources without all the observable layer.
toArray(): Array<ObservableMap>Return an array with the observable resources.
isRequest(label: string): booleanHelper method that asks the collection whether there is an ongoing request with the given label.
Example:
filesCollection.isRequest('saving')
isEmpty: booleanHelper method that asks the collection whether there is any model in it.
Example:
const promise = usersCollection.fetch()
usersCollection.isEmpty // => true
await promise
usersCollection.isEmpty // => false
usersCollection.models.length // => 10
at(index: number): ?ModelFind a model at the given position.
get(id: number, { required?: boolean = false }): ?ModelFind a model (or not) with the given id. If required it will raise an error if not found.
filter(query: Object | Function): Array<Model>Helper method that filters the collection by the given conditions represented as a key value.
Example:
// using a query object
const resolvedTasks = tasksCollection.filter({ resolved: true })
resolvedTasks.length // => 3
// using a query function
const resolvedTasks = tasksCollection.filter(model => model.resolved)
resolvedTasks.length // => 3
It's important to notice that using the object API we can optimize the filtering using indexes.
find(query: Object | Function, { required?: boolean = false }): ?ModelSame as filter but it will halt and return when the first model matches
the conditions. If required it will raise an error if not found.
Example:
// using a query object
const user = usersCollection.find({ name: 'paco' })
user.get('name') // => 'paco'
// using a query function
const user = usersCollection.find(model => model.name === 'paco')
user.get('name') // => 'paco'
usersCollection.find({ name: 'foo'}) // => Error(`Invariant: Model must be found`)
last(): ?ModelReturns the last model of the collection. If the collection is empty, it returns null
add(data: Array<Object|T>|T|Object): Array<Model>Adds models with the given array of attributes.
usersCollection.add([{id: 1, name: 'foo'}])
reset(data: Array<Object|T>): Array<Model>Resets the collection with the given models.
usersCollection.reset([{id: 1, name: 'foo'}])
remove(ids: Array<number|T>|number|T): voidRemove any model with the given ids.
Example:
usersCollection.remove([1, 2, 3])
set(models: Array<Object | Model>, options: Object): voidMerge the given models smartly the current ones in the collection. It detects what to add, remove and change.
Options:
add = true Change to disable adding modelschange = true Change to disable updating modelsremove = true Change to disable removing modelsconst companiesCollection = new CompaniesCollection([
{ id: 1, name: 'Teambox' }
{ id: 3, name: 'Zpeaker' }
])
companiesCollection.set([
{ id: 1, name: 'Redbooth' },
{ id: 2, name: 'Factorial' }
])
companiesCollection.get(1).get('name') // => 'Redbooth'
companiesCollection.get(2).get('name') // => 'Factorial'
companiesCollection.get(3) // => null
build(attributes: Object|T): ModelInstantiates and links a model to the current collection.
const factorial = companiesCollection.build({ name: 'Factorial' })
factorial.collection === companiesCollection // => true
factorial.get('name') // 'Factorial'
create(target: Object | Model, options: Object)Add and save to the server the given model. If attributes are given,
also it builds the model for you. It tracks the state of the request
using the label creating.
Options:
optimistic = true Whether we want to create the resource in the client
first or wait for the server's response.path (Optional) Target API path where we want perform the save action. It
has preference over url().const promise = tasksCollection.create({ name: 'Do laundry' })
tasksCollection.isRequest('creating') // => true
await promise
tasksCollection.at(0).get('name') // => 'Do laundry'
fetch(options: Object)Fetch the date from the server and then calls set to update the current
models. Accepts any option from the set method.
const promise = tasksCollection.fetch()
tasksCollection.isEmpty // => true
tasksCollection.isRequest('fetching') // => true
await promise
tasksCollection.isEmpty // => false
rpc(method: 'string', body: {}): PromiseExactly the same as the model one, but at the collection level.
Alias for models.forEach
Example: collection.forEach(model => console.log(model.get('id')))
(callback: (model: T) => P): Array
Alias for models.map
Example: collection.map(model => model.get('id')) // => [1,2,3...]
Returns a shallow array representation of the collection
Returns a defensive shallow array representation of the collection
apiClientThis is the object that is going to make the xhr requests to interact with your API.
There are currently three implementations:
jQuery in the mobx-rest-jquery-adapter package.fetch in the mobx-rest-fetch-adapter package.axios in the mobx-rest-axios-adapter package.Initially you need to configure apiClient() with an adapter and the apiPath. You can also set additional options, like headers to send with all requests.
For example, if you're using JWT and need to send it using the Authorization header, it could look like this:
const options = {
apiPath: window.env.apiUrl,
}
if (token) {
options.commonOptions = {
headers: {
Authorization: `Bearer ${token}`
}
}
}
apiClient(adapter, options)
All options:
AuthorizationA collection looks like this:
// TasksCollection.js
const apiPath = '/api'
import adapter from 'mobx-rest-fetch-adapter'
import { apiClient, Collection, Model } from 'mobx-rest'
// We will use the adapter to make the `xhr` calls
apiClient(adapter, { apiPath })
class Task extends Model { }
class Tasks extends Collection {
url () { return `/tasks` }
model () { return Task }
}
// We instantiate the collection and export it as a singleton
export default new Tasks()
And here an example of how to use React with it:
import tasksCollection from './TasksCollection'
import { computed } from 'mobx'
import { observer } from 'mobx-react'
@observer
class Task extends React.Component {
onClick () {
this.props.task.save({ resolved: true })
}
render () {
return (
<li key={task.id}>
<button onClick={this.onClick.bind(this)}>
resolve
</button>
{this.props.task.get('name')}
</li>
)
}
}
@observer
class Tasks extends React.Component {
componentDidMount () {
// This will call `/api/tasks?all=true`
tasksCollection.fetch({ data: { all: true } })
}
@computed
get activeTasks () {
return tasksCollection.filter({ resolved: false })
}
render () {
if (tasksCollection.isRequest('fetching')) {
return <span>Fetching tasks...</span>
}
return (
<div>
<span>{this.activeTasks.length} tasks</span>
<ul>{activeTasks.map((task) => <Task task={task} />)}</ul>
</div>
)
}
}
Your collections and models will have the following state shape:
models: Array<Model> // This is where the models live
request: { // An ongoing request
label: string, // Examples: 'updating', 'creating', 'fetching', 'destroying' ...
abort: () => void, // A method to abort the ongoing request
progress: number // If uploading a file, represents the progress
},
error: { // A failed request
label: string, // Examples: 'updating', 'creating', 'fetching', 'destroying' ...
body: Object, // A string representing the error
}
attributes: Object // The resource attributes
optimisticId: string, // Client side id. Used for optimistic updates
request: { // An ongoing request
label: string, // Examples: 'updating', 'creating', 'fetching', 'destroying' ...
abort: () => void, // A method to abort the ongoing request
},
error: { // A failed request
label: string, // Examples: 'updating', 'creating', 'fetching', 'destroying' ...
body: string, // A string representing the error
},
This is something that mobx makes really easy to achieve:
import users from './UsersCollections'
import comments from './CommentsCollections'
import { computed } from 'mobx'
class Task extends Model {
@computed
author () {
return users.get(this.get('user_id'))
}
@computed
comments () {
return comments.filter({ task_id: this.get('id') })
}
}
Developed and battle tested in production in Factorial
(The MIT License)
Copyright (c) 2019 Pau Ramon masylum@gmail.com
Permission 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:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE 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.
7.1.1
path option to Collection#create, Model#destroy and Model#saveFAQs
REST conventions for mobx.
The npm package mobx-rest receives a total of 1,543 weekly downloads. As such, mobx-rest popularity was classified as popular.
We found that mobx-rest demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.