# Getting Started
***NexORM*** is a powerful ORM designed to simplify database management while delivering high performance and flexibility. Inspired by [**MongoDB**](https://www.mongodb.com/docs/), [**Prisma**](https://www.prisma.io/docs), and [**TypeORM**](https://typeorm.io/), it combines the best features of these tools, offering advanced operators (like $set and $inc with more), a built-in caching system, and a **decorator-based** schema definition for clean and intuitive modeling.
With full **TypeScript** support, ***Nexorm*** ensures **type-safe** , modern development using ~~**JavaScript (ES2021)**~~. It supports **MySQL**, **PostgreSQL**, **SQLite**, **MariaDB**, and **MSSQL**, making it suitable for projects of any scale, from small apps to complex enterprise systems.
Start building with ***NexORM*** to enjoy effortless, scalable, and maintainable database interactions.
## Features
* **Full Type Support:** *Seamless TypeScript integration for type-safe development.*
* **Decorator-Based Schema Definition:** *Clean and intuitive schema modeling using decorators.*
* **Multi-Database Support:** *Compatible with MySQL, PostgreSQL, SQLite, MariaDB, and MSSQL.*
* **Full JSON Support:** *Easily handle arrays and objects in JSON format.*
* **Hooks Support:** *Lifecycle hooks for enhanced control over database events.*
* **Encryption, Decryption, and Hashing:** *Built-in utilities for secure data management.*
* **Validation Support:** *Ensure data integrity with powerful validation tools.*
* **Multi-Connection Support:** *Manage multiple database connections effortlessly.*
* **CLI Support:** *Command-line tools for streamlined database operations.*
* **Cache Support:** *Built-in caching for faster queries and improved performance.*
* **Index Support:** *Optimize queries with advanced indexing capabilities.*
* **Advanced Operator Support:** *Extendable operators for flexible database operations.*
* **Debug and Logging Support:** *Track and troubleshoot with detailed logs and debug tools.*
And more...
***With NexORM your schemas & models look like this:***
```typescript
/* ./schemas/user.ts */
import Model from 'nexorm/model';
import {
Schema, Timestamps,
Column, Default, Required
} from 'nexorm/decorators';
@Schema
@Timestamps /* UpdatedAt And CreatedAt Sections */
class UserSchema {
@Column
@Required
static personName = String; /* Required String Column */
@Column
@Required
static personSurname = String; /* Required String Column */
@Column
@Default(16)
static personAge = Number; /* Number Column If Value Is Not Available */
/* Value Is Set To '16' */
@Column
@Default(['Personal'])
static tags = Array(String); /* String[] Column If Value Is Not Available */
/* Value Is Set To '["Personal"]' */
@Column
static audit = Object; /* Object Column */
};
/* Integrating The Schema Into The Model And Exporting */
export default new Model(UserSchema);
```
***And your domain logic will look this way:***
```typescript
import User from './schemas/user';
const allUsers = await User.$everything();
const firstUser = await User.$searchFirst();
const filteredUsers = await User.$search({
$where: {
personName: 'John',
personAge: {
$gte: 18
}
}
});
const findUser = await User.$searchOne({
$where: {
tags: {
$in: [['Personal']]
}
},
$options: {
$sort: {
personAge: -1
}
}
});
```
## Installation
1. **Install the npm package:**\ **`npm install nexorm --save`**
2. **You may need to install `reflect-metadata`:**\ **`npm install reflect-metadata --save`** \
**and import it somewhere in the global place of your app (for example in `src/index.ts`):**\ **`import 'reflect-metadata';`**
3. **You may need to install node typings:**\ **`npm install @types/node --save-dev`**
4. **Install a database driver:**
* for **MySQL**\ **`npm install mysql2 --save`**
* for **PostgreSQL**\ **`npm install pg --save`**
* for **SQLite**\ **`npm install sqlite3 --save`**
* for **Microsoft SQL Server**\ **`npm install tedious --save`**
* for **MariaDB**\ **`npm install mariadb --save`**
### TypeScript Configuration
Also, make sure you are using TypeScript version **4.5** or higher, and you have enabled the following settings in **`tsconfig.json`**:
```json
"emitDecoratorMetadata": true,
"experimentalDecorators": true,
```
You may also need to enable **`es6`** in the **`lib`** section of compiler options, or install **`es6-shim`** from **`@types`**.
## Quick Start
The quickest way to get started with NexORM is to use its CLI commands to generate a **`nexorm.config.ts`** or ~~**`nexorm.config.js`**~~ file.
```typescript
nexorm init /* With Selection Prompts */
nexorm init -y /* Skip All Prompts */
nexorm init --database sqlite --language ts --babel false /* For Manuel */
```
After edit the **`nexorm.config.ts`** or ~~**`nexorm.config.js`**~~ file and put your own database connection configuration options in there:
```typescript
/* nexorm.config.ts */
/* eslint-disable @typescript-eslint/no-var-requires */
/** @type {import('nexorm').NexormConfig} */
import type { NexormConfig } from "nexorm";
export default [{
$provider: "nexorm",
$database: "sqlite",
$databaseEngine: "InnoDB",
$filePath: "./nexorm.sqlite",
$autoConnect: true,
$onConnection: () => {
console.log("[Nexorm] Database ready!");
},
$onError: (error: Error) => {
console.error("[Nexorm] Error connecting to database:", error);
},
}] satisfies NexormConfig;
```
### Configuration File Options
You can adjust the configuration file according to your needs using the table below.
Value
Type
Default
$provider*
'nexorm'|String
nexorm
$database*
'mysql'|'postgres'|'sqlite'|'mariadb'|'mssql'
sqlite
$dialectModule?
any
(Empty)
$autoConnect?
Boolean
true
$filePath?
String
./nexorm.sqlite
$databaseEngine?
String
B-tree
$ssl?
Boolean
(Empty)
$pool?
Object
(Empty)
$pool.$acquire?
Number
(Empty)
$pool.$idle?
Number
(Empty)
$pool.$max?
Number
(Empty)
$pool.$min?
Number
(Empty)
$pool.$evict?
Number
(Empty)
$onConnection?
Function
(() ⇒ {..});
$onDisconnect?
Function
(Empty)
$onError?
Function
(() ⇒ {..});
$host?
String
(Empty)
$port?
String
(Empty)
$username?
String
(Empty)
$password?
String
(Empty)
$connectionURI?
String
(Empty)
$cache?
Object
(Empty)
$cache.$type?
'memory'
(Empty)
$cache.$duration?
Number
(Empty)
## Create Model
Working with a database starts with creating tables. How do you tell **NexORM** to create a database table? The answer is - through the models. Your models in your app are your database tables.
For example, you have a **`Member`** model:
```typescript
@Schema
class Member {
@Column
@UUID()
static userId = String;
@Column
static username = String;
@Column
static displayName = String;
@Column
static age = Number;
@Column
static avatar = Buffer;
@Column
static banner = String;
@Column
static createdAt = Date;
@Column
static lastJoinedAt = Date;
@Column
@Hash('SHA256','hex')
static password = String;
@Column
@Default(false)
static isPremium = Boolean;
@Column
static badges = Array(String);
@Column
static logins = { timestamp: Number, ip: String };
};
export default new Model(Member);
```
And you want to store photos in your database. To store things in the database, first, you need a database table, and database tables are created from your models. Not all models, but only those you define as *entities*.
## Updating in the database
Now let's update a member from the database:
```typescript
import Member from './schemas/Member';
import * as fs from 'fs';
/* Update Or Create Row */
var upsertedMember = await Member.$upsert({
$where: {
isPremium: true
},
$update: {
$toggle: {
isPremium: true
},
$camelcase: {
username: true
}
},
$rules: {
username: {
$alphaNumeric: true
}
}
});
/* Update One Row */
await Member.$update({
$where: {
userId: '1234567890',
username: 'fivesobes'
},
$update: {
$set: {
avatar: fs.readFileSync(path.join(__dirname, 'avatar.png')),
lastJoinedAt: new Date()
},
$toggle: {
isPremium: true
},
},
$options: { $upsert: true }
});
/* Update Many Rows */
await Member.$updateMany({
$where: {
isPremium: true,
badges: {
$in: [['Verify', 'VIP']]
}
},
$update: {
$set: {
badges: []
},
$toggle: {
isPremium: true
}
},
});
```
## Searching in the database
Now let's search a member from the database:
import Member from './schemas/Member';
/* Search All */
var allMembers = await Member.$everything();
/* Search One */
var member = await Member.$searchOne({
$where: {
userId: '1234567890',
},
$options: {
$attributes: ['userId','username','displayName','avatar','banner'],
$raw: true
}
});
/* Search Many */
var memberList = await Member.$search({
$where: {
isPremium: true
},
$options: {
$sort: {
lastJoinedAt: -1,
createdAt: -1
},
$limit: 30,
$cache: true
}
});
/* Search By Id */
var searchMemberById = await Member.$searchById('7ca9320b-1803-459c-a1ff-39b8d5e14a25');
/* Search By Ids */
var searchMembersByIds = await Member.$searchByIds([
'7ca9320b-1803-459c-a1ff-39b8d5e14a25',
'7ca9320b-1803-459c-a1ff-39b8d5e14a26',
'7ca9320b-1803-459c-a1ff-39b8d5e14a27'
]);
/* Distinct Rows */
var memberListDistinct = await Member.$distinct({
$field: ['userId','username','displayName'],
$options: {
$cache: { $key: 'memberList', $ttl: 60_000 }
}
});
/* Get Count */
var count = await Member.$count({
$where: {
lastJoinedAt: {
$gte: new Date('2021-01-01')
}
},
$options: {
$paranoid: true
}
});
/* Search And Get Count */
var [ members, count ] = await Member.$searchAndCount({
$where: {
createdAt: {
$lte: new Date('2021-01-01'),
$gte: new Date('2020-01-01')
}
}
});
## Deleting in the database
Now let's delete a member from the database:
```typescript
import Member from './schemas/Member';
/* Delete All */
await Member.$truncate();
/* Delete One */
var deletedMember = await Member.$delete({
$where: {
userId: '1234567890',
isPremium: {
$eq: false
}
}
});
/* Delete Many */
var deletedMembers = await Member.$deleteMany({
$where: {
isPremium: false,
banner: {
$startsWith: '.png'
}
},
$options: {
$limit: 40,
$logging(sql, benchmark) {
console.log(`${sql} took ${benchmark}ms`);
},
$force: true
}
});
/* Soft Delete One */
await Member.$softDelete({
$where: {
username: 'fivesobes'
}
});
/* Soft Delete Many */
await Member.$softDeleteMany({
$where: {
isPremium: false
},
$options: {
$limit: 5
}
});
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://fivesobes.gitbook.io/nexorm/getting-started.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
