a-toolbox
javascript lightweight basic tools for node.js and browser
Purpose
"This is my rifle. There are many others like it, but this one is mine."
Install
npm i a-toolbox --save
Quick start
const tools = require('a-toolbox')
tools.string.trim('({cut these brackets please)}', ['{', '}', '(', ')'])
modular import
const tools = {
string: require('a-toolbox/string'),
fs: require('a-toolbox/fs')
}
On browser
<script src="node_modules/a-toolbox/dist/atoolbox.min.js"></script>
<script>
var data = {
name: 'Alice',
year: 2014,
color: 'purple'
};
var str = '<div>My name is {name} I was born in {year} and my favourite color is {color}</div>{nothing}';
console.log('template:', tools.string.template(str, data));
</script>
API
array
array.remove(array, item)
remove an element from array
it removes only the first occurrence
Example
let a = ['js','ruby','python']
tools.array.remove(a, 'ruby')
array.removeAt(array, index)
- array <Array<*>>
- index <number>
remove an element from array at position
Example
let a = [1,2,3]
tools.array.removeAt(a, 0)
array.last(array)
- array <Array<*>>
- return: * last element of the array or undefined
get last element of array or undefined
Example
tools.array.last([1,2,3])
array.at(array)
- array <Array<*>>
- return: * nth element of array; if negative, start from end: -1 = last element; undefined if missing
get nth element of array
Example
tools.array.at([1,2,3], 0)
array.first(array)
- array <Array<*>>
- return: * first element of the array or undefined
get first element of array or undefined
Example
tools.array.first([1,2,3])
array.contains(array, item)
- array <Array<*>>
- item <*>
- return: boolean
check if array contains an element
Example
tools.array.contains([1,2,3], 1)
array.insert(array, index, item)
- array <Array<*>>
- index <number>
- item <*>
insert an item into array at index position
Example
let a = ['john','alice','bob']
tools.array.insert(a, 0, 'mary')
array.concat(arrays)
- arrays <...Array<*>> to chain
- return: Array<*> chained arrays
concat arrays
Example
tools.array.concat([0,1,2],[3,4,5])
array.empty()
empty array - need to keep references
Example
let a = [0,1,2]
tools.array.empty(a)
array.add(array, item, [unique=false])
- array <Array<*>>
- item <*>
- [unique=false] <boolean>
push item into array, optionally check if already exists
Example
let a = [0,1,2,3]
tools.array.add(a, 3, true)
array.flat(array)
- array <Array<*>>
- return: Array<*> flatten array
creates a new array with all sub-array elements concatted into it recursively like Array.prototype.flatten()
Example
let a = [0,[1,2],[3]] >
tools.array.flat(a)
array.sortingInsert(array_, item)
- array_ <Array<*>>
- item <*>
insert an element in a sorted array, keeping sorted
Example
let a = [0,1,2,10,11,20]
tools.array.sortingInsert(a, 15)
array.binaryIndexOf(array, item)
Example
tools.array.binaryIndexOf([0,1,2,3], 0)
fs
note: not available on browser
fs.exists(path)
- path <string> path
- return: Promise.<boolean> true if file or directory exists
replace deprecated fs.exists
Example
tools.fs.exists('/tmp/file')
fs.isFile(path)
- path <string> file path
- return: Promise.<boolean> true if it exists and is a file
Example
tools.fs.isFile('/tmp/file')
fs.isDirectory(path)
- path <string> dir path
- return: Promise.<boolean> true if it exists and is a dir
Example
tools.fs.isDirectory('/tmp')
fs.touch(path, [mode=0o666])
- path <string> file path
- [mode=0o666] <number>
- return: Promise.<void>
create an empty file if not exists
Example
tools.fs.touch('/tmp/touch-me')
fs.unlink(path, [safe=true])
- path <string> file path
- [safe=true] <boolean> if safe do not throw exception
- return: Promise.<void>
delete file, optionally in safe mode
Example
tools.fs.unlink('/tmp/file')
hash
hash.sha256(data)
- data <string> any string
- return: string sha256 in hex format
Generate hash using sha256 in hex format
Example
tools.hash.sha256('usk6fgbuygbu6')
object
object.flat(obj)
- obj <Object>
- return: Object
flat keys in object
Example
tools.object.flat({ a: { a1: 1, a2: 2 }, b: 3 })
object.merge(a, b)
merge b into a
Example
let a = {a:1,b:'ciao'}
tools.object.merge(a, {a:4,c:{d:8,e:9}})
object.clone(obj)
- obj <Object|Array> The array or the object to clone
- return: Object|Array
Clone an array or an object in input
Example
tools.object.clone({a: 1, b: 'ciao'})
object.getKeys(obj)
-
obj <Object>
-
return: Array<string>
Example
tools.object.getKeys({a: () => { }, b: 1, c: 'ciao'})
object.inherits(destination, source)
- destination <Object>
- source <Object>
it use Object.getOwnPropertyNames
to inherits child from parent, without prototype
Example
let a = {}
tools.object.inherits(a, {f0:() => { },p1:1,p2:'ciao'})
object.empty(obj)
empty object - need to keep references
Example
let a = {a:0,b:1,c:2,d:[],e:{f:-1}}
tools.object.empty(a)
object.raise(flat)
- flat <Object>
- return: Object
restore flat object
Example
tools.object.raise({ 'a.a1': 1, 'a.a2': 2, 'b': 3 })
object.getByFlatKey(obj, fkey)
- obj <Object>
- fkey <string>
- return: Object
get value in object using a flat key
Example
tools.object.getByFlatKey({ a: { b: {c: 1} } }, 'a.b.c')
tools.object.getByFlatKey({ a: { b: [{c: 1}] } }, 'a.b[0].c')
object.setByFlatKey(obj, fkey, val)
- obj <Object>
- fkey <string>
- val <*>
set value in object using a flat key
Example
let a = {}
tools.object.setByFlatKey(a, 'a.b.c', 1)
let a = {}
tools.object.setByFlatKey(a, 'a.b[0].c', 1)
util
util.isSet(val)
check if val
is setted, means it's not null
or undefined
util.onBrowser()
check if you are on browser or not
string
string.template(str, obj, [remove=false])
- str <string>
- obj <Object>
- [remove=false] <boolean> remove missing placeholders from obj, default false
- return: string
replace placeholders inside graph brackets {} with obj dictionary
~ES6 template string without $
Example
tools.string.template('hi {name} how are you?', {name: 'Alice'})
string.trim(str, cuts)
- str <string>
- cuts <Array>
- return: string
trim string
Example
tools.string.trim(' regular trim ')
string.replaceAll(str, from, to)
- str <string>
- from <string>
- to <string>
- return: string
Example
tools.string.replaceAll('abcadaeafaga', 'a', '')
string.capitalize(str)
-
str <string>
-
return: string
Example
tools.string.capitalize('alice')
string.prependMissing(prefix, str)
-
prefix <string>
-
str <string>
-
return: string
Example
tools.string.prependMissing('miss ', 'Alice')
random
random.rnd(max)
- max <number>
- return: number
get random int from 0 to max
Example
tools.random.rnd(10)
random.number(min, max)
- min <number>
- max <number>
- return: number
get random int from min to max
Example
tools.random.number(10, 20)
random.string([length=8], [set=abcdefghijklmnopqrstuvwxyz])
- [length=8] <number>
- [set=abcdefghijklmnopqrstuvwxyz] <Array>
- return: string
get random string
Example
tools.random.string(8)
random.hex([length=8])
- [length=8] <number>
- return: string
get random hex string
Example
tools.random.hex(8)
random.hash(salt)
- salt <?string>
- return: string
get random hash string
Example
tools.random.hash()
random.element(array, not)
- array <Array<*>>
- not <Array<*>>
- return: * element
get random element from array
Example
tools.random.element([1,2,3,4,5])
sys
note: not available on browser
sys.isRoot()
- return: bool is root or not
check if running user is root
time
time.chrono.set([tag=chrono])
start a timer identified by tag
Example
tools.time.chrono.set('query')
time.chrono.reset([tag=chrono])
reset the timer identified by tag
Example
tools.time.chrono.reset('query')
time.chrono.clear([tag=chrono])
discard the timer identified by tag
Example
tools.time.chrono.clear('query')
time.chrono.get([tag=chrono])
- [tag=chrono] <string>
- return: number ms
get the timer in ms from start (or reset) identified by tag
Example
tools.time.chrono.get('query')
time.gc()
clear timers (if you care about memory)
task
class task.Worker(options)
- options <Object>
- options.done <function> callback when all tasks are completed
simple parallel tasks manager
Example
const tasks = new tools.task.Worker({done: () => { console.log('well done') }})
const _asyncOperationTimeout = [500, 1000, 200, 1500, 100];
for (const i in _asyncOperationTimeout) {
_tasks.todo('task#' + i);
}
for (const i in _asyncOperationTimeout) {
setTimeout(function (i) {
return function () {
console.log('done task #', i);
_tasks.done('task#' + i);
};
}(i), _asyncOperationTimeout[i]);
}
Worker.todo()
add task
Example
tasks.todo('task#1')
Worker.done()
declare task it's done
Example
tasks.todo('task#1')
event
class event.Emitter()
simple event emitter
Example
const emitter = new tools.event.Emitter()
emitter.on('event#0', (value0, value1) => {
console.log('event #0 happened with', value0, value1)
})
emitter.once('event#0', (value0, value1) => {
console.log('event #0 happened (once) with', value0, value1)
})
emitter.emit('event#0', 1, 2)
emitter.emit('event#0', 3, 4)
emitter.off('event#0')
Emitter.emit(name, ...values)
- name <string> event name
- ...values <*> values to pass to the event listener
emit an event
Example
event.emit('event#0', 'a value', 99, {another: 'VALUE'})
Emitter.on(name, callback)
- name <string> event name
- callback <function>
listen to an event
Example
emitter.on('event#0', (value0, value1) => {
console.log('event #0 happened (once) with', value0, value1)
})
Emitter.once(name, callback)
- name <string> event name
- callback <function>
listen to an event only once
Example
emitter.once('event#0', (value0, value1) => {
console.log('event #0 happened (once) with', value0, value1)
})
Emitter.off(name)
stop listening to an event
Example
emitter.off('event#0')
Changelog
v. 1.7.2
- add
object.getByFlatKey
support also Array
v. 1.7.1
- add
fs.isFile
and fs.isDirectory
v. 1.6.2
fs.exists
return true on files and directories, instead of only files
v. 1.5.1
string.template
support multi-level syntax object
v. 1.5.1
object.setByFlatKey
support also Array
v. 1.5.0
- add
event.Emitter
(simple event emitter, for browser)
v. 1.2.0
- use hash.js instead of
crypto
(for browser)
v. 1.0.0
- general review
- modular loader
- browser version
TODO
License
The MIT License (MIT)
Copyright (c) 2015-2019, braces lab
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.