qwux

Minimal set of utility functions written in TypeScript. Mostly for personal use. I only include the functions I actually need here. Tried to not duplicate native javascript functions.

License.

API

• Arrays
  • after before last without uniq insert move divide zip
• Objects
  • isTrueObject values each pick omit objectMap toArray
• Strings
  • capitalize
• Values
  • isEmpty isNil
• Functions
  • noop identity compose repeat
• Math
  • constrain
• Sorting
  • sortByKey
• Timing
  • throttled
• Misc
  • uniqId

Arrays

after

• Gets the item after an item in an array.

after :: (array, item) -> item
/*
@array The array to act on.
@item An item in the array.
@return The item found, or undefined.
*/

// Example
after([a, b, c], b) -> c

before

• Gets the item before an item in an array.

before :: (array, item) -> item
/*
@array The array to act on.
@item An item in the array.
@return The item found, or undefined.
*/

// Example
before([a, b, c], b) -> a

last

• Gets the last item in an array.

last :: (array) -> item
/*
@array The array to act on.
@return The last item.
*/

// Example
last([a, b, c]) -> c

without

• Returns an array with items filtered out.

without :: (array, ...items) -> array
/*
@array The array to act on.
@items The items to filter out.
@return The array minus @items.
*/

// Examples
without([a, b, c], c) -> [a, b]
without([a, b, c], b, c) -> [a]

uniq

• Retains only unique values from an array.

uniq :: (array) -> array
/*
@array The array to act on.
@return The array with unique values only.
*/

// Examples
uniq([a, a, b]) -> [a, b]
uniq([a, a, b, b, c, c]) -> [a, b, c]

insert

• Inserts an item into the array at a position. If the position exceeds the length of the array, append the item.

insert :: (array, i, ...items) -> array
/*
@array The array to act on.
@i The position to insert the item(s).
@items Any number of items to insert at @i.
@return The array with the items inserted at position @i.
*/

// Example
insert([a, c], 1, b) -> [a, b, c]

move

• Moves an item in an array to another position and returns the new array.

move :: (array, from, to) -> array
/*
@array The array to act on.
@from The source position.
@to The destination position.
@return New array with item moved.
*/

// Example
move([a, b, c], 0, 2) -> [b, c, a]

divide

• Divides an array into two parts at a position.

divide :: (array, i) -> [array, array]
/*
@array The array to act on.
@i The position to divide the array.
@return The divided array.
*/

// Example
divide([a, b, c], 1) -> [[a], [b, c]]

zip

• Zips respective indices of multiple arrays into a single array.

zip :: (...arrays) -> ...arrays
/*
@arrays The arrays to zip together.
@return The zipped arrays.
*/

// Examples
zip([a, b], [1, 2]) -> [[a, 1], [b, 2]]
zip([a, b, c], [1, 2, 3]) -> [[a, 1], [b, 2], [c, 3]]
zip([a, b], [1]) -> [[a, 1], [b, undefined]]

Objects

isTrueObject

• Determines if a value is a true object.
• Only {} or {v: k, ...} values are considered true objects.

isTrueObject :: (value) -> boolean
/*
@value Any value.
@return True if the object is a true object.
*/

// Examples
isTrueObject({}) -> true
isTrueObject([]) -> false
isTrueObject(null) -> false
isTrueObject(undefined) -> false
isTrueObject(function () {}) -> false
isTrueObject('string') -> false
isTrueObject(42) -> false

values

• Gets the values of an object.

values :: (obj) -> array
/*
@obj The object to act on.
@return The values of the object.
*/

// Example
values({a:1, b:2} -> [1, 2]

each

• Iterates over an object.

each :: (obj, fn) -> results
/*
@obj The object to iterate over.
@fn (value, key) Called over each member of the object.
@return An array of return values from @fn.
*/

// Examples
each({a:1, b:2, c:3}, v => v * 2) -> [2, 4, 6]
each({a:1, b:2, c:3}, (v, k) => {k: v}) -> [{a:1}, {b:2}, {c:3}]

pick

• Picks props from an object and returns a new object.

pick :: (obj, ...keys) -> object
/*
@obj The object to act on.
@keys The keys to pick from the object.
@return The new object formed from the picked keys.
*/

// Examples
pick({a:1, b:2}, 'b') -> {b:2}
pick({a:1, b:2, c:3}, 'a', 'b') -> {a:1, b:2}

omit

• Omits props from an object and returns a new object.

omit :: (obj, ...keys) -> object
/*
@obj The object to act on.
@keys The keys to omit from @obj.
@return The new object without @keys.
*/

// Examples
omit({a:1}, 'a') -> {}
omit({a:1, b:2, c:3}, 'a', 'b') -> {c:3}

objectMap

• Maps each value in an object and returns a new object. Similar to array map, but for objects.

objectMap :: (obj, fn) -> object
/*
@obj The object to map over.
@fn (value, key) The function to call over each property of object. Its return
                 value will be used to form the new object.
@return The new object.
*/

// Example
objectMap({a:1, b:2}, (v, k) => v * 2) -> {a:2, b:4}

toArray

• Converts an object to an array of the form [{key: value}, ...].

toArray :: (obj) -> array
/*
@obj The object to convert.
@return An array of {key: value} objects.
*/

// Example
toArray({a:1, b:2}) -> [{a:1}, {b:2}]

Strings

capitalize

• Capitalizes the first letter of a string.

capitalize :: (str) -> string
/*
@str The string to capitalize.
@return The capitalized string.
*/

// Examples
capitalize('foo') -> 'Foo'
capitalize('foo bar') -> 'Foo bar'  // Only affects the first character.
capitalize(' foo') -> ' foo'

Values

isEmpty

• Checks if a value is empty.
• Values are considered empty if they have zero length or are non-enumerable.

isEmpty :: (value) -> boolean
/*
@value Any value of any type.
@return True if the value is empty, otherwise false.
*/

// Examples
isEmpty([]) -> true
isEmpty([a]) -> false
isEmpty({}) -> true
isEmpty({a:1}) -> false
isEmpty(42) -> true
isEmpty(null) -> true
isEmpty('foobar') -> false
isEmpty(function () {}) -> true

isNil

• Returns true if a value is undefined or null.

isNil :: (value) -> boolean
/*
@value Any value.
@return True if the value is undefined or null.
*/

// Examples
isNil(null) -> true
isNil(undefined) -> true
isNil([]) -> false

Functions

noop

• Returns undefined.

noop :: () -> undefined

identity

• Returns the given value.

identity :: (value) -> value

compose

• Composes multiple functions against a value.
• The return value of each call is provided as the argument to the subsequent call.
• Functions are called from right to left.
• It takes the form f(g(h(x))) and allows you to use the prettier (f∘g∘h)(x) form.

compose :: (...fns) => (value) -> result
/*
@fns Called from right to left.
@value The value to call against.
@return The final return value after all functions are applied.
*/

// Example
compose(
  sumArray,
  array => map(x => x * 2)  // [4, 6, 8]
  array => map(x => x + 1)  // [2, 3, 4]
)([1, 2, 3]) -> 18

repeat

• Repeats a value or calls a function n times.

repeat :: (n, value) -> results
/*
@n The number of times to repeat the value or function.
@value A value or function to repeat.
@return An array of results.
*/

// Examples
repeat(5, a) -> [a, a, a, a, a]
repeat(5, () => a) -> [a, a, a, a, a]

Math

constrain

• Constrains a value between a min and max value.

constrain :: (value, [min, max]) -> number
/*
@value The value to constrain.
@min The lower bound.
@max The upper bound.
@return The constrained value.
*/

// Examples
constrain(15, [10, 20]) -> 15
constrain(0, [10, 20]) -> 10
constrain(100, [10, 20]) -> 20

Sorting

sortByKey

• Sorts an array of objects by key and returns the new array.

sortByKey :: (array, key) -> array
/*
@array The array of objects to sort.
@key The key to sort by.
@return The new sorted array.
*/

// Example
sortByKey([{name: 'foo'}, {name: 'bar'}], 'name') -> [{name: 'bar', name: 'foo'}]

Timing

throttled

• Limits how soon a function may be called relative to its previous call.

throttled :: (fn, ms) -> function
/*
@fn The function to throttle.
@ms How many milliseconds must elapse before this function can run again.
@return The throttled function.
*/

// Example
onChange = throttled(onChange, 1000)  // Process change events at most once per second.

Misc

uniqid

• Generates a unique id.

uniqId :: () -> id
/*
@return A unique string id
*/

// Examples
uniqId() -> '0'
uniqId() -> '1'
uniqId() -> '2'

License

MIT