@shabushabu/belay

Belay

An active-record(ish) implementation for a JSON:API that gets you safely to the top

ToDo

• Add http tests for the builder
• Add tests for scoped model events and boot method
• Review existing tests with regard to the package being Nuxt-only now
• Add tests for Collection & Paginator hydration
• Allow for mixins to be set on the model (this.constructor.prototype or this.prototype ? / in boot method ?)
• Non-existing relationships will have to be saved before the model
• World domination

Installation

‼️ 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'
  },
  // ...
}

Usage

Single Table Inheritance

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

Schemas

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)
  }
}

Model

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.

Creating

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()

Updating

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()

Upserting

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()

Deleting

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()

Model Attributes & Relationships

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)

Events

Belay fires off a variety of events for most of its operations. Here's a full list:

• Model.SAVED / savsed
  • Fires when a model was created and updated
  • Payload: { response, model }
• Model.CREATED / created
  • Fires when a model was created
  • Payload: { response, model }
• Model.UPDATED / updated
  • Fires when a model was updated
  • Payload: { response, model }
• Model.TRASHED / trashed
  • Fires when a model was trashed
  • Payload: { response, model }
• Model.DESTROYED / destroyed
  • Fires when a model was destroyed
  • Payload: { response, model }
• Model.FETCHED / fetched
  • Fires when a model was retrieved from the API
  • Payload: { response, model }
• Model.ATTACHED / attached
  • Fires when a relationship was attached to a model
  • Payload: { key, model, attached }
• Model.DETACHED / detached
  • Fires when a relationship was detached to a model
  • Payload: { key, model, detached }
• Model.COLLECTED / collected
  • Fires when a collection was retrieved
  • Payload: { response, collection, model }
• Model.RELATIONS_SAVED / relationsSaved
  • Fires when relationships have been auto-saved
  • Payload: { responses, model }
• Model.RELATIONSHIP_SET / relationshipSet
  • Fires when a relationship was set
  • Payload: { key, model, attached }
• Model.RELATIONSHIP_REMOVED / relationshipRemoved
  • Fires when a relationship was removed
  • Payload: { key, model }
• Model.ATTRIBUTE_SET / attributeSet
  • Fires when an attribute was set
  • Payload: { key, model }
• Model.ATTRIBUTE_REMOVED / attributeRemoved
  • Fires when an attribute was removed
  • Payload: { 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) => { ... })
  }

  ...
}

In your components...

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.

Builder

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()

‼️ Caveats

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 😬

Tests

Do read the tests themselves to find out more about Belay!

$ yarn run test

Credits

• All Contributors
• BTT, aka Boris Travelled Today, where Belay was extracted from
• Robson Tenório for the builder, the parser and some of the model
• Ivan Boyko [cc] for the belay icon

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

License

The MIT License (MIT). Please see License File for more information.