4.0 Model definition syntax

[felixfbecker]

Because the dicussion is spread across many issues and PRs, I wanted to open a new issue to discuss the future syntax for model definition.

Currently, besides the old define(), this syntax is possible in v4.0.0-1:

export class User extends Model {
 
    get fullName() {
        return this.firstName + ' ' + this.lastName;
    }
 
    set fullName(fullName) {
        const names = fullName.split(' ');
        this.lastName = names.pop();
        this.firstName = names.join(' ');
    }
}
User.init(({
    username: {
        type: DataTypes.STRING,
        primaryKey: true
    },
    lastName: DataTypes.STRING,
    firstName: DataTypes.STRING,
}, { sequelize })

If you prefer to not do the initialization (which also attaches the connection to the model) inside the model file, but rather from a model index file, this is also possible:

export class User extends Model {
 
    get fullName() {
        return this.firstName + ' ' + this.lastName;
    }
 
    set fullName(fullName) {
        const names = fullName.split(' ');
        this.lastName = names.pop();
        this.firstName = names.join(' ');
    }

    static init(sequelize) {
        super.init({
            username: {
                type: DataTypes.STRING,
                primaryKey: true
            },
            lastName: DataTypes.STRING,
            firstName: DataTypes.STRING,
        }, { sequelize })
    }
}

With the help of a decorator library and Babel transpilation, this is also possible:

@Options({ sequelize })
@Attributes({
    username: {
        type: DataTypes.STRING,
        primaryKey: true
    },
    lastName: DataTypes.STRING,
    firstName: DataTypes.STRING,
})
export class User extends Model {
 
    get fullName() {
        return this.firstName + ' ' + this.lastName;
    }
 
    set fullName(fullName) {
        const names = fullName.split(' ');
        this.lastName = names.pop();
        this.firstName = names.join(' ');
    }
}

And with TypeScript you can go even further:

@Options({ sequelize })
export class User extends Model {
 
    @Attribute({
        type: DataTypes.STRING,
        primaryKey: true
    })
    public username: string;
 
    @Attribute(DataTypes.STRING)
    public firstName: string;
 
    @Attribute() // Type is inferred as DataTypes.STRING 
    public lastName: string;
 
    get fullName(): string {
        return this.firstName + ' ' + this.lastName;
    }
 
    set fullName(fullName: string) {
        const names = fullName.split(' ');
        this.lastName = names.pop();
        this.firstName = names.join(' ');
    }
}

BUT we definitely do not want to require the usage of any transpiler. The Model.init() API feels a bit weird, especially how the sequelize connection is passed. Some thoughts:

• If we want to make models independent one day from connections, this is has the benefit of easily omitting the sequelize option
• But we would probably still need to require that models are registered in a model manager, so we could inverse the syntax (something like sequelize.add(Model) instead of passing the connection. That is not implemented atm though, currently the model needs to know about the connection.

Please chime in and share your thoughts and ideas!

Issues/PRs for reference: #5898 #6439 #5877 #5924 #5205 #4728

[felixfbecker]

@leebenson

The only small addition I'd love to see is a way to get the attributes defined in the class, similar to the syntax I referenced in #6439 (comment)

@options({ tableName: 'user', sequelize }) class User extends Model {

 // Attributes can be specified by a decorator...
@attribute name = {
   type: DataTypes.STRING,
   unique: true,
   // ...
 }

 // Class methods can be created using the `static` keyword
 static someClassMethod() {
   // `this` references the loaded sequelize instance... so we can get other models, etc.
 }

 // And instance methods are everything non-static
 someInstanceMethod() {
   // this.name, etc
 }
}

That's how Mobx do it, and adoption seems to be pretty good. Personally, I find the more that can be described succinctly in the body of the class, the easier it is to reason about what's a field, what's a class method and what's an instance, without having to define those in multiple places.

So the attribute configuration is defined as an attribute name on the model prototype? Is that even supported syntax in Node 4/6? Is that the attribute initializer proposal? If yes, I don't think we should put the configuration directly on the prototype per-attribute. It should sit under attributes, as it does now. And we shouldn't try to make JavaScript look like TypeScript by abusing property initializers.

[leebenson]

The decorator proposal is in flux, so I can't say whether that will be a future ECMAScript standard. That's basically what mobx do right now, and it works well.

In the meantime, this is how I'm handling loading models in v4. I'd appreciate your advice if you think this abuses the current API in any way.

Model loader

(influenced by Sequelize CLI 2.3; updated to match my environment)

// Checks whether we have the right env vars set; exits if not
require('./env')('DB_NAME', 'DB_USER', 'DB_PASSWORD');

import fs from 'fs';
import path from 'path';
import Sequelize from 'sequelize';

// Delay returns a promise that resolves after the number of
// milliseconds passed have elapsed.  This is useful for 'suspending'
// an awaited statement inside of an async function (in other words -
// to simulate a pause)
import delay from 'delay';

// Path to look for model files
const modelPath = path.join(__dirname, 'db_models');

// Open a new Sequelize client
const sequelize = new Sequelize(
  process.env.DB_NAME, // database name
  process.env.DB_USER, // username
  process.env.DB_PASSWORD, // password
  {
    host: 'percona', // points to a linked Docker host
    dialect: 'mysql',
  },
);

// Load each model file
export const models = Object.assign({}, ...fs.readdirSync(modelPath)
  .filter(function (file) {
    return (file.indexOf('.') !== 0) && (file.slice(-3) === '.js');
  })
  .map(function (file) {
    const model = require(path.join(modelPath, file)).default;
    return {
      [model.name]: model.init(model.fields, {
        sequelize,
      }),
    };
  })
);

// Load model associations
for (const model of Object.keys(models)) {
  typeof models[model].associate === 'function' && models[model].associate(models);
}

// Ping checks that the database server can be connected to. It attempts
// to connect every second for 60 seconds, before giving up and throwing
// an error back up to the chain.  This function is especially useful when using
// Docker Compose with a linked DB, which may not always be ready before
// the API server starts
export async function ping() {
  for (let i = 1; i <= 60; i++) {
    try {
      await sequelize.authenticate();
      return;
    } catch (e) {
      console.log(`DB connection attempt #${i} failed, retrying...`);
      await delay(1000);
    }
  }

  throw new Error("Couldn't connect to database!");
}

Sample Model definition (in this case, 'Session')

export default class Session extends Model {

  static fields = {
    id: {
      type: Sequelize.UUID,
      defaultValue: Sequelize.UUIDV4,
      primaryKey: true,
    },

    browser: {
      type: Sequelize.TEXT,
    },

    expiresAt: {
      type: Sequelize.DATE,
      defaultValue() {
        return moment().add(30, 'days').toDate();
      },
    },

    whatever: {
      type: Sequelize.VIRTUAL,
      get() {
        return 'it worked!';
      },
    },

    idAgain: {
      type: Sequelize.VIRTUAL,
      get() {
        return this.get('id');
      },
    }
  };

  // Session middleware that Koa uses to create a `ctx.session` object
  // for all subsequent middleware. (method appears at class-level and
  // *not* on the instance

  static middleware() {

    // We'll return this as an async function, so that it can be invoked
    // in the Koa config and bound to the currently loaded model
    return async function (ctx, next) {
      // ... omitted for brevity
    }.bind(this);
  }

  // This function is instance-level... it'll bind to the active record
  instanceFunction() {
    return true;
  }
}

Invoking the above inside an async function seems to work perfectly...

import * as db from './dbLoader';

(async function () {
  // Wait for the DB to be ready
  await db.ping();

  // Start a new instance
  const s = new db.models.Session;

  // Make sure we've got what we expect...
  console.log('s.id ->', s.id);
  console.log('s.idAgain ->', s.idAgain);
  console.log('s.middleware -> ', s.middleware);
  console.log('s.fields ->', s.fields);
  console.log('s.whatever ->', s.whatever);
  console.log('s.instanceFunction() ->', s.instanceFunction());

  // Plus the static method means I can wire up things that belong at
  // the class-level, like middleware
  const app = new Koa;
  app.use(db.models.Session.middleware());
})();

... which returns the expected output:

server_1 | Executing (default): SELECT 1+1 AS result
server_1 | s.id -> 5c3f792a-c66f-442d-96f8-ccbb630f7bae
server_1 | s.idAgain -> 5c3f792a-c66f-442d-96f8-ccbb630f7bae
server_1 | s.middleware -> undefined
server_1 | s.fields -> undefined
server_1 | s.whatever -> it worked!
server_1 | s.instanceFunction() -> true

[leebenson]

A few reasons why I chose the syntax in the above post.

• IMO, decorators proved to be overkill; assigning a static fields object at the class level gives me the 'class encapsulation' I was looking for without relying on an ECMAScript proposal that's in flux.
• Defining static/instance methods in one place and fields in another looked disjointed... this solves it by placing field defs inside the class, without bleeding out to the instance.
• The model loader wires up the models, so all we need to care about is creating a class that extends Sequelize.Model and exporting it as the default. This is a good separation of concerns, I think - previously, I was doing the sequelize.define() separately inside of each model file and wound up with repeated boilerplate for every new table definition.
• Table names are implicitly added from the class name, reducing repetition with an explicit tableName property.

[felixfbecker]

@leebenson

IMO, decorators proved to be overkill; assigning a static fields object at the class level gives me the 'class encapsulation' I was looking for without relying on an ECMAScript proposal that's in flux.

See my previous comment. Yes, decorators are still a proposal, but the complete Angular 2 framework is already built on it and that is now at a release candidate, people already use this in production and it works very well.

Please note that class properties can not be used in Node 4/6. It is a Stage 1 proposal, while decorators are already Stage 2. So the API you are proposing will not work without transpilation either, just like a decorator API.

I think aestetically, a static property and a decorator are on the same level, but decorators fit the use case better semantically (you decorate the class with metadata) and they have the benefit of normalization, while the class property would result in unexpected behaviour and would still require a seperate .init() call.

Defining static/instance methods in one place and fields in another looked disjointed

I agree.

Table names are implicitly added from the class name, reducing repetition with an explicit tableName property.

This is already implemented in 4.0.0-1. The tableName was just an example of passing options, I removed it to clarify it.

The model loader wires up the models, so all we need to care about is creating a class that extends Sequelize.Model and exporting it as the default. This is a good separation of concerns, I think - previously, I was doing the sequelize.define() separately inside of each model file and wound up with repeated boilerplate for every new table definition.

I don't get what you are trying to say. Imo a model file should be as self-contained as possible. I actually even use late imports instead of the module.exports = function(sequelize, DataTypes) { pattern, so I don't even need a model index file that "wires up" the models, they wire up themselves, including associations. I tried to highlight a bit of this in my PR to update the docs, see https://github.com/felixfbecker/sequelize/blob/76590ab17ad8d160272a7e02bd7b381bc49ae919/docs/docs/models-definition.md#one-file-per-model-pattern

[leebenson]

See my previous comment. Yes, decorators are still a proposal, but the complete Angular 2 framework is already built on it and that is now at a release candidate, people already use this in production and it works very well.

No arguments there. I'm already using decorators with mobx too, and I love them! I just couldn't find a better fit for wiring up field definitions than a static property on the class. A decorator function seemed like overkill.

I don't get what you are trying to say. Imo a model file should be as self-contained as possible. I actually even use late imports instead of the module.exports = function(sequelize, DataTypes) { pattern, so I don't even need a model index file that "wires up" the models, they wire up themselves, including associations. I tried to highlight a bit of this in my PR to update the docs, see https://github.com/felixfbecker/sequelize/blob/76590ab17ad8d160272a7e02bd7b381bc49ae919/docs/docs/models-definition.md#one-file-per-model-pattern

What I'm saying is that defining field types within the body of the class seems like a better approach.

In your example, you do this...

class Pub extends Sequelize.Model { }
Pub.init({
  name: Sequelize.STRING,
  address: Sequelize.STRING,
  latitude: {
    type: Sequelize.INTEGER,
    allowNull: true,
    defaultValue: null,
    validate: { min: -90, max: 90 }
  },
  longitude: {
    type: Sequelize.INTEGER,
    allowNull: true,
    defaultValue: null,
    validate: { min: -180, max: 180 }
  }
}, {
  sequelize,
  validate: {
    bothCoordsOrNone() {
      if ((this.latitude === null) !== (this.longitude === null)) {
        throw new Error('Require either both latitude and longitude or neither')
      }
    }
  }
})

This part irks me...

class Pub extends Sequelize.Model { }
Pub.init({
// ...
})

You've created a class to extend Model, but it's blank. Presumably the only benefit here is that you've removed the need to explicitly define tableName.

Then in a separate call, you initialise it with .init() and feed in the field definitions.

IMO, it looks better to keep them defined within the class. Whether it's a decorator or a static property is less relevant... more so is that syntax outside of the class makes it hard to reason about exactly what fields the model contains. I have 500+ lines of field definitions and boilerplate in some places... I'd rather keep that inside the class than stick it where my .init() code goes, which could well be somewhere outside of the model definition entirely.

Just my personal preference.

[felixfbecker]

Yes, init() after the class is definitely the ugly part about the API. But as I said, there is no way to do it without using a transpiler atm (and then decorators are a better solution). And we of course also still have define().

[leebenson]

Another option is static method... they've been in Node since 4+ and don't require any transpilation at all:

class Session extends Sequelize.Model {
  static fields() {
    return {
      id: {
        type: Sequelize.UUID,
        // ....
      }
    }
  }
}

[mickhansen]

@felixfbecker Is the model name taken from the class name? In that case we need a way to override it because a lot of people generally have lower case model names but would probably have lint rules telling them to have uppercase class names

[felixfbecker]

@leebenson Yes, but imo having a method that always returns the same configuration object just because the language doesn't have property declarations yet is syntax abuse and DSLish.

@mickhansen yes, the model name is the name property of the class, which is the class name. It is a native property of all functions. It can be overridden with the modelName option or when using sequelize.define(). But to be honest I think we should use PascalCase naming in the docs because it is confusing when User.name !== 'User'.

[leebenson]

@felixfbecker re: lower casing, I'm currently doing it explicitly like this (in my model loader)

import utils from 'sequelize/lib/utils';

// Load each model file
export const models = Object.assign({}, ...fs.readdirSync(modelPath)
  .filter(function (file) {
    return (file.indexOf('.') !== 0) && (file.slice(-3) === '.js');
  })
  .map(function (file) {
    const model = require(path.join(modelPath, file)).default;
    return {
      [model.name]: model.init(
        (typeof model.fields === 'function' && model.fields()) || {},
        Object.assign({
            sequelize,
            tableName: utils.pluralize(model.name.toLowerCase()), // <--- this bit
          },
          (typeof model.attributes === 'function' && model.attributes()) || {},
        ),
      ),
    };
  })

With my session definitions now looking closer to this:

export default class Session extends Model {

  static fields() {
    return {
      id: {
        type: Sequelize.UUID,
        defaultValue: Sequelize.UUIDV4,
        primaryKey: true,
      },
     // ....
    };
  }

//.....
}

So a Session class becomes a sessions table.

I agree with you that a method returning the same static data isn't ideal. It's an alternative to requiring a transpilation step, though, and it's only run once. Plus, it's an opportunity to bind the current sequelize client as a parameter, in case definitions somehow rely on it.

Hard to get that with a static class attribute or a decorator that's outside of the definition scope.

[felixfbecker]

Please note that tableName and modelName are two different options.

Plus, it's an opportunity to bind the current sequelize client as a parameter, in case definitions somehow rely on it.

I am highly against this. In a static method, I expect this to be the class. Or are you not talking about binding?

Hard to get that with a static class attribute or a decorator that's outside of the definition scope.

It's super simple to share the sequelize instance is to simply have a module that exports it, and require it in the model files.

[mickhansen]

But to be honest I think we should use PascalCase naming in the docs because it is confusing when User.name !== 'User'

Definitely, just need to make sure it's possible to reconfigure