Intaglio
Note: These docs are in the process of being written. The code examples are up to date, but not exhaustive.
Intaglio is an awesome, define-once, use anywhere ORM. The goals of this project are to make an easy to use, persistence independent ORM for JavaScript that can be used in the front or back end to make rapid prototyping and development a breeze. Intaglio takes an ActiveRecord style approach to defining models by allowing your repositories (persistent storage handlers) to define the schema.
Installation
To use with NPM:
npm install --save intaglio
To use with Bower
bower install --save intaglio
Quick-Start Guide
To get up and running quickly with Node and MySQL, here's how you would instantiate the ORM:
var Intaglio = ; /** * Instantiate the MySQL repository that the ORM will bind to. */var repository = host: "localhost" user: "db_user" password: "password" database: "database_name"; /** * Create an ORM to work with. This returns a promise because the ORM must wait * for the repository to become ready. The MySQL repository makes a few queries * on instantiation to get the database structure. We can't start using it until * these calls have completed. */IntaglioORM;
Repositories
Currently, Intaglio ships with a MySQL and a REST respository (designed to be used with the Intaglio based REST server) to get you up and running quickly. The MySQL repository will use database introspection to define your model schema so all you need to provide are the connection details to get started using with Node. The REST repository comes with a Request based driver as well as a jQuery based one to be used on the front end.
Using the ORM
Considerations
The ORM should be pretty easy to use, but there are some things to keep in mind. We made some design decisions to make the implentation simpler and easier to maintain.
Naming Conventions
The ORM will not care what names you use on the repository side, but it will normalize them to make it easier to code around. All model names and property names will be normalized to camelCase. Model names will also be made singular. So if your repository provides a model named user_profiles
, it will be normalized to userProfile
.
Primary Keys
The ORM will expect some sort of primary key to bind to. Also, while multiple column keys can be used, they are not well tested, so if you use them, let us know what issues you run into.
Schema Used for the Examples
In the following examples, we'll use a user
model that has the following schema:
- id (Primary Key)
- first_name
- last_name
Creating Objects from Models
// Create an empty user objectvar user = ORM; // Set a single value to the objectuser; // Set multiple values to the objectuser; // Save the object. This returns a promise.user; // Create an object with values and save itORM;
Finding Objects
In order to make things easy to use, Intaglio relies on natural language chain style queries:
// Finds and returns the first model in the repository that has the firstName of DonnyORM; // Finds and returns all models in the repository that have the firstName of DonnyORM; // Finds a user with an id of 1ORM;
Updating Objects
ORM;
Deleting Objects
ORM;
Extend Models
To add methods to models or override functionality, you can extend the model. If you override a method, you can access the original method using this._super
.
// Extend the user modelORM;
Events
The models in the ORM have a few built in events that you can bind to:
// Load WalterORM;
Custom Events
// Extend the user model to add a custom functionality that triggers a custom eventORM; var Walter Donny; // Load WalterORM;