js-lib

Standard library for universal (browser + Node.js) javascript

Design

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:

• We believe Lodash is outdated (many functions are pre-ES6 / obsolete by ES6).
• Because it has so many outdated functions - its size is bigger, and solutions to tree-shake exist, but complicated.
• First-class TypeScript support (all code in this repo is TypeScript).

This package is intended to be 0-dependency (exception: tslib from TypeScript), "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 es2017.

Exports default CJS version for Node as es2019 (with native async/await, for better performance, async stack-traces, etc).

Mutation

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

Highlights

• 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)
• ...

Packaging

• engines.node >= Node.js LTS
• main: dist/index.js: commonjs, es2021 - targeting Node.js
• module: dist-esm/index.js: esm, es2017 - targeting Browsers
• types: dist/index.d.ts: typescript types
• /src folder with source *.ts files included