@ezez/utils

@ezez/utils

Formerly: bottom-line-utils, but I never liked the name

A tiny and fast utils library.

Documentation

Documentation can be found here: documentation.

Installing

npm install @ezez/utils

Motivation

Lodash complexity that causes big bundle sizes just for using single function (even with tree shaking!).

Lodash is trying to cover each possible use case, even very rare while typical observed use case of lodash is basic methods used on basic data. As an example, let's take a _.pick method that simply returns an object, based on source object, with just some properties copied. Easy, right? Few lines of code? Lodash makes that 114 imports!

@ezez/utils aims to:

• cover only most typical use cases of given functions,
• add useful methods that are missing in lodash,
• NOT being 100% compatible replacement for lodash/underscore, while keeping MOST behavior identical,
• not being a "polyfill" (no map/forEach functions etc.),
• perform fast and have code size small.

Supported methods

String related

• addPrefix - add prefix to a string if not already present
• addSuffix - add suffix to a string if not already present
• capitalize - capitalize a string, optionally lower casing the rest
• isNumericString - check if given value is a numeric string, features configurable
• occurrences - count occurrences of a substring in a string, optionally allow overlapping
• replace - replace all occurrences of a substring using a map of replacements
• stripPrefix - strip prefix from a string
• stripSuffix - strip suffix from a string

Number related

• cap - cap a value between lower and upper bound
• round - round a value to given precision
• scale - scale given value from old range to new range

Array related

• compareArrays - compare two arrays
• ensureArray - ensure that given value is an array
• insertSeparator - insert a separator between every character in an array
• last - get last element of an array
• match - split your array into two groups - one that matches given predicate, and one that doesn't
• mostFrequent - find most frequent value in an array
• pull - remove values from an array (by mutating)
• remove - remove values from an array (by mutating) using predicate function and return removed values
• sortBy - sort an array by given property (create callback function for Array.prototype.sort)
• unique - get unique values from an array

Object related

• compareProps - compare two objects and return list of different properties
• deserialize - deserialize values serialized with serialize
• isPlainObject - check if given value is a plain object
• mapValues - map values of an object
• merge - merge two objects shallowly, allowing to remove properties while doing so
• omit - omit properties from an object
• pick - pick some properties from an object
• replaceDeep - recursively replace all occurrences of a value in an object/array
• sortProps - sort object properties by key
• serialize - like JSON.stringify but any data type is allowed

Date related

• ensureDate - ensure that given value is a Date instance
• ensureTimestamp - ensure that given value is a numeric timestamp
• formatDate - format a date using a format string, syntax from PHP

Type/data safety

• coalesce - return first non-nullish value
• ensureError - ensure that given value is an error
• escapeRegExp - escape a string to be used in a regular expression
• safe - runs function and returns its result or default value if function throws an error

Flow related

• later - create a promise you can resolve later, outside of Promise constructor
• mapAsync - map an array asynchronously if sync version blocks your event loop for too long
• noop - do nothing
• rethrow - throw given value
• seq - sequentially execute Promise-returning functions until one returns a value
• wait - wait given amount of time (async)
• waitSync - wait given amount of time (sync)
• waitFor - wait for a condition to be true, checking every given amount of time

Various

• get - extract a value from a deep object using specified path, optionally with a default value
• getMultiple - same as above, but test multiple paths
• set - set a value in a deep object using specified path
• setImmutable - set a value in a deep object using specified path, but return a new object
• isEmpty - check if given value is empty
• throttle - throttle a function, very configurable
• truthy - is value truthy? (useful for filtering with more correct TypeScript support than filter(Boolean))

Methods will be added as I need them. I am open for suggestions and PRs. See next heading for list of methods that I want to add.

Methods to be supported

(TODO)

• debounce

Tested

This library is fully unit tested and can be used on production. See License.

License

MIT

Changelog

[4.0.0] - 2024-05-16

Breaking

• replaceDeep will not mutate anything by default anymore — previously it was wrongly documented as always mutating, but it was not mutating objects. Mutating behavior can now be enabled and additionally controlled by defining if instances properties are allowed to be mutated.
• [serialize] to avoid excessive calls to serializer functions - they are now only called with non-plain objects or unknown data types, this breaks some rare use cases

Changed

• serialize custom serializers now allow things like Date (that defines .toJSON) to be supported as the user would expect

Added

• replaceDeepByFn method for more granular control over replacing values. replaceDeep is a simplified wrapper over the new function
• trim, trimStart, and trimEnd methods

Dev

• upgraded some jsdocs