June release - 2021

This is the first release after the major release of v5. So, this is special as it contains a handful of bug fixes and some improvements that didn't make it to the main release last month.

As always, let's start with the highlights of the release.

Upgrading to the latest versions

The following packages have been updated during the current release.

• Updated @adonisjs/assembler from version 5.1.1 -> 5.3.1
• Updated @adonisjs/ally from version 3.2.1 -> 4.0.2
• Updated @adonisjs/lucid from version 14.0.0 -> 15.0.1
• Updated @adonisjs/mail from version 7.1.1 -> 7.2.1
• Updated @adonisjs/core from version 5.1.6 -> 5.1.8

You can upgrade to the latest versions of all the packages using the npm update command or manually installing packages with the @latest tag.

npm i @adonisjs/assembler@latest
npm i @adonisjs/ally@latest
npm i @adonisjs/lucid@latest
npm i @adonisjs/mail@latest
npm i @adonisjs/core@latest

Async local storage and HTTP Context

This is a big one, contributed by @targos . We are using ALS (async local storage) within the HTTP requests to make the HTTP context available anywhere inside your codebase.

For example, with ALS enabled, you can write the following code.

import HttpContext from '@ioc:Adonis/Core/HttpContext'

class User extends BaseModel {
  public static query() {
    const ctx = HttpContext.get()!
    return super.query(ctx.tenant.connection)
  }
}

ALS is a complicated topic, as you first have to understand how the Node.js event loop works and its impact on how we write and structure our code.

We recommend first reading about async hooks and async local storage in general and then head over to AdonisJS ALS guide to learn about the usage within the framework.

• Original implementation PR#18
• Further changes to the API PR#42

Facebook, Linkedin, and Discord social auth drivers

Along with the existing set of Ally drivers. We now also have the following drivers available.

• LinkedIn
• Discord driver is contributed by Mesteery PR#120
• Facebook driver is contributed by irwing-reza PR#121

Check out this boilerplate repo to create your custom ally drivers. We will appreciate it if you can publish it as a package on npm and share it with the rest of the community.

Support for calendar events in the mailer

The mailer now allows sending calendar invites by either attaching an existing invite (.ics file) or creating one on the fly using the calendar's fluent API. For example:

Mail.sendLater((message) => {
  message.icalEvent((calendar) => {
    calendar
      .createEvent({
        summary: 'Adding support for ALS',
        start: DateTime.local().plus({ minutes: 30 }),
        end: DateTime.local().plus({ minutes: 60 }),
      })
  })
})

The docs have been updated to cover the calendar invites API.

Events error handler

The error handling with events so far was not that good. To capture errors that occurred during the emit lifecycle of an event, you will have to wrap your Event.emit calls inside a try/catch statement.

After this release, you can register a custom onError handler to listen for errors occurred during the emit life cycle an event.

import Event from '@ioc:Adonis/Core/Event'

Event.onError((event, error, eventData) => {
  // handle the error
})

Run migrations programmatically

The latest release of @adonisjs/lucid allows running migrations programmatically using the Migrator module. For example:

import Route from '@ioc:Adonis/Core/Route'
import Migrator from '@ioc:Adonis/Lucid/Migrator'
import Database from '@ioc:Adonis/Lucid/Database'
import Application from '@ioc:Adonis/Core/Application'

Route.get('/', async () => {
  const migrator = new Migrator(Database, Application, {
    direction: 'up',
    dryRun: true,
  })

  await migrator.run()
  return migrator.migratedFiles
})

Read the migration docs to learn more about the API.

Breaking changes

We have two very minor breaking changes in this release inside the @adonisjs/lucid and @adonisjs/ally packages.

Lucid

We have renamed the following TypeScript ambient modules. This change will ideally not impact your applications, as these modules only contains the static types and were not commonly used.

• Changed @ioc:Adonis/Lucid/Model to @ioc:Adonis/Lucid/Orm
• Changed @ioc:Adonis/Lucid/Relations to @ioc:Adonis/Lucid/Orm
• Changed @ioc:Adonis/Lucid/DatabaseQueryBuilder to @ioc:Adonis/Lucid/Database

Ally

As we are adding new drivers to the codebase, the possibility of not able to get a user's email address is increasing. Hence, we have to update the email property in the AllyUserContract type to be null | string.

After this change, you will have to guard against missing emails as follows.

const facebookUser = await ally.use('facebook').user()

if (!facebookUser.email) {
  // handle the use case for missing email
}

Features & small improvements

• feat: add nl2br helper 42ba955af
• feat: add stringify global helper fd0cd1ae5
• improvement: do not report SQL errors to validator 5480de78d
• feat: add support to serializing props by giving preference to user input ef4668fe4
• feat: add withScopes method 039defb13 , 65ab31ec8
• feat: add support for query isolation b808f03b7
• improvement: detect port for the encore dev server when default one cb877cf6e .
• improvement: cleanup build directory when there is an error during the build process e88001fac
• improvement: pass debug flag and custom reporter data to cloned queries 091dea1bb
• feat: expose default naming strategy from Orm binding b69305497
• improvement: improve database config options 398b24a87
• feat: add helpers shortcut to repl context e43695bcf
• feat: add support for serializing models directly from paginator 6b67cad88

Bug fixes

• fix: request.completeUrl should include the port alongwith the hostname 068c63aa3
• fix: allow runtime variables in aliases dynamic imports 4355e448d
• fix: do not attempt to serialize relationship values set as null 85e440783
• fix: apply relationship constraints during paginate and first methods 7fd7ea417
• fix: use correct query for health checks for oracledb 48dc522ab
• fix(httpexceptionhandler): add missing await to view.render method call 34e613323
• fix: broken extend logic for ally manager 1a722f8e4
• fix webpack dev server not being killed by CTRL + C on windows 232f1ad51