6.0.0 Release Notes

[devinivy]

Note

The name of this module has switched from schwifty to @hapipal/schwifty on npm.

Summary

Schwifty v6.0.0 is focused on modernization, slimming the API surface area, and consitency across the hapi pal ecosystem (esp. consistent with Schmervice). This release has also been published as @hapipal/schwifty as part of an organization-wide effort to standardize the names and documentation for all hapi pal modules under the @hapipal npm scope.

• Upgrade time: low to moderate - a few hour for most users. The upgrade time should be lowest for users of the pal boilerplate and haute-couture. It could be a more extensive upgrade particularly for users who are on a version of node below v12 or version of hapi below v19.
• Complexity: low to moderate - there are several API changes, but each one is expected to be straightforward to detect, confirm, and fix.
• Risk: low - most breaking changes are relevant to configuration that occurs before the server starts, so an incomplete or incorrect upgrade will typically be apparent before running in production.
• Dependencies: moderate - all dependents will have at least some API changes to address.

Breaking Changes

• The package is now published as @hapipal/schwifty rather than schwifty.
• Versions of node below v12 and versions of hapi below v19 are no longer supported.
• server.schwifty() has been renamed to server.registerModel(), and now only accepts a model or list of models (no longer an object with knex, migrationsDir, and models).
• When registering schwifty, options.models is no longer supported.
• Model.getJoiSchema() has been replaced by Model.joiSchema and Model.joiSchemaPatch.

New Features

• In node v12+ static class properties are supported, so you are encouraged to define Model.tableName and Model.joiSchema directly and access them directly (previously these were often defined as getters, and Model.joiSchema was accessed through the cached Model.getJoiSchema()).
• Similarly, the model's patch Joi schema can be accessed at Model.joiSchemaPatch, derived as a cached getter from Model.joiSchema. Previously Model.joiSchemaPatch was accessed as Model.getJoiSchema(true).

Bug fixes

None

Migration Checklist

Update to the new @hapipal/schwifty package

The entire hapi pal ecosystem is in the process of moving to the @hapipal npm scope, so the package name has changed to @hapipal/schwifty. You can find our organization on npm here.

Checklist:

• In package.json replace "schwifty": "5.x.x" (or similar) with "@hapipal/schwifty": "6.x.x".
• If you are a user of haute-couture, you will want to upgrade to haute-couture to v4. See its migration guide here. The reason for this is due to server.schwifty() being renamed to schwifty.registerModel(), which is a detail that haute-couture depends on.
• Ensure that your deployment does not register both schwifty and @hapipal/schwifty packages. To do so, you might run npm ls schwifty in your project in order to find any other other plugins on your server using an older version of Schwifty. If they do, you should update them to use Schwifty v6 as well.

Node and hapi version

Make sure your node version is v12 or newer. This release is designed with language features in mind that are only available in node v12 or higher (especially static class properties). Node v14 is the current LTS and the recommended version of node. This release also will enforce that it is running on hapi v19 or newer.

Separate model registration from plugin configuration

To reduce the API surface area and be more consistent with Schmervice, now models must be registered using server.registerModel() (no longer passed on options.models during plugin registration). By the same token, all other configuration must be passed during plugin registration (no longer passed to server.schwifty()).

Checklist:

• Find all calls to server.schwifty() which pass models, and update them to instead call server.registerModel().

  // Before (v5)
  server.schwifty(Model);
  server.schwifty([ModelA, ModelB]);
  server.schwifty({ models: [ModelC, ModelD] });
  
  // After (v6)
  server.registerModel(Model);
  server.registerModel([ModelA, ModelB]);
  server.registerModel([ModelC, ModelD]);

• Find all places that options.models is passed during plugin registration, and instead add models using server.registerModel() after plugin registration.

  // Before (v5)
  await server.register({
      plugin: Schwifty,
      options: {
          migrationsDir: './some/directory',
          models: [ModelA, ModelB]
      }
  });
  
  // After (v6)
  await server.register({
      plugin: Schwifty,
      options: {
          migrationsDir: './some/directory'
      }
  });
  
  server.registerModel([ModelA, ModelB]);

  If you happen to use the feature whereby the option.models plugin option specifies a directory where models are located, there is no comparable feature in Schwifty v6. It is recommended to use haute-couture to auto-load models from a directory.

• Find all places that (non-model) configuration is passed to server.schwifty(), and instead pass that configuration as plugin options during registration.

  // Before (v5)
  await server.register({
      plugin: Schwifty
  });
  
  server.schwifty({
      migrationsDir: './some/directory'
  });
  
  // After (v6)
  await server.register({
      plugin: Schwifty,
      options: {
          migrationsDir: './some/directory'
      }
  });

Replace Model.getJoiSchema() with Model.joiSchema or Model.joiSchemaPatch

Schwifty v5 and below were designed with versions of node in mind that did not support static class properties, and Model.joiSchema was assumed to be defined as a getter. The downside to this is that the schema would be rebuilt each time Model.joiSchema was accessed, so Model.getJoiSchema() existed to introduce some caching to avoid this performance penalty. In Schwifty v6 we support node v12+, so Model.getJoiSchema() has been removed, and Model.joiSchema should be defined directly as a static class property rather than as a getter.

Checklist:

• Switch static get joiSchema() getter to a static class property (you may additionally update tableName).

  // Before (v5)
  class Dog extends Schwifty.Model {
      static get tableName() {
  
          return 'Dog';
      }
  
      static get joiSchema() {
  
          return Joi.object({
              id: Joi.number(),
              name: Joi.string()
          });
      }
  }
  
  // After (v6)
  class Dog extends Schwifty.Model {
      static tableName = 'Dog';
      static joiSchema = Joi.object({
          id: Joi.number(),
          name: Joi.string()
      });
  }

• Find usage of Model.getJoiSchema() and replace it with Model.joiSchema.

• Find usage of Model.getJoiSchema(true) and replace it with Model.joiSchemaPatch.