@thorbens/database v1.0.0-alpha.25

Description

This repository provides a common description for database operations (CRUD). The code is writte in in Typescript and transpiled against the node 14 LTS features set.

1. Documentation
2. Usage
3. Recommended Usage
4. Common Database
5. Implementations

Documentation

The generate typedoc documentation can be found here.

Usage

A database implementation should implement the abstract Database class.

import {Database} from "@thorbens/database";

class MyDatabase implements Database {
...
}

To perform CRUD operations, a Repository should be used. Therefore, a model should be defined:

class MyDatabaseModel extends DatabaseModel {
  foo: string;
}

Performing a query against the repository:

// create a new database instance
const database = new MyDatabase();
// depending on implementation, connect may be called before any operation
await database.connect();
// retrieve the repository for your model
const repository = database.getRepository(MyDatabaseModel);
// create a query to perform a complex request
const query = repository.createQuery();
// retrieve the condition builder for building conditions
const conditionBuilder = database.getConditionBuilder<MyDatabaseModel>();
// create a simple equal operator
const equalOperator = conditionBuilder.createEqualOperator(
  "foo",
  "bar"
);
// add the operator the the query
query.addCondition(equalOperator);

// execute the query
const result = await repository.findByQuery(query);

Recommended use for retrieving a database instance

Invoke a database via typescript-ioc:

import { Container, Scope } from "typescript-ioc";
import { Database } from "@thorbens/database";

// bind your database implementation to the database
Container.bind(Database).to(MyDatabase).scope(Scope.Singleton);

And inject it in your services:

import {Inject} from "typescript-ioc";
import {Database} from "@thorbens/database";

class DatabaseService {
    private readonly database: Database;

    public constructor(
        @Inject database: Database,
        ...
    ) {
        this.database = database;
    }
}

CommonDatabase

The CommonDatabase package provides an abstraction for database operations. To create conditions for an unknown database, the CommonDatabaseConditionBuilder can be used. A DatabaseConditionParser is able to parse CommonDatabaseOperatorObjects for the implemented database.

CommonDatabaseConditionBuilder & DatabaseConditionParser

CommonDatabaseConditionBuilder provides functionality to build database conditions such as logical conditions (e.g. or condition) and atom conditions (e.g. equal condition). This might be useful to send complex dynamic database queries generated by a client to a backend service:

Example:

import {CommonDatabaseConditionBuilder} from "@thorbens/database";

// build a condition in your client
const conditionBuilder = new CommonDatabaseConditionBuilder<MyDatabaseModel>();
const value = "foo";
const key = "bar";
const operator = conditionBuilder.createEqualOperator(key, value);
const commonObject = operator.toCommonObject();

// send the common object to a receiver (e.g. a backend service)
...

// use it with your database
const receivedCommonObject = ...
const myDatabase = new MyDatabase();
const parsedCondition = myDatabase.getConditionParser().parse(receivedCommonObject);
if (!parsedCondition) {
    // error handling
}
const query = myDatabase.createQuery<MyDatabaseModel>();
query.addCondition(parsedCondition);
...

Implementations