1.0.6 • Published 10 months ago

lowly-db v1.0.6

Weekly downloads
-
License
MIT
Repository
-
Last release
10 months ago

LowlyDB

NPM Version NPM Downloads NPM License

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.

1.0.6

10 months ago

1.0.5

10 months ago

1.0.4

10 months ago

1.0.3

10 months ago

1.0.2

10 months ago

1.0.1

10 months ago

1.0.0

10 months ago