sxy-standard - JS Standard Library

yarn add sxy-standard

to import all core functions:
import 'sxy-standard'
to import everything functions:
import 'sxy-standard/all'

--pure ( The functions changes no data, only returning a result, and will give the same result every time with the same set of arguments )
--no-side-effects ( The functions changes no data, only returning a result, but may not give the same result each time with the same set of arguments )
--side-effects ( )
--deterministic ( )
--non-deterministic ( )

Objects

to import only object functions:
import 'sxy-standard/objects.js'

#### Object.map

--pure
Map an object to a new object. Keys are preserved. See Array.prototype.map

In: object, function(key, value, orginialObject) => newValue
Out: object

Object.map( { a: 1, b: 3 }, (key, value) => value * 3 ) )
// returns { a: 3, b: 9 }

#### Object.remap

--pure
Map an object to a new object, with the ability to change keys.

In: object, function(key, value, orginialObject) => [newKey, neyValue]
Out: object

Object.map( { a: 1, b: 3 }, (key, value) => [key + key, value * 3] ) )
// returns { aa: 3, bb: 9 }

#### Object.reduce

--pure
Reduce an object into a single value or item. See Array.prototype.reduce

In: object, function(key, value, orginialObject) => compositeValue, initialCompositeValue
Out: "compositeValue" as returned by the function

Object.reduce( { a: 1, b: 3 }, (composite, key, value) => composite + value ), 0 )
// returns 4

#### Object.forEach

--pure
Run a function for each item in the object. Note that the key and value arguments passed to the callback are in the opposite order. Think of arrays as being value orientied, but key being important in objects. See Array.prototype.forEach

Note: I recommend using Assoc instead. This has the benefit of avoiding confusion over argument ordering.

In: object, function(key, value, originalObject) => void
Out: void

Object.forEach( { a: 1, b: 3 }, (key, value) => console.log(${key}: ${value}) )
// logs:
// a: 1
// b: 33

#### Object.copy

--pure
Alias to lodash.cloneDeep. Clones the object including deep objects. This allows truly coping an object where a tool like the spread operator would fail due to only copying the first level of childrens, while inheriting references to the original inner contents. See https://lodash.com/docs/4.17.15#cloneDeep

Object.clone exists as an alias for Object.copy
Object.deepClone exists as an alias for Object.copy

Object.clone( { a: 1, b: 3 } )
// returns a new object { a: 1, b: 3 }
// see the description above for more information

Assoc

to import only Assoc:
import 'sxy-standard/assoc.js'

Assoc is a class of iterable object / associative array.
It is identical to an ordinary object, except that it can be iterated with for ... of ...

const assoc = new Assoc({ a: 1, b: 3 })

for (const key of assoc) { console.log(key) }
// logs
// a
// b

for (const [key, value] of assoc) { console.log(${key}: ${value}) }
// logs
// a: 1
// b: 3

Compared to Object.entries()

const assoc = new Assoc({ a: 1, b: 3 })
for (const [key, value] of assoc)

is equivalent to:

const obj = { a: 1, b: 3 }
for (const [key, value] of Object.entries(obj))

Promises

to import only object functions:
import 'sxy-standard/promises.js'

#### Promise.allObj

--pure ( the promises passed may not be )
Return a promise that resolves when all promises passed complete, and returns an object populated with the results paired to the keys of the original promise object. See Promise.all

In: object { key: promise, ... },
Out: object { key: promiseResult, ... }

const promiseA = new Promise( (resolve) => setTimeout(() => resolve(1), 1000) )
const promiseB = new Promise( (resolve) => setTimeout(() => resolve(3), 2000) )
Promise.allObj( { a: promiseA, b: promiseB }, ).then ( results => / do something / )
// After 2 seconds the promise will complete and results will be { a: 1, b: 3 }

Utils

to import only util functions:
import 'sxy-standard/utils.js'

#### sxy.calledFrom

--pure
Retuns the file location where the current script/function was called/loaded from.
Functions passed in ignoredFunctions are ignored (if the current script/function was called from that function, calledFrom() will continue to find the previous call location).
If passed, the number of calls specified in skip will be skipped, returning an earlier call location. Functions excluded in ignoredFunctions are not counted as skipped. Skipped calls are additional.

In: object { ignoredFunctions?: [function, ...], skip?: int }
Out:
sxy.calledFrom()

/extra - Extra Functions

yarn add sxy-standard

to import all extras:
import 'sxy-standard/extra'

Extra / Web

to import only extra/web functions:
import 'sxy-standard/extra/web.js'

#### sxy.standardizeWebPath

--pure
Takes a web path such as /home/ and standardizes it. Leading slashes are added, trailing slashes are removed

In: string
Out: string

'' -> '/'
'/' -> '/'
'//' -> '/'
'///' -> '//' ( ! )
'/home/' -> '/home'
'index.html' -> '/index.html'