Getting Started

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

Setting up the Database

Requiring the package

JavaScript

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

TypeScript

import { Database } from 'simpl.db';

Creating the Database

The paths for the dataFile and collectionsFolder options, if provided, must be absolute.

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().

JavaScript

const db = new SimplDB();

TypeScript

const db = new Database();

Queries

The database provide CRUD methods (and many more) for handling data. For more details for each method, please head over to the Database page and subpages.

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

JavaScript

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

TypeScript

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

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

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:

JavaScript

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

TypeScript

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

Now, queries like this:

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

Can be replaced with this:

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

For more details, please head over to the Database#createCollection() page.

Queries

Collections provide CRUD methods (and many more) for handling data. For more details for each method, please head over to the Collection page and subpages.

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() and 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).

Encrypting and decrypting data will increase your code's execution time a little.

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.

It's highly recommended that the Encryption Key only includes numbers and uppercase and lowercase letters, since some special characters could break it.

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 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.