millerdrew / trilogy

No-hassle SQLite with a Promise-based document store style API, type-casting schema models, and support for both native & pure JavaScript backends.

trilogy is a Promise-based layer over SQLite, featuring type-casting schema models and allowing both native & pure JavaScript backends ( and in-memory databases ).

• features
• installation
• usage
• contributing
• license

---

features

• Model your tables with native JavaScript

  Set up database tables with types like String, Date, and 'increments' - and trilogy will handle all the type-casting involved so that you always receive what you expect to receive.

• Uses knex to build queries

  trilogy uses knex internally to build its queries - but it's also exposed so you can use it to build your own ultra-complex queries. No need to mess with ridiculous multi-line strings.

• Swappable SQLite backends ( plus in-memory storage )

  trilogy supports both the native sqlite3 module as well as sql.js - meaning you can easily embed a SQLite database without a compilation step like gyp, which can get a little tricky when dealing with multiple platforms or architectures.

  You can even swap the backend after you've started, with no changes to the rest of your code! 🎉

• trilogy ❤️ Electron & NW.js

  If you've run into issues using sqlite3 in Electron or NW.js, like many have before you, you can easily use trilogy with the sql.js backend, which doesn't need to be compiled at all! Plus, you still get all the greatness of a simple API and all the raw power of knex's query building - wrapped in a neat little package. 🎁

installation

1. Install trilogy

   npm i trilogy

2. Install a backend

   npm i sqlite3

   or

   npm i sql.js

usage

See the documentation here for the full API - including usage syntax and examples.

Here's a quick overview. It uses async & await but is easily usable with vanilla Promises.

import Trilogy from 'trilogy'

// defaults to using the `sqlite3` backend
const db = new Trilogy('./file.db')

// choose `sql.js` to avoid native compilation :)
const db = new Trilogy('./file.db', {
  client: 'sql.js'
})

// set the filename to ':memory:' for fast, in-memory storage
const db = new Trilogy(':memory:', {
  // it works for both clients above!
  client: 'sql.js'
})

;(async function () {
  const games = await db.model('games', {
    name: { type: String },
    genre: String,                           // type shorthand
    released: Date,
    awards: Array,
    id: 'increments'                         // special type, primary key
  })

  await games.create({
    name: 'Overwatch',
    genre: 'FPS',
    released: new Date('May 23, 2016'),
    awards: [
      'Game of the Year',
      'Best Multiplayer Game',
      'Best ESports Game'
    ]
  })

  const overwatch = await games.findOne({ name: 'Overwatch' })

  console.log(overwatch.awards[1])
  // -> 'Best Multiplayer Game'
})()

contributing

This project is open to contributions of all kinds! Don't worry if you're not 100% up to speed on the process - there's a short outline in the Contributor Guide.

You'll also find a reference for the set of labels used to categorize issues, with descriptions of each. (Contributor Guide - issue labels)

Also, please read and follow the project's Code of Conduct.

license

MIT © Bo Lingen / citycide

See license