flocky

A TypeScript and JavaScript utility library with clarity and efficiency at the core. 0 dependencies.

Installation • Usage • API Reference • Contributors • License

Installation

# Using `yarn`
yarn add flocky

# Using `npm`
npm install --save flocky

Import

// Importing the full library (tree shakable!)
import * as flocky from 'flocky'
flocky.sum([1, 2, 3])

// Importing the full library, with a named import (tree shakable!)
import { sum } from 'flocky'
sum([1, 2, 3])

// Importing only part of the library (in case you are not using tree shaking)
import { sum } from 'flocky/sum'
import sum from 'flocky/sum'
sum([1, 2, 3])

// /!\ Note that the following is NOT allowed (because it does not create tree shakable bundles)
// import flocky from 'flocky'

// Importing the full library (tree shakable!)
import * as flocky from 'flocky'
flocky.sum([1, 2, 3])

// Importing the full library, with a named import (tree shakable!)
import { sum } from 'flocky'
sum([1, 2, 3])

// Importing only part of the library (in case you are not using tree shaking)
import { sum } from 'flocky/es6/sum'
import sum from 'flocky/es6/sum'
sum([1, 2, 3])

// /!\ Note that the following is NOT allowed (because it does not create tree shakable bundles)
// import flocky from 'flocky'

// Importing the full library
const flocky = require('flocky')
flocky.sum([1, 2, 3])

// Importing the full library, with a named import
const { sum } = require('flocky')
sum([1, 2, 3])

// Importing only part of the library
const sum = require('flocky/sum')
const { sum } = require('flocky/sum')
sum([1, 2, 3])

API Reference

average(array)

Compute the average of the values in an array.

flocky.average([1, 4, 2, -4, 0])
// -> 0.6

^{Source • Minify: 106 B • Minify & GZIP: 87 B}

chunk(array, size)

Split an array of elements into groups of size. If the array can't be split evenly, the final chunk will contain the remaining elements.

flocky.chunk([1, 2, 3, 4, 5, 6, 7], 3)
// -> [[1, 2, 3], [4, 5, 6], [7]]

^{Source • Minify: 113 B • Minify & GZIP: 105 B}

clone(value)

Create a deep clone of value. This method only supports types native to JSON, so all primitive types, arrays and objects.

const original = [{ a: 1 }, { b: 2 }]
const clone = flocky.clone(original)
original[0] === clone[0]
// -> false

^{Source • Minify: 83 B • Minify & GZIP: 78 B}

compact(array)

Create an array with all falsy (undefined, null, false, 0, NaN, '') values removed.

flocky.compact([1, 2, 3, null, 4, false, 0, NaN, 5, ''])
// -> [1, 2, 3, 4, 5]

^{Source • Minify: 75 B • Minify & GZIP: 73 B}

debounce(func, wait)

Creates a debounced function that delays invoking func until wait milliseconds have elapsed since the last time the debounced function was invoked.

const func = () => console.log('Heavy processing happening')
const debouncedFunc = flocky.debounce(func, 250)

^{Source • Minify: 225 B • Minify & GZIP: 160 B}

duplicates(array, identity?)

Create a version of an array, in which only the duplicated elements are kept. The order of result values is determined by the order they occur in the array. Can be passed an optional identity function to select the identifying part of objects.

flocky.duplicates([1, 1, 2, 4, 2, 1, 6])
// -> [1, 2, 1]

flocky.duplicates(['foo', 'bar', 'foo', 'foobar'])
// -> ['foo']

const input = [{ id: 1, a: 1 }, { id: 1, a: 2 }, { id: 2, a: 3 }, { id: 1, a: 4 }]
flocky.duplicates(input, (element) => element.id)
// -> [{ id: 1, a: 2 }, { id: 1, a: 4 }]

^{Source • Minify: 336 B • Minify & GZIP: 156 B}

escapeRegExp(string)

Escapes special characters in a string for use in a regular expression.

flocky.escapeRegExp('Hey. (1 + 1 = 2)')
// -> 'Hey\\. \\(1 \\+ 1 = 2\\)'

^{Source • Minify: 107 B • Minify & GZIP: 99 B}

get(object, path, defaultValue?)

Get the value at a path of an object (with an optional defaultValue)

Using this method will ignore type information, and you will have to type the return type yourself. If you can, it is always better to access properties directly, for example with the "optional chaining" operator.

const object = {a: {b: {c: 1}}}
flocky.get(object, 'a.b.c')
// -> 1

const object = {a: {b: {c: 1}}}
flocky.get(object, 'x.x.x')
// -> undefined

const object = {a: {b: {c: 1}}}
flocky.get(object, 'x.x.x', 'default')
// -> 'default'

^{Source • Benchmark • Minify: 403 B • Minify & GZIP: 264 B}

hash(data)

Create a hashed string representation of the passed in data.

This function is not cryptographically secure, use bcrypt for anything security related.

flocky.hash('some really long string')
// -> 'x1nr7uiv'

flocky.hash({id: 'AAA', name: 'BBB'})
// -> 'x16mynva'

^{Source • Benchmark • Minify: 538 B • Minify & GZIP: 333 B}

identifier()

Generate a random identifier with UUID v4 format.

flocky.identifier()
// -> 'bfc8d57e-b9ab-4245-836e-d1fd99602e30'

^{Source • Minify: 270 B • Minify & GZIP: 197 B}

matchAll(regExp, string)

Find all matches of a regular expression in a string.

flocky.matchAll(/f(o+)/g, 'foo bar baz foooo bar')
// -> [
// ->   { match: 'foo', subMatches: ['oo'], index: 0 },
// ->   { match: 'foooo', subMatches: ['oooo'], index: 12 },
// -> ]

^{Source • Minify: 192 B • Minify & GZIP: 139 B}

max(array)

Compute the maximum of the values in an array.

flocky.max([1, 4, 2, -3, 0])
// -> 4

^{Source • Minify: 72 B • Minify & GZIP: 73 B}

memoize(func, options?)

Creates a function that memoizes the result of func.

const func = (a, b) => a + b
const memoizedFunc = flocky.memoize(func)
const memoizedFuncWithTtl = flocky.memoize(func, { ttl: 30 * 1000 })

^{Source • Benchmark • Minify: 979 B • Minify & GZIP: 466 B}

min(array)

Compute the minimum of the values in an array.

flocky.min([1, 4, 2, -3, 0])
// -> -3

^{Source • Minify: 72 B • Minify & GZIP: 73 B}

omit(object, keys)

Create an object composed of all existing keys that are not specified in keys.

const object = { a: 1, b: 2, c: 3 }
flocky.omit(object, ['a'])
// -> { b: 2, c: 3 }

^{Source • Benchmark • Minify: 145 B • Minify & GZIP: 130 B}

pick(object, keys)

Create an object composed of the specified keys.

const object = { a: 1, b: 2, c: 3 }
flocky.pick(object, ['a', 'c'])
// -> { a: 1, c: 3 }

^{Source • Minify: 100 B • Minify & GZIP: 93 B}

random(lower, upper, float?)

Generate a random number between lower and upper (inclusive). If float is true or lower or upper is a float, a float is returned instead of an integer.

flocky.random(1, 10)
// -> 8

flocky.random(1, 20, true)
// -> 14.94849340769861

flocky.random(2.5, 3.5)
// -> 3.2341312319841373

^{Source • Minify: 233 B • Minify & GZIP: 135 B}

randomString(length)

Generate a random alphanumeric string with length length.

flocky.randomString(5)
// -> 'tfl0g'

^{Source • Minify: 251 B • Minify & GZIP: 210 B}

roundTo(number, precision)

Round a floating point number to precision decimal places.

flocky.roundTo(3.141592653589, 4)
// -> 3.1416

flocky.roundTo(1.005, 2)
// -> 1.01

flocky.roundTo(1111.1, -2)
// -> 1100

^{Source • Minify: 228 B • Minify & GZIP: 156 B}

sample(array)

Get a random element from the array.

flocky.sample([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
// -> 8

^{Source • Minify: 93 B • Minify & GZIP: 89 B}

shuffle(array)

Create an array of shuffled values, using a version of the Fisher-Yates shuffle.

flocky.shuffle([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
// -> [3, 7, 2, 1, 10, 4, 6, 9, 5, 8]

^{Source • Minify: 164 B • Minify & GZIP: 137 B}

sleep(ms)

Return a promise that waits for ms milliseconds before resolving.

async flocky.sleep(25)

^{Source • Minify: 104 B • Minify & GZIP: 89 B}

slugify(string)

Generate a URL-safe slug of a string.

flocky.slugify(' Issue #123 is _important_! :)')
// -> 'issue-123-is-important'

^{Source • Minify: 128 B • Minify & GZIP: 114 B}

sum(array)

Compute the sum of the values in an array.

flocky.sum([1, 4, 2, -4, 0])
// -> 3

^{Source • Minify: 89 B • Minify & GZIP: 77 B}

toMap(array, key, target?)

Create a lookup map out of an array of objects, with a lookup key and an optional target.

flocky.toMap(
  [
    { id: 1, name: 'Stanley', age: 64 },
    { id: 2, name: 'Juliet', age: 57 },
    { id: 3, name: 'Alex', age: 19 }
  ],
  'id'
)
// -> {
// ->   1: { id: 1, name: 'Stanley', age: 64 },
// ->   2: { id: 2, name: 'Juliet', age: 57 },
// ->   3: { id: 3, name: 'Alex', age: 19 }
// -> }

flocky.toMap(
  [
    { id: 1, name: 'Stanley', age: 64 },
    { id: 2, name: 'Juliet', age: 57 },
    { id: 3, name: 'Alex', age: 19 }
  ],
  'name',
  'age'
)
// -> { Stanley: 64, Juliet: 57, Alex: 19 }

^{Source • Minify: 94 B • Minify & GZIP: 92 B}

unique(array, identity?)

Create a duplicate-free version of an array, in which only the first occurrence of each element is kept. The order of result values is determined by the order they occur in the array. Can be passed an optional identity function to select the identifying part of objects.

flocky.unique([1, 1, 2, 4, 2, 1, 6])
// -> [1, 2, 4, 6]

flocky.unique(['foo', 'bar', 'foo', 'foobar'])
// -> ['foo', 'bar', 'foobar']

const input = [{ id: 1, a: 1 }, { id: 1, a: 2 }, { id: 2, a: 3 }, { id: 1, a: 4 }]
flocky.unique(input, (element) => element.id)
// -> [{ id: 1, a: 1 }, { id: 2, a: 3 }]

^{Source • Benchmark • Minify: 282 B • Minify & GZIP: 158 B}

Contributors

Thanks goes to these wonderful people (emoji key):

David Reeß

Jeff Hage

darthmaim

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

License

MIT