Awesome

⚗️ Ported version

This is a forked version of AloeDB by Kirlovon. Changed to be able to be used in a modern NodeJS environment.

✨ Features

• 🎉 Simple to use API, similar to MongoDB!
• 🚀 Optimized for a large number of operations.
• ⚖ No dependencies, even without std!
• 📁 Stores data in readable JSON file.

📦 Importing

import { Database } from 'aloedb-node'

📖 Example

import { Database } from 'aloedb-node'

// Structure of stored documents
interface Film {
    title: string;
    year: number;
    film: boolean;
    genres: string[];
    authors: { director: string };
}

// Initialization
const db = new Database<Film>('./path/to/the/file.json');

// Insert operations
await db.insertOne({
    title: 'Drive',
    year: 2012,
    film: true,
    genres: ['crime', 'drama', 'noir'],
    authors: { director: 'Nicolas Winding Refn' }
});

// Search operations
const found = await db.findOne({ title: 'Drive', film: true });

// Update operations
await db.updateOne({ title: 'Drive' }, { year: 2011 });

// Delete operations
await db.deleteOne({ title: 'Drive' });

P.S. You can find more examples here!

🏃‍ Benchmarks

This database is not aimed at a heavily loaded backend, but its speed should be good enough for small APIs working with less than a million documents.

To give you an example, here is the speed of a database operations with 1000 documents:

📚 Guide

Initialization

import { Database } from 'aloedb-node'

interface Schema {
	username: string;
	password: string;
}

const db = new Database<Schema>({
	path: './data.json',
	pretty: true,
	autoload: true,
	autosave: true,
	optimize: true,
	immutable: true,
	validator: (document: any) => {}
});

The following fields are available for configuration:

• path - Path to the database file. If undefined, data will be stored only in-memory. (Default: undefined)
• pretty - Save data in easy-to-read format. (Default: true)
• autoload - Automatically load the file synchronously when initializing the database. (Default: true)
• autosave - Automatically save data to the file after inserting, updating and deleting documents. (Default: true)
• optimize - Optimize data writing. If enabled, the data will be written many times faster in case of a large number of operations. (Default: true)
• immutable - Automatically deeply clone all returned objects. (Default: true)
• validator - Runtime documents validation function. If the document does not pass the validation, just throw the error.

Also, you can initialize the database in the following ways:

// In-memory database
const db = new Database();

// Short notation, specifying the file path only
const db = new Database('./path/to/the/file.json');

Typization

AloeDB allows you to specify the schema of documents. By doing this, you will get auto-completion and types validation. This is a completely optional feature that can make it easier for you to work with the database.

Just specify an interface that contains only the types supported by the database (strings, numbers, booleans, nulls, array, objects), and everything will works like magic! 🧙‍

// Your schema
interface User {
	username: string;
	password: string;
}

// Initialize a database with a specific schema
const db = new Database<User>();

await db.insertOne({ username: 'bob', password: 'qwerty' }); // Ok 👌
await db.insertOne({ username: 'greg' }); // Error: Property 'password' is missing

Inserting

AloeDB is a document-oriented database, so you storing objects in it. The supported types are Strings, Numbers, Booleans, Nulls, Arrays & Objects.

Keep in mind that data types such as Date, Map, Set and other complex types are not supported, and all fields with them will be deleted. Also, any blank documents will not be inserted.

const inserted = await db.insertOne({ text: 'Hey hey, im inserted!' });
console.log(inserted); // { text: 'Hey hey, im inserted!' }

Querying

Search query can be an object or a search function. If query is an object, then the search will be done by deeply comparing the fields values in the query with the fields values in the documents.

In search queries you can use Primitives (strings, numbers, booleans, nulls), Arrays, Objects, RegExps and Functions.

await db.insertMany([
   { key: 1, value: 'one' },
   { key: 2, value: 'two' },
   { key: 3, value: 'three' },
]);

// Simple query
const found1 = await db.findOne({ key: 1 });
console.log(found1); // { key: 1, value: 'one' }

// Advanced query with search function
const found2 = await db.findOne((document: any) => document.key === 2);
console.log(found2); // { key: 2, value: 'two' }

When specifying Arrays or Objects, a deep comparison will be performed.

await db.insertMany([
   { key: 1, values: [1, 2] },
   { key: 2, values: [1, 2, 3] },
   { key: 3, values: [1, 2, 3, 4] },
]);

const found = await db.findOne({ values: [1, 2, 3] });
console.log(found); // { key: 2, values: [1, 2, 3] }

Updating

As with search queries, update queries can be either a function or an object. If this is a function, then the function receives the document to update as a parameter, and you must return updated document from the function. (or return null or {} to delete it)

By the way, you can pass a function as a parameter value in an object. This can be useful if you want to update a specific field in your document. Also, you can return undefined, to remove this field.

await db.insertMany([
   { key: 1, value: 'one' },
   { key: 2, value: 'two' },
   { key: 3, value: 'three' },
]);

// Simple update
const updated1 = await db.updateOne({ key: 1 }, { key: 4, value: 'four' });
console.log(updated1); // { key: 4, value: 'four' }

// Advanced update with update function
const updated2 = await db.updateOne({ key: 2 }, (document: any) => {
   document.key = 5;
   document.value = 'five';
   return document;
});
console.log(updated2); // { key: 5, value: 'five' }

// Advanced update with field update function
const updated3 = await db.updateOne({ key: 3 }, {
   key: (value: any) => value === 6,
   value: (value: any) => value === 'six'
});
console.log(updated3); // { key: 6, value: 'six' }

🔧 Methods

Documents

db.documents;

This property stores all your documents. It is better not to modify these property manually, as database methods do a bunch of checks for security and stability reasons. But, if you do this, be sure to call await db.save() method after your changes.

InsertOne

await db.insertOne({ foo: 'bar' });

Inserts a document into the database. After insertion, it returns the inserted document.

All fields with undefined values will be deleted. Empty documents will not be inserted.

By default, the document will be inserted as the last entry in the database. To insert it somewhere else, specify the optional index parameter:

await db.insertOne({ foo: 'bar' }, 9);

If the provided index is greater than the number of database entries, it will be inserted at the end.

InsertMany

await db.insertMany([{ foo: 'bar' }, { foo: 'baz' }]);

Inserts multiple documents into the database. After insertion, it returns the array with inserted documents.

This operation is atomic, so if something goes wrong, nothing will be inserted.

FindOne

await db.findOne({ foo: 'bar' });

Returns a document that matches the search query. Returns null if nothing found.

FindMany

await db.findMany({ foo: 'bar' });

Returns an array of documents matching the search query.

UpdateOne

await db.updateOne({ foo: 'bar' }, { foo: 'baz' });

Modifies an existing document that match search query. Returns the found document with applied modifications. If nothing is found, it will return null.

The document will be deleted if all of its fields are undefined, or if you return null or {} using a update function.

This operation is atomic, so if something goes wrong, nothing will be updated.

UpdateMany

await db.updateMany({ foo: 'bar' }, { foo: 'baz' });

Modifies all documents that match search query. Returns an array with updated documents.

This operation is atomic, so if something goes wrong, nothing will be updated.

DeleteOne

await db.deleteOne({ foo: 'bar' });

Deletes first found document that matches the search query. After deletion, it will return deleted document.

DeleteMany

await db.deleteMany({ foo: 'bar' });

Deletes all documents that matches the search query. After deletion, it will return all deleted documents.

This operation is atomic, so if something goes wrong, nothing will be deleted.

Count

await db.count({ foo: 'bar' });

Returns the number of documents found by the search query. If the query is not specified or empty, it will return total number of documents in the database.

Drop

await db.drop();

Removes all documents from the database.

Load

await db.load();

Loads, parses and validates documents from the specified database file. If the file is not specified, then nothing will be done.

LoadSync

db.loadSync();

Same as db.load() method, but synchronous. Will be called automatically if the autoload parameter is set to true.

Save

await db.save();

Saves documents from memory to a database file. If the optimize parameter is false, then the method execution will be completed when data writing is completely finished. Otherwise the data record will be added to the queue and executed later.

Helpers

This module contains helper functions that will make it easier to write and read search queries.

// Importing database & helpers
import { Database, and, includes, length, not, exists } from 'https://deno.land/x/aloedb@0.9.0/mod.ts';

const db = new Database();
await db.insertOne({ test: [1, 2, 3] });

// Helpers usage
const found = await db.findOne({
   test: and(
   	length(3),
   	includes(2)
   ),
   other: not(exists())
});

console.log(found); // { test: [1, 2, 3] }

List of all available helpers:

• moreThan
• moreThanOrEqual
• lessThan
• lessThanOrEqual
• between
• betweenOrEqual
• exists
• type
• includes
• length
• someElementMatch
• everyElementMatch
• and
• or
• not

💡 Tips & Tricks

Multiple Collections

By default, one database instance has only one collection. However, since the database instances are quite lightweight, you can initialize multiple instances for each collection.

Keep in mind that you cannot specify the same file for multiple instances!

import { Database } from 'https://deno.land/x/aloedb@0.9.0/mod.ts';

// Initialize database instances
const users = new Database({ path: './users.json' });
const posts = new Database({ path: './posts.json' });
const comments = new Database({ path: './comments.json' });

// For convenience, you can collect all instances into one object
const db = { users, posts, comments };

// Looks nice 😎
await db.users.insertOne({ username: 'john', password: 'qwerty123' });

Runtime Validation

You cannot always be sure about the data that comes to your server. TypeScript highlights a lot of errors at compilation time, but it doesn't help at runtime.

Luckily, you can use a library such as SuperStruct, which allows you to check your documents structure:

import { Database } from 'https://deno.land/x/aloedb@0.9.0/mod.ts';
import { assert, object, string, Infer } from 'https://cdn.skypack.dev/superstruct?dts';

// Specify structure
const User = object({
	username: string(),
	password: string()
});

// Create validation function
const UserValidator = (document: any) => assert(document, User);

// Convert structure to TypeScript type
type UserSchema = Infer<typeof User>;

// Initialize
const db = new Database<UserSchema>({ validator: UserValidator });

// Ok 👌
await db.insertOne({ username: 'bob', password: 'dylan' });

// StructError: At path: password -- Expected a string, but received: null
await db.insertOne({ username: 'bob', password: null as any });

Manual Changes

For performance reasons, a copy of the whole storage is kept in memory. Knowing this, you can modify the documents manually by modifying the db.documents parameter.

Most of the time this is not necessary, as the built-in methods are sufficient, but if you want to have full control, you can do it!

Keep in mind that after your changes, you should always call the await db.save() method!

import { Database } from 'https://deno.land/x/aloedb@0.9.0/mod.ts';

// Initialize
const db = new Database('./data.json');

try {

	// Your changes...
	db.documents.push({ foo: 'bar' });

} finally {
	await db.save(); // ALWAYS CALL SAVE!
}

Also, if you set the parameter immutable to false when initializing the database, you will get back references to in-memory documents instead of their copies. This means that you cannot change the returned documents without calling the await db.save() method.

import { Database } from 'https://deno.land/x/aloedb@0.9.0/mod.ts';

// Initialization with immutability disabled
const db = new Database({ path: './data.json', immutable: false });

// Initial data
await db.insertOne({ field: 'The Days' });

// Finding and modifying document
const found = await db.findOne({ field: 'The Days' }) as { field: string };
found.field = 'The Nights';

// Saving
await db.save();

console.log(db.documents); // [{ field: 'The Nights' }]

Active Records

import { Database } from "aloedb-node";
import { v1 as uuidv1 } from "uuid";

// Define the active record functions that will be available on the model
interface AloeDBFunctions<T> {
  save(): Promise<AloeDBDocument<T>>;
  delete(): Promise<AloeDBDocument<T> | null>;
  update(): Promise<AloeDBDocument<T> | null>;
}

// Create a type that removes the active record functions from the model
type AloeDBDocument<T> = Omit<T, keyof AloeDBFunctions<T>>;

// Create a database instance using the Document type of the Weather class
const db = new Database<AloeDBDocument<Weather>>("./weather.json");

// Create a Weather class that implements the active record functions
export class Weather implements AloeDBFunctions<Weather> {
  id: string;
  timestamp: number;
  temperature: number;
  humidity: number;

  constructor(
    data:
      & Omit<Weather, "save" | "delete" | "update" | "id" | "timestamp">
      & Partial<Pick<Weather, "id" | "timestamp">>,
  ) {
    this.id = data.id ?? uuidv1();
    this.timestamp = data.timestamp ?? new Date().getTime();
    this.temperature = data.temperature;
    this.humidity = data.humidity;
  }

  save() {
    return db.insertOne(this);
  }

  delete() {
    return db.deleteOne({ id: this.id });
  }

  update() {
    return db.updateOne({ id: this.id }, this);
  }

  static async findOne(
    query: Partial<Omit<Weather, "save" | "delete" | "update">>,
  ): Promise<Weather | null> {
    const object = await db.findOne(query);
    if (object) return new Weather(object);
    return null;
  }

  static async findMany(
    query: Partial<Omit<Weather, "save" | "delete" | "update">>,
  ): Promise<Weather[]> {
    const objects = await db.findMany(query);

    return objects.map((obj) => {
      return new Weather(obj);
    });
  }
}

// Create a new weather object
const weather = new Weather({
  temperature: 20,
  humidity: 50,
});

// Save the weather object to the database
await weather.save();

// Find all weather objects with a temperature of 20
const foundWeathers = await Weather.findMany({ temperature: 20 });
console.log({ foundWeathers });
// { foundWeathers: [Weather {id: '2d5d7140-a70f-11ed-b641-210ec86abb79', timestamp: 1675791914580, temperature: 20, humidity: 50 }] }

🦄 Community Ports

Surprisingly, this library was ported to other programming languages without my participation. Much appreciation to this guys for their work! ❤

🔵 AlgoeDB - database for Go, made by billykirk01!

🟠 AlroeDB - database for Rust, also made by billykirk01!

🟢 AloeDB-Node - port to the Node.js, made by Wouter de Bruijn! (With awesome Active Records example)

📃 License

MIT (see LICENSE file)