Repository files navigation

trilogy is a simple Promise-based wrapper for SQLite databases.It supports both the native C++sqlite3 driver and the pureJavaScriptsql.js backend — compile natively for speedwhen you need it, or usesql.js headache-free in cross-platform environmentsandElectron apps.

It's not an ORM and isn't intended to be one — it doesn't have anyrelationship features. Instead it focuses on providing a simple, clear APIthat's influenced more byMongoose than by SQL.

features ·installation ·usage ·contributing ·license

• 🔗automatically casts data between JavaScript & SQLite types

  Define schemas with types likeString,Date, or'increments' —trilogy will handle all the type-casting involved to map accuratelybetween JavaScript and the underlying SQLite database.

• 🔋powered by theknex query builder

  trilogy uses knex internally to build its queries, but it's also exposed soyou can use it to build your own. No need to mess with ridiculous multi-linestrings.

• 🔩supports multiple swappable backends (plus in-memory storage )

  Both the nativesqlite3 moduleandsql.js (pureJavaScript!) are supported. There is also memory-only storage for fast,unpersisted data handling, which is great for tests and performance criticalsituations.

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

• 👮written inTypeScript

  trilogy is written in and provides a first-class experience for TypeScript.

• 🔌lifecycle hooks

  Any number of hooks (aka subscribers or listeners) can be attached at severalpoints in the lifecycle — for exampleonQuery,beforeCreate,afterUpdate.These are useful for debugging and extensibility.

• 💞perfect forElectron &NW.js

  Compiling thesqlite3 module for all the platforms you target with Electronor NW.js can be difficult. That's why trilogy also supports thesql.js backend,which doesn't need to be compiled at all!

1. Install trilogy

   #using yarnyarn add trilogy#using npmnpm i trilogy

2. Install a backend

   #using yarnyarn add sqlite3#using npmnpm i sqlite3

   or

   #using yarnyarn add sql.js#using npmnpm i sql.js

Full documentation isavailable here and includes guides, an APIreference, and more.

Here's a quick overview. It usesasync &await but is easily usable withvanilla Promises.

import{connect}from'trilogy'// defaults to using the `sqlite3` backendconstdb=connect('./file.db')// choose `sql.js` to avoid native compilation :)constdb=connect('./file.db',{client:'sql.js'})// set the filename to ':memory:' for fast, in-memory storageconstdb=connect(':memory:',{// it works for both clients above!client:'sql.js'});(asyncfunction(){constgames=awaitdb.model('games',{name:{type:String},genre:String,// type shorthandreleased:Date,awards:Array,id:'increments'// special type, primary key})awaitgames.create({name:'Overwatch',genre:'FPS',released:newDate('May 23, 2016'),awards:['Game of the Year','Best Multiplayer Game','Best ESports Game']})constoverwatch=awaitgames.findOne({name:'Overwatch'})console.log(overwatch.awards[1])// -> 'Best Multiplayer Game'})()

This project is open to contributions of all kinds! Don't worry if you'renot 100% up to speed on the process — there's a short outline in theContributor 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'sCode of Conduct.

MIT © Bo Lingen / citycide

Seelicense