passive-db

A simple passive local DB that allows you to store as much data as your drive has free space.

Compatibility

• ✅ Linux - Built for

• ℹ️ Windows - You'll need WSL

• ⚠️ Mac - Not tested

• ✅ JS and TS

• ✅ ES5 and ES6

Overview

This package offers very simple calls and convenient solutions.

Entry - A generic entry class that you can use to create new entries.

IMPORTANT NOTE: All nonSync functions of a pair are Promise based

Bind functions can be set to not update the parent entries automatically. In "target - source" functions target is the entry to edit and source is the referece

DB - The DB class that you'll manage your DB through.

.onready - A function that will be called when the db is set up, alternatively you can eyeball the delay with timeouts.

.getEntry - Returns an entry promise from the database from it's ID, which can be obtained from parent entries.

.getentriesync - .getEntry but synchronously. Uses fs.readFileSync

.setEntry - Writes/updates the passed entry to the database.

.setentriesync - .setEntry but synchronously. Uses fs.writeFileSync

.deleteEntry - Removes the passed entry/id from the database.

.deleteentriesync - .deleteEntry but synchronously. Uses fs.rmSync

.find - Pass an entry or entry id. The function will asynchronously iterate over the child entries and appeds them to a new array if the predicate is true and returns a promise for the finsihed list.

.bindEntry - Appends an entry to another entry.

.bindentriesync - .bindEntry but synchronously. Uses .setentriesync

.unbindEntry - Removes an entry from another entry.

.unbindentriesync - .unbindEntry but synchronously. Uses .setentriesync

.bindMaster - Appends an entry to the master record.

.bindMasterSync - .bindMaster but synchronously. Uses .updateMasterSync

.unbindMaster - Removes an entry from the master record.

.unbindMasterSync - .unbindMaster but synchronously. Uses .updateMasterSync

.updateMaster - Writes the master record to the database.

.updateMasterSync - .updateMaster but synchronously. Uses fs.writeFileSync

For example, let's save a message under a parent entry titled "messages":

JS es5

const passive = require("passive-db");

// initialize your new database
const db = new passive.DB("path-to-db");

db.onready = () => {
	
	// this will be our parent entry
	var messages = new Entry({name: "messages"})
	db.setEntrySync(messages);
	
	var message = new Entry({data: new Date().toString()});
	db.setEntrySync(message);
	
	// bind the entries to not loos them
	db.bindEntrySync(messages, message, true);
	db.bindMasterSync(messages, true);

};

To retrieve data use the find method:

TS es6

import { UUID } from "crypto";
import {DB, Entry} from "./src/main";

const db = new DB("path-to-db");

db.onready = async function () {

	const messages_parent = (
		// let's ask the db to search for an entry
		await db.find("master",
			// we're searching for an entry named "messages"
			(entry) => {return entry.name == "messages"},
			// stop after we found one
			1,
			// allow to search for a long time
			9000000,
			// tell the db that we want to get entries and not ids
			"Entry"
		)
	// pick the first one in the array
	)[0] as Entry<Message>;

	// iterate over the child entries
	messages_parent.records.forEach(async (id) => {
		var message_entry = await db.getEntry(id);
		// logs every message
		console.log(message_entry);
	})
};

Misc

What is the master record?

This passive DB works in a parent-child entry configuration where parent entries have child entries. The master record is a placeholder for your top level entries. If you dont bind your entry to anything and then save it in the database, then you have created an orphan entry, which are really hard to clean up.