Package Exports

@uql/core
@uql/core/entity/decorator
@uql/core/entity/util
@uql/core/options
@uql/core/querier
@uql/core/sql
@uql/core/util

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@uql/core) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

`{*}` uql = Universal Query Language

uql is a plug & play ORM, with a declarative JSON syntax to query/update different data-sources. Basically, just declare what you want from your datasource, and then uql will run efficient (and safe) SQL (or Mongo) queries.

Given uql is just a library/parser, its queries can be written and sent from the web/mobile to the backend, or use directly in the backend, or even use in the mobile with an embedded database.

Features
Installation
Entities
Configuration
Declarative Transactions
Programmatic Transactions
Generate REST APIs from Express
Consume REST APIs from Frontend
FAQs

🌟 Features

supports on-demand populate (at multiple levels), projection of fields/columns (at multiple levels), complex filtering (at multiple levels), grouping, and pagination.
programmatic and declarative transactions
generic and custom repositories
relations between entities
supports entities inheritance patterns
connection pooling
supports Postgres, MySQL, MariaDB, SQLite, MongoDB
code is readable, short, performant and flexible
plugins for frameworks: express, more soon...

🔋 Installation

Install the core package:

npm install @uql/core --save or yarn add @uql/core
Install the database package according to your database:
- for MySQL or MariaDB
  
  npm install @uql/mysql --save or yarn add @uql/mysql (also for mariadb)
- for PostgreSQL
  
  npm install @uql/postgres --save or yarn add @uql/postgres
- for SQLite
  
  npm install @uql/sqlite --save or or yarn add @uql/sqlite
- for MongoDB
  
  npm install @uql/mongo --save or or yarn add @uql/mongo
Set as true the following properties in the tsconfig.json file: experimentalDecorators and emitDecoratorMetadata

🥚 Entities

Take any dump class (DTO) and annotate it with the decorators from package '@uql/core/entity/decorator'. Notice that the inheritance between entities is optional.

import { v4 as uuidv4 } from 'uuid';
import { Id, Property, OneToMany, OneToOne, ManyToOne, Entity } from '@uql/core/entity/decorator';

/**
 * an abstract class can optionally be used as a template for the entities
 * (so boilerplate code is reduced)
 */
export abstract class BaseEntity {
  @Id({ onInsert: () => uuidv4() })
  id?: string;

  /**
   * 'onInsert' callback can be used to specify a custom mechanism for
   * obtaining the value of a property when inserting:
   */
  @Property({ onInsert: () => Date.now() })
  createdAt?: number;

  /**
   * 'onUpdate' callback can be used to specify a custom mechanism for
   * obtaining the value of a property when updating:
   */
  @Property({ onUpdate: () => Date.now() })
  updatedAt?: number;

  @Property()
  status?: number;
}

@Entity()
export class Company extends BaseEntity {
  @Property()
  name?: string;

  @Property()
  description?: string;
}

/**
 * a custom name can be specified for the corresponding table/document
 */
@Entity({ name: 'user_profile' })
export class Profile extends BaseEntity {
  /**
   * a custom name can be optionally specified for every property (this also overrides parent's class ID declaration)
   */
  @Id({ name: 'pk' })
  id?: string;

  @Property({ name: 'image' })
  picture?: string;
}

@Entity()
export class User extends BaseEntity {
  @Property()
  name?: string;

  @Property()
  email?: string;

  @Property()
  password?: string;

  @OneToOne({ mappedBy: 'user' })
  profile?: Profile;
}

@Entity()
export class TaxCategory extends BaseEntity {
  /**
   * Any entity can specify its own ID Property and still inherit the others
   * columns/relations from its parent entity.
   * 'onInsert' callback can be used to specify a custom mechanism for
   * auto-generating the primary-key's value when inserting
   */
  @Id({ onInsert: () => uuidv4() })
  pk?: string;

  @Property()
  name?: string;

  @Property()
  description?: string;
}

@Entity()
export class Tax extends BaseEntity {
  @Property()
  name?: string;

  @Property()
  percentage?: number;

  @ManyToOne()
  category?: TaxCategory;

  @Property()
  description?: string;
}

⚙️ Configuration

uql's initialization should be done once (e.g. in a file imported from a bootstrap file of your app).

import { setOptions } from '@uql/core';
import { PgQuerierPool } from '@uql/postgres';

setOptions({
  querierPool: new PgQuerierPool({
    host: 'localhost',
    user: 'theUser',
    password: 'thePassword',
    database: 'theDatabase',
  }),
  logger: console.log,
  debug: true,
});

🗣️ Declarative Transactions

uql supports both, programmatic and declarative transactions, with the former you have more flexibility (hence more responsibility), with the later you can describe the scope of your transactions.

take any service class, annotate a property to inject the querier with @InjectQuerier()
add Transactional() decorator on the function. The optional attribute propagation (defaults to required) can be passed to customize its value, e.g. @Transactional({ propagation: 'supported' }).

import { Querier } from '@uql/core/type';
import { Transactional, InjectQuerier } from '@uql/core/querier/decorator';

class ConfirmationService {

  @Transactional()
  async confirmAction(body: Confirmation,. @InjectQuerier() querier?: Querier): Promise<void> {
    if (body.type === 'register') {
      const newUser: User = {
        name: body.name,
        email: body.email,
        password: body.password,
      };
      await querier.insertOne(User, newUser);
    } else {
      const userId = body.user as string;
      await querier.updateOneById(User, userId, { password: body.password });
    }

    await querier.updateOneById(Confirmation, body.id, { status: CONFIRM_STATUS_VERIFIED });
  }
}

export const confirmationService = new ConfirmationService();

// then you can just import the constant `confirmationService` in another file,
// and when you call `confirmationService.confirmAction` all the operations there
// will automatically run inside a single transaction
await confirmationService.confirmAction(data);

🛠️ Programmatic Transactions

obtain the querier object with await getQuerier()
open a try/catch/finally block
start the transaction with await querier.beginTransaction()
perform the different operations using the querier
commit the transaction with await querier.commitTransaction()
in the catch block, add await querier.rollbackTransaction()
release the querier back to the pool with await querier.release() in the finally block.

import { getQuerier } from '@uql/core';

async function confirmAction(confirmation: Confirmation): Promise<void> {
  const querier = await getQuerier();

  try {
    await querier.beginTransaction();

    if (confirmation.entity === 'register') {
      const newUser: User = {
        name: confirmation.name,
        email: confirmation.email,
        password: confirmation.password,
      };
      await querier.insertOne(User, newUser);
    } else {
      // confirm change password
      const userId = confirmation.user as string;
      await querier.updateOneById(User, userId, { password: confirmation.password });
    }

    await this.querier.updateOneById(Confirmation, body.id, { status: CONFIRM_STATUS_VERIFIED });

    await querier.commitTransaction();
  } catch (error) {
    await querier.rollbackTransaction();
    throw error;
  } finally {
    await querier.release();
  }
}

⚡ Generate REST APIs from Express

uql provides a express plugin to automatically generate REST APIs for your entities.

Install express plugin in your server project npm install @uql/express --save or yarn add @uql/express
Initialize the express middleware in your server code to generate CRUD REST APIs for your entities

import * as express from 'express';
import { entitiesMiddleware } from '@uql/express';

const app = express();

app
  // ...other routes may go before and/or after (as usual)
  .use(
    '/api',
    // this will generate CRUD REST APIs for the entities.
    // all entities will be automatically exposed unless
    // 'include' or 'exclude' options are provided
    entitiesMiddleware({
      exclude: [Confirmation],
    })
  );

🌐 Consume REST APIs from Frontend

uql provides a client plugin to consume the REST APIs from the frontend.

Install client plugin in your frontend project npm install @uql/client --save or yarn add @uql/client

import { querier } from '@uql/client';

// 'Item' is an entity class
const lastItems = await querier.find(Item, {
  sort: { createdAt: -1 },
  limit: 100,
});

📖 Frequently Asked Questions

Why uql if there already are GraphQL, TypeORM, Mikro-ORM, Sequelize?

GraphQL requires additional servers and also learning a new language; uql should allow same this, but without need to configure and maintaining additional components.

On the other hand, existing ORMs like TypeORM, Mikro-ORM, and Sequelize; are in one way or another, coupled to databases; uql uses a declarative JSON syntax (agnostic from the datasource) which can easily be serialized and send as messages (e.g. through the network) between different components of a system (e.g. micro-services), and then each one has the flexibility to decide how to process these messages.

At last but not at least, uql helps with the communication between the different tiers of your system, e.g. it allows the frontend to send dynamic requests to the backend (like GraphQL).

@uql/core