" class="reference-link">Tsfunct

Tsfunct is a TypeScript functional library made directly with and for TS with its static
typesystem in mind.

Installation

To install this package run either:

yarn add @siegrift/tsfunct

or if you use npm

npm i @siegrift/tsfunct --save

Important: This library is using latest TS features when needed. Keep this in mind if you are
trying to use it in your project.

API and documentation

Extended documentation can be found at github pages. You can
also play with the library on CodeSandbox.

The error handling utilities, go and goSync are inspired by
promise-utils library which offers extended
functionality.

You can check the sources of all helpers in the
src/lib folder.

Motivation

Most popular libraries providing helper functions for JS and TS are
lodash and ramda. Many
functions have poor TS typings, often for the added benefit of flexibility.

There are certain helpers (mainly for immutable object manipulation) which can be typed better if
they are designed specifically for TS. Let’s take a look at get(obj, path) helper in both lodash
(4.14.132) and ramda (0.26.9), when using it on a strongly typed TS object.

(Lodash gets it at least correct, but cannot
determine the result type. Ramda allows you to pass a type that is being returned, but you can omit
it and produce incorrect result type)

(There are no TS warnings about accessing
value on nonexistent path)

Lets look what you can get by using get(obj, path) with TSfunct.

There are many advantages of this
helper:

• The result has correct type
• The path can be autocompleted and must be able to exist in the object
• Handles arrays, optional and nullable values (even in intermediate objects)

When you call update for the first time, value in
update function can be undefined (if any intermediate value doesn’t exist). However, when calling
it for a second time, it is guaranteed that the values on the path exist.

Immutability

All functions in this library are immutable. However, some functions allow you to pass a predicate
function. If this function is mutable they will modify the source value as well.

const original = [{ a: 0 }, { a: 1 }, { a: 2 }];
const mapped = map(original, (val) => (val.a = 3));
// 'mapped'  will equal to [3, 3, 3]
// 'original' will equal to [{ a: 3 }, { a: 3 }, { a: 3 }]

Chaining

Chaining is not supported and it’s not a good idea in general. If you want to learn more, read
this article

Functional programming style

Functions in this library are written imperatively (e.g.
const get = (object, path) => implementation compared to traditional functional
const get = (path) => (object) => implementation) for better typing and autocompletion support.

If you are looking for more FP helpers have a look at
monocle or fp ts or
lodash fp)

Limitations

Most of the helpers are typed manually and have some restrictions on its arguments. For example,
path array can be “up to X elements” only in some helpers…

Bear in mind that TS is unsound! Types might easily lie to you if you are not careful. For example,

const arr: number[] = [1, 2, 3];
const num: number = get(arr, [999]); // this line won't trigger TS error!
console.log(num); // undefined!

Other limitation is for example TS path autocompletion for immutability helpers, which is tracked in
this issue and will be fixed in the future.

Issues

Each helper is heavily tested and I try to make the library as stable as possible. In case there is
a bug or unwanted behavior, please create an issue.

Contribution

If you would like to fix an issue or create another helper, feel free to create a PR for it. To
contribute just follow these steps:

1. fork the repository
2. make sure you have yarn installed and run: yarn
3. create a new branch with you feature
4. commit & push
5. create PR to the original repo

Publishing

To release a new version follow these steps:

1. git checkout master && git pull - ensure you are on the “master” branch with latest changes
2. yarn version - choose “x.y.z” as the version to be released
3. git show - verify the changes of the version commit
4. yarn build - only build the package after the “yarn version” command so the bundled
   “package.json” uses the updated version
5. yarn publish --access public
6. git push --follow-tags - to push the commits to a “main” branch