@bithero/simple-rest-orm

Simple-rest-ORM

An Simple ORM for rest API's

License

AGPL-3.0-or-later; see LICENSE file for more details

Usage

import { jsonName, jsonProperty } from 'ts-serializable';
import { entity, Entity, registerClient } from '@bithero/simple-rest-orm';
import 'reflect-metadata';

// Defining an entity by extending Entity; with the @entity decorator you can specify extra options
// such as the entity name to use or the clientname
@entity({name: 'my-entity', client: 'myClient'})
class MyEntity extends Entity {
    @jsonName('_name')
    @jsonProperty(String)
    private name: string;

    @jsonProperty(String)
    public city: string;

    // Constructors need to have default arguments because the serlizer needs an
    //  default constructor (i.e. `new MyEntity();`)
    public constructor(name: string = "") {
        super();
        this.name = name;
    }

    public getName(): string {
        return this.name;
    }
}

// Registering an client to use; the name (second argument) is optional and defaults to 'default'
registerClient({
    // each buildRequest* function can either return an Request object, an URL or an string containing an url
    buildRequestFind(entityName, id) {
        return `http://localhost:3000/api/${entityName}/${id}`;
    },
    buildRequestAll(entityName, query) {
        return new URL(`http://localhost:3000/api/${entityName}`);
    },
    buildRequestQuery(entityName, query) {
        return new Request(`http://localhost:3000/api/${entityName}/query`, { method: 'POST', body: JSON.stringify(query) });
    },
    buildRequestDelete(entityName, id) {
        return new Request(`http://localhost:3000/api/${entityName}/${id}`, { method: 'DELETE' });
    },
    buildRequestCreate(entityName, data) {
        return new Request(`http://localhost:3000/api/${entityName}`, { method: 'POST', body: JSON.stringify(data) });
    },
    buildRequestUpdate(entityName, data) {
        return new Request(`http://localhost:3000/api/${entityName}/${data.id}`, { method: 'PUT', body: JSON.stringify(data) });
    },
    sendRequest: fetch,
}, 'myClient');

// retriving an single entitiy
let result = await MyEntity.find("123");

// retrieving all entities
let all = await MyEntity.all();

// quering multiple entities; the query can be completly custom and is defined by your API
let results = await MyEntity.query({ name: { $regex: "^Peter" } });

// deleting either works on an entity
result.delete();
// ... or via the entity
MyEntity.delete("1234");

// creating entities is as simple as instantiate an object and calling `save()`
let newEntity = new MyEntity("Dan");
newEntity.save();

// ... and updateing is even simpler!
newEntity.city = "London";
newEntity.save();

Associations

import { jsonProperty } from 'ts-serializable';
import { entity, Entity, oneToMany, oneToOne } from '@bithero/simple-rest-orm';
import 'reflect-metadata';

@entity({ name: 'ref-entity' })
class RefEntity extends Entity {}

@entity({name: 'my-entity'})
class MyEntity extends Entity {

    // Uses an subroute to lookup the references; i.e.:
    //  ==> GET /my-entity/<this.id>/refs
    // Note: this field is generated and completly overwritten after de-serialization
    @oneToMany({ type: 'subroute', subroute: 'refs', entity: RefEntity })
    private refs_a: RefEntity[];

    // Uses an array of id's inside this entity to lookup the references:
    //  this['refs_b'] = [ '1234', '5678' ]
    //      ==> GET /ref-entity/1234
    //      ==> GET /ref-entity/5678
    @oneToMany({ type: 'arrayOfIds', entity: RefEntity })
    @jsonProperty([String])     // Needed in order to de-serialize the array of id's
    private refs_b: RefEntity[];

    // Uses an single id inside this entity to lookup the reference
    //  this['ref'] = '1234'
    //    ==>
    //  this['ref'] = fetch( GET /ref-entity/1234 )
    @oneToOne({ entity: RefEntity })
    @jsonProperty(String)       // Needed in order to de-serialize the id
    private ref: RefEntity;
}