logdnastdlib
Standardized modular package exposing language constructs - free of business logic.
Main Goals
- Free of business logic
- Consistent api
- Explicitness
- Lacking in dependencies
- Lacking indirection
- Highly debuggable
- Highly testable
Installation
> npm install @logdna/stdlib- stdlib
- Main Goals
- Installation
- API
- array
- iter
- json
- object
has(obj: Object, property: String [, separator: String = '.']): Booleanget(obj: Object, property: String [, separator: String = '.']): anyset(obj: Object, property: String, value:any[, separator: String = '.' ]): Objectfilter(obj: Object, test: Function): Objecttypecast(obj: Object [, depth: Number = 1000]): Object
- string
typeOf(element:any): StringCallable: Class- path
- Authors
- Contributors ✨
API
array
Common array manipulation functions
toArray(item: any): Array
Converts or wraps anything in an array. Set objects will be converted to arrays. A String will be treated as a CSV and parsed into an array. If an array cannont be coerced from the input value, it will be wrapped in an a single element array
Arguments:
item- The element to convert to an array.
returns result Array: The resulting array for input coercion
Example
const {array} = require('@logdna/stdlib')
array.toArray() // []
array.toArray(null) // []
array.toArray(1) // [1]
array.toArray('1,2, 4, 3') // [1, 2, 4, 3]iter
Iteration tools for complex and efficient iteration. Inspired by python's itertools
cycle(items: Array): Generator
Iterates endlessly over a single array of items. The elements of the array can be of any type.
Arguments:
items(Array) - An array to iterate over
returns Generator A generator object containing the passed in elements
Example
const {iter} = require('@logdna/stdlib')
const numbers = iter.cycle([1, 2, 3])
numbers.next().value // 1
numbers.next().value // 2
numbers.next().value // 3
numbers.next().value // 1
numbers.next().value // 2
numbers.next().value // 3json
Common json functions
parse(input: String): Object
Safe json parsing function that attempts to json parse a string. If it cannont, undefined will be returned
Arguments
input(String) - a json string to parse
returns Object A fully parsed javascript object
Example
const {json} = require('@logdna/stdlib')
json.parse('{"valid": "json"}') // {valid: 'json'}
json.parse('{"invalid" json') // undefinedobject
Common object manipulation and intropsection functions
has(obj: Object, property: String [, separator: String = '.']): Boolean
Determines if a specified key is a direct property of an object. This function is safe
to call on objects that do not inherit from Object.prototype, unlike attempting to call .hasOwnProperty
on input objects
Arguments
obj(Object) - The object to introspectkey(String) - The name of the property to locate- (optional)
separator(String) - Delimiter character- default:
'.'
- default:
returns Boolean - True of the key is defined on the input object.
Example
const {object} = require('@logdna/stdlib')
object.has({a: 1}, 'a') // true
object.has({}, 'test') // false
object.has(Object.create(null), 'test') // false
object.has({}, 'hasOwnProperty') // false
object.has({one: {two: {three: 3}}}, 'one-two-three', '-') // trueget(obj: Object, property: String [, separator: String = '.']): any
Returns the value from an object at a specified object path.
Arguments
obj(Object) - The object to introspectkey(String) - The name of the property to local- (optional)
separator(String) - Delimiter character- default:
'.'
- default:
returns any - The value at the specified key. If no value is found, undefined will be returned.
Example
const {object} = require('@logdna/stdlib')
const obj = {one: {two: {three: 3}}}
const value = object.get(obj, 'one-two-three', '-') // 3set(obj: Object, property: String, value: any [, separator: String = '.' ]): Object
Sets a property at the deepest level. Nested objects will be created if they do not exist. Returns the modified object. This will not work on complex Types like arrays or maps; Only POJOs.
NOTE: if you find your self wanting to set the value at a specific index of an array - you probably want an object.
Arguments
obj(Object) - The object to introspectkey(String) - The name of the property to localvalue(any) - The value to set at the specified path- (optional)
separator(String) - Delimiter character- default:
'.'
- default:
Example
const {object} = require('@logdna/stdlib')
const obj = {one: {two: {three: 3}}}
const value = object.set(obj, 'four.five', 6)
// {one: { two: three: 3 }, four: {five: 6}}filter(obj: Object, test: Function): Object
Similar to array.filter, removes keys from an input object that do not pass the
test function
Arguments
obj(Object) - The object to introspecttest(Function) - The function to be used to reject keys from the input object. If this function returns atruthyvalue, the key will be included in the final output. Iffalseyit will be excluded
Example
const {object} = require('@logdna/stdlib')
const obj = {one: { two: three: 3 } }
object.filter({two: 2, three: 3}, (key) => {
return key.match(/ee$/)
}) // {three: 3}returns Object An object containing only the keys which passed the test function.
typecast(obj: Object [, depth: Number = 1000]): Object
Recursively typecast string values of enumerable object properties,
using string.typecast()
Arguments
returns Object A new object with all string properties typecast.
Example
const {object} = require('@logdna/stdlib')
const obj = {foo: '1', bar: 'null', baz: 'three', qux: {foo: '2'}}
const casted = typecast(obj)
// {foo: 1, bar: null, baz: 'three', qux: {foo: 2}}
const with_depth = typecast(obj, 0)
// {foo: 1, bar: null, baz: 'three', qux: {foo: '2'}}string
camelcase(text: String): String
Casts a string value to its camel case variant
Arguments
strString - The string value to convert
returns String A camelcase version of the input string
Example
const {string} = require('@logdna/stdlib')
string.camelcase('Hello George Washington') // helloGeorgeWashingtonlowercase(text: String): String
A safe alternative to String.prototype.toLowerCase(). This can be called non string inputs and they will be converted to string prior to lower casing.
Arguments
strString - The string value to convert
returns String A lowercased version of the input string
Example
const {string} = require('@logdna/stdlib')
string.lowercase('Hello George Washington') // hello george washington
string.lowercase({}) // [object object]
string.lowercase(null) // ''
string.lowercase(undefined) // ''uppercase(text: String): String
A safe alternative to String.prototype.toUpperCase(). This can be called non string inputs and they will be converted to string prior to upper casing.
Arguments
strString - The string value to convert
returns String A uppercased version of the input string
Example
const {string} = require('@logdna/stdlib')
string.uppercase('Hello George Washington') // HELLO GEORGE WASHINGTON
string.uppercase({}) // [OBJECT OBJECT]
string.uppercase(null) // ''
string.uppercase(undefined) // ''slugify(text: String [, separator: String = '-']): String
Converts a string to a url friendly format by replacing spaces and symbols with a known value and converting to lower case
Arguments
strString - The string value to convert- (optional)
separator(String) - Delimiter character- default:
'-'
- default:
returns String A slugified version of the input string
Example
const {string} = require('@logdna/stdlib')
string.slugify('A fake Sentence') // a-fake-sentence
string.slugify('A fake Sentence', '::') // a::fake::sentencetypecast(text: String): Object
Best effort to cast a string to its native couter part where possible. Supported casts are booleans, numbers, null and undefined.
Arguments
value- The value to cast
returns The native representation of the string input. If the value could not be cast, it will be returned as it was passed.
Example
const {string} = require('@logdna/stdlib')
string.typecast('null') // null
string.typecast('true') // true
string.typecast('10.01') // 10.01
string.typecast({}) // {}typeOf(element: any): String
A more accurate version of the javascript built-in function typeof
Arguments
input- The input object to introspect
returns String A normalized string representation of the input object
Example
const {typeOf} = require('@logdna/stdlib')
typeOf(new Date()) // 'date'
typeOf(/\w+/) // regexp
typeOf(() => {}) // function
typeOf(new Set()) // setCallable: Class
A class object whose instances are derived from Function and can be called.
When exteded, a Symbol function defined by Symbol.for('call') will be executed
with any arguments that were passed
Example
const {Callable} = require('@logdna/stdlib')
const __call__ = Symbol.for('call')
class Hello extends Callable {
constructor(opts) {
this.yell = !!opts.yell
}
[__call__](name) {
const output = `Hello, ${name}`
console.log(this.yell ? `${output.toUpperCase()}!` : output)
}
}
const screamAt = new Hello({yell: true})
screamAt('bill') // HELLO, BILL!path
moduleId(location: String [, root: String = process.cwd(), sep: String = ':']): String
Returns the path from root to the module at location, separated by sep.
Arguments
location(String) - The module's location, typically__filename- (optional)
root(String) - The root directory to find the relative path tolocationfrom- default:
process.cwd()
- default:
- (optional)
separator(String) - Delimiter character- default:
':'
- default:
Example
const {path} = require(@logdna/stdlib)
const my_module = path.moduleId(__filename)
// e.g. lib:my-module
const pipe_delimited_module = path.moduleId(__filename, __dirname, '|')
// e.g. lib|my-moduleAuthors
Contributors ✨
Thanks goes to these wonderful people (emoji key):
 Darin Spivey 💻 👀 ⚠️ 📖 |
 Eric Satterwhite 💻 👀 ⚠️ 📖 |
 Jon Moses 📖 🐛 |
 Mike Del Tito 💻 👀 ⚠️ 📖 |
 Samir Musali 💻 |
 Wei Zou 💻 👀 ⚠️ 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!