@naturalcycles/js-lib
Advanced tools
Standard library for universal (browser + Node.js) javascript
Inspired by Lodash, bluebird, promise-fun and other useful small packages.
Designed to play well with the rest of opinionated "Natural Cycles JS Platform" (link pending). This
package is the lowest-level production dependency (not devDependency) of the Platform. Almost
everything else depends on it.
All functions in this package are exported in index.ts (flat), no namespacing is used. So, to
avoid conflicts and "global import namespace" pollution , all functions are prefixed with an
underscore (e.g _.pick becomes _pick), with some exceptions (later). Promise functions are
prefixed with p, e.g pMap.
Decorators are _prefixed and PascalCased (e.g @_Debounce).
_is to be consistent with other naming in this package. PascalCase is to distinguish decorators from similar functions that are not decorators. Example:\_debounceis a function (lodash-based),\_Debounceis a decorator (used as@\_Debounce).
PascalCase convention follows Angular/Ionic convention (but doesn't follow TypeScript documentation
convention; we had to pick one).
Interfaces and Classes are named as usual (no prefix, PascalCase, e.g AppError).
Q: Why not just use lodash?
A:
This package is intended to be 0-dependency, "not bloated", tree-shakeable. Supported by reasonably modern Browsers and Node.js latest LTS.
To fulfil that requirement it exports ESM version (for Browsers) as es2015, to support Browsers that don't natively support async/await (es2017).
Exports default CJS version for Node as es2017 (with native async/await, for better performance, async stack-traces, etc).
All function does NOT mutate the arguments by default.
Many functions support "mutation flag", which can be set to true to perform a mutation.
For example:
const obj = { a: 'a', b: 'b' }
// Non-mutating (default)
const obj2 = _pick(obj, ['a'])
// { a: 'a' }
// Mutating (opt-in)
_pick(obj, ['a'], true)
// obj was mutated
pMap (based on https://github.com/sindresorhus/p-map)StringMap@_Memo_merge (based on https://gist.github.com/Salakar/1d7137de9cb8b704e48a)_deepEquals (based on https://github.com/epoberezkin/fast-deep-equal/)_sortObjectDeep (based on https://github.com/IndigoUnited/js-deep-sort-object)_set (based on https://stackoverflow.com/a/54733755/4919972)_unset (based on https://github.com/jonschlinkert/unset-value)Inspired by bluebird and Sindre's promise-fun packages.
"Copy-pasted" (with small adjustments) here, because:
Bluebird is outdated (pre-ES6)
p-* packages are amazing, but not all of them are needed. Some of them are very much needed
though.
To fix issues with Types. Here, everything is TypeScript, so, first class support and sync.
To fix issues with IDE auto-imports, which is still quite bad for "default exported" packages.
Downside is that (as every fork) we lose "auto-update" possibility from these packages. We believe it's not as bad, because packages imported here have mature API and stability (example: pMap).
Based on https://github.com/sindresorhus/p-map
Based on https://github.com/sindresorhus/p-props
Based on https://github.com/sindresorhus/p-filter
Allows to create a "ResolvablePromise", which is a normal native Promise (so, can be awaited, etc),
extended with .resolve() and .reject() methods, so you can control it. Similar to jQuery's
Deferred, or RxJS's Subject (which is both an Observable and allows to emit values).
// todo: example
Based on https://github.com/sindresorhus/p-retry
Based on https://github.com/sindresorhus/delay
// todo: example
// todo: example
// todo: example
// todo: example
Inspired by Lodash's _.pick.
_pick({ a: 'a', b: 'b', c: 'c' }, ['a', 'b'])
// { a: 'a', b: 'b' }
_pick({ a: 'a', b: 'b', c: 'c' }, ['a'])
// { a: 'a' }
_pick({ a: 'a', b: 'b', c: 'c' }, ['d'])
// {}
_pick({ a: 'a', b: 'b', c: 'c' }, [])
// {}
// Supports "mutation flag" which would mutate the object and return it (same object):
const obj = { a: 'a', b: 'b', c: 'c' }
const obj2 = _pick(obj, ['a'], true)
obj === obj2 // true
Inspired by Lodash's _.omit. The opposite of _pick.
_omit({ a: 'a', b: 'b', c: 'c' }, ['a', 'b'])
// { c: 'c' }
_omit({ a: 'a', b: 'b', c: 'c' }, ['a'])
// { b: 'b', c: 'c' }
_omit({ a: 'a', b: 'b', c: 'c' }, ['d'])
// { a: 'a', b: 'b', c: 'c' }
_omit({ a: 'a', b: 'b', c: 'c' }, [])
// { a: 'a', b: 'b', c: 'c' }
// Supports "mutation flag" which would mutate the object and return it (same object):
const obj = { a: 'a', b: 'b', c: 'c' }
const obj2 = _omit(obj, ['a', 'b'], true)
obj === obj2 // true
Similar to _omit, but supports deep object access via dot-notation (a.b). Supports "mutation
flag" argument.
const obj = {
a: 'a',
b: {
b1: 'b1',
b2: 'b2',
},
}
_mask(obj, ['b.b1'])
// { a: 'a', b: { b1: 'b1' }}
_mask(obj, ['b.b1'], true)
// obj was mutated
Needed due to https://github.com/microsoft/TypeScript/issues/13778
Only affects typings, no runtime effect.
Needed due to https://github.com/microsoft/TypeScript/issues/13778
Only affects typings, no runtime effect.
Like .find(), but tries to find an element from the END of the array.
const a = [1, 2, 3, 4, 5, 2, 1]
_takeWhile(a, r => r <= 3)
// [1, 2, 3]
_takeRightWhile(a, r => r <= 3)
// [1, 2]
// Note that the order is reversed when taking from Right!
_dropWhile(a, r => r <= 3)
// [4, 5, 2, 1]
_dropRightWhile(a, r => r <= 3)
// [5, 4, 3, 2, 1]
// Note that the order is reversed when dropping from Right!
_countBy(['a', 'aa', 'aaa', 'aaa', 'aaaa'], r => r.length)
// {
// 1: 1,
// 2: 1,
// 3: 2,
// 4: 1,
// })
Inspired by Lodash's _.intersection.
_intersection([2, 1], [2, 3])
// [2]
_intersection([1], [2])
// []
_intersection()
// []
_intersection([1])
// [1]
Inspired by Lodash's _.difference
_difference([2, 1], [2, 3])
// [1]
_difference([1], [2])
// [1]
_difference([1], [1])
// []
_difference([1])
// [1]
_inRange(-10, 1, 5)
// false
_inRange(1, 1, 5)
// true
_inRange(3, 1, 5)
// true
_inRange(5, 1, 5)
// false
_inRange(7, 1, 5)
// false
Things that should exist in type-fest, but don't (yet).
const m: StringMap = { a: 'a' }
// Same as:
// const m: { [a: string]: string | undefined }
const m: StringMap<number> = { a: 5 }
// Same as:
// const m: { [a: string]: number | undefined }
engines.node >= Node.js LTSmain: dist/index.js: commonjs, es2017 - targeting Node.jsmodule: dist-esm/index.js: esm, es2015 - targeting Browserstypes: dist/index.d.ts: typescript types/src folder with source *.ts files includedFAQs
Standard library for universal (browser + Node.js) javascript
The npm package @naturalcycles/js-lib receives a total of 2,317 weekly downloads. As such, @naturalcycles/js-lib popularity was classified as popular.
We found that @naturalcycles/js-lib demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.