Objection.js: Version 1.0

[koskimas]

I think we should jump to 1.0 after 0.9. Starting from 1.0 objection will follow semver.

The only significant difference will be a more stable API. No breaking changes between minor or patch versions and new major versions will be released less frequently than minor versions now. New features can still be added easily.

I think objection is ready for this. What do you think? If there are things you wish to change, now is the time to open an issue and start a discussion. What I'm mostly looking for is inconsistencies in terminology, naming and the API in general.

__EDIT__: Objection has always followed a modified version of semver where patch releases never intentionally break backward compatibility. Breaking changes have only been introduced in minor version updates.

[fl0w]

On Gitter you mentioned tableRefFor and tableNameFor, and while not currently public you expressed an intent to make them public as soon as you felt comfortable with the approach. Any updates on if these are viable public interfaces before 1.0?

[koskimas]

@fl0w I think those could be made public for 0.9. I'll create an issue as a reminder.

[elhigu]

When 1.0 is released, should we lock up also the knex version which is used by it, since knex is not yet stable?

[koskimas]

@elhigu Maybe.. But that was a real PITA before. Most issues and pull requests were about bumping the knex version 😄

[devinivy]

I would suggest not pinning knex– I think it's fine for v1 software to have a peer dependency on a package that's not v1. Also, knex is widely used and has proven to be relatively stable. I suppose if you find it really important, you could pin the peer dependency and cause npm to warn users upon install (that's all npm would do, right?), but still allow users to choose their own version.

Over the next week or so we at @BigRoomStudios will be thinking about objection v1 and report back with any notes/suggestions. I think one area of interest for v1 is to catch common misconfiguration/misuse (like this https://github.com/Vincit/objection.js/commit/d2e40624a1ec6d4368f38e5fdd779a37bf5bc479) and provide useful errors– I suggest this now because I can see how introducing those errors in the future may technically be a breaking change in some cases.

[koskimas]

I would also love to add a cross-db error API but as I have mentioned before it would be best implemented as a separate library. Then it could possibly be moved to knex at some point.

Currently errors thrown from db for example in case of foreign key constraint violation differ from db to db and are usually difficult to reason with. I would love to have something like:

class DbError extends Error { ... }

class ConstraintViolationError extends DbError {
  get column() { ... }
  get table() { ... }
  get constraintName() { ... }
}

class ForeignKeyConstraintViolationError extends ConstraintViolationError {
  ...
}

// etc.

If someone is looking for an open source project, here's one that I think would benefit the whole node.js DB scene.

[elhigu]

@devinivy I've been doing backwards incompatible changes (mostly throwing errors instead of silently ignoring invalid use) in pretty much every knex version lately and it seems that those keeps coming. For example next version jumps from 0.13 -> 0.14 because some stuff doesn't work the same way that earlier.

I agree that objection should not disallow using different knex versions, but I don't see that objection can guarantee stability between different knex versions.

So IMO there needs to be some way (I suppose documentation would be minimum viable solution, but I would prefer runtime error which can be explicitly disabled) to communicate to the user, which knex version is officially supported.

[devinivy]

Oh, I see– yeah, I think it's fair for objection to specify a range of knex minor versions that it supports. Before v1, minor version updates indicate potential breaking changes per semver. I thought we were talking about pinning knex to a specific patch version.

Also @koskimas huge +1 to that. It would be a very useful project.

[fl0w]

On the topic of errors and breaking changes. Instead of extending the error object, would it be of interest to append a unique identifier - effectively making a change in error message a minor/patch update instead?

This would be inline with what node core is doing with https://github.com/nodejs/node/issues/11273

[koskimas]

@fl0w That could be an even better approach. The only problem I can think of is that the errors thrown by databases pretty much already contain all meaningful property names like code, message, type etc. At least postgres errors do, and that's enough. Our property would need to be something that doesn't conflict with any of the existing properties. Maybe we could use errorSymbol = Symbol() and something like

const { errorSymbol, errorCodes } = require('db-error');

function onError(error) {
  if (error[errorSymbol].code === errorCodes.ConstraintViolation) {
    console.log(error[errorSymbol].column)
    console.log(error[errorSymbol].constraintName)
  }
}

[koskimas]

Actually the above approach has at least one severe downside: The custom information would not appear in the stack trace or error message. So uncaught errors would be as confusing as always.

Let's continue the error handling conversation here.

[mceachen]

@koskimas IMHO your work has been 1.0-worthy for as long as I've used the project. You've done an excellent job of shipping stable releases.

Given the API of Objection is strongly tied to Knex, which isn't 1.0 yet, you'll need to increment the major version of Objection when Knex adds non-backward-compatible changes, but I don't think that's bad--that's just how semver works. I think it's strictly better, in fact, in that your users will know when big things have changed.

Thanks again for Objection! Looking forward to v1.0.0!

[jtlapp]

FYI, I'm looking at revised typings that fix query builder issues but that aren't backward compatible with existing typings in one regard:

QueryBuilder<Person> would previously yield a Person[] but now yields just a Person. To get a person array under this proposal, you'd do QueryBuilder<Person, Person[]>.

This possibility suggests that we may want to get the typings completely working before going to 1.0, lest we later feel pressure to bump the version number for non-backwards-compatible typings.

[mceachen]

@jtlapp let's keep typing discussions on different issues and channels, but grossly speaking, I would like the typings to follow semver semantics along with the rest of the codebase. It might help to get an idea of how many people use the typings in the first place, as well.

All users of Objection + TypeScript: could you :tada: this comment to get a rough user count, please?

[koskimas]

I think we are pretty close to the 1.0 release! I'd love it if you could try out the RC versions before the official release. The RC 10 should already be really stable and close to the final release. You can find the 1.0 changelog here.

[koskimas]

1.0 is now released.