supergeneric
TypeScript icon, indicating that this package has built-in type declarations

3.0.1 • Public • Published

supergeneric

npm version

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

Weekly Downloads

14

Version

3.0.1

License

MIT

Unpacked Size

29 kB

Total Files

69

Last publish

Collaborators

  • krwhitley