Library for functional coding in the modern environment.
- Get the most from TypeScript's inference power.
- The implementation of each function should be as minimal as possible.
- Respect the immutability.
- All functions must be safe as much as possible.
- Do not override native methods, if function will make same work and produce result same as native method.
- Each function is maximally independent module (I try my best, though there can be some dependencies).
- TypeScript included out the box
- Small size
- Separated modules. You can import only needed functions into your code.
npm i @fluss/coreimport { curry } from '@fluss/core';
// or
import { curry } from '@fluss/core/curry';Library embraces a lot of ES modules. It doesn't support CommonJS. If you need old module system, transform code with any tool (Babel etc.).
Compose functions from left to right. Can handle asynchronous functions along with synchronous ones.
const fn /*: (str: string) => string */ = pipe(
(str) => str + 2,
(str: string) => str + 3,
);
const result /*: '123' */ = fn('1');
const composed /* Promise<number> */ = pipe(
async (str: string) => str + 2,
parseInt,
);
const asyncResult /*: Promise<number> */ = composed('1');Returns own argument back to the calling place.
const value = 5;
const result /*: 5 */ = identity(value);Execute fn only once. And then after function if it is provided.
const doOnlyOnce = once(() => {
/* Initialize something. */
});Reverses function's parameters.
const fn = (s: string, n: number) => Number(s) + n;
const flipped /*: (args_0: number, args_1: string) => number */ = flip(fn);
// ...
flipped(1, '2'); // -> 3Create curried version of function with optional partial application. If function accepts variadic arguments (...rest), then you can apparently define function's arity.
const fn /*: Curried<(arg_0: string, arg_1: string) => string, 2> */ = curry(
(str1: string, str2: string) => str1 + str2 + 3,
);There is a special value _ that you can use with curried function to preserve place for an argument for the next function execution.
// _anotherFn_ will accept first parameter from original _fn_ function.
const anotherFn /*: Curried<(arg_0: string) => string, 1> */ = fn(_, '2');Creates function for binary operation. For unknown operator it returns tuple with left and right operands.
const sum = [1, 2, 3, 4, 5, 6].reduce(binary('+'), 0);Checks if value is not null and undefined.
const y /*: boolean */ = isJust(null);
const y1 /*: boolean */ = isJust(false);
const y2 /*: boolean */ = isJust(0);Checks if value is Error or its extended classes.
const y /*: false */ = isError(null);
const y1 /*: true */ = isError(new Error('message'));
const y2 /*: true */ = isError(new TypeError('message'), TypeError);
const y3 /*: false */ = isError(new Error('message'), TypeError);Checks if value is Promise.
const y /*: false */ = isPromise(false);
const y1 /*: true */ = isPromise(Promise.resolve(9));Check if value is a function.
const f: unknown = () => 2;
if (isFunction<() => number>(f)) {
// `f` will be type of () => number here.
}Makes function be executed once per frames count. If frames argument is equal to 0 or less, then, if present, requestAnimationFrame is used. Otherwise, setTimeout function is in use.
const cpuHeavyFunction = throttle(() => {
/* Do some heavy stuff. */
}, 4);
document.addEventListener('scroll', cpuHeavyFunction);Executes function while it is not in process. It can handle asynchronous functions.
const consequentFunction = consequent((...args) => {
/* Some work here */
});
consequentFunction(); // Start doing the job.
consequentFunction(); // If previous invocation is not completed then this is ignored.Delays function invocation for frames from last invocation of debounced function. If interval between invocations will be less than frames time, then original function won't be executed.
const debouncedFunction = debounce((event: ScrollEvent) => {
/* Some work here */
}, 2);
// It starts job when you finish scrolling.
window.addEventListener('scroll', debouncedFunction);Delays function invocation by some frames. If frames equals to zero or less, then requestAnimationFrame function is used.
delay(() => {
/* Some work here. */
}); // Will use `requestAnimationFrame` in browser.
const stamp = delay(() => {
/* Some another work here. */
}, 2); // Will use `setTimeout`.
stamp.canceled; // -> false
stamp.result; // -> Promise<T> holds result if delayed function.
stamp.cancel(); // -> cancels delay.Wraps function and cache all execution results. Allows to customize key for cache. By default, it is first function's argument. Cache readable object is visible to outside.
const fn = (num: number) => Math.random() * num;
const memoizedFn = memoize(fn);
const result1 = memoizedFn(1); // Function is executed
const result2 = memoizedFn(1); // Value from cache will be returned
const result3 = memoizedFn(4); // Function is executed
// Allows manually clear cache.
memoizedFn.cache.clear();Performs side effect on value while returning it as is. It does not wait for side effect callback to be finished.
const result /*: 5 */ = tap(console.log)(5);Performs side effect on value while returning it as is. It waits for side effect callback to be finished.
const result /*: 5 */ = awaitedTap(prepareListenerForTheValue)(5);Replaces conditional flow (ternary operator and if/else).
const multiplyIf = when((num: number) => num > 10)((num) => num * 3, identity);
const result /*: number */ = multiplyIf(9); // Will be returned as is.
const result2 /*: number */ = multiplyIf(11); // Will be multiplied.Checks if value is instance of Option monad.
isOption(8); // false
isOption(Some(8)); // trueCreates the Option monad instance with the Just state.
Some(2); // Option<number>Option with the Nothing state.
const a /*: None */ = None;Monad that gets rid of null and undefined. Its methods work only if inner value is not nothing(null and undefined) and its state is Just, otherwise they aren't invoked (except extract and fill). Wraps nullable value and allows to work with it without checking on null and undefined.
Checks if value is instance of Result monad.
isResult(8); // false
isResult(Ok(8)); // trueWraps a value with the Result monad with the Right state.
// We are sure that 8 is not "left" value.
Ok(8); // Result<number, never>Creates the Result monad instance with the Left state.
Err(new Error('Error is occurred!')); // Result<never, Error>Runs function and return a result wrapped in the Result monad.
const result /*: Either<Error, string> */ = tryExecute(() => {
if (someVariable > 3) {
return someVariable; // the Ok will be returned.
} else {
throw new Error('The variable is less than 3.'); // the Err will be returned.
}
});Monad that can contain success value or failure value. Allow handle errors in functional way.
Defines the Task monad or copies fork function from another Task or Promise.
function getSomeDataFromInternet(): Promise<string> {
/* useful code */
}
const dataTask = Task(getSomeDataFromInternet()).map(JSON.parse);
// Runs the task and returns the Promise with the Result.
// The returned Promise never throws, so you don't have wrap it with try/catch.
const data = await dataTask.run();Wraps value to process as Task.
const data = {
/* some data */
};
const dataTask = Succeed(data)
.map(JSON.stringify)
.chain(Task(sendOverInternet));
// somewhere in the code
dataTask.run();Create a failed Task.
const dataTask = Fail(someError);
// somewhere in code
dataTask.run();Check if a value is instance of the Task.
const dataTask = Succeed(8);
isTask(dataTask); // trueMonad that allow to perform some actions asynchronously and deferred in time (in opposite Promise that starts doing job immediately after definition).
Difference between Task and Promise.
Create the List from values, array-like objects or iterables.
const numbers /*: List<number> */ = List(1, new Set([2]), [3]);Create the List from function that returns iterator.
const numbers /*: List<number> */ = iterate(function* () {
yield 1;
yield 2;
yield 3;
});Checks if value is instance of the List.
const result /*: boolean */ = isList(List());Monad that represents lazy Array. It can decrease computation step comparably to Array. Actual execution of List's methods starts when one of terminating method (method that do not return a new List instance) is called.
Creates a live empty stream.
const y /*: Stream<number, number> */ = Stream((value: number) => Math.pow(value, 2));
y.forEach((value) => (document.body.innerHTML = value));
// Somewhere in the code
y.send(2); // document.body.innerHTML will set to equal to 4Structure that makes operations with values over time in live mode.
Queues a data returned by fn to be evaluated at interpreter's idle period.
const value /*: Idle<boolean> */ = Idle(() => 1).map((num) => num > 7);
// somewhere in the code
const evaluated /*: boolean */ = value.extract();Monad that allow to defer data initialization.
Add recognition of Idle, Option, List and Result data structures for JSON.parse.
const obj = JSON.parse('{"type":"__$Option","value":1}', reviver);
// obj will be instance of Option type.Have fun ✌️