{"id":14956901,"url":"https://github.com/rogerpadilla/nukak","last_synced_at":"2025-04-04T23:06:50.166Z","repository":{"id":38418335,"uuid":"296392091","full_name":"rogerpadilla/nukak","owner":"rogerpadilla","description":"The smartest TypeScript ORM","archived":false,"fork":false,"pushed_at":"2025-01-29T18:21:52.000Z","size":5925,"stargazers_count":95,"open_issues_count":1,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-28T22:14:14.326Z","etag":null,"topics":["data-mapper","javascript-orm","node-orm","orm","orm-framework","orm-javascript","orm-library","orm-nodejs","orm-typescript","typescript-orm"],"latest_commit_sha":null,"homepage":"https://nukak.org","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rogerpadilla.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-17T17:09:00.000Z","updated_at":"2025-01-29T18:21:56.000Z","dependencies_parsed_at":"2022-09-09T15:52:04.842Z","dependency_job_id":"aeb7ab8a-188c-4dc7-8960-db280b603998","html_url":"https://github.com/rogerpadilla/nukak","commit_stats":{"total_commits":1487,"total_committers":2,"mean_commits":743.5,"dds":"0.34835238735709484","last_synced_commit":"06a7b7e8352740b223d56b61d931cb348d11637a"},"previous_names":["rogerpadilla/uql"],"tags_count":240,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerpadilla%2Fnukak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerpadilla%2Fnukak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerpadilla%2Fnukak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rogerpadilla%2Fnukak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rogerpadilla","download_url":"https://codeload.github.com/rogerpadilla/nukak/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247229087,"owners_count":20904978,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-mapper","javascript-orm","node-orm","orm","orm-framework","orm-javascript","orm-library","orm-nodejs","orm-typescript","typescript-orm"],"created_at":"2024-09-24T13:13:42.151Z","updated_at":"2025-04-04T23:06:50.143Z","avatar_url":"https://github.com/rogerpadilla.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- ![code](/assets/code.webp 'code') --\u003e\n\n[![nukak maku](https://nukak.org/nukak-maku.jpg)](https://nukak.org)\n\n[![tests](https://github.com/rogerpadilla/nukak/actions/workflows/tests.yml/badge.svg)](https://github.com/rogerpadilla/nukak) [![coverage status](https://coveralls.io/repos/rogerpadilla/nukak/badge.svg?branch=main)](https://coveralls.io/r/rogerpadilla/nukak?branch=main) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/rogerpadilla/nukak/blob/main/LICENSE) [![npm version](https://badge.fury.io/js/nukak.svg)](https://badge.fury.io/js/nukak)\n\n[nukak](https://nukak.org) is the [smartest ORM](https://medium.com/@rogerpadillac/in-search-of-the-perfect-orm-e01fcc9bce3d) for TypeScript, it is designed to be fast, safe, and easy to integrate into any application.\n\n[nukak](https://nukak.org) can run in Node.js, Browser, Cordova, PhoneGap, Ionic, React Native, NativeScript, Expo, Electron, Bun and Deno.\n\n[nukak](https://nukak.org) has a consistent API for distinct databases, including PostgreSQL, MySQL, MariaDB, and SQLite.\n\n\u0026nbsp;\n\n```ts\nconst companyUsers = await userRepository.findMany({\n  $select: { email: true, profile: ['picture'] },\n  $where: { email: { $endsWith: '@example.com' } },\n  $sort: { createdAt: -1 },\n  $limit: 100,\n});\n```\n\n\u0026nbsp;\n\n## Why nukak?\n\nSee [this article](https://medium.com/@rogerpadillac/in-search-of-the-perfect-orm-e01fcc9bce3d) in medium.com.\n\n\u0026nbsp;\n\n## Features\n\n- **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](https://www.nukak.org/docs/querying-relations).\n- **Serializable queries**: its [syntax](https://nukak.org/docs/querying-logical-operators) can be `100%` valid `JSON` allowing the queries to be transported across platforms with ease.\n- **Unified API across Databases**: same query is transparently transformed according to the configured database.\n- **FP + OOP**: Combines the best elements of `FP` (Functional Programming) and `OOP` (Object Oriented Programming).\n- [Declarative](https://nukak.org/docs/transactions-declarative) and [imperative](https://nukak.org/docs/transactions-imperative) `transactions` for flexibility, and `connection pooling` for scalability.\n- Transparent support for [inheritance between entities](https://nukak.org/docs/entities-inheritance) for reusability and consistency.\n- Modern [Pure ESM](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): `ESM` is natively supported by Node.js 16 and later.\n- **High performance**: the [generated queries](https://www.nukak.org/docs/querying-logical-operators) are fast, safe, and human-readable.\n- Supports the [Data Mapper](https://en.wikipedia.org/wiki/Data_mapper_pattern) pattern for maintainability.\n- [soft-delete](https://nukak.org/docs/entities-soft-delete), [virtual fields](https://nukak.org/docs/entities-virtual-fields), [repositories](https://nukak.org/docs/querying-repository).\n- Automatic handing of `json`, `jsonb` and `vector` fields.\n\n\u0026nbsp;\n\n## 1. Install\n\n1. Install the core package:\n\n   ```sh\n   npm install nukak --save\n   ```\n\n2. Install one of the specific adapters for your database:\n\n| Database     | Driver           | Nukak Adapter    |\n| ------------ | ---------------- | ---------------- |\n| `PostgreSQL` | `pg`             | `nukak-postgres` |\n| `SQLite`     | `sqlite sqlite3` | `nukak-sqlite`   |\n| `MariaDB`    | `mariadb`        | `nukak-maria`    |\n| `MySQL`      | `mysql2`         | `nukak-mysql`    |\n\nFor example, for `Postgres`:\n\n```sh\nnpm install pg nukak-postgres --save\n```\n\n3. Additionally, your `tsconfig.json` may need the following flags:\n\n   ```json\n   \"target\": \"es2022\",\n   \"experimentalDecorators\": true,\n   \"emitDecoratorMetadata\": true\n   ```\n\n\u0026nbsp;\n\n---\n\n\u0026nbsp;\n\n## 2. Define the entities\n\nTake any dump class (aka DTO) and annotate it with the decorators from `nukak/entity`.\n\n```ts\nimport { randomUUID } from 'node:crypto';\nimport { Id, Field, Entity } from 'nukak/entity';\n\n/**\n * any class can be annotated with this decorator to make it works as\n * an entity.\n */\n@Entity()\nexport class User {\n  /**\n   * an entity must specify an ID Field, its name and type are automatically detected.\n   * the `onInsert` property can be used to specify a custom mechanism for\n   * auto-generating the primary-key's value when inserting.\n   */\n  @Id({ onInsert: () =\u003e randomUUID })\n  id?: string;\n\n  /**\n   * the properties of the class can be annotated with this decorator so they\n   * are interpreted as a column, its name and type are automatically detected.\n   */\n  @Field()\n  name?: string;\n\n  /**\n   * fields are `updatable: true` by default but can also be marked as `updatable: false` so they can only be inserted and read after.\n   */\n  @Field({ updatable: false })\n  email?: string;\n\n  /**\n   * by default, fields are `eager: true`, but they can also be marked as `eager: false` (aka lazy fields).\n   */\n  @Field({ eager: false })\n  password?: string;\n}\n```\n\n\u0026nbsp;\n\n## 3. Setup a querier-pool\n\nA querier-pool can be set in any of the bootstrap files of your app (e.g. in the `server.ts`).\n\n```ts\n// file: ./shared/orm.ts\n\nimport { PgQuerierPool } from 'nukak-postgres';\n\nexport const querierPool = new PgQuerierPool(\n  {\n    host: 'localhost',\n    user: 'theUser',\n    password: 'thePassword',\n    database: 'theDatabase',\n  },\n  // optionally, a logger can be passed to log the generated SQL queries\n  { logger: console.debug },\n);\n```\n\n\u0026nbsp;\n\n## 4. Manipulate the data\n\n```ts\nimport { querierPool } from './shared/orm.js';\nimport { User } from './shared/models/index.js';\n\nasync function findLastUsers(limit = 100) {\n  const querier = await querierPool.getQuerier();\n  const users = await querier.findMany(User, {\n    $select: { id: true, name: true, email: true },\n    $sort: { createdAt: 'desc' },\n    $limit: limit,\n  });\n  return users;\n}\n\nasync function createUser(data: User) {\n  const querier = await querierPool.getQuerier();\n  const id = await querier.insertOne(User, data);\n  return id;\n}\n```\n\n\u0026nbsp;\n\nLearn more about `nukak` at its website https://nukak.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frogerpadilla%2Fnukak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frogerpadilla%2Fnukak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frogerpadilla%2Fnukak/lists"}