stdlib

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
    • toArray(item: any): Array
      • Example
  • iter
    • cycle(items: Array): Generator
      • Example
  • json
    • parse(input: String): Object
      • Example
  • object
    • has(obj: Object, property: String [, separator: String = '.']): Boolean
      • Example
    • get(obj: Object, property: String [, separator: String = '.']): any
      • Example
    • set(obj: Object, property: String, value: any [, separator: String = '.' ]): Object
      • Example
    • filter(obj: Object, test: Function): Object
      • Example
    • typecast(obj: Object [, depth: Number = 1000]): Object
      • Example
  • string
    • camelcase(text: String): String
      • Example
    • lowercase(text: String): String
      • Example
    • uppercase(text: String): String
      • Example
    • slugify(text: String [, separator: String = '-']): String
      • Example
    • typecast(text: String): Object
      • Example
  • typeOf(element: any): String
    • Example
  • Callable: Class
    • Example
• 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 // 3

json

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') // undefined

object

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 introspect
• key (String) - The name of the property to locate
• (optional) separator (String) - Delimiter character
  • 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', '-') // true

get(obj: Object, property: String [, separator: String = '.']): any

Returns the value from an object at a specified object path.

Arguments

• obj (Object) - The object to introspect
• key (String) - The name of the property to local
• (optional) separator (String) - Delimiter character
  • 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', '-') // 3

set(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 introspect
• key (String) - The name of the property to local
• value (any) - The value to set at the specified path
• (optional) separator (String) - Delimiter character
  • 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 introspect
• test (Function) - The function to be used to reject keys from the input object. If this function returns a truthy value, the key will be included in the final output. If falsey it 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

• obj (Object) - The input object
• key (Number) - The maximum depth to recursively typecast

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

• str String - 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') // helloGeorgeWashington

lowercase(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

• str String - 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

• str String - 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

• str String - The string value to convert
• (optional) separator (String) - Delimiter character
  • 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::sentence

typecast(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()) // set

Callable: 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!

Authors

• Eric Satterwhite <[email protected]>

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!