datamapper

DataMapper
==========

DataMapper is an ORM with a focus on being easy to use.

DataMapper works Synchronously and is designed for applications where multiple concurrent requests are not important. It will reduce the concurrency of web servers. DataMapper was originally designed for use in an Electron Application where concurrency is not an issue and should not be used on web servers

Currently it only supports MySQL using the mysql package.

This is a Work in progress and currently only supports basic features:

- Entirely synchronous code
- Look up records by ID
- Loop through all records in the table

DataMapper allows you to access any database table as if it was a simple array. No callback hell, no obscure function names, just a simple array interface for all your database tables.

DataMapper does not load the entire database table into memory, it queries the database for just-in-time responses

Usage:

``js

//Load the MySQL module
const MySQL = require('mysql');

//Load the DataMapper module
const DataMapper = require('datamapper');

//Connect to the database and select a database:

var connection = new mysql.createConnection({
host: '127.0.0.1',
user: 'youruser',
password: 'yourpassword',
database: 'databasename'
});


//Now create a DataMapper instance by passing it a database connection and a table name, and name of the primary key column:

var albums = DataMapper.MySQL(connection, 'albums', 'id');

//Perform a SELECT query using the primary key:
//This will perform SELECT * FROM albums WHERE id = 123 and return the resulting record.
var album = albums[123];

console.log('Selected album title:');
console.log(album.title);

console.log('Selected album artist:');
console.log(album.artist);

console.log('end');


`

DataMapper is entirely synchronous so each command will run in order, avoiding callback hell and needlessly confusing code.

The code above will output something like:

`

Selected album title:
Empires
Selected album artist:
VNV Nation
end
`

You can also use the array directly:

`php

var albums = DataMapper.MySQL(connection, 'albums', 'id');

console.log(albums[123].title);
console.log(albums[123].artist);

`

DataMapper will cache the record internally so this will only perform a single SELECT query.

Looping through results
=======================

You can loop through all the records in the table using a simple for..of loop:

`js

var albums = Mapper.MySQL(connection, 'albums', 'id');

console.log('All albums:');

for (var album of albums) {
console.log(album.id + ': ' + album.artist + ': ' + album.title);
}

console.log('End of list');
`

Will output something like

`
All albums:
123: VNV Nation: Empires
124: Tool: Lateralus
125: Gary Numan: Splinter
126: VNV Nation: Transnational
127: VNV Nation: Automatic
End of list

`

Searching, limits and offsets
=============================

You can search for records using a simple API and the for...of loop:

`js

var albums = Mapper.MySQL(connection, 'albums', 'id');


for (album of album.filter({artist: 'VNV Nation'})) {
console.log(album.id + ': ' + album.artist + ': ' + album.title);
}

`

Which will output something like:

`
123: VNV Nation: Empires
126: VNV Nation: Transnational
127: VNV Nation: Automatic

`

You can also apply limits and offsets:

`js
var albums = Mapper.MySQL(connection, 'albums', 'id');


for (album of album.filter({artist: 'VNV Nation'}).limit(2).offset(1)) {
console.log(album.id + ': ' + album.artist + ': ' + album.title);
}

`

:

`
126: VNV Nation: Transnational
127: VNV Nation: Automatic

`

Inserting data
==============

To insert data you can either write to a specific primary key, e.g.

`js
//Issue an INSERT query, automatically setting the primary key
albums[1000] = {name: 'OK Computer', artist: 'Radiohead'};
`

This will create an INSERT query: INSER INTO albums (id, name, artist) VALUES (1000, 'OK Computer', 'Radiohead').

If there is already a record using the ID 1000, it will issue an update query: UPDATE albums SET artist = 'Radiohead', name = 'OK Computer' WHERE id = 1000


Alternatively you can write to the end of the table (For MySQL the primary key must be auto_increment for SQLite, ROWID is used):

`js

var newAlbum = {artist: 'Covenant', name: 'Northern Light'};
albums.push(newAlbum);

`

This will also set the primary key on the object:

`js
var newAlbum = {artist: 'Covenant', name: 'Northern Light'};
albums.push(newAlbum);

console.log(newAlbum.id); //The automatically generated ID e.g. 145
``