Skip to content

Latest commit

 

History

History
131 lines (82 loc) · 4.27 KB

README.md

File metadata and controls

131 lines (82 loc) · 4.27 KB
Raw

Build Status Coverage Status

adelia

🐧 Antarctic-friendly ORM for Node

Adélie penguins on an iceberg

Photo (c) by Jason Auch

Design Principles

Adelia is meant to be a fast, simple, promise-based ORM for Node, loosely inspired to Martin Fowler's ActiveRecord pattern popularized by Ruby on Rails. Due to the async IO nature of Node and DB clients, the API must be async. Adelia uses Promises to offer a clean, uncluttered API that's easy to compose and reason about.

Features

  • Accessors: has, get, set, unset.
  • Persistence: save, delete.
  • Query: find, findById, findAll, findByQuery, countAll.
  • Relationships: hasOne, hasMany, belongsTo, hasAndBelongsToMany.
  • Specialization: create.

Configuration

Set these environment variables in your script:

  • DB one of the supported databases: mysql (default), or sqlite (experimental).

MySQL

Set these variables to configure Adelia to use a MySQL database server:

  • MYSQL_HOST host of the MySQL database server.
  • MYSQL_PORT port of the MySQL database server.
  • MYSQL_USER username to connect to the MySQL database server.
  • MYSQL_PASSWORD password of the user of the MySQL database server.
  • MYSQL_DB name of the MySQL database.

This assumes you already have a MySQL server to use. For local development, see the Development section below.

SQLite

Set this variable to configure Adelia to use a SQLite database:

  • SQLITE_DB path to the SQLite database file.

Usage

Adelia has a concise, promise-based API that allows you to perform chained operations to query and fetch model objects, access their properties, persist, and delete them. Here's an example:

const Model = require('adelia').Model;

// Creates a specialized model class
const Penguin = Model.create('penguin');

// Instantiates a penguin
const emperor = new Penguin({
  species: 'Emperor'
});

let emperor_id;

// Saves the penguin to DB
emperor.save()
	.then(model => model.get('id'))
	.then(id => { emperor_id = id; });

// Fetches a model from the DB
Penguin.find(emperor_id)
	.then(model => model.get('species'))
	.then(name => console.log(`My species is ${name}`));
// => My species is Emperor

Status

  • MySQL support: STABLE
  • SQLite support: EXPERIMENTAL

MySQL support is currently stable, with some known issues. SQLite support is currently experimental. Tests are failing locally and in TravisCI. If you'd like to use Adelia on SQLite and can contribute fixes and enhancements, please submit a PR!

Contributing

Thank you for your interest in Adelia! Feel free to open issues or submit a PR. See the Contributing Guidelines for detailed instructions.

Development

Adelia is a Node module. If you are unsure what to do, follow these steps:

Installing a local MySQL server

For development, it's best to use a local MySQL server. I use MAMP on Mac OS X, but you can also run MySQL server in a Docker container.

Install dependencies

npm install

Run tests

The default test target should be sufficient for most contributors:

npm test

If you want to run tests for MySQL alone, run:

npm run test-mysql

There are also SQLite specific tests:

npm run test-sqlite

Code of Conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

License

MIT

Copyright (c) 2016, 2017 Claudio Procida