nukak-express

The perfectionistic ORM for TypeScript and modern JavaScript ideated to be fast, safe, and simple to plug into any application. Inspired by others such as TypeORM and Mongo driver.

 

Features

• Serializable queries: its syntax is 100% valid JSON allowing the queries to be transported across platforms with ease.
• Type-safe and Context-aware queries: squeeze the strength of TypeScript so it auto-completes, validates, and infers the appropriate operators on any level of the queries, including the relations and their fields.
• High performance: the generated queries are fast, safe, and human-readable.
• Combines the best elements of OOP (Object Oriented Programming) and FP (Functional Programming).
• Declarative and imperative transactions for flexibility, and connection pooling for scalability.
• Modern Pure ESM packages. ESM is natively supported by Node.js 12 and later.
• soft-delete, virtual fields, repositories.
• Supports the Data Mapper pattern for maintainability.
• Transparent support for inheritance between entities for reusability and consistency.
• Unified syntax across Databases: providing a standard API and transparently transforming queries according to the configured database.

 

Install

1. Install the core package:

   npm install nukak --save
   

2. Install one of the specific adapters for your database:

Database	Driver	Nukak Adapter
MySQL	mysql2	nukak-mysql
MariaDB	mariadb	nukak-maria
SQLite	sqlite sqlite3	nukak-sqlite
PostgreSQL	pg	nukak-postgres
MongoDB	mongodb	nukak-mongo (alpha)

For example, for Postgres:

npm install pg nukak-postgres --save

1. Additionally, your tsconfig.json may need the following flags:

   "target": "es2020",
   "experimentalDecorators": true,
   "emitDecoratorMetadata": true
   

 

Configure

A default querier-pool can be set in any of the bootstrap files of your app (e.g. in the server.ts).

import { setQuerierPool } from 'nukak';
import { PgQuerierPool } from 'nukak-postgres';

export const querierPool = new PgQuerierPool(
  {
    host: 'localhost',
    user: 'theUser',
    password: 'thePassword',
    database: 'theDatabase',
  },
  // optionally, a logger can be passed to log the generated SQL queries
  { logger: console.log }
);

// the default querier pool that `nukak` will use
setQuerierPool(querierPool);

 

Define the entities

Take any dump class (aka DTO) and annotate it with the decorators from nukak/entity.

import { v4 as uuidv4 } from 'uuid';
import { Id, Field, Entity } from 'nukak/entity';

/**
 * any class can be annotated with this decorator to make it works as
 * an entity.
 */
@Entity()
export class User {
  /**
   * an entity should specify an ID Field, its name and type are automatically detected.
   * the `onInsert` property can be used to specify a custom mechanism for
   * auto-generating the primary-key's value when inserting.
   */
  @Id({ onInsert: uuidv4 })
  id?: string;

  /**
   * the properties of the class can be annotated with this decorator so they
   * are interpreted as a column, its name and type are automatically detected.
   */
  @Field()
  name?: string;

  @Field()
  email?: string;

  @Field()
  password?: string;
}

 

Manipulate the data

import { getQuerier } from 'nukak';
import { User } from './shared/models/index.js';

async function findLastUsers(limit = 10) {
  const querier = await getQuerier();
  const users = await querier.findMany(
    User,
    {
      $sort: { createdAt: -1 },
      $limit: limit,
    },
    ['id', 'name', 'email']
  );
  await querier.release();
  return users;
}

async function createUser(body: User) {
  const querier = await getQuerier();
  const id = await querier.insertOne(User, body);
  await querier.release();
  return id;
}

 

Learn more about nukak at its website https://nukak.org

Changelog

[0.2.21] 2023-04-15

• fix(nukak-browser): check if ids are returned before use $in to delete them.

• Reuse community open-source npm packages to escape literal-values according to each DB vendor.