Installation

With npm:

npm install @rnacanvas/utilities

Usage

All exports of this package can be accessed as named imports.

// some example imports
import { detectMacOS } from '@rnacanvas/utilities';
import { DownloadableFile } from '@rnacanvas/utilities';
import { KeyBinding } from '@rnacanvas/utilities';

function first()

Returns the first item in an array.

Throws for empty arrays.

first([5, 4, 3, 2, 1]); // 5

first(['b']); // "b"

first([]); // throws

function last()

Returns the last item in an array.

Throws for empty arrays.

last([5, 4, 3, 2, 1]); // 1

last(['b']); // "b"

last([]); // throws

function middleThree()

Returns the middle three items in an array.

Throws for arrays with less than three items and arrays with even numbers of items.

middleThree([1, 2, 3, 4, 5]); // [2, 3, 4]

middleThree([1, 2, 3, 4, 5, 6]); // throws

middleThree([]); // throws
middleThree(['a']); // throws
middleThree(['a', 'b']); // throws
middleThree(['a', 'b', 'c']); // ["a", "b", "c"]

function middleFour()

Returns the middle four items in an array.

Throws for arrays with less than four items and arrays with odd numbers of items.

middleFour([1, 2, 3, 4, 5, 6]); // [2, 3, 4, 5]

middleFour([1, 2, 3, 4, 5, 6, 7]); // throws

middleFour([]); // throws
middleFour(['a']); // throws
middleFour(['a', 'b']); // throws
middleFour(['a', 'b', 'c']); // throws
middleFour(['a', 'b', 'c', 'd']); // ["a", "b", "c", "d"]

function removeWhitespace()

Returns a new string with all whitespace characters having been omitted from the input string.

removeWhitespace(' a s d f '); // "asdf"

// different kinds of whitespace characters
removeWhitespace(' a\ts\nd\rf\r\n'); // "asdf"

// no whitespace characters
removeWhitespace('asdf'); // "asdf"

// an empty string
removeWhitespace(''); // ""

function splitLines()

Splits a string into its constituent lines regardless of newline character encoding (e.g., CR, LF, CRLF).

splitLines('asdf\nqwer'); // ["asdf", "qwer"]

splitLines('1\n2\r3\r\n4'); // ["1", "2", "3", "4"]

Note that empty strings might be present in the returned array after splitting.

splitLines('\nasdf'); // ["", "asdf"]

splitLines('qwer\r'); // ["qwer", ""]

splitLines('asdf\n\n\nqwer'); // ["asdf", "", "", "qwer"]

function isJSON()

Returns true if a value is a string in JSON format.

Returns false otherwise.

isJSON('{ "a": 1, "b": 2 }'); // true

isJSON('[1, 2, 3]'); // true

isJSON('"asdf"'); // true

isJSON('2'); // true

// no double-quotes
isJSON('asdf'); // false

// missing closing bracket
isJSON('{ "a": 1, "b": 2'); // false

// not a string
isJSON({ "a": 1, "b": 2 }); // false

// some more non-string values
isJSON([1, 2, 3]); // false
isJSON(2); // false

function isJSONSerializable()

Returns true if a value can be serialized to a JSON string.

Returns false otherwise.

isJSONSerializable({ "a": 1, "b": 2 }); // true

var o = {};

// a circular reference
o.o = o;

isJSONSerializable(o); // false

// some simple cases
isJSONSerializable([1, 2, 3]); // true
isJSONSerializable('asdf'); // true
isJSONSerializable(2); // true

function shuffled()

Returns a new array containing the same values as in the input array but shuffled in random order.

(Does not modify the input array of values.)

shuffled([1, 2, 3, 4, 5]); // [3, 1, 5, 2, 4]

function hasFocus()

The hasFocus() function returns true if and only if the passed in node is the active element of the document.

hasFocus(document.activeElement); // true

hasFocus(document.createElement('div')); // false

function containsFocus()

The containsFocus() function returns true if and only if the passed in node contains the active element of the document (or is the active element of the document).

var ele1 = document.createElement('div');
var ele2 = document.createElement('div');

// element 1 contains element 2
ele1.append(ele2);

// make elements focusable
ele1.tabIndex = 0;
ele2.tabIndex = 0;

ele1.focus();
containsFocus(ele1); // true
containsFocus(ele2); // false

ele2.focus();
containsFocus(ele1); // true
containsFocus(ele2); // true

class DownloadableFile

Represents a file that can be downloaded by the user.

var file = new DownloadableFile('A file.txt', 'Some text.', { type: 'text/plain' });

file.name; // "A file.txt"
file.content; // "Some text."
file.type; // "text/plain"

// download the file for the user
file.download();

A blob can be used in place of a string for the content of a downloadable file.

var blob = new Blob(['<p>Hello</p>'], { type: 'text/html' });

var file1 = new DownloadableFile('hello.html', blob);

// specifying file type overrides blob type
var file2 = new DownloadableFile('hello.txt', blob, { type: 'text/plain' });

file2.type; // "text/plain"
file1.type; // "text/html"

All constructor parameters are optional.

var file = new DownloadableFile();

// default values
file.name; // "Unnamed.txt"
file.content; // ""
file.type; // "text/plain"

class KeyBinding

The KeyBinding class represents a key binding.

See the @rnacanvas/key-bindings package for documentation.

function detectWindows()

Returns true if it is detected that the user is using Windows and returns false otherwise.

detectWindows();

function detectMacOS()

Returns true if it is detected that the user is using macOS and returns false otherwise.

detectMacOS();