objdb

Overview

Objdb is a module containing features allowing you to manage an object that is being saved automatically Class: Database it also provides a Serialization API Class: Serializer

powerful but not enough, still working on it to make it as good as expected.

Requires Node.js 10 or higher version

Project's advancement

• Supports JavaScript's OOP
• Provides own Serialization API
• Backup system
• Client and Server: remotely operate over the data

Supported data types

It supports the most of :

• the instances of the built-in classes Object Array Map Set Date Buffer RegExp String Boolean Number
• the primitive types string number boolean bigint undefined null

Limits

You can not use these types inside a database

• Function / Class constructor / Generator function
• Symbol
• WeakMap and WeakSet
• Proxy
• and more

Quick Documentation

• Objdb
  • Class: Database
    • Static property: Database.defaultPath
    • new Database([options])
    • db.save()
    • db.forceSave()
    • db.close()
    • db.delete()
    • db.backups <BackupManager>
    • Event: save
    • Event: backup
  • Class: BackupManager private
    • backups.create()
    • backups.max <number>
    • backups.interval <number>
    • backups.cache
    • backups.oldest
    • backups.latest
  • Class: Backup private
    • backup.delete()
    • backup.load()
    • backup.save()
    • backup.name <string>
    • backup.fullPath <string>
    • backup.createdAt <Date>
  • Class: Serializer
    • Static method: Serializer.clone([value])
    • Static property: Serializer.version <string>
    • Static property: Serializer.defaultConstructors
    • new Serializer([constructors])
    • ser.constructors
    • ser.serialize([value])
    • ser.deserialize(data)

Objdb

The module's structure is like a namespace containing classes.

Common way to require/import objdb:

const { /* Classes... */ } = require('objdb');

import { /* Classes... */ } from 'objdb';

Class: Database

Once the instance is created, you can store, edit, remove values inside of it, it will all be saved automatically.

Supports JavaScript's OOP via prototype restoring.

This class is avaiable in the module's namespace:

const { Database } = require('objdb');

Example of usage

// Creates an instance of Database with default settings
const db = new Database();
// Will be stored in ./data/default.json
// Note: It does not save unless you modify
 
db.test = 'successful';
db.some = new Map();
db.some.set('more', 'datas');
 
// Optional
test.save();

Static property: Database.defaultPath

• Type: <string>
• Default: './data'

Allows you to change the default path to folder for every Database instance to create, (will become their default option).

new Database([options])

• options <Object>
  • name <string> The name of the database Default: 'default'.
  • path <string> The path to the folder where the file will be stored Default: Database.defaultPath.
  • defaults <Object> The default values, Default: {}.
  • constructors <Array> The constructors to use for the prototype restorer Default: [].
  • interval <number> The interval which the automatic saving system will check for changes then save, Minimum: 1000 Never: Infinity Default: 8000.
  • backupInterval <number> The interval in hours which the backup system will make a new backup Minimum: 1 Never: Infinity Default: 8.
  • maxBackups <number> Limits the count of backups Default: 6.
  • Returns: a new instance if the file is not already opened, once opened every calls to new will return the same instance, you can use db.close() to close a <Database>.

Creates an instance with specified settings, (default settings if omitted).

The full path of the data file is formated as path/name.json

Example

class Player { /* Imagination */ }
class Sword { /* Imagination */ }
 
const db = new Database({
  name: 'fantastic',
  defaults: {
    players: new Map();
  },
  constructors: [ Player, Sword ]
});

db.save()

Attempts to save, cancels the operation if no changes were found.

If the last save were in the last 1000ms it postpones the operation until that 1000ms expires.

It is called on interval by the automatic saving system.

db.forceSave()

Synchronous version of db.save(), it overrides the 1000ms rule.

It is called once the process exits or whenever the <Database> is being closed with db.close().

db.close()

Attempts to synchronously save and closes this instance then changes it's prototype to <Object>.

This instance will not be an instance of <Database> anymore, and thus, you will neither be able to use it's methods nor properties.

db.delete()

• Returns: A <Promise> resolving <undefined> once the operation is done.

Closes this instance (with db.close()), then deletes the corresponding file and it's backups.

Event: save

This event is triggered whenever a save operation is completed.

Event: backup

• backup <Backup> the backup that has been created.

This event is triggered whenever a backup has been created.

Class: BackupManager

This class is used to list backups upon the database, it is not exported.

backups.create()

• Returns: <Backup>

Creates a new backup and deletes the oldest one if the backups count limit is reached.

backups.cache

• Type: An <Array> of <Backup>.

backups.oldest

• Type: <Backup> or <undefined>.

Returns the oldest cached backup.

backups.latest

• Type: <Backup> or <undefined>.

Returns the latest cached backup.

Class: Backup

This class is used to represent a single backup, few methods and properties are avaiable, it is not exported.

backup.delete()

• Returns: A <Promise> resolving <undefined> once the deletion is done.

Deletes the corresponding backup file to this instance.

backup.load()

Loads values from the backup into the corresponding <Database> to this instance.

backup.save()

Saves the values from the corresponding <Database> into the corresponding backup file.

Class: Serializer

Allows you to convert mostly all of the JavaScript's values into <string>.

OOP is conserved as well as circular and multiple referenced objects.

This class is avaiable in the module's namespace:

const { Serializer } = require('objdb');

Static method: Serializer.clone([value])

• value <any>
• Returns: a clone of value.

Clones value.

Static property: Serializer.defaultConstructors

• Type: An <Array> of <Constructor>.

Contains Object Array Map Set Buffer Date RegExp String Boolean Number by default.

new Serializer([constructors])

• constructors <Array> An array of <Constructor> that makes possible OOP operations on parsed data, extends Serializer.defaultConstructors Default:[].

Creates an instance with specified constructors.

ser.constructors

• Type: An <Array> of <Constructor>

The constructors that is used to restore prototypes of data when parsing.

ser.serialize([value])

• value <any> The value to serialize.
• Returns: <string>

Serializes value to string with a weird JSON structure containing few properties:

• version <string> Representing the version of the serializer
• value <number> Indexing the references, may be the reference itself when value is primitive
• references An <Array> containing references as complex structures

const sr = new Serializer();
 
// An object to serialize
const o = { testing: Infinity, serialization: Buffer.from('asd'), [0]: /ab+c/i };
 
sr.serialize(o);
// '{"version":"1.0","value":0,"references":[["Object",[[0,"0",1],[0,"testing",[3,"Infinity"]],[0,"serialization",2]]],["RegExp",[],"ab+c","i"],["Buffer",[],"YXNk"]]}'

ser.deserialize(data)

• data <string> The serialized value to parse
• Returns: <any>

Parses data to return a clone of the value that has been serialized using ser.serialize([value])