LowlyDB

LowlyDB is a lightweight, file-based NoSQL database for quick data storage and retrieval in JSON format. It offers basic CRUD operations, schema validation, and transactional support.

Features

• CRUD Operations: Create, Read, Update, and Delete records easily.
• Schema Validation: Validate data records against a schema.
• Auto-Increment ID: Automatically generates unique IDs for new records.
• Transactional Support: Perform multiple actions atomically.
• File-Based Storage: Stores data persistently in a JSON file.
• Simple API: Easy-to-use methods for interacting with the database.

Installation

npm install lowly-db

Usage

Initialization

import LowlyDB from "lowly-db";

const db = new LowlyDB("myDatabase.json", {
  name: "string",
  age: "number"
});

API Methods

constructor(filePath, schema = null)

• Parameters:
  • filePath (string): Path to the JSON file for storage.
  • schema (object): Optional schema for data validation.
• Description: Initializes the database with the specified file and schema.

create(record)

• Parameters:
  • record (object): The record to create.
• Returns: The created record.
• Description: Adds a new record to the database. If no id is provided, it auto-generates one.
• Example:

  db.create({ name: "Alice", age: 25 });

read(query = {})

• Parameters:
  • query (object): The query to filter records.
• Returns: An array of matching records.
• Description: Retrieves records matching the query. Returns all records if the query is empty.
• Example:

  db.read({ age: 25 });

update(query, updates)

• Parameters:
  • query (object): The query to find records to update.
  • updates (object): The fields to update.
• Description: Updates all records matching the query.
• Example:

  db.update({ name: "Alice" }, { age: 26 });

delete(query)

• Parameters:
  • query (object): The query to find records to delete.
• Description: Deletes all records matching the query.
• Example:

  db.delete({ age: 25 });

findById(id)

• Parameters:
  • id (number|string): The record's ID.
• Returns: The matching record or null if not found.
• Description: Finds a record by its unique ID.
• Example:

  db.findById(1);

deleteById(id)

• Parameters:
  • id (number|string): The record's ID.
• Description: Deletes a record by its unique ID.
• Example:

  db.deleteById(1);

count(query = {})

• Parameters:
  • query (object): The query to filter records.
• Returns: The number of matching records.
• Description: Counts the records matching the query.
• Example:

  db.count({ age: 25 });

clear()

• Description: Deletes all records in the database.
• Example:

  db.clear();

transaction(actions)

• Parameters:
  • actions (function[]): An array of functions that take the database instance as a parameter.
• Description: Performs multiple actions atomically. Rolls back changes if an error occurs.
• Example:

  db.transaction([
    db => db.create({ name: "John", age: 30 }),
    db => db.update({ name: "John" }, { age: 31 })
  ]);

Error Handling

• Schema Validation: Throws an error if a record doesn't match the schema.
• Duplicate IDs: Throws an error if an attempt is made to create a record with an existing ID.

Example

import LowlyDB from "lowly-db";

const db = new LowlyDB("users.json", { name: "string", age: "number" });

// Create a new record
db.create({ name: "Alice", age: 25 });

// Read records
const users = db.read({ age: 25 });
console.log(users);

// Update a record
db.update({ name: "Alice" }, { age: 26 });

// Delete a record
db.delete({ age: 26 });

License

This project is licensed under the MIT License.

Acknowledgements

This library was inspired by the need for lightweight, file-based data storage solutions for simple projects.