node-lite-db v2.0.1
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.
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
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. |