@tfagaming/jsondb v1.3.0

@tfagaming/jsondb

A simple JSON database. It has many useful methods and very easy to use.

Install

npm install @tfagaming/jsondb

Usage

This is an example of JSON file.

{
    "a": 1,
    "b": 3,
    "c": 9,
    "z": 9,
    "d": 10,
    "e": 7,
    "t": null
}

Using the class JSONDB:

Define a new database:

import { JSONDB } from '@tfagaming/jsondb';

const db = new JSONDB('path/to/the/json/file.json');

Available types to use for the type parameter: string, number, boolean, { k: string: JSONValueTypes }, null, and JSONValueTypes[].

Note: Every method has it's description and examples of usage, you just need an Intellisense to read all methods information (use Visual Studio Code for an example).

Simple usage:

db.set('a', 15);

db.get('z'); // => 9
db.get('y'); // => undefined

db.has('b'); // => true
db.has('u'); // => false

db.delete('a');
db.purge('a', 'b');

db.first(); // => 1
db.last(); // => 7

db.isRepeated(9); // => true
db.isRepeated(3); // => false

Advanced usage:

// Returns the data in an array.
db.toArray(); // => [{ a: 1 }, ...]

// Similar to Array#every.
db.hasAll('a', 'b', 'c'); // => true
db.hasAll('a', 'b', 'c', 'y'); // => false
db.hasAll('y'); // => false

// Similar to Array#some.
db.hasAny('a', 'b', 'c'); // => true
db.hasAny('a', 'b', 'c', 'y'); // => true
db.hasAny('y'); // => false

// Pick multiple values by keys name.
db.pick('a', 'b'); // => [{ a: 1 }, { b: 3 }]

// Opposite of Object#fromEntries.
db.entries(); // => [ ['a', 1], ['b', 3], ... ]

// Delete a key by value.
db.deleteByValue(10);

// Array of keys or values.
db.keys(); // => ['a', 'b', 'c', ...]
db.values(); // => [1, 3, 9, ...]

// First key or value in object.
db.first(); // => 1
db.firstKey(); // => 'a'

// Last key or value in object.
db.last(); // => 7
db.lastKey(); // => 'e'

// Get index of key by key's name.
db.indexOf('c'); // => 2

// Similar to Array#map, Array#forEach, and Array#reduce.
db.map((v, k) => `${k}: ${v}`); // => ['a: 1', 'b: 3', ...]
db.forEach((v, k) => ...);
db.reduce((accumulator, k, v) => ..., initialValue);

db.sort((a, aValue, b, bValue) => ...);

// Whenever a key's value is null value.
db.isEmpty('t'); // => true
db.isEmpty('a'); // => false
db.isEmpty('y'); // => undefined

// Type of key's value.
db.typeof('a'); // => 'number'
db.typeof('t'); // => 'null'

// Similar to Array#find and Array#filter.
db.find((v) => v >= 9); // => [ { c: 9 }, { z: 9 }, { d: 10 } ]
db.filter((v, k) => ...);

// Increment or decrement a key's value by one.
db.increment('a');
db.decrement('a');

// Get a key's value. If doesn't exist, returns a default value.
db.ensure('a', 69); // => 1
db.ensure('k', 420); // => 420

// Random key name or value.
db.random('key'); // => 'z'
db.random('value'); // => 3
db.random(); // => { d: 10 }

// Create some groups.
db.group({ A: ['a', 'b'], B: ['d', 'z'], C: ['e'] }); // => [ { A: [{ a: 1 }, { b: 3 }] }, { B: [{ d: 10 }, { z: 9 }] }, { C: [{ e: 7 }] } ]

// Delete all keys.
db.init();

// Import a JSON file data and export one.
db.import('path/to/file.json', true);
db.export('filename.json');

// Set all key's values to a specific value.
db.fill(69);

// Sorts alphabetically the key names.
db.alpha();

// Swap key's name by it's value and the value by it's key name.
db.swap();

// Similar to Array#slice.
db.trim(3);

// Rename a key's name.
db.rename('a', 'w');

// Merge an object to the JSON file.
db.merge({ w: 1, x: 2, y: 3, z: 5 });

// Similar to Array#push, the other pulls one element.
db.push(...);
db.pull(...);

// Similar to Object#freeze.
db.freeze();

Using the class JSONSchemaDB:

Define a new database:

import { JSONSchemaDB } from '@tfagaming/jsondb';

const db = new JSONSchemaDB<{ id: number, name: string, age?: number }>('path/to/the/json/file.json');

Note: The JSON file content must be an array, not an object.

Options:

{
    automaticId?: boolean, // => Automatically adds ID to an object (like SQL).
    uneditableId?: boolean // => Force uneditable ID when using 'updateOne' or 'updateMany'.
}

Usage:

// Find a single object by filter.
db.findOne((obj) => obj.id === 1);
db.findOne((obj) => obj.id === 1 && obj.name === 'Hello');
db.findOne((obj) => obj.name !== 'Hello' && obj.age > 24);

// Find multiple objects by filter.
db.findMany((obj) => obj.id === 1);
db.findMany((obj) => obj.id === 1 && obj.name === 'Hello');
db.findMany((obj) => obj.name !== 'Hello' && obj.age < 24);

// Find one and/or many and deletes it.
db.findOneAndDelete((obj) => ...);
db.findManyAndDelete((obj) => ...);

// Find one and returns the object index in the array.
db.findOneAndReturnIndex((obj) => ...);

// Find one or delete one by ID, only if schema has the property 'id'.
db.findOneById(...);
db.deleteOneById(...);

// Set a new or multiple objects in the array.
db.create({ ... });
db.createMany({ ... });

// Update an object or mutliple objects data.
db.updateOne((obj) => ..., { ... });
db.updateMany((obj) => ..., { ... });

// Finds how many objects exist by the predicate.
db.count((obj) => ...);
db.count();

// Increment or decrement a variable by value.
db.incrementOne((obj) => ..., { age: 10 }); // (Adds 10 to the "age" property)
db.decrementOne((obj) => ..., { age: 10 }); // (Adds -10 to the "age" property)

License

GPL-3.0, General Public License v3.0.