Lowly-db NPM | npm.io

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 });