marpple / fxts

A functional programming library for TypeScript/JavaScript

FxTS

FxTS is a functional library for TypeScript/JavaScript programmers.

Why FxTS?

• Lazy evaluation
• Handling concurrent requests
• Type inference
• Follow iteration protocols Iterable / AsyncIterable

Installation

npm install @fxts/core

Documentation

Please review the API documentation

Usage

import { each, filter, fx, map, pipe, range, take } from "@fxts/core";

pipe(
  range(10),
  map((a) => a + 10),
  filter((a) => a % 2 === 0),
  take(2),
  each((a) => console.log(a)),
);

// chaining
fx(range(10))
  .map((a) => a + 10)
  .filter((a) => a % 2 === 0)
  .take(2)
  .each((a) => console.log(a));

Usage(concurrent)

import { concurrent, countBy, flat, fx, map, pipe, toAsync } from "@fxts/core";

// maybe 1 seconds api
const fetchWiki = (page: string) =>
  fetch(`https://en.wikipedia.org/w/api.php?action=parse&page=${page}`);

const countWords = async (concurrency: number) =>
  pipe(
    ["html", "css", "javascript", "typescript"],
    toAsync,
    map(fetchWiki),
    map((res) => res.text()),
    map((words) => words.split(" ")),
    flat,
    concurrent(concurrency),
    countBy((word) => word),
  );

await countWords(); // 4 seconds
await countWords(2); // 2 seconds

you can start here

Build

• npm run build

Running Test

• npm test

Running Type Test

• npm run compile:check

License

Apache License 2.0

fxts's Issues

Add `omitBy` and `pickBy` function

Suggestion

⭐ Suggestion

💻 Use Cases

pickBy(
  ([key, value]) => key === 'b' || typeof value === 'boolean',
  { a: 1, b: '2', c: true }
);
// { b: '2', c: true }

await pickBy(
  async ([key, value]) => key === 'b' || typeof value === 'boolean',
  { a: 1, b: '2', c: true }
);

pipe(
  { a: 1, b: '2', c: true },
  pickBy(([key, value]) => key === 'b' || typeof value === 'boolean')
);

await pipe(
  { a: 1, b: '2', c: true },
  pickBy(async ([key, value]) => key === 'b' || typeof value === 'boolean')
);

omitBy(
  ([key, value]) => key === 'b' || typeof value === 'boolean',
  { a: 1, b: '2', c: true }
);
// { a: 1 }

await omitBy(
  async ([key, value]) => key === 'b' || typeof value === 'boolean',
  { a: 1, b: '2', c: true }
);

pipe(
  { a: 1, b: '2', c: true },
  omitBy(([key, value]) => key === 'b' || typeof value === 'boolean')
);

await pipe(
  { a: 1, b: '2', c: true },
  omitBy(async ([key, value]) => key === 'b' || typeof value === 'boolean')
);

Missed signature in `reduce` function

Bug Report

💻 Code

const work = reduce((a, b) => a + b, [1, 2, 3]);
const notWork = reduce((a, b) => a + b, toAsync([1, 2, 3]));

🙁 Actual behavior

There is a problem that the value of a is inferred as unknown when AsyncIterable type is passed as an argument.
This bug is probably caused by missing some signatures of the reduce function.

🙂 Expected behavior

It would be nice to be able to infer the value a in AsyncIterable normally.

---

Version Infomation

• Operating system: Mac 12.0.1
• Typescript: 4.5.0
• Nodejs: 14.18.1

Add `pick` and `omit` function

Suggestion

⭐ Suggestion

💻 Use Cases

const product = {
  name: 'iphone',
  price: 1000,
  description: '...',
  image_url: '...',
};

pick(["name", "price"], product); // { name: 'iphone', price: 1000 }

omit(["name", "price"], product); // { description: '...', image_url: '...' }

Add `compress` function

Suggestion

⭐ Suggestion

ref https://docs.python.org/3/library/itertools.html#itertools.compress

💻 Use Cases

const iter1 = compress([false,true,false,false,true],  [1, 2, 3, 4, 5]);
iter1.next(); // {value: 2, done:false}
iter1.next(); // {value: 5, done:false}
iter1.next(); // {value: undefined, done:true }

const iter2 = compress([1,0,0,1,0],  "abcde");
iter2.next(); // {value: "a", done:false}
iter2.next(); // {value: "d", done:false}
iter2.next(); // {value: undefined, done:true }

Need `join` function

Suggestion

⭐ Suggestion

I would like to use join function like other library lodash#join

💻 Use Cases

_.join(['a', 'b', 'c'], '~');
// => 'a~b~c'

Add `intersectionBy` function

Suggestion

⭐ Suggestion

💻 Use Cases

const iter = intersectionBy((o) => o.x, [{ x: 2 }, { x: 1 }], [{ x: 1 }, {x : 3}, {x : 4}]);
iter.next(); // {value:{x: 1}, done:false}
iter.next(); // {value:undefined, done:true}

Add `keys` function

Suggestion

⭐ Suggestion

Returns a Iterable/AsyncIterable containing the own properties of the given object

💻 Use Cases

const iter = keys({a:1, b:2, c:3 });
iter.next(); // {value: 'a', done:false}
iter.next(); //  {value:'b', done:false}
iter.next(); //  {value:'c', done:false}
iter.next(); //  {value:undefined, done:true}

Add `isNil` function

Suggestion

⭐ Suggestion

Checks if the given value is null or undefined.

💻 Use Cases

isNil(1); // false
isNil('1'); // false
isNil(undefined); // true
isNil(null); // true

Return type of pipe using each isn't inferred correctly

Bug Report

💻 Code

const ex1 = pipe([1, 2, 3], each(console.log)); // const ex1: void      inferred correctly  

const ex2 = pipe([1, 2, 3], take(1), each(console.log)); //   const ex2: IterableIterator<number>     inferred incorrectly 

🙁 Actual behavior

Type of ex2 is inferred IterableIterator<number>

🙂 Expected behavior

Type of ex2 is expected to be void.

---

Version Infomation

• Operating system: Linux 5.11.0-40-generic # 44~20.04.2-Ubuntu SMP Tue Oct 26 18:07:44 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux
• Typescript: Version 4.5.2
• Nodejs: v14.17.4
• FxTS: v.0.2.2

Add `zipWith` function

Suggestion

⭐ Suggestion

Returns Iterable/AsyncIterable out of the two supplied by applying f to each same positioned pair in Iterable/AsyncIterable.

💻 Use Cases

const iter = zipWith((a,b) => [a,b], [1,2,3], ['a','b','c']);
iter.next(); // {value: [1, 'a'] , done: false}
iter.next(); // {value: [2, 'b'] , done: false}
iter.next(); // {value: [3, 'c'] , done: false}

Add `intersection` function

Suggestion

⭐ Suggestion

Combines two Iterable or AsyncIterable into a set (i.e. no duplicates) composed of those elements common to both Iterable/AsyncIterable.

💻 Use Cases

const iter = intersection([1,2,3,4], [4,3,5,6]);
iter.next() // {value: 4, done:false};
iter.next() // {value: 3, done:false};
iter.next() // {value: undefined, done:true};

Add `consume` function

Suggestion

⭐ Suggestion

Consumes the given number of Iterable/AsyncIterable. If the number is empty, all is consumed.

💻 Use Cases

const iterator = (function *(){ 
  yield 1; 
  yield 2; 
  yield 3;  
})();
consume(iterator, 2);
iterator.next(); // {value:3, done:false}

// with pipe
pipe(
  range(10),
  peek(updateApi),
  concurrent(5),
  consume,
);

Add `cycle` function

Suggestion

⭐ Suggestion

ref https://docs.python.org/3/library/itertools.html#itertools.cycle

💻 Use Cases

const iter = cycle("abc")
iter.next(); // {value:"a", done: false}
iter.next(); // {value:"b", done: false}
iter.next(); // {value:"c", done: false}
iter.next(); // {value:"a", done: false}
iter.next(); // {value:"b", done: false}

// with pipe
pipe(
  cycle([1,2,3,4]),
  take(5),
  toArray,
); // [1,2,3,4,1]

Add `average` function

Suggestion

⭐ Suggestion

💻 Use Cases

average([1,2,3,4,5]); // 3
await average(toAsync([1,2,3,4,5])); // 3

Add `values` function

Suggestion

⭐ Suggestion

Returns a Iterable/AsyncIterable of all values of the given object

💻 Use Cases

const iter = values({a:1,b:2,c:3});
iter.next(); // {value:1, done:false}
iter.next(); // {value:2, done:false}
iter.next(); // {value:3, done:false}
iter.next(); // {value:undefined, done:true}

Add search function on website

Suggestion

⭐ Suggestion

With more functions, the page needs a search function.

💻 Use Cases

Feature request - `curry` utility

Suggestion

⭐ Suggestion

curry is an essential utility for FP, yet most libraries (especially lodash) fail to provide correct type definition.
Are there any plans for exporting curry? (since other utilities from fxts support currying, as I noticed)

💻 Use Cases

const strictEq = curry(<T>(left: T, right: T) => left === right)

const twos = pipe([1, 1, 1, 2, 2, 2], filter(strictEq(2))) // [2, 2, 2]

Add `includes` function

Suggestion

⭐ Suggestion

Checks if the specified value is equal.

💻 Use Cases

includes('c', 'abcd'); // true
includes(3, [1,2,3,4]); // true

Add `juxt` function

Suggestion

⭐ Suggestion

Applies a list of function to a Iterable/AsyncIterable of values.

💻 Use Cases

juxt([Math.max, Math.min])(1,2,3,-4,5,6) // [6, -4]

Add `slice` function

Suggestion

⭐ Suggestion

Returns an Iterable/AsyncIterable of the given elements from startIndex(inclusive) to endIndex(exclusive).

💻 Use Cases

const iter1 = slice(0, 2, [1,2,3,4,5]); // [1, 2]
iter1.next(); // {value:1, done:false}
iter1.next(); // {value:2, done:false}
iter1.next(); // {value:undefined, done:true}


const iter2 = slice(0, 2, 'abcde'); // [1, 2]
iter2.next(); // {value:'a', done:false}
iter2.next(); // {value:'b', done:false}
iter2.next(); // {value:undefined, done:true}

Add `reverse` function

Suggestion

⭐ Suggestion

Returns the given elements in reverse order.

💻 Use Cases

reverse([1,2,3,4,5,6]); // [6,5,4,3,2,1]
reverse('abcde'); // 'edcba'

FxTS v0.3 plan

New Functions

Lazy

• pluck
• dropWhile & dropUntil
• zipWith
• split

Strict

• pick & omit
• pickBy & omitBy
• join
• includes (alias as contains)
• findIndex
• nth
• sort
• isObject
• isNil

Function Composition

• curry

Add `size` function

Suggestion

⭐ Suggestion

💻 Use Cases

size(range(10, 16)); // 5
await size(toAsync(range(10, 16))); // 5

Add `findIndex` function

Suggestion

⭐ Suggestion

Returns the index of the first element of Iterable/AsyncIterable which matches f, or -1 if no element matches.

💻 Use Cases

const arr = [{a:1}, {a:2}, {a:3}]
findIndex((obj) =>  obj.a === 1, arr); // 0 
findIndex((obj) =>  obj.a === 2, arr); // 1 
findIndex((obj) =>  obj.a === 4, arr); // -1

Add `isObject` function

Suggestion

⭐ Suggestion

https://lodash.com/docs/4.17.15#isObject

Since the purpose of this function is to check only objects, not primitive values, it seems to be implemented in the same way as isObject of lodash.

💻 Use Cases

https://lodash.com/docs/4.17.15#isObject

Add `apply` function

Suggestion

⭐ Suggestion

💻 Use Cases

apply(Math.max, [1, 2, 3, 4, 5]); // 5

pipe(
  repeat(10),
  map(a => a * Math.random())
  take(5),
  apply(max)
);

Add `noop` function

Suggestion

⭐ Suggestion

Returns undefined

💻 Use Cases

noop() // undefined

Add `evolve` function

Suggestion

⭐ Suggestion

💻 Use Cases

  const add1 = (a: number) => a + 1;
  const toUpper = (a: string) => a.toUpperCase();

  const obj = { a: 1, b: 'hello', c: true };

  evolve({ a: add1, b: toUpper, c: not }, obj);
  // { a: 2, b: 'HELLO', c: false }

Add `repeat` function

Suggestion

⭐ Suggestion

Returns a Iterable/AsyncIterable of size n containing a specified value.

💻 Use Cases

const iter = repeat(2, 10);
iter.next(); // {value: 10, done:false}
iter.next(); // {value: 10, done:false}
iter.next(); // {value: undefined, done:true}

// with pipe
pipe(
  repeat(2, 10),
  toArray,
); // [10, 10]

Add `differenceBy` function

Suggestion

⭐ Suggestion

💻 Use Cases

const iter = differenceBy(a => a.x, [{ x: 1 }, { x: 4 }], [{ x: 1 },  { x: 2 },  { x: 3 } ])
iter.next(); // {value: {x: 2}, done: false}
iter.next(); // {value: {x: 3}, done: false}
iter.next(); // {value: undefined, done: true}

Add `split` function

Suggestion

⭐ Suggestion

Splits string by separator. (not support unicode)

💻 Use Cases

const iter = split(',', '1,2,3,4,5,6');
iter.next(); // 1
iter.next(); // 2
iter.next(); // 3
iter.next(); // 4
iter.next(); // 5
iter.next(); // 6
iter.next(); // undefined

Provide lazy functions first

Suggestion

⭐ Suggestion

tc39 also prepares methods for lazy evaluation.
We need to develop the functions being prepared in tc39 in advance.

Additional context
fxts can be evaluated concurrently, and it is also meaningful in that it is provided as a function rather than a method.

If the above proposal(tc39) is reflected, it is likely that our library can be used with native methods. like lodash

💻 Use Cases

refer
https://github.com/tc39/proposal-iterator-helpers

Add `difference` function

Suggestion

⭐ Suggestion

Returns Iterable/AsyncIterable of all elements in the iterable2 not contained in the iterable1.

💻 Use Cases

const iter = difference([2,1], [2,3]);
iter.next(); // {value: 3, done:false}
iter.next(); // {value: undefined, done: true}

Add `sort` function

Suggestion

⭐ Suggestion

Same logic as the Array.prototype.sort function, but acceptsIterable and AsyncIterable as arguments.

💻 Use Cases

const iter = [1, 2, 3, 4, 5].revers()[Symbol.iterator]();
const asyncIter = toAsync([1, 2, 3, 4, 5].revers()[Symbol.iterator]());

sort((a, b) => a - b, iter); // [1, 2, 3, 4, 5]
await sort((a, b) => a - b, asyncIter); // [1, 2, 3, 4, 5]

Add `add` function

Suggestion

⭐ Suggestion

💻 Use Cases

add(1, 2); // 3
await add(1, Promise.resolve(3)); // 4

add('a', 'b'); // 'ab'
await add('a', Promise.resolve('c')); // 'ac'

Suggest squash merge when merged main branch

Suggestion

Hello. If you open the main branch's command log now, you can see unnecessary merge commits mixed in.

These noise commits do not help make pretty commitments.

Why don't we force a square merge when we merge the main branch?

Image

Add `scan` function

Suggestion

⭐ Suggestion

💻 Use Cases

const iter = scan((acc, cur) => acc * cur, 1, [1, 2, 3, 4 ]);
iter.next(); // {value: 1, done:false}
iter.next(); // {value: 1, done:false}
iter.next(); // {value: 2, done:false}
iter.next(); // {value: 6, done:false}
iter.next(); // {value: 24, done:false}
iter.next(); // {value: undefined, done: true}

Add `min` and `max` functions

Suggestion

⭐ Suggestion

💻 Use Cases

min([5, 3, 1]); // 1;
min([5, NaN, 1]); // NaN;

max([1, 3, 5]); // 5;
max([1, NaN, 1]); // NaN;
max([1, Infinity, 1]); // Infinity;

await min(toAsync([5, 3, 1])); // 1;
await max(toAsync([1, 3, 5])); // 5;

Add `sum` function

Suggestion

⭐ Suggestion

💻 Use Cases

sum([1,2,3,4,5]); // 15
sum(['a', 'b', 'c']); // 'abc'

await sum(toAsync([1,2,3,4,5])); // 15
await sum(toAsync(['a', 'b', 'c'])); // 'abc'

Add `entries` function

Suggestion

⭐ Suggestion

Returns an Iterable/AsyncIterable of key-value pairs for the given object

💻 Use Cases

const iter = entries({a:1,b:2,c:3});
iter.next(); // {value: ['a', 1] , done:false}
iter.next(); // {value: ['b', 2] , done:false}
iter.next(); // {value: ['c', 3] , done:false}
iter.next(); // {value: undefined , done: true}

Feature ` dropWhile` `dropUntil` function

Suggestion

⭐ Suggestion

• dropWhile(Lazy):
  Returns Iterable/AsyncIterable excluding elements dropped from the beginning. Elements are dropped until the value applied to f returns falsey.

• dropUntil(Lazy):
  Returns Iterable/AsyncIterable excluding elements dropped from the beginning. Elements are deleted until the value applied to f returns truly. (It is deleted including the value applied as true.)

💻 Use Cases

const dropWhileIter = dropWhile(a => a < 5, [1,2,3,4,5,6,7,8,9,10]);
dropWhileIter.next(); // 5
dropWhileIter.next(); // 6
dropWhileIter.next(); // 7
dropWhileIter.next(); // 8
dropWhileIter.next(); // 9
dropWhileIter.next(); // 10

const dropUntilIter = dropUntil(a => a > 5, [1,2,3,4,5,6,7,8,9,10]);
dropUntilIter.next(); // 7
dropUntilIter.next(); // 8
dropUntilIter.next(); // 9
dropUntilIter.next(); // 10

Add `sortBy` function

Suggestion

⭐ Suggestion

💻 Use Cases

const products = [
  { id: 1, name: 'T-shirt', price: 50 },
  { id: 2, name: 'Phone case', price: 30 },
  { id: 3, name: 'Key ring', price: 15 },
];
sortBy(a => a.price, products);

Add `isEmpty` function

Suggestion

⭐ Suggestion

Returns true if the given value is empty value, false otherwise.

💻 Use Cases

isEmpty(1); // false
isEmpty(0); // false
isEmpty(false); // false
isEmpty(true); // false
isEmpty(new Date()); // false
isEmpty(undefined); // true
isEmpty(null); // true

isEmpty({}); // true
isEmpty({a:1}); // false

isEmpty([]); // true
isEmpty([1]); // false

isEmpty(""); // true
isEmpty("a"); // false

isEmpty(function(){}); // false
isEmpty(Symbol("")); // false

feat: contribution guideline

There is no contribution guideline yet, so we'd better make it.

example
https://github.com/mattermost/mattermost-server/blob/master/CONTRIBUTING.md
https://github.com/firebase/firebase-js-sdk/blob/master/CONTRIBUTING.md
https://github.com/yorkie-team/yorkie/blob/main/CONTRIBUTING.md
https://reactjs.org/docs/how-to-contribute.html

`npm run test` failed intermittently due to timeout

Bug Report

💻 Code

npm run test failed intermittently due to timeout.

🙁 Actual behavior

The setTimeout set in test does not match intermittently.

🙂 Expected behavior

The test action should always succeed.

---

Version Infomation

• Operating system:
• Typescript:
• Nodejs: 16.3.0

Add `pluck` function

Suggestion

⭐ Suggestion

Returns Iterable/AsyncIterable by plucking the same named property off all objects in Iterable/AsyncIterable supplied.

💻 Use Cases

const iter = pluck('age', [{age:21}, {age:22}, {age:23}]);
iter.next(); // 21
iter.next(); // 22
iter.next(); // 23

Show test coverage

Suggestion

⭐ Suggestion

All the intended parts are meeting the tests.
By displaying coverage to users, we can make it appear more reliable.

Add `fork` function

Suggestion

⭐ Suggestion

💻 Use Cases

Add `nth` function

Suggestion

⭐ Suggestion

Returns the nth element of the given Iterable/AsyncIterable

💻 Use Cases

nth(2, [1,2,3,4]); // 1
nth(5, [1,2,3,4]); // undefined
nth(2, ['name', 'gender', 'age']); // 'age'
nth(3, ['name', 'gender', 'age']); // undefined
nth(2, 'abcdefg'); // 'b'
nth(10, 'abcdefg'); // undefined

v0.4 Iteration Plan

Lazy

• #67
• #72
• #69
• #87
• #73
• #60
• #78
• #80
• #81
• #82
• #85
• #86

Function

• #83
• #61
• #63

Strict

• #84
• #68
• #71
• #74
• #64
• #75
• #76
• #77
• #79
• #66