An active-record(ish) implementation for a JSON:API that gets you safely to the top
boot
methodboot
method ?)‼️ Well, this will work once Belay has been published to NPM, but this early in the dev process I’ll just not bother and use yarn link
.
$ yarn add @shabushabu/belay
In nuxt.config.js
(making sure that the module is above @nuxtjs/axios
):
export default {
// ...
modules: [
// ...
'@shabushabu/belay',
'@nuxtjs/axios',
// ...
],
// default values
belay: {
useStore: true,
namespace: 'belay',
disableStoreEvents: false,
autoSaveRelationships: true,
hierarchiesLocation: '~/models/Hierarchies'
},
// ...
}
Belay supports STI, so something like the following is possible:
export class Vehicle extends Model {
static subTypeField () {
return 'data.attributes.subType'
}
static children () {
return {
car: Car,
bus: Bus
}
}
}
export class Car extends Vehicle {}
export class Bus extends Vehicle {}
The above can lead to circular imports, though, so it’s necessary to create a Hierarchies.js
file.
export * from './Vehicle'
export * from './Car'
export * from './Bus'
We then use this file to import our models, thus avoiding the issue:
import { Car, Bus } from './Hierarchies'
export class Vehicle extends Model {
static children () {
return {
car: Car,
bus: Bus
}
}
}
Here’s a great article by Michel Weststrate explaining things more in-depth
Belay uses JSON Schema for some basic validation on the model. It will somewhat intelligently merge the JSON:API schema with whatever you hand to it.
./models/schemas/category.json
{
"definitions": {
"attributes": {
"properties": {
"title": {
"type": "string"
},
"createdAt": {
"type": ["string", "null"],
"format": "date-time"
},
"updatedAt": {
"type": ["string", "null"],
"format": "date-time"
}
}
}
}
}
./models/Category.js
import { Model } from '@shabushabu/belay'
import schema from './schemas/category'
export class Category extends Model {
constructor (resource) {
super(resource, schema)
}
}
Here is an example of a model:
import { Model, DateCast } from '@shabushabu/belay'
import { Media, User, Category } from './Hierarchies'
import schema from './schemas/page'
export class Page extends Model {
constructor (resource) {
super(resource, schema)
}
static jsonApiType () {
return 'pages'
}
get attributes () {
return {
title: '',
content: '',
createdAt: null,
updatedAt: null,
deletedAt: null
}
}
get casts () {
return {
createdAt: new DateCast(),
updatedAt: new DateCast(),
deletedAt: new DateCast()
}
}
get relationships () {
return {
user: this.hasOne(User, 'user').readOnly(),
category: this.hasOne(Category, 'categories'),
media: this.hasOne(Media, 'media')
}
}
}
export default Page
jsonApiType
must be set. This would be the data.type
field on your API response. Belay also assumes that this is the base URI for HTTP requests (can be changed by overriding the baseUri
getter).
attributes
lets us define any attributes and their default values.
casts
allows us to mutate any attributes. By default Belay ships with a DateCast
and a CollectionCast
, but custom casts can also be created, for example for a money value object.
And finally, relationships
lets us define HasOne
and HasMany
relationships. Belay also includes a flag to auto-update any relationships when the model is saved. This behaviour can be completely deactivated via Model.autoSaveRelationships(false)
, but can also be set individually via the readOnly
method on the relation.
There are two ways to instantiate a new Belay model. By passing in nothing, aka undefined, or an object of attributes that is invalid JSON:API.
const page = new Page({
title: 'Contact Us'
})
page.content = "Go on, we don't bite"
const response = await page.create()
When a valid JSON:API object is passed into a Belay model, then it assumes it came from the API and sets its flags accordingly. Any relationships within includes
will also be hydrated, e.g. a user
relationship will turn into a User
model.
const validJsonApiResponse = { data: ... }
const page = new Page(validJsonApiResponse)
page.content = "Go on, we don't bite"
const response = await page.update()
Not sure why you wouldn’t know where your data comes from, but the createOrUpdate
method got your back!
const objectOfUnknownPedigree = { ... }
const page = new Page(objectOfUnknownPedigree)
page.content = "Go on, we don't bite"
const response = await page.createOrUpdate()
If the model attributes contain a deletedAt
field and deletedAt
is null, then Belay will set it to the current date, indicating that the model has been soft deleted. If the deletedAt
field is not null, however, then Belay will set the wasDestroyed
flag to true.
The deletedAt
attribute can be configured via the trashedAttribute
Model option or by overriding the trashedAttribute
getter.
const page = new Page({ data: ... })
const response = await page.delete()
Belay makes quite heavy use of Proxies. These allow us to do some nifty stuff with attributes and relationships without having to explicitly create this functionality on the model. The idea behind Belay is that it always keeps an up-to-date reference of a JSON:API resource in the background. So, when we update a model property Belay actually sets the value of that property on that JSON:API resource.
const page = new Page()
page.title = 'Some title'
page.content = 'Lorem what?'
page.category = new Category({ name: 'Boring' })
The proxy first checks if the property is contained within the attributes
of the model. If there isn’t an attribute with the given key, then Belay checks the relationships.
So, the above example would actually give us something like the following JSON:API representation:
{
"data": {
"id": "904754f0-7faa-4872-b7b8-2e2556d7a7bc",
"type": "pages",
"attributes": {
"title": "Some title",
"content": "Lorem what?",
"createdAt": null,
"updatedAt": null,
"deletedAt": null
},
"relationships": {
"category": {
"data": {
"type": "categories",
"id": "9041eabb-932a-4d47-a767-6c799873354a"
}
}
}
}
}
Additionally, it’s also possible to remove attributes and relationships like so:
const page = new Page()
delete page.title
delete page.category
Relationships, especially HasMany
, can also be set and removed another way:
const page = new Page()
// actual method on the model
page.attach('media', media)
// handled by the proxy
page.attachMedia(media)
// actual method on the model
page.detach('media', media)
// handled by the proxy
page.detachMedia(media)
Belay fires off a variety of events for most of its operations. Here’s a full list:
Model.SAVED
/ savsed
{ response, model }
Model.CREATED
/ created
{ response, model }
Model.UPDATED
/ updated
{ response, model }
Model.TRASHED
/ trashed
{ response, model }
Model.DESTROYED
/ destroyed
{ response, model }
Model.FETCHED
/ fetched
{ response, model }
Model.ATTACHED
/ attached
{ key, model, attached }
Model.DETACHED
/ detached
{ key, model, detached }
Model.COLLECTED
/ collected
{ response, collection, model }
Model.RELATIONS_SAVED
/ relationsSaved
{ responses, model }
Model.RELATIONSHIP_SET
/ relationshipSet
{ key, model, attached }
Model.RELATIONSHIP_REMOVED
/ relationshipRemoved
{ key, model }
Model.ATTRIBUTE_SET
/ attributeSet
{ key, model }
Model.ATTRIBUTE_REMOVED
/ attributeRemoved
{ key, model }
Here are some event examples, that all do the same thing:
Model.on(Model.SAVED, (payload) => { ... })
Model.onSaved((payload) => { ... })
Model.on([Model.CREATED, Model.UPDATED], (payload) => { ... })
Events can also be scoped to a specific model:
// Prefixing the event with the model type
Model.on('pages.saved', (payload) => { ... })
// Setting the event handler on a specific model
Page.on('saved', (payload) => { ... })
Page.onSaved((payload) => { ... })
And finally, when setting up your models, you can just override the boot
method to set up your scoped events:
import { Model } from '@shabushabu/belay'
export class Page extends Model {
...
static boot () {
this.onSaved((payload) => { ... })
}
...
}
Belay comes with a little helper method (mapResourceProps
) that allows you to re-hydrate your models semi-automatically after you got them from within the new fetch
hook.
import { mapResourceProps } from '@shabushabu/belay'
import { Page } from '@/models/Hierarchies'
/**
* @property {Page} pageModel
*/
export default {
async fetch () {
this.page = await Page.find(this.$route.params.slug)
},
data: () => ({
page: new Page()
}),
computed: {
...mapResourceProps({
page: Page
})
}
}
this.page
gets turned into a regular POJO with SSR, which is obviously not in our best interest. So, the helper dynamically adds the relevant computed properties. In this case this would be this.pageModel
, but it is also possible for collections and paginators.
import { mapResourceProps, Paginator, Collection } from '@shabushabu/belay'
...
computed: {
...mapResourceProps({
pages: Paginator, // this.pagesPaginator
categories: Collection // this.categoriesCollection
})
}
It is your responsibility to ensure that the dynamically generated props do not clash with any of your other props.
Any model can also be used statically. Under the hood null
is passed to the model, indicating that we want to run a query.
// get all pages
const response = await Page.get()
// get a single page
const page = await Page.find('904754f0-7faa-4872-b7b8-2e2556d7a7bc')
Query parameters can also be passed to the builder:
// GET /pages?filter[title]=Cool&include=user&limit=10
const response = await Page.where('title', 'Cool').include('user').limit(10).get()
This package uses sProxy quite a bit, so if you only target modern browsers, like Firefox, Chrome, Safari 10+ and Edge, then you’re golden. Not so much if you have to support old and tired browsers like IE. There is a polyfill, but use at your own risk.
Belay is still young and while it is tested, there will probs be bugs. I will try to iron them out as I find them, but until there’s a v1 release, expect things to go 💥. Oh, and one more thing, while this package is intended to work perfectly with Nuxt and Vue, I haven’t actually gotten round to testing Belay out in a real app yet. Might have to wait for Vue 3 😬
Do read the tests themselves to find out more about Belay!
$ yarn run test
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email boris@shabushabu.eu instead of using the issue tracker.
Author: ShabuShabu
Source Code: https://github.com/ShabuShabu/Belay
#vuejs #vue #javascript