> For the complete documentation index, see [llms.txt](https://simpldb.js.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simpldb.js.org/getting-started.md).

# Getting Started

Please read the Introduction section if you haven't already.

## Setting up the Database

### Requiring the package

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const SimplDB = require('simpl.db');
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { Database } from 'simpl.db';
```

{% endtab %}
{% endtabs %}

### Creating the Database

{% hint style="warning" %}
The paths for the `dataFile` and `collectionsFolder` options, **if provided**, must be absolute.
{% endhint %}

{% hint style="warning" %}
**If you are working with a large amount of data**, it's **highly recommended** that the `autoSave` option is set to `false` and that you manually save the changes with [Database#save()](https://simpldb.gitbook.io/docs/documentation/database/save).
{% endhint %}

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const db = new SimplDB();
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const db = new Database();
```

{% endtab %}
{% endtabs %}

### Queries

The database provide [CRUD](https://developer.mozilla.org/en-US/docs/Glossary/CRUD) methods (and many more) for handling data.\
For more details for each method, please head over to the [Database page and subpages](/documentation/database.md).

## Setting up Collections

These structures allow you to store data in a more organized way.\
They are typically used to store information where every entry share a similar or even the same structure (e.g. users, posts, etc.).\
\
Collections provide methods to easily handle the data, easier than storing everything in the Database with simple key-value pairs.

### Creating Collections

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const Users = db.createCollection('users');
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
type User = {
  name: string
  age: number
  balance: number
}

const Users = db.createCollection<User>('users');
```

{% endtab %}
{% endtabs %}

In order to reduce the queries, you can provide **default values** for a collection, which will be automatically assigned to the entries when created.\
Here is an example:

{% tabs %}
{% tab title="JavaScript" %}

```javascript
const Users = db.createCollection('users', {
  balance: 0
});
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
const Users = db.createCollection<User>('users', {
  balance: 0
});
```

{% endtab %}
{% endtabs %}

Now, queries like this:

```javascript
Users.create({
  name: 'John',
  balance: 0
});
```

Can be replaced with this:

```javascript
Users.create({ name: 'John' });
```

For more details, please head over to the [Database#createCollection()](/documentation/database/createcollection.md) page.

### Queries

Collections provide [CRUD](https://developer.mozilla.org/en-US/docs/Glossary/CRUD) methods (and many more) for handling data.\
For more details for each method, please head over to the [Collection page and subpages](/documentation/collection.md).

## Encrypting and Decrypting data

Simpl.DB allows you to encrypt and decrypt data. This is useful to store important data such as passwords or secret tokens.\
In order to keep the package as speedy as possible, only the [Database#set()](https://simpldb.gitbook.io/docs/documentation/database/set) and [Database#get()](https://simpldb.gitbook.io/docs/documentation/database/get) methods support encryption and decryption, respectively.

To enable these functionalities, you must have an **Encryption Key** (you can read more about encryption keys [here](https://www.cloudflare.com/learning/ssl/what-is-a-cryptographic-key/)).

{% hint style="warning" %}
Encrypting and decrypting data will increase your code's execution time a little.
{% endhint %}

{% hint style="info" %}
Please make sure that, when generating your Encryption Key through the website provided below, you only check the **Include Numbers**, **Include Lowercase Characters**, **Include Uppercase Characters**, **Exclude Similar Characters** and **Generate On Your Device** options and that you have the **Password Length** option set to 32.
{% endhint %}

{% hint style="warning" %}
It's **highly recommended** that the Encryption Key **only includes numbers and uppercase and lowercase letters**, since some special characters could break it.
{% endhint %}

Since Simpl.DB uses AES256-CTR to encrypt and decrypt data, your Encryption Key must be a combination of 32 random characters. To generate yours, visit [this website](https://passwordsgenerator.net) or simply write it yourself (not recommended).

Once you have your hands on a brand new Encryption Key, **make sure you store it in a safe place**, such as an environment variable in a `.env` file or something similar.