@ramster/general-tools v2.3.0

Ramster General Tools

A general toolkit module that contains various utility methods. Can be used both in the browser and in node. It's mostly meant as a companion to ramster and ramster-ui, but works just as fine on its own.

Table Of Contents

• Getting Started
• arraySort - Sorts an array of objects by a list of inner properties. Supports SQL-style sorting by multiple field names and directions.
• changeKeyCase - Changes the case of all keys in an object or string and its children between loweCamelCase and UpperCamelCase, based on the provided map.
• checkRoutes - Checks whether a route exists in a list of HTTP routes. Supports ExpressJS-style route parameters, i.e. /users/item/:id.
• decodeQueryValues - Recursively performs decodeURIComponent on an object or value and returns the decoded object.
• emptyToNull - Takes an object or value and transforms undefined, null and empty strings to null. Recursively does so for objects without mutating the provided data.
• findVertexInGraph - Finds a vertex in a graph, then returns it and its path.
• flattenObject - Takes a deeply nested object and flattens it into top-level key-value pairs. Particularly suitable for turning nested objects into get params.
• getNested - Extracts a value from a deeply nested object, for example foo.bar.0.baz from {foo: {bar: {baz: 'test'}}}.
• setNested - Sets a value in a deeply nested object, for example foo.bar.0.baz in {foo: {bar: {baz: 'test'}}}.
• stringifyNestedObjects - Takes a nested object and turns its non-Date, non-null object keys into stringified json keys, which can later be decoded by the decodeQueryValues method.

Getting Started

It's really simple - just do

npm i @ramster/general-tools 

and you're good to go. Both the "import" and "require" syntax are supported, so either of these are valid:

import {getNested} from '@ramster/general-tools'
const {getNested} = require('@ramster/general-tools')

arraySort

Sorts an array of objects by a list of inner properties. Supports SQL-style sorting by multiple field names and directions.

import {arraySort, IArraySortSortingDirections} from '@ramster/general-tools'

const arrayToBeSorted = [
	{firstName: 'John', lastName: 'Doe'},
	{firstName: 'Jane', lastName: 'Doe'},
	{firstName: 'Peter', lastName: 'Parker'},
	{firstName: 'Peter', lastName: 'parker'}
]
const sortedArray = arraySort(
	arrayToBeSorted,
	[
		{direction: IArraySortSortingDirections.Ascending, fieldName: 'firstName'},
		{direction: IArraySortSortingDirections.Descending, fieldName: 'lastName'}
	],
	{caseSensitive: true}
)
// this will give us:
// [
//     {firstName: 'Jane', lastName: 'Doe'}
//     {firstName: 'John', lastName: 'Doe'}
//     {firstName: 'Peter', lastName: 'parker'}
//     {firstName: 'Peter', lastName: 'Parker'}
// ]
console.log(sortedArray)

Method parameters

IArraySortOrderBy details

IArraySortOptions details

changeKeyCase

Changes the case of all keys in an object or string and its children between loweCamelCase and UpperCamelCase, based on the provided map.

import {changeKeyCase} from '@ramster/general-tools'

const keyCaseMap = {ProductId: 'productId', UserId: 'userId'},
	inputObject = {ProductId: 10, UserId: 15},
	inputString = '?ProductId=10&UserId=15'

const ouputObject = changeKeyCase(inputObject, keyCaseMap),
	outputString = changeKeyCase(inputString, keyCaseMap)

// this will give us:
// {productId: 10, userId: 15}
console.log(outputObject)

// this will give us:
// '?productId=10&userId=15'
console.log(outputString)

Method parameters

checkRoutes

Changes the case of all keys in an object or string and its children between loweCamelCase and UpperCamelCase, based on the provided map.

import {checkRoutes} from '@ramster/general-tools'

const routes = [
	'/main',
	'/api/:component/list'
]
const firstResult = checkRoutes('/api/users/list', routes),
	secondResult = checkRoutes('/foo/bar', routes)
// this will give us:
// true
console.log(firstResult)

// this will give us:
// false
console.log(secondResult)

Method parameters

decodeQueryValues

Recursively performs decodeURIComponent on an object or value and returns the decoded object. Additionally, if an object is provided, any key that starts with "json" will be parsed using JSON.parse().

import {decodeQueryValues} from '@ramster/general-tools'

const inputObject = {
	foo: '%2Fbar',
	number: '15',
	boolean: 'true',
	_json_test: '{"key1": "value1", "key2": "35", "key3": "false"}'
}
const firstResult = decodeQueryValues(inputObject),
	secondResult = decodeQueryValues(inputObject, {castTrueAndFalseToBoolean: true, parseNumbersToFloat: true)
// this will give us:
// {
//     foo: '/bar',
//     number: '15',
//     boolean: 'true',
//     test: {
//         key1: 'value1',
//         key2: '35',
//         key3: 'false'
//     }
// }
console.log(firstResult)

// this will give us:
// {
//     foo: '/bar',
//     number: 15,
//     boolean: true,
//     test: {
//         key1: 'value1',
//         key2: 35,
//         key3: false
//     }
// }
console.log(secondResult)

Method parameters

IDecodeQueryValuesOptions details

emptyToNull

Takes an object or value and transforms undefined, null and empty strings to null. Recursively does so for objects without mutating the provided data.

import {emptyToNull} from '@ramster/general-tools'

// this will give us:
// {test: null, test3: null, test4: 'test'}
console.log(emptyToNull({test: null, test2: undefined, test3: '', test4: 'test'}))

Method parameters

findVertexInGraph

Finds a vertex in a graph, then returns it and its path in the form of an IFindVertexInGraphReturnData object (see the last table below for more info on this object).

import {findVertexInGraph, IFindVertexInGraphSearchTypes} from '@ramster/general-tools'

// this will give us:
// {pathToVertex: '0.children.10.children.15', vertex: {data: 't1'}}
console.log(
	findVertexInGraph(
		{
			0: {
				children: {
					10: {
						children: {
							15: {data: 't1'}
						},
						data: 'test'
					}
				},
				data: 't0'
			}
		}
	),
	15,
	{searchType: IFindVertexInGraphSearchTypes.DFS}
)

Method parameters

IFindVertexInGraphGraph details

IFindVertexInGraphGraphVertex details

IFindVertexInGraphOptions details

IFindVertexInGraphSearchTypes enum details

IFindVertexInGraphReturnData details

flattenObject

Takes a deeply nested object and flattens it into top-level key-value pairs. Particularly suitable for turning nested objects into get params.

import {flattenObject} from '@ramster/general-tools'

let result = flattenObject(
	{
		testKey: [{testKey1: 'test'}, date],
		testKey2: 'test test test',
		testKey3: {testKey4: [null, 'test', {tq: 11}]},
		testKey4: null
	}
)
// this will give us:
// [
// 	{key: 'testKey[][testKey1]', value: 'test'},
// 	{key: 'testKey[]', value: date.toString()},
// 	{key: 'testKey2', value: 'test test test'},
// 	{key: 'testKey3[testKey4][]', value: 'test'},
// 	{key: 'testKey3[testKey4][][tq]', value: 11}
// ]
console.log(result)

Method parameters

getNested

Extracts a value from a deeply nested object, for example foo.bar.0.baz from {foo: {bar: {baz: 'test'}}}.

import {getNested} from '@ramster/general-tools'

const inputObject = {
	foo: [
		{bar: 'test'},
		{bar: 'test2'},
		{bar: 'test'},
		{bar: 'test3'}
	]
}
const firstResult = getNested(inputObject, 'foo.0.bar'),
	secondResult = getNested(inputObject, 'foo.bar'),
	thirdResult = getNested(inputObject, 'foo.bar', {arrayItemsShouldBeUnique: true})
// this will give us:
// 'test'
console.log(firstResult)

// this will give us:
// ['test', 'test2', 'test', 'test3']
console.log(secondResult)

// this will give us:
// ['test', 'test2', 'test3']
console.log(thirdResult)

Method parameters

IGetNestedOptions details

setNested

Sets a value in a deeply nested object, for example foo.bar.0.baz in {foo: {bar: {baz: 'test'}}}.

import {setNested} from '@ramster/general-tools'

const inputObject = {
	foo: [
		{bar: 'test'},
		{bar: 'test2'},
		{bar: 'test'},
		{bar: 'test3'}
	]
}
const firstResult = setNested(inputObject, 'foo.0.bar', 'TEST'),
	secondResult = setNested(inputObject, 'foo.bar', 'TEST'),
	thirdResult = setNested(inputObject, 'foo.baz.bar', 'TEST')
// this will give us:
// true,
// {
//     foo: [
//         {bar: 'TEST'},
//         {bar: 'test2'},
//         {bar: 'test'},
//         {bar: 'test3'}
//     ]
// }
console.log(firstResult, inputObject)

// this will give us:
// true,
// {
//     foo: [
//         {bar: 'TEST'},
//         {bar: 'TEST'},
//         {bar: 'TEST'},
//         {bar: 'TEST'}
//     ]
// }
console.log(secondResult, inputObject)

// this will give us:
// false
console.log(thirdResult)

Method parameters

stringifyNestedObject

Takes a nested object and turns its non-Date, non-null object keys into stringified json keys, which can later be decoded by the decodeQueryValues method.

import {stringifyNestedObject} from '@ramster/general-tools'

let date = new Date()
let result = stringifyNestedObject(
	{
		testKey: [{testKey1: 'test'}, date],
		testKey2: 'test test test',
		testKey3: {testKey4: [null, 'test', {tq: 11}]}
	}
)
// this will give us:
// {
// 	_json_testKey: '[{"testKey1":"test"},"2020-05-20T09:20:55.327Z"]',
// 	testKey2: 'test test test',
// 	_json_testKey3: '{"testKey4":[null,"test",{"tq":11}]}'
// }
console.log(result)

Method parameters