UniMapperJS

UniMapperJS is universal Node.js (native ES6/ES7) LINQ-like object mapper (ORM/ODM) which can map whatever you create adapter for.

!! Under DEVELOPMENT !!

See wiki

Main Features

• Adapters - if your database isn't supported, you can write own adapter,
• migrations - migration scripts - you can check migration script before applying,
• seeding - seed default data into storage,
• more connections across adapters (eg. take data from MongoDB or two MongoDBs and insert it into MySQL),
• unit of work - tracking changes in transactions,
• updating just changed properties - saving resources,
• quering like C# LINQ to Entities (with JS function names)

TODO

• implement Entity.addUnique() which allow UNIQUE key over more fields
• implement Entity.addPrimary() which allow PRIMARY key over more fields
• implement bulk operations
• implement JOINs
• implement nested operations (eg. saving Enterprise should save all Employees in Enterprise.Employees collection too. Same rollbacking etc.)
• add beforeSave() method into entity class - allow some operation before saving
• add baseQuery property into entity class - it'll be used in ALL select queries (can be used for soft-delete)
• implement client-side execution (query from client will send AJAJ request to server which will handle it as normal server query; something like automatic GraphQL)
• add whereOr() and whereOrIf() into Query

Example

You can clone and play with the example in this repo.

Directory structure of this example

• entities
• migrations
• domain.js
• create-migration.js
• run-migration.js

Create domain

domain.js

const $um = require("unimapperjs");
const MySqlAdapter = require("unimapperjs/adapters/MySqlAdapter");
 
// Domain creation - connect to database via MySQL adapter
const domain = $um.createDomain(MySqlAdapter, { // connection string or object with options - specific to adapter
    host: '127.0.0.1',
    user: 'test',
    password: 'test',
    database: "test"
});
exports.domain = domain;

Create entities

Then create entities in given domain. In TypeScript you can declare entity like this one.

etities/Student.ts

import {type} from "unimapperjs";
import {Entity} from "unimapperjs/src/Entity";
import {domain} from "../domain";
import {Teacher} from "./Teacher";
 
@domain.entity()
export class Student extends Entity<Student>
{
    /**
     * Student Id
     */
    id: number;
 
    /**
     * Student name
     */
    name: string;
 
    /**
     * Student's teacher id
     */
    teacherId: number;
 
    /**
     * Navigation property to Teacher
     */
    teacher: Promise<Teacher>;
 
    static map(map: Student) {
        const {Teacher} = require("./Teacher");
 
        map.id = <any>type.uuid;
        map.name = <any>type.string.length(100);
        map.teacherId = <any>type.number;
        map.teacher = <any>type.foreign(Teacher.name)
            .withForeign<Student>(s => s.teacherId);
    }
}

entities/Teacher.ts

import {type} from "unimapperjs";
import {Entity} from "unimapperjs/src/Entity";
import {domain} from "../domain";
import {Student} from "./Student";
 
/**
 * Teacher entity
 */
@domain.entity()
export class Teacher extends Entity<Teacher>
{
    /**
     * Teacher ID
     */
    id: number;
 
    /**
     * First name
     */
    firstName: string;
 
    /**
     * Last name
     */
    lastName: string;
 
    /**
     * Navigations property to assigned students
     */
    students: Promise<Array<Student>>;
 
    /**
     * Mapping
     */
    static map(map: Teacher) {
        const {Student} = require("./Student");
 
        map.id = <any>type.number.primary().autoIncrement();
        map.firstName = <any>type.string.length(50);
        map.lastName = <any>type.string.length(50);
        map.students = <any>type.foreign(Student.name)
            .hasMany<Student>(s => s.teacherId);
    }
}

Migrate

Now you can run migraion.

create-migration.js

const $umjs = require("unimapperjs");
const $path = require("path");
const {domain} = require("./domain");
 
// Discove all entities from given path
$umjs.initEntitiesFrom($path.resolve(__dirname, "entities"));
 
// Run it in next event loop iteration
setImmediate(async () => {
    await domain.createMigration($path.resolve(__dirname, "migrations"));
    await domain.dispose();
});

New migration script is gonna be generated in folder ./migrations like this one.

/**
 * Migration script
 */
 
module.exports = {
    up: async function up(adapter) {
        await adapter.createEntity("Student", {
              "id": {
                  "type": "String"
                , "length": 37
                , "primary": true
            }
            , "name": {
                  "type": "String"
                , "length": 100
            }
            , "teacherId": {
                  "type": "Number"
                , "length": 11
            }
        });
 
        await adapter.createEntity("Teacher", {
              "id": {
                  "type": "Number"
                , "length": 11
                , "primary": true
                , "autoIncrement": true
            }
            , "firstName": {
                  "type": "String"
                , "length": 50
            }
            , "lastName": {
                  "type": "String"
                , "length": 50
            }
        });
 
        await adapter.addForeignKey("Student", "teacherId", "Teacher", "fk_Student_teacherId_Teacher_id");
    }
};

You can run that migration script with

run-migration.js

const $path = require("path");
const {domain} = require("./domain");
 
setImmediate(async () => {
    await domain.runMigration($path.resolve(__dirname, "migrations"));
    await domain.dispose();
});

Insert some data

let teacher = new Teacher({
    firstName: "John",
    lastName: "Wick"
});
await Teacher.insert(teacher);
 
let teacher2 = new Teacher();
teacher2.firstName = "John";
teacher2.lastName = "Smith";
await Teacher.insert(teacher2);
 
let student = new Student({
    name: "Bart Simpson",
    teacherId: teacher.id
});
await Student.insert(student);
 
student.teacher = teacher2;
await student.save();

Make some queries

// Teachers their first name contains "u"
let teachers = await Teacher.getAll()
    .filter(t => t.firstName.includes("u"))
    .sort(t => t.firstName)
    .exec();

// Students their name starts with 'P' or ends with 's'
let startsWith = "P";
let students = await Student.getAll()
    .filter(s => s.name.startsWith($) || s.name.endsWith("s"), startsWith)
    .sortDesc(s => s.name)
    .slice(3, 8) // limit 5, skip 3
    .exec();

let onlyActive = true;
let activeSubjectsCount = await Subject.getAll()
    .filterIf(s => s.active === true, onlyActive) // if (onlyActive) { .filter(s => s.active === true) }
    .count()
    .exec();

let subjectNames = await Subject.getAll()
    .sort(s => s.name)
    .map(s => s.name) // select only names ; in SQL SELECT name FROM Subject
    .exec();

let subjectMap = await Subject.getAll()
    .sort(s => s.name)
    .map(s => ({
        id: s.id,
        name: s.name
    }))
    .exec();