Josh API Documentation

The full API documentation pulled directly from the source code via jsdocs-to-markdown.

Josh

Kind: global class

new Josh([options])

Initializes a new Josh, with options.

Param

Type

Description

[options]

Object

Additional options an configurations.

[options.name]

string

Required. The name of the table in which to save the data.

[options.provider]

string

Required. A string with the name of the provider to use. Should not be already required, as Josh takes care of doing that for you. Must be a valid provider that complies with the Provider API. The provider needs to be installed separately with yarn or npm. See https://josh.evie.dev/providers for details.

[options.ensureProps]

boolean

defaults to true. If enabled and an inserted value is an object, using ensure() will also ensure that every property present in the default object will be added to the value, if it's absent.

[options.autoEnsure]

*

default is disabled. When provided a value, essentially runs ensure(key, autoEnsure) automatically so you don't have to. This is especially useful on get(), but will also apply on set(), and any array and object methods that interact with the database.

[options.serializer]

function

Optional. If a function is provided, it will execute on the data when it is written to the database. This is generally used to convert the value into a format that can be saved in the database, such as converting a complete class instance to just its ID. This function may return the value to be saved, or a promise that resolves to that value (in other words, can be an async function).

[options.deserializer]

function

Optional. If a function is provided, it will execute on the data when it is read from the database. This is generally used to convert the value from a stored ID into a more complex object. This function may return a value, or a promise that resolves to that value (in other words, can be an async function).

Example

const Josh = require("@joshdb/core");
const provider = require("@joshdb/sqlite");
// sqlite-based database, with default options
const sqliteDB = new Josh({
name: 'mydatabase',
provider,
});

josh.keys ⇒ Promise.<Array.String>

Get all the keys in the database.

Kind: instance property of Josh Returns: Promise.<Array.String> - An array of all the keys as string values.

josh.values ⇒ Promise.<Array>

Get all the values in the database.

Kind: instance property of Josh Returns: Promise.<Array> - An array of all the values stored in the database.

josh.size ⇒ Promise.<number>

Get the amount of rows inside the database.

Kind: instance property of Josh Returns: Promise.<number> - An integer equal to the amount of stored key/value pairs.

josh.get(keyOrPath) ⇒ Promise.<*>

Retrieves (fetches) a value from the database. If a simple key is provided, returns the value. If a path is provided, will only return the value at that path, if it exists.

Kind: instance method of Josh Returns: Promise.<*> - Returns the value for the key or the value found at the specified path.

Param

Type

Description

keyOrPath

string

Either a key, or full path, of the value you want to get. For more information on how path works, see https://josh.evie.dev/path

josh.getMany(keys) ⇒ Promise.<Object>

Retrieve many values from the database. If you provide josh.all as a value (josh being your variable for the database), the entire data set is returned.

Kind: instance method of Josh Returns: Promise.<Object> - An object with one or many key/value pairs where the property name is the key and the property value is the database value.

Param

Type

Description

keys

Array.<string> | symbol

An array of keys to return, or db.all to retrieve them all.

josh.random(count) ⇒ Promise.<Object>

Returns one or more random values from the database.

Kind: instance method of Josh Returns: Promise.<Object> - An array of key/value pairs each in their own array. The array of values should never contain duplicates. If the requested count is higher than the number of rows in the database, only the available number of rows will be returned, in randomized order. Each array element is comprised of the key and value: // TODO : FIX [['a', 1], ['b', 2], ['c', 3]]

Param

Type

Description

count

number

Defaults to 1. The number of random key/value pairs to get.

josh.randomKey(count) ⇒ Promise.<Array.<string>>

Returns one or more random keys from the database.

Kind: instance method of Josh Returns: Promise.<Array.<string>> - An array of string keys in a randomized order. The array of keys should never contain duplicates. If the requested count is higher than the number of rows in the database, only the available number of rows will be returned.

Param

Type

Description

count

number

Defaults to 1. The number of random key/value pairs to get.

josh.has(keyOrPath) ⇒ Promise.<boolean>

Verifies whether a key, or a specific property of an object, exists at all.

Kind: instance method of Josh Returns: Promise.<boolean> - Whether the key, or property specified in the path, exists.

Param

Type

Description

keyOrPath

string

Either a key, or full path, of the value you want to get. For more information on how path works, see https://josh.evie.dev/path

josh.set(keyOrPath, value) ⇒ Promise.<Josh>

Store a value in the database. If a simple key is provided, creates or overwrites the entire value with the new one provide. If a path is provided, and the stored value is an object, only the value at the path will be overwritten.

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Description

keyOrPath

string

Either a key, or a full path, where you want to store the value. For more information on how path works, see https://josh.evie.dev/path

value

*

The value to store for the key, or in the path, specified. All values MUST be "simple" javascript values: Numbers, Booleans, Strings, Arrays, Objects. If you want to store a "complex" thing such as an instance of a class, please use a Serializer to convert it to a storable value.

josh.setMany(data, overwrite) ⇒ Promise.<Josh>

Store many values at once in the database. DOES NOT SUPPORT PATHS. Or autoId.

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Description

data

Object

The data to insert. Must be an object as key/value pairs.

overwrite

boolean

Whether to overwrite existing keys. Since this method does not support paths, existin data will be lost.

Example

josh.setMany({
"thinga": "majig",
"foo": "bar",
"isCool": true
});

josh.update(keyOrPath, input) ⇒ Promise.<Object>

Update an object in the database with modified values. Similar to set() except it does not overwrite the entire object. Instead, the data is merged with the existing object. Object properties not included in your data are not touched.

Kind: instance method of Josh Returns: Promise.<Object> - The merged object that will be stored in the database.

Param

Type

Description

keyOrPath

string

Either a key, or full path, of the value you want to update.

input

Object | function

Either the object, or a function. If a function is provided, it will receive the current value as an argument. You are expected to return a modified object that will be stored in the database.

Example

josh.set('thing', {
a: 1,
b: 2,
c: 3
});
josh.update('thing', {
a: 'one',
d: 4
});
// value is now {a: 'one', b: 2, c: 3, d: 4}
josh.update('thing', (previousValue) => {
...previousValue,
b: 'two',
e: 5,
});
// value is now {a: 'one', b: 'two', c: 3, d: 4, e: 5}

josh.ensure(keyOrPath, defaultValue) ⇒ Promise.<*>

Returns the key's value, or the default given, ensuring that the data is there. This is a shortcut to "if josh doesn't have key, set it, then get it" which is a very common pattern.

Kind: instance method of Josh Returns: Promise.<*> - The value from the database for the key, or the default value provided for a new key.

Param

Type

Description

keyOrPath

string

Either a key, or full path, of the value you want to ensure.

defaultValue

*

Required. The value you want to save in the database and return as default.

Example

// Simply ensure the data exists (for using property methods):
josh.ensure("mykey", {some: "value", here: "as an example"});
josh.has("mykey"); // always returns true
josh.get("mykey", "here") // returns "as an example";
// Get the default value back in a variable:
const settings = mySettings.ensure("1234567890", defaultSettings);
console.log(settings) // josh's value for "1234567890" if it exists, otherwise the defaultSettings value.

josh.delete(keyOrPath) ⇒ Promise.<Josh>

Remove a key/value pair, or the property and value at a specific path, or clear the database.

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Description

keyOrPath

string | symbol | Array.<string>

Either a key, or full path, of the value you want to delete. If providing a path, only the value located at the path is deleted. If providing an array, will delete all keys in that array (does not support paths) Alternatively: josh.delete(josh.all) will clear the database of all data.

josh.push(keyOrPath, value, allowDupes) ⇒ Promise.<Josh>

Add a new value to an array.

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Default

Description

keyOrPath

string

Either a key, or full path, where the array where you want to add a value.

value

*

The value to add to the array.

allowDupes

boolean

true

Whether to allow duplicate values to be added. Note that if you're pushing objects or arrays, duplicates can occur no matter what, as detecting duplicate objects is CPU-intensive.

josh.remove(keyOrPath, value) ⇒ Promise.<Josh>

Remove a value from an array, by value (simple values like strings and numbers) or function (complex values like arrays or objects).

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Description

keyOrPath

*

Either a key, or full path, where the array where you want to remove from, is stored.

value

* | function

Required. The value to remove from the array. OR a function to match a value stored in the array. If using a function, the function provides the value and must return a boolean that's true for the value you want to remove.

Example

// Assuming
josh.set('array', [1, 2, 3])
josh.set('objectarray', [{ a: 1, b: 2, c: 3 }, { d: 4, e: 5, f: 6 }])
josh.remove('array', 1); // value is now [2, 3]
josh.remove('objectarray', (value) => value.e === 5); // value is now [{ a: 1, b: 2, c: 3 }]

josh.inc(keyOrPath) ⇒ Promise.<Josh>

Increments (adds 1 to the number) the stored value.

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Description

keyOrPath

*

Either a key, or full path, to the value you want to increment. The value must be a number.

josh.dec(keyOrPath) ⇒ Promise.<Josh>

Decrements (remove 1 from the number) the stored value.

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Description

keyOrPath

*

Either a key, or full path, to the value you want to decrement. The value must be a number.

josh.find(pathOrFn, predicate) ⇒ Promise.<Object>

Finds a value within the database, either through an exact value match, or a function. Useful for Objects and Array values, will not work on "simple" values like strings. Returns the first found match - if you need more than one result, use filter() instead. Either a function OR a value must be provided. Note that using functions here currently is very inefficient, so it's suggested to use paths whenever necesary.

Kind: instance method of Josh Returns: Promise.<Object> - Returns an array composed of the full value (NOT the one at the path!), and the key.

Param

Type

Description

pathOrFn

function | string

Mandatory. Either a function, or the path in which to find the value. If using a function: it will run on either the stored value, OR the value at the path given if it's provided. - The function receives the value (or value at the path) as well the the key currently being checked. - The function must return a boolean or truthy/falsey value! Oh and the function can be async, too ;) If using a path: - A "value" predicate is mandatory when checking by path. - The value must be simple: string, boolean, integer. It cannot be an object or array.

predicate

string

Optional on functions, Mandatory on path finds. If provided, the function or value acts on what's at that path.

Example

// Assuming:
josh.set("john.shmidt", {
fullName: "John Jacob Jingleheimer Schmidt",
id: 12345,
user: {
username: "john.shmidt",
firstName: "john",
lastName: "shmidt",
password: "somerandombcryptstringthingy",
lastAccess: -22063545000,
isActive: false,
avatar: null,
}
});
// Regular string find:
josh.find("user.firstName", "john")
// Simple function find:
josh.find(value => value.user.firstName === "john");
// Function find with a path:
josh.find(value => value === "john", "user.firstName");
// The return of all the above if the same:
{
"john.shmidt": {
fullName: "John Jacob Jingleheimer Schmidt",
id: 12345,
user: {
username: "john.shmidt",
firstName: "john",
lastName: "shmidt",
password: "somerandombcryptstringthingy",
lastAccess: -22063545000,
isActive: false,
avatar: null,
}
}
}

josh.filter(pathOrFn, predicate) ⇒ Promise.<Object>

Filters for values within the database, either through an exact value match, or a function. Useful for Objects and Array values, will not work on "simple" values like strings. Returns all matches found - if you need a single value, use find() instead. Either a function OR a value must be provided. Note that using functions here currently is very inefficient, so it's suggested to use paths whenever necesary.

Kind: instance method of Josh Returns: Promise.<Object> - Returns an array of key/value pair(s) that successfully passes the provided function.

Param

Type

Description

pathOrFn

function | string

Mandatory. Either a function, or the path in which to find the value. If using a function: it will run on either the stored value, OR the value at the path given if it's provided. - The function receives the value (or value at the path) as well the the key currently being checked. - The function must return a boolean or truthy/falsey value! Oh and the function can be async, too ;) If using a path: - A "value" predicate is mandatory when checking by path. - The value must be simple: string, boolean, integer. It cannot be an object or array.

predicate

string

Optional on functions, Mandatory on path finds. If provided, the function or value acts on what's at that path.

josh.map(pathOrFn) ⇒ Promise.<Array.<*>>

Maps data from each value in your data. Works similarly to Array.map(), but can use both async functions, as well as paths. Note that using functions here currently is very inefficient, so it's suggested to use paths whenever necesary.

Kind: instance method of Josh Returns: Promise.<Array.<*>> - An array of values mapped from the data.

Param

Type

Description

pathOrFn

function | string

Mandatory. Either a function, or the path where to get the value from. If using a path, the value at the path will be returned, or null. If using a function, the function is run on the entire value (no path is used). The function is given the key and value as arguments, and the value returned will be accessible in the return array.

josh.includes(keyOrPath, value) ⇒ boolean

Performs Array.includes() on a certain value. Works similarly to Array.includes().

Kind: instance method of Josh Returns: boolean - Whether the value is included in the array.

Param

Type

Description

keyOrPath

string

Either a key, or full path, to the array you want to check for the value. The value must be an array.

value

*

Either the value to check in the array, or a function to determine the presence of the value. If using a value, note that this won't work if the value you're checking for is an array or object - use a function for that. If using a function, the function takes in the value and index, and must return a boolean true when the value is the one you want.

Example

josh.set('arr', ['a', 'b', 1, 2, { foo: "bar"}]);
josh.includes('arr', 'a'); // true
josh.includes('arr', 1) // true
josh.includes('arr', val => val.foo === 'bar'); // true

josh.some(pathOrFn, value) ⇒ boolean

Checks whether at least one key contains the expected value. The loop stops once the value is found.

Kind: instance method of Josh Returns: boolean - Whether the value was found or not (if one of the rows in the database match the value at path, or the function has returned true)

Param

Type

Description

pathOrFn

string

Either a function, or the full path to the value to check against the provided value. If using a path, the value at he path will be compared to the value provided as a second argument. If using a function, the function is given the full value for each key, along with the key itself, for each row in the database. It should return true if your match is found.

value

string | number | boolean | null

The value to be checked at each path. Cannot be an object or array (use a function for those). Ignored if a function is provided.

josh.every(pathOrFn, value) ⇒ boolean

Checks whether every single key contains the expected value. Identical to josh.some() except all must match except just one.

Kind: instance method of Josh Returns: boolean - Whether the value was found or not, on ever single row.

Param

Type

Description

pathOrFn

*

Either a function, or the full path to the value to check against the provided value. If using a path, the value at he path will be compared to the value provided as a second argument. If using a function, the function is given the full value for each key, along with the key itself, for each row in the database. It should return true if your match is found.

value

string | number | boolean | null

The value to be checked at each path. Cannot be an object or array (use a function for those).

josh.math(keyOrPath, operation, operand, path) ⇒ Promise.<Josh>

Executes a mathematical operation on a value and saves the result in the database.

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Description

keyOrPath

string

Either a key, or full path, to the numerical value you want to exceute math on. Must be an Number value.

operation

string

Which mathematical operation to execute. Supports most math ops: =, -, *, /, %, ^, and english spelling of those operations.

operand

number

The right operand of the operation.

path

string

Optional. The property path to execute the operation on, if the value is an object or array.

Example

// Assuming
josh.set("number", 42);
josh.set("numberInObject", {sub: { anInt: 5 }});
josh.math("number", "/", 2); // 21
josh.math("number", "add", 5); // 26
josh.math("number", "modulo", 3); // 2
josh.math("numberInObject.sub.anInt", "+", 10); // 15

josh.autoId() ⇒ Promise.<string>

Get an automatic ID for insertion of a new record.

Kind: instance method of Josh Returns: Promise.<string> - A unique ID to insert data. Example

const Josh = require("@joshdb/core");
const provider = require("@joshdb/sqlite");
const sqliteDB = new Josh({
name: 'mydatabase',
provider,
});
(async() => {
const newId = await sqliteDB.autoId();
console.log("Inserting new row with ID: ", newID);
sqliteDB.set(newId, "This is a new test value");
})();

josh.import(data, overwrite, clear) ⇒ Promise.<Josh>

Import an existing json export from josh or enmap. This data must have been exported from josh or enmap, and must be from a version that's equivalent or lower than where you're importing it.

Kind: instance method of Josh Returns: Promise.<Josh> - This database wrapper, useful if you want to chain more instructions for Josh.

Param

Type

Default

Description

data

string

The data to import to Josh. Must contain all the required fields provided by export()

overwrite

boolean

true

Defaults to true. Whether to overwrite existing key/value data with incoming imported data

clear

boolean

false

Defaults to false. Whether to clear the enmap of all data before importing (WARNING: Any exiting data will be lost! This cannot be undone.)

josh.export() ⇒ Promise.<string>

Exports your entire database in JSON format. Useable as import data for both Josh and Enmap. WARNING: This currently requires loading the entire database in memory to write to JSON and might fail on large datasets (more than 1Gb)

Kind: instance method of Josh Returns: Promise.<string> - A JSON string that can be saved wherever you need it. Example

const fs = require("fs");
josh.export().then(data => fs.writeFileSync("./export.json"), data));

Josh.multi(names, options) ⇒ Array.<Map>

Initialize multiple Josh instances easily. Used to simplify the creation of many tables

Kind: static method of Josh Returns: Array.<Map> - An array of initialized Josh instances.

Param

Type

Description

names

Array.<string>

Array of strings. Each array entry will create a separate josh with that name.

options

Object

Options object to pass to each josh, excluding the name..

Example

// Using local variables.
const Josh = require('josh');
const provider = require("@joshdb/sqlite");
const { settings, tags, blacklist } = Josh.multi(['settings', 'tags', 'blacklist'], { provider });
// Attaching to an existing object (for instance some API's client)
const Josh = require("@joshdb/core");
const provider = require("@joshdb/sqlite");
Object.assign(client, Josh.multi(["settings", "tags", "blacklist"], { provider }));