nukak-maria
TypeScript icon, indicating that this package has built-in type declarations

0.4.2 • Public • Published

tests coverage status license npm version

nukak is the smartest ORM for TypeScript, it is designed to be fast, safe, and easy to integrate into any application. It takes inspiration from mongo queries.

nukak can run in Node.js, Browser, Cordova, PhoneGap, Ionic, React Native, NativeScript, Expo, Electron, Bun and Deno.

nukak has a consistent API for distinct databases, including PostgreSQL, MySQL, SQLite, MariaDB, and MongoDB.

 

const companyUsers = await userRepository.findMany({
  $project: { email: true, profile: ['picture'] },
  $filter: { email: { $endsWith: '@domain.com' } },
  $sort: { createdAt: 'desc' },
  $limit: 100,
});

 

Why nukak?

See this article in medium.com.

 

Features

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

 

1. Install

  1. Install the core package:

    npm install nukak --save
  2. Install one of the specific adapters for your database:

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

For example, for Postgres:

npm install pg nukak-postgres --save
  1. Additionally, your tsconfig.json may need the following flags:

    "target": "es2022",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true

 


 

2. 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;
}

 

3. Setup a default querier-pool

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 when calling `getQuerier()` and
// in the `@Transactional` decorator (by default).
setQuerierPool(querierPool);

 

4. Manipulate the data

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

async function findLastUsers(limit = 100) {
  const querier = await getQuerier();
  const users = await querier.findMany(User, {
    $project: { id: true, name: true, email: true },
    $sort: { createdAt: 'desc' },
    $limit: limit,
  });
  await querier.release();
  return users;
}

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

 

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

Package Sidebar

Install

npm i nukak-maria

Homepage

nukak.org

Weekly Downloads

0

Version

0.4.2

License

MIT

Unpacked Size

19.3 kB

Total Files

12

Last publish

Collaborators

  • rogerpadilla