trilogy

# changelog

# 2.0.5 (opens new window) (2021-08-08)

# BUG FIXES

# 2.0.4 (opens new window) (2021-08-08)

# BUG FIXES

# 2.0.3 (opens new window) (2020-06-20)

# BUG FIXES

# v2.0.2 (opens new window) (2019-06-30)

# BUG FIXES

# 2.0.1 (opens new window) (2019-06-24)

# BUG FIXES

# 2.0.0 (opens new window) (2019-06-12)

v2.0.0 is a significant release. The highlights are:

  • rewritten in TypeScript
  • lifecycle hooks
  • Node 8.10 minimum version requirement

To try it out, use:

# using yarn
yarn add trilogy@2.0.0

# using npm
npm i trilogy@2.0.0

The documentation has also been expanded and improved, and is available at https://trilogy.js.org (opens new window).

# codename: solid source

trilogy has been rewritten in TypeScript, which paid off early and often — two of the last three 1.x patch releases contained fixes found in the process of refactoring the code base with types. It also provides a greatly improved editing experience:

click to expand 
import * as trilogy from 'trilogy'

const db = trilogy.connect(':memory:')

// you can provide types like this to `model()`
// to get compiler assistance
type Person = {
  name: string
}

;(async () => {
  const people = await db.model<Person>('people', {
    name: String
  })

  await people.create({ names: 'typo' })
  // !> Property 'names' does not exist in type 'Person'. Did you mean 'name'?
})()

# lifecycle hooks

A set of lifecycle hooks has been implemented, of which before* variants support canceling events. These hooks are useful for debugging, logging, and simple plugin-like addons.

click to expand 
const { connect, EventCancellation } = require('./dist')

const db = connect(':memory:')

;(async () => {
  const notRobots = await db.model('notRobots', {
    name: String,
    intelligence: Number
  })

  const unsub = await notRobots.beforeCreate(async person => {
    if (person.intelligence < 1650) {
      console.log('ignoring total human- ... uh, robot')
      return EventCancellation
    }

    person.name += ' (totally not a robot)'
  })

  console.log(await db.create('notRobots', {
    name: '0110101101001111010001010',
    intelligence: 96156615
  }))

  // -> { name: '0110101101001111010001010 (totally not a robot)',
  //      intelligence: 96156615 }

  console.log(await db.create('notRobots', {
    name: 'Tom',
    intelligence: 100
  }))

  // "ignoring total human- ... uh, robot"
  // -> undefined

  // removes the hook, objects after this are unaffected
  unsub()

  await db.close()
})()
# BUG FIXES
# FEATURES
# PERFORMANCE
# BREAKING CHANGES
  • schema: providing both the nullable & notNullable properties will cause an Error to be thrown.
  • where,cast: invalid where clauses and unrecognized types at casting will now cause Errors to be thrown.
  • schema-helpers: an error will be thrown when column type cannot be retrieved.
  • invariant: InvariantErrors are no longer thrown, they are Errors instead.
  • flow: flow definitions have been removed.
  • find*: find() and findOne() on models no longer accept an optional column argument. Instead, use the new findIn() or findOneIn() methods. Top level trilogy methods still accept table.column dot notation.
  • count: model.count no longer has a signature allowing a column as the first parameter. This is now a separate method called countIn.
  • schema-helpers: using an unknown column type in a descriptor will now result in an error.
  • an error will now be thrown immediately from methods that require a property name if none is provided.
  • date serialization has changed to improve reliability and predictability.
  • incr & decr have been renamed to increment & decrement.
  • invalid options objects passed to methods accepting them will now cause exceptions to be thrown.
  • the verbose option has been removed from trilogy instances. Use the new onQuery hook instead.

Support for Node 4 and Node 6 has been dropped, meaning trilogy now requires >=8.10.

trilogy no longer has a default export in order to better support TypeScript users. The recommended way to create a new instance has also changed (though the old way is still possible).

// before
import Trilogy from 'trilogy'
const db = new Trilogy(':memory:')

// after
import { connect } from 'trilogy'
const db = connect(':memory:')

# v1.4.6 (opens new window) (2019-05-30)

To prevent installation breakage on newer Node releases, a third-party dependency now has its version pinned.

# BUG FIXES
  • package: pin osom dependency to prevent installation breakage

# 1.4.5 (opens new window) (2018-04-24)

No changes since 1.4.4 - this release restores the v1 release line to the latest tag, where a v2 beta was accidentally publish.

# 1.4.4 (opens new window) (2018-01-09)

# BUG FIXES

# 1.4.3 (opens new window) (2018-01-09)

# BUG FIXES

# 1.4.2 (opens new window) (2017-12-08)

# BUG FIXES
# PERFORMANCE

# 1.4.1 (opens new window) (2017-11-16)

Small patch for TypeScript users to correctly export types.

# BUG FIXES
  • types: fix TypeScript typings (#75) @IKnowBashFu

# 1.4.0 (opens new window) (2017-11-04)

# FEATURES

# 1.3.0 (opens new window) (2017-08-24)

This release brings a pair of exciting features!

First up is the ability to define getters and setters when creating models. These are useful for things like formatting after selects and making sure conforming data before inserts.

const people = await db.model('people', {
  name: String,
  username: {
    type: String,
    get (username) {
      return `username is: ${username}`
    },
    set (username) {
      // remove anything that isn't alphanumeric or underscore
      return username.replace(/[^\w]/gi, '')
    }
  }
})

await people.create({
  name: 'Bo Lingen',
  username: 'ci.ty]ci[d/e'
})
// -> { name: 'Bo Lingen', username: 'citycide' }

await people.get('username', { name: 'Bo Lingen' })
// -> 'username is: citycide'

// can use `getRaw()` and `setRaw()` to bypass getters / setters
// other methods may also accept a `raw` property in their options object
await people.getRaw('username', { name: 'Bo Lingen' })
// -> 'citycide'

There's also a new memory-only mode - if the file path is exactly ':memory:', no file will be created and an in-memory store will be used. This doesn't persist any data but is useful for speed and performance reasons. For example, most of trilogy's tests now use in-memory databases to avoid tons of disk usage.

const db = new Trilogy(':memory:')
# BUG FIXES
# FEATURES
# PERFORMANCE

# 1.2.1 (opens new window) (2017-07-25)

# BUG FIXES

# 1.2.0 (opens new window) (2017-06-09)

# FEATURES

# 1.1.0 (opens new window) (2017-03-23)

# BUG FIXES
# FEATURES

# 1.0.0 (opens new window) (2017-03-16)

We've officially arrived at 1.0.0!

But don't let that stop you from submitting issues if you come across problems, or pull requests if there's something that can be improved or added.

Thanks for the help getting here!

# BUG FIXES

# 1.0.0-rc.5 (opens new window) (2017-02-26)

This is probably the last release candidate before 1.0.0!

...

I feel like I've said that before.

# BUG FIXES

# 1.0.0-rc.4 (opens new window) (2017-02-24)

This is probably the last release candidate before 1.0.0!

# BUG FIXES

# 1.0.0-rc.3 (opens new window) (2017-02-04)

This release contains a breaking change regarding the return value of create(). You can follow the discussion leading up to this change in #21 (opens new window), #22 (opens new window), & #24 (opens new window).

Many thanks to @jonataswalker (opens new window) who put in a lot of effort for this one.

# BUG FIXES
# FEATURES
# PEFORMANCE
# BREAKING CHANGES
  • create: The return value of create() is no longer the number of created objects. Instead, create() returns the created object.

# 1.0.0-rc.2 (opens new window) (2017-01-17)

# BUG FIXES

# 1.0.0-rc.1 (opens new window) (2017-01-13)

🙌 Welcome to the very first official release candidate of Trilogy! 🙌

The next version will be v1.0.0 unless there are any significant issues discovered.

There have not been significant changes since v0.11.1.

# BUG FIXES
# FEATURES

# 0.11.1 (opens new window) (2017-01-10)

This is a small feature patch on top of v0.11.0 adding model() options that include the ability to set compound primary keys, multiple unique properties, and add timestamp properties (created_at and updated_at).

Note: the changes below are mostly from v0.11.0.

# BUG FIXES
# FEATURES
# BREAKING CHANGES

Major breakage inbound. See #14 (opens new window) for more info and useful migration tips.

# 0.10.0 (opens new window) (2016-12-17)

# BUG FIXES
# FEATURES
# BREAKING CHANGES
  • Any instances of retrieving knex's schema or query builder through trilogy must now use for example: db.queryBuilder.[method] instead of db.getQueryBuilder().[method]. The same applies to schema builder.
  • Any commonjs users requireing trilogy no longer need .default due to using commonjs export instead of Babel's export default fill.

# 0.9.2 (opens new window) (2016-09-14)