Upgrading from 4.0

The 4.1 release contains bunch of bug fixes and API improvements to keep the code base simple and less magical. I tried to keep the breaking changes as few as possible, however cannot eliminate them completely.

Getting started

The first step is to get the latest version of all dependencies. I personally use npm-check to pull latest versions of packages.

npm install -g npm-check

Run the following command to interactively update dependencies.

npm-check -u

Exception handling

One of the biggest changes have been done in the Global exception handler.

Make the following changes inside app/Exceptions/Handler.js file. Feel free to ignore this section, if you never created the global exception handler.

  1. Make sure your exception handler extends the BaseExceptionHandler.

    const BaseExceptionHandler = use('BaseExceptionHandler')
    
    class ExceptionHandler extends BaseExceptionHandler {
    }
  2. Call super.handle for exceptions you don’t want to handle.

    class ExceptionHandler extends BaseExceptionHandler {
      async handle (error, { response }) {
        if (error.name === 'UserNotFoundException') {
          // handle it yourself
          return
        }
    
        super.handle(...arguments)
      }
    }
  3. At last you can remove Exception.bind calls from your codebase, since all exceptions will be routed to the global exception handler.

Routing

Route.url

The Route.url generates a fully qualified URL to a pre-registered route. Earlier the domain was passed as a string literal and now it is accepted as an object.

Earlier

Route.url('posts/:id', { id: 1 }, 'blog.adonisjs.com')

Now

Route.url('posts/:id', { id: 1 }, { domain: 'blog.adonisjs.com' })

Validator

The validator provider now uses latest version of Indicative. Here’s the list of breaking changes due to API changes done in Indicative.

formatters

There is no concept of named formatters anymore. If you want to use a pre-existing formatter, you pass it as a reference, instead of passing it’s name.

Earlier

const { validate } = use('Validator')
validate(data, rules, messages, 'jsonapi')

Now

const { validate, formatters } = use('Validator')
validate(data, rules, messages, formatters.JsonApi)

The same applies to route validators too.

Earlier

class StoreUser {
  get formatter () {
    return 'jsonapi'
  }
}

Now

const { formatters } = use('Validator')

class StoreUser {
  get formatter () {
    return formatters.JsonApi
  }
}

configure

New version of Indicative exposes the configure method to define library wide defaults. They same can be used with Validator provider too.

const { formatters, configure } = use('Validator')

configure({
  FORMATTER: formatters.JsonApi
})

Lucid

Date formatting was inconsistent with newly created records and already existing records. Same has been fixed in the newer release with a small breaking change. Make sure to read the related issue.

dates

The date fields will longer be casted to moment instances on the model instance. For example

Earlier

const user = await User.find(1)
user.created_at instanceof moment // true

Now

const user = await User.find(1)
user.created_at instanceof moment // false

This change prevents you from mutating the date on the model instance directly and instead make use of castDates hook to mutate the date when you serialize the model properties.

The castDates hook will work as earlier

class User extends Model {
  static castDates (field, value) {
    if (field === 'dob') {
      return `${value.fromNow(true)} old`
    }
    return super.formatDates(field, value)
  }
}

Goodies

Bunch of bug fixes have been done to keep the codebase reliable. Also a handful of perfomance improvements have been done.

Validator

Since indicative is written from groundup, the new version is 2x faster than the old one.

Middleware

The middleware parsing layer now resolves all middleware at the time of booting the app and just instantiates a new instance of them for each request. Whereas earlier the resolve process was done for each request.

Betters errors

The errors will appear in a nice formatted way on your terminal as shown in the screenshot.

DTHfXErU8AADIyQ