node-lite-db

A lightweight node database, implemented with json files, which can handle concurrent calls to the database, and only requires 2 lines of code to configure. This package was designed to be a simple solution that can help projects quickly get off the ground using persistant state. This is not a robust solution, but can be quite powerful.

Github

Documentation

Getting Started

Install package to your project.

npm install node-lite-db

We recommended creating a dedicated file for initializing your database, for example a file named database.ts. This folder can be anywhere within your project, however we like to create the file in the root directory.

Import node-db-lite into your new file database.ts.

import { DatabaseNode, DocumentNode } from "node-db-lite";

and create new DatabaseNode and DocumentNode like below

const db = new DatabaseNode("data");

When the server starts this will create your database file structure in ./data.

There are 2 ways to create a new document on a database. They both accomplish the same thing, with the same return of a new DocumentNode instance with the options provided.

// Option 1 - call document method on the db instance to create new document instance
const doc_1 = db.document("doc_1", []);
// Option 2 - pass the db instance as a parameter to a new document instance.
const doc_2 = new DocumentNode("doc_2", [], db);

Next if we want to add something to our doc_1 document we can call the .save() method on the document instance, and pass the data object we'd like to save as a new record.

doc_1.save({ text: "lorem ipsum", numbers: [1, 2, 3, 4, 5] });

Congratulations you have successfully saved your first record to your database using node-lite-db! Be sure to checkout the documentation below for important configuration and what other cool stuff you can do with your database.

Required Configuration

Nodemon

If you are using nodemon, you need to tell nodemon to ignore your database paths, otherwise the watcher will restart every time you make an update to the database. These paths will be whatever you pass to any DatabaseNode instance. They can be ignored by adding a nodemon.json file to the root directory of your project with the paths listed inside the ignore property, if we want nodemon to ignore our database for the getting started example we need to add the following:

nodemon.json

{
  "ignore": ["data"]
}

Database Configuration

You can pass a DatabaseOptions object when creating a new DatabaseNode instance to set its configuration for all child DocumentNodes. The default options are below.

DatabaseOptions Example

const db_options = {
  /* Label used for logs generated from the database instance and its children DocumentNode instances*/
  messageLabel: "lite-db",
  /* Extension used for database files */
  fileExtension: ".db",
};

const db = new DatabaseNode("data", db_options);

You can pass a DocumentOptions object when creating a new DocumentNode instance.

DocumentOptions

const doc_options = {
  /* Whether or not the document should auto generate ids for saved records */
  generateId: true,
};

const doc = new DocumentNode("document", [], doc_options);

API Documentation

Classes

DatabaseNode

Represents a database connection.

Kind: global class

• DatabaseNode
  • new DatabaseNode(path, options)
  • instance
    • .log(content)
    • .document(documentName, initialData, options) ⇒ DatabaseNode
    • .getPath() ⇒ string
    • .getMessageLabel() ⇒ string
    • .getFileExtension() ⇒ string
  • static
    • .databases

new DatabaseNode(path, options)

Creates a database node.

Returns: DatabaseNode - A new instance of DatabaseNode. If you attempt to create a database with a path that already exists, the existing instance with that path will be return instead.

| Param | Type | Description | | ------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | path | string | A unique absolute path where the database documents will be written to. Root directory is identified with Node process.cwd(). | | options | DatabaseOptions | undefined | Optional configuration object that overides some default database settings. |

databaseNode.log(content)

Logs content to the console using the databases messageLabel.

Kind: instance method of DatabaseNode

| Param | Type | Description | | ------- | ---------------- | ------------------- | | content | any | The content to log. |

databaseNode.document(documentName, initialData, options) ⇒ DatabaseNode

Create a new document in the database.

Kind: instance method of DatabaseNode
Returns: DatabaseNode - A new document instance that can be used to interact with the database document.

| Param | Type | Description | | ------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | documentName | string | The name of the document you want to create. | | initialData | Array.<any> | An array of data that should initially be in the document. Note: This only applies to newly created documents, not restored documents. | | options | DocumentOptions | undefined | Optional configurations for the newly created DocumentNode. |

databaseNode.getPath() ⇒ string

Getter method for the path property.

Kind: instance method of DatabaseNode
Returns: string - - The database path.

databaseNode.getMessageLabel() ⇒ string

Getter method for the messageLable property.

Kind: instance method of DatabaseNode
Returns: string - - The messageLabel to be used for database logs.

databaseNode.getFileExtension() ⇒ string

Getter method for the fileExtension property.

Kind: instance method of DatabaseNode
Returns: string - - The fileExtension to be used for writing new documents.

DatabaseNode.databases

Kind: static property of DatabaseNode
Properties

| Name | Description | | --------- | ----------------------------------------- | | databases | store of the existing database instances. |

DocumentNode

Represents a document file.

Kind: global class

• DocumentNode
  • new DocumentNode(documentName, initialData, database, options)
  • .log(content)
  • .buildDocumentUrl(documentName) ⇒ string
  • .restoreData(documentName, data) ⇒ Array.<any>
  • .getOneById(id) ⇒ object | undefined
  • .getFirstMatch(condition) ⇒ object | undefined
  • .getAllMatches(condition) ⇒ Array.<object>
  • .getAll() ⇒ Array.<object>
  • .save(record, cb) ⇒ string | number | undefined
  • .delete(id, cb)
  • .clear(documentName)

new DocumentNode(documentName, initialData, database, options)

Create a new document in the database.

Returns: DocumentNode - A new document instance that can be used to interact with the database document.

| Param | Type | Description | | ------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | documentName | string | The name of the document you want to create. | | initialData | Array.<any> | An array of data that should initially be in the document. Note: This only applies to newly created documents, not restored documents. | | database | DatabaseNode | The database instance of DatabaseNode you would like to create the document in. | | options | DocumentOptions | Optional configurations for the newly created DocumentNode. |

documentNode.log(content)

Logs content to the console using the databases messageLabel.

Kind: instance method of DocumentNode

| Param | Type | Description | | ------- | ---------------- | ----------- | | content | any | Content |

documentNode.buildDocumentUrl(documentName) ⇒ string

Builds absolute url for document read/write location.

Kind: instance method of DocumentNode
Returns: string - - The url to the document.

| Param | Type | Description | | ------------ | ------------------- | --------------------------------------- | | documentName | string | The document name to build the url for. |

documentNode.restoreData(documentName, data) ⇒ Array.<any>

Attempts to restore data if document file already exists.

Kind: instance method of DocumentNode
Returns: Array.<any> - - An array of data contained in the document file.

| Param | Type | Description | | ------------ | ------------------------------ | ------------------------------------------------------- | | documentName | string | The documentName. | | data | Array.<any> | The initial data for the file if it cannot be restored. |

documentNode.getOneById(id) ⇒ object | undefined

Retrieve first record that matches the given id

Kind: instance method of DocumentNode
Returns: object | undefined - - The found record or undefined if the record could not be found.

| Param | Type | Description | | ----- | ------------------------------------------ | --------------------- | | id | number | string | The id to search for. |

documentNode.getFirstMatch(condition) ⇒ object | undefined

Retrieve the first record in the document that passes the given test

Kind: instance method of DocumentNode
Returns: object | undefined - - Returns the first record to pass the test

| Param | Type | Description | | --------- | --------------------- | ------------------------------------- | | condition | function | A test to check the reecords against. |

documentNode.getAllMatches(condition) ⇒ Array.<object>

Retrieve all records in the document that pass the given test

Kind: instance method of DocumentNode
Returns: Array.<object> - - The matching data.

| Param | Type | Description | | --------- | --------------------- | ----------------------------------------------- | | condition | function | A test that returns true when condition is met. |

documentNode.getAll() ⇒ Array.<object>

Retrieve all records in the document

Kind: instance method of DocumentNode
Returns: Array.<object> - - All records in the document.

documentNode.save(record, cb) ⇒ string | number | undefined

Add one new record to the document

Kind: instance method of DocumentNode
Returns: string | number | undefined - - The id of the saved record, if id property exists on record.

| Param | Type | Description | | ------ | --------------------- | ---------------------------------------------------- | | record | object | Record to save. | | cb | function | Callback function to run when the process completes. |

documentNode.delete(id, cb)

Add one record from the document by id

Kind: instance method of DocumentNode

| Param | Type | Description | | ----- | ------------------------------------------ | ---------------------------------------------------- | | id | string | number | Id of the record to delete. | | cb | function | Callback function to run when the process completes. |

documentNode.clear(documentName)

Hard deletes all information within document. All data will be lost forever.

Kind: instance method of DocumentNode

| Param | Type | Description | | ------------ | ------------------- | ----------------------------------------------------------------------------------------- | | documentName | string | The name of the document you are attempting to clear. This redudancy is a safety measure. |