# Utilities

nanoSQL uses numerous utility functions that you can take advantage of in your projects.

# Usage / Installation

Using with <script>

const utils = window["@nano-sql/core"].utilities;
// uuid function:
utils.uuid();

Using with module loader

import * as utils from "@nano-sql/core/lib/utilities";
// uuid function:
utils.uuid();

# Functions

# binarySearch

Uses fast binary search to a find value in a sorted array. Returns location of the value. Orders of magnitude faster than .indexOf but only works with sorted arrays.

Arguments:

Examples

utils.binarySearch([1, 2, 3], 2.5) // 2
utils.binarySearch([1, 2, 3], 2.5, true) // -1
utils.binarySearch([1, 2, 3], 2, true) // 1

# titleCase

Converts a single word into title case.

Arguments:

Examples

utils.titleCase("hellO") // Hello
utils.titleCase("hello, WORLD!") // Hello, world!

# slugify

Converts a word, phrase, or sentence into a slug friendly format. Spaces are replaced with dashes, the whole string is lowercased and all non alphanumeric characters are removed.

Arguments:

Examples

utils.slugify("hello, WORLD!") // hello-world

# noop

Does nothing. Takes no arguments, returns nothing.

Examples

utils.noop();

# nan

Takes anything and converts it into a float. If it's already float does nothing.

Arguments:

Examples

utils.nan(NaN) // 0
utils.nan("hello, world!") // 0
utils.nan(20) // 20
utils.nan(200.290) // 200.290

# assign

A faster Object.assign for dereferencing objects. Internally just uses JSON.parse(JSON.stringify(obj)). This is considerably faster than iterating through the object recursively and cloning the properties.

If there are any functions in the object they will be ignored.

Arguments:

Examples

utils.assign({key: "value"}) // {key: "value"}

# maybeAssign

Checks if an object is frozen, returns a deep copy if it's frozen. Otherwise does nothing.

Arguments:

Examples

utils.maybeAssign({key: "value"}) // {key: "value"}

# objectsEqual

Recursively compare two javascript variables to see if they match. Works for primitives, objects, and arrays. Arrays must be in the same order to be considered equal.

Arguments:

Examples

utils.objectsEqual(20, 20) // true
utils.objectsEqual([20], [20]) // true
utils.objectsEqual([10, 20], [20, 10]) // false
utils.objectsEqual({key: "value"}, {key: "value"}) // true

# chainAsync

Execute a series of items serially (one after another) with an asynchronous function. Returns a promise.

Arguments:

Examples

utils.chainAsync(["1", "2", "3"], (item, i, next, err) => {
    next(item + "-0");
}).then((result) => {
    console.log(result);
    // ["1-0", "2-0", 3-0"]
}).catch((err) => {
    // error happend
});

# allAsync

Execute a series of items in parallel with an asynchronous function. Returns a promise.

The order of items in the result set is maintained regardless of the order the execution finishes in.

Arguments:

Examples

utils.allAsync(["1", "2", "3"], (item, i, next, err) => {
    next(item + "-0");
}).then((result) => {
    console.log(result);
    // ["1-0", "2-0", 3-0"]
}).catch((err) => {
    // error happend
});

# random16Bits

Produces a random number between 0 and 65,536. Uses feature detection to use the strongest entropy & crypto available in NodeJS or the browser. Falls back to Math.random.

Takes no arguments.

Examples

utils.random16Bits() // 2938
utils.random16Bits() // 10930
utils.random16Bits() // 20029

# throttle

Provided a function and time, guarantees the function will not fire more frequently than the time provided. Does not fire on the first call.

Arguments:

Examples

let count = 0;
const throttledFn = utils.throttle(undefined, (passedArg) => {
    count++;
    console.log(count, passedArg);
}, 1000);
setInterval(() => {
    throttledFn("hello");
}, 50);
// every second on the console:
// 1 "hello"
// 2 "hello"
....

# timeid

Returns a timeId or timeIdms, depending on the argument passed in.

Arguments:

Examples

utils.timeid() // "1546890739-0aae8"
utils.timeid(true) // "1546890778707-03aa2"

# uuid

Returns a V4 UUID. There are no arguments.

Examples

utils.uuid() // "8eeff8e6-934a-4920-83d7-6d9a01583b20"

# hash

A quick and dirty hashing function, returns a string representing the hash of the passed in value. Stolen from https://github.com/darkskyapp/string-hash

Arguments:

Examples

utils.hash("hello, world!"); // 147bde48

# intersect

Given two arrays, check to see if any values in the two arrays are the same.

Arguments:

Examples

utils.intersect([1, 2], [2, 3]) // true
utils.intersect([1, 2], [4, 3]) // false

# isObject

Checks to see if the provided argument is a javascript object, does NOT include arrays, functions, null, etc. Only {} objects.

Arguments:

Examples

utils.isObject([]); // false
utils.isObject(2); // false
utils.isObject({}); // true
utils.isObject(() => {}) // false

# objSort

Useful for sorting arrays of objects based on nested values. Returns a function that can be used in Array.sort

Arguments:

Examples

const sortFn = utils.objSort("nested.value");
[
    {nested: {value: 2}},
    {nested: {value: 3}},
    {nested: {value: 1}}
].sort(sortFn);
/*
[
    {nested: {value: 1}},
    {nested: {value: 2}},
    {nested: {value: 3}}
]
*/

# rad2deg

Converts radians to degrees.

Arguments:

Examples

utils.rad2deg(2.29) // 131.20733508495852
utils.rad2deg(Math.PI) // 180

# deg2rad

Converts degrees to radians.

Arguments:

Examples

utils.deg2rad(29.8) // 0.5201081170943103
utils.deg2rad(180) // 3.141592653589793

# crowDistance

Haversine formula to determine the distance between two GPS points.

Arguments:

Examples

utils.crowDistance(10, 20, -10, 20); // 2223.8985328911745

# levenshtein

Levenshtein distance between two strings. This small library is used for this feature, so you can think of this function as an alias for that library.

Arguments:

Examples

utils.levenshtein("hello", "hello, world!") // 8

# resolvePath

Turns a string describing an object path into an array of strings. Accepts any JSON notation for the path.

Arguments:

Examples

utils.resolvePath("nested[0].value.here") // ["nested", "0", "value", "here"]

# deepFreeze

Recursively freeze a javascript object to prevent it from being modified or mutated.

Arguments:

Examples

const frozenArray = utils.deepFreeze([1, 2, 3]);
frozenArray[0] = 2; // throws error, doesn't work.

# deepSet

Given an object, path, and value set the value at the path in the object. If any of the nested objects don't exist they will be created.

Returns the modified object, also mutates the object in place.

Arguments:

Examples

let obj = {nested: {value: 20}}
utils.deepSet("nested.value", obj, 30);
// {nested: {value: 30}}
utils.deepSet("nested.arr[0]", obj, true);
// {nested: {value: 30, arr: [true]}}
utils.deepSet("nested.value.obj", obj, {});
// {nested: {value: {obj: {}}, arr: [true]}}

# deepGet

Given an object and path get the value at the path. Doesn't cause an error if any part of the path is undefined, making this safer than the typical method for getting objects.

Returns the value or undefined.

Arguments:

Examples

utils.deepGet("nested.value", {nested: {value: 20}); // 20
utils.deepGet("nested.arr[0]", {nested: {value: 20}); // undefined

# setFast

A universal/isomorphic setImmediate. Works just like setTimeout(callback, 0), but orders of magnitude faster.

Arguments:

Examples

utils.setFast(() => {
    console.log("YO!");
})
// "YO!"

# Constants

# isSafari

Detects if the environment is Safari web browser (desktop) or ANY web browser on iOS.

# isMSBrowser

Detects if the running browser is IE or Edge

# isAndroid

Detects if the running environment is on an android based browser.