supergeneric

3.0.1 • Public • Published

supergeneric

Just a collection of my favorite bespoke functions that I manage to work into nearly every project. Added to NPM for my convenience (and yours, if you happen to use it)!

Importing

```import { sum } from 'supergeneric'

// or for the tree-shaking minimalists...
import { sum } from 'supergeneric/sum'```

Migrating from v1.x to v2.x

Previously, functions were grouped into collections, such as `import { sum } from 'supergeneric/math'`. This is no longer the case. All functions are named exports from the base module, or may be referenced directly by name (e.g. "supergeneric/sum").

```// version 1.x
import { sum } from 'supergeneric/math'

// version 2.x
import { sum } from 'supergeneric'```

API

• ascending - ascending sort function
`[7, 1, 4, 2].sort(ascending) // [1, 2, 4, 7]`
• average(values: number[]): number - returns the average of an array of numbers
`average([7, 1, 4, 2]) // 3.5`
• binarySearch(items: any[], by?: function) => (target: any): object - binary searches through items, using the by function as a value getter, or the item itself. Assumes the items are already ascendingly-sorted (on the value itself or the value of the by function). Returns `{ item, index }`. No recursion used for low memory overhead, and finds items in very few steps. Saves more time the bigger the length of items.
```const doubles = Array(1000)
.fill(0)
.map((v, i) => i * 2)

const searchDoubles = binarySearch(doubles) // save a reference to the search

searchDoubles(4) // { item: 4, index: 2 }
searchDoubles(3) // undefined

// more complex using a by function
const complex = Array(1000)
.fill(0)
.map((v, i) => ({ value: i * 2 }))

const searchComplex = binarySearch(complex, item => item.value)

searchComplex(4) // { item: { value: 4 }, index: 2 }```
• console - a color-injected version of `window.console`. Only the first argument (string) will be colored... the rest will be left alone.
```console.magenta('foo', 'bar') // foo bar (foo in magenta text)

// available colors
console.blue
console.cyan
console.green
console.grey
console.magenta
console.orange
console.purple
console.red
console.teal```
• convert
• dates
• descending - descending sort function
`[7, 1, 4, 2].sort(descending) // [7, 4, 2, 1]`
• first - first element in an array
`first([7, 1, 4, 2]) // 7`
• generateHash(length:number = 6): string - generates an alpha-numeric (alpha on first letter) key of `length` characters
```generateHash()  // RUaLy4
generateHash(4) // w9Y7```
• getMilliseconds(duration: string): number - returns numeric milliseconds (for duration math) from a string duration. Duration is case insensitive, and accepts singular or plural versions. Numbers are ignored and passed-through.
```getMilliseconds(131)          // 131
getMilliseconds('1 second')   // 1000
getMilliseconds('4 minutes')  // 1000 * 60 * 4
getMilliseconds('2 days')     // 1000 * 60 * 60 * 24 * 2
getMilliseconds('1 WEEK')     // 1000 * 60 * 60 * 24 * 7```
• last - last element in an array
`last([7, 1, 4, 2]) // 2`
• makePath(...segments: any, options:? object): string - joins segments with default delimiter of '/', removing empty sections and duplicate delimiters. Accepts a single option `{ delimiter: '|' }` to modify the delimiter.
```makePath('foo', 'bar', 'baz')                       // foo/bar/baz
makePath('foo', undefined, 13)                      // foo/13
makePath('foo/', undefined, 13)                     // foo/13
makePath('foo', 'bar', 'baz', { delimiter: '.' })   // foo.bar.baz```
• max(values: number[]): number - returns the largest number in values, shorthand for `Math.max(...values)`
`max([7, 1, 4, 2]) // 7`
• mean(values: number[]): number - returns the average of an array of numbers (alias for average(values: number[]): number).
`mean([7, 1, 4, 2]) // 3.5`
• median(values: number[], sortBy?: function): number - returns the median value from an array of items.
```median([2, 4, 1, 3, 0])     // 2
median([2, 4, 1, 3, 0, 0])  // 1.5

// or with a sorter function for objects
const items = [
{ foo: 2 },
{ foo: 4 },
{ foo: 1 },
{ foo: -1 },
]

const byFoo = sortBy('foo')

median(items, byFoo) // { foo: 1 }```
• merge(...items: object[]): object - merges all items, shorthand for `Object.merge(...items)`
`merge({ age: 1 }, { name: 'Mittens' }) // { age: 1, name: 'Mittens' }`
• mergeClean(...items: object[]): object - same as merge, but removes empty properties
`merge({ age: 1, pets: undefined }, { name: 'Mittens' }) // { age: 1, name: 'Mittens' }`
• min(values: number[]): number - returns the smallest number in values shorthand for `Math.min(...values)`
`min([7, 1, 4, 2]) // 1`
• numbers(item: any): any - returns a number if the item can be parsed as a number, otherwise leaves it unchanged. Used in mapping functions.
`['12', 4, '3.14', 'foo'].map(numbers) // [12, 4, 3.14, 'foo']`
• onlyNumbers(items: any[]): number[] - returns only the numeric elements in items
`onlyNumbers([1, 'foo', undefined, 5, NaN]) // [1, 5]`
• random(min: number, max: number): number - returns a random number between min and max, inclusive.
`random(1,9) // 7`
• randomArray(length: number, filler?: function = () => Math.random()): any[] - returns an Array of length, filled by the filler function (Math.random by default, returning float values from 0 to 1).
```randomArray(4) // [0.1231, 0.9999, 0.4612, 0]
randomArray(8, () => randomItem('ABC')) // ACCABACA```
• randomItem(items: any[]): any - returns a randomly-selected item from array (or string) items
```randomItem('foobarbaz')    // a
randomItem([8, 7, 4, 1])   // 7```
• range(length: number, options?: object): number[] - returns an Array of length, filled by the range values, starting at 0. Accepts one option, `from: number` to change the starting value.
```range(5)                  // [0, 1, 2, 3, 4]
range(5, { from: 1 })     // [1, 2, 3, 4, 5]```
• recurse - it's a secret.
• required(message: string): Error - throws an error with message if called. Useful for assigning default values to this to force entry.
```const foo(bar = required('bar is a required option of foo(bar)')) => `foo:\${bar}:baz`

foo('cat') // foocatbaz
foo() // throws Error('bar is a required option of foo(bar)')```
• round(value: number, precision: number = 0): number - rounds value by precision digits (default 0 for integer-rounding).
```round(3.1415926)    // 3
round(3.1415926, 2) // 3.14```
• rounder(precision: number = 0) => round(value) - curried round function for mapping, etc.
```const roundTo1Decimal = rounder(1)

[67.14, 16.88, 1.16].map(roundTo1Decimal) // [67.1, 16.9, 1.2]```
• sortBy(key: string|function, options?: object) - sorting function that sorts by key (attribute name as string, or item function), and accepts a single option of `{ descending: true }` for reverse sorting.
```const items = [
{ foo: 2 },
{ foo: 1 },
{ foo: -1 },
]

const foo = item => item.foo
const byFoo = sortBy('foo')
const byFoo2 = sortBy(foo)

items.sort(byFoo).map(foo)                        // [-1, 1, 2]
items.sort(byFoo2).map(foo)                       // [-1, 1, 2]
items.sort(byFoo, { descending: true }).map(foo)  // [2, 1, -1]```
• stddev(values: number[]): number - returns the standard deviation of values.
`stddev([7, 4, 2, 1]) // 2.6457513110645907`
• sum(values: number[]): number - returns the sum of values
`sum([7, 1, 4, 2]) // 14`

Package Sidebar

Install

`npm i supergeneric`

14

3.0.1

MIT

29 kB

69