feat(functions): adding a functions module with pipe()

[guy-borderless]

Hi,
I'd like to suggest adding an std module for utilities related to functions.

related: #4386

There are common manipulations to functions implemented in numerous npm packages and toolbelts, and using them where appropriate greatly improves code quality. It would be handy to have these in deno_std.
I want to suggest for starters the following two:

1. pipe
2. set_arguments (currying / dependency injection)

These two scenarios have some typescript knowledge behind them and it makes sense to reach for a proper utility.

Both of these have many different implementations in terms of code and typings. In my opinion, the implementation most in line with the pragmatic spirit of the std should avoid functional programming jargon for simplicity and accessibility to beginners.

For discussion in this PR I have included two implementations (without tests) that I think would suit the deno_std

pipe has good typescript performance and small implementation. I'm also using it in several projects.

set_arguments has a very non-academic intuitive signature that I think suites nicely with the deno_std. This signature does not expect a data-last coding convention, so it doesn't leak to the rest of the code. I have also provided a more classic functional programming implementation of this called curry to contrast.

I can significantly simplify the typing definition of set_arguments if you'd like me to go ahead with preparing this PR.

Since functions are an important primitive in JS, I'm sure more utilities will be added.

[kt3k]

Are pipe and set_arguments common in JS ecosystem? I rarely see them in various code bases.

I personally think inline arrow functions express the operation like set_arguments better.

const myNewFunc = set_arguments(myFunc, 1, undefined, 3);
// vs
const myNewFunc = (x: number) => myFunc(1, x, 3);

[guy-borderless]

Are pipe and set_arguments common in JS ecosystem? I rarely see them in various code bases.

I personally think inline arrow functions express the operation like set_arguments better.

const myNewFunc = set_arguments(myFunc, 1, undefined, 3);
// vs
const myNewFunc = (x: number) => myFunc(1, x, 3);

Both curry and pipe are very common and implemented by all lodash style toolbelts (including lodash of course), as well as many specific packages. Your example works because you have the number primitive. In cases of a business object, which you may or may not control, it's much nicer to use something like curry or set_arguments.

pipe is a common pattern, for example in ETL code when you have a lot of linear transformations, it makes the code much more readable, as it prevents spaghetti.

[kt3k]

Your example works because you have the number primitive.

I don't understand this. Inline arrow function example should work with any parameters available in that scope. I think that has the same capability as what set_arguments (or curry) can do.

BTW do you suggest curry or set_arguments? or both?

pipe is a common pattern, for example in ETL code when you have a lot of linear transformations, it makes the code much more readable, as it prevents spaghetti.

Can you elaborate on more specific examples where pipe is better for readability? The given example looks too trivial to replace with simple function composition.

const func = pipe(Math.abs, Math.sqrt, Math.floor);
//
const func = (num: number) => Math.floor(Math.sqrt(Math.abs(num)))

[guy-borderless]

Your example works because you have the number primitive.

I don't understand this. Inline arrow function example should work with any parameters available in that scope. I think that has the same capability as what set_arguments (or curry) can do.

BTW do you suggest curry or set_arguments? or both?

pipe is a common pattern, for example in ETL code when you have a lot of linear transformations, it makes the code much more readable, as it prevents spaghetti.

Can you elaborate on more specific examples where pipe is better for readability? The given example looks too trivial to replace with simple function composition.

const func = pipe(Math.abs, Math.sqrt, Math.floor);
//
const func = (num: number) => Math.floor(Math.sqrt(Math.abs(num)))

I see set_arguments as just a less functional version of curry, so if we want to be more strict it's either, depending on the policy.

Yes, of course, you can create an arrow function to inject parameters:

const fnWithFirstDeps = (dataArg: Parameters<typeof fn>[2]) => fn(dependency1, dependency2, dataArg)

I think it's a common and rather generic need, so having a utility that obviates the need to create a local function for it and improves readability is handy, while also encouraging a good coding practice (dependency injection). Sometimes different parts of the code inject different dependencies, having a utility encourages doing the injection locally and not creating another function or re-using the above function which entangles concerns.

const fnWithFirstDeps = setArguments(fn, dependency1, dependency2,)

pipe is useful in data processing. You don't want to compose many functions to create a pipe as this creates long bracket scopes and isn't readable. Here is a less trivial example:

const extracted = {
  bedrooms:  pipe(
      selectOne.attributes,
      parseMatchingText("bedrooms"),
      removeLabel,
      parseNumber,
    ),
  bathrooms:  pipe(
      selectOne.attributes,
      h.parseMatchingText("bathrooms"),
      removeLabel,
      parseNumber,
    ),
}

[kt3k]

I'm also not a fan of these typings. curry and setArguments seem having limits in number of arguments, while inline arrow function composition doesn't have such limitation. The type of pipe function looks extremely hard to understand. I guess the type error message will be also harder to understand with pipe than plain function composition.

[kt3k]

(BTW while I'm personally not in favor of this, we are open for adding this package if there's enough community support to this idea.)

[guy-borderless]

I'm also not a fan of these typings. curry and setArguments seem having limits in number of arguments, while inline arrow function composition doesn't have such limitation. The type of pipe function looks extremely hard to understand. I guess the type error message will be also harder to understand with pipe than simpler function composition.

Typing for a number of arguments is very common and gives a good experience. As far as I can see, it's a theoretical, not a practical issue.

[iuioiua]

This PR and #4386, which has been open since February, have had near-zero community support. Perhaps, it'd be best to have this done as a 3rd party package and see if it evolves enough to provide a stronger argument for its addition sometime in the future.

[Kacaii]

Honestly pipe would help a ton. Looking forward to this one!

[kt3k]

@guy-borderless Can you limit this PR to pipe function? Also can you write test cases for it?

[guy-borderless]

@guy-borderless Can you limit this PR to pipe function? Also can you write test cases for it?

Of course! On it.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.32%. Comparing base (05b6d7e) to head (9fc723a).
Report is 183 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6143      +/-   ##
==========================================
+ Coverage   96.29%   96.32%   +0.03%     
==========================================
  Files         493      544      +51     
  Lines       39530    41610    +2080     
  Branches     5833     6313     +480     
==========================================
+ Hits        38065    40082    +2017     
- Misses       1423     1485      +62     
- Partials       42       43       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[guy-borderless]

Per feedback, PR was limited to pipe() and tests were added.

[BlackAsLight]

Per feedback, PR was limited to pipe() and tests were added.

You also got to get all the tests to pass. Looks like the title isn't named right and you're missing the copyright notice in some of the files.

[guy-borderless]

Per feedback, PR was limited to pipe() and tests were added.

You also got to get all the tests to pass. Looks like the title isn't named right and you're missing the copyright notice in some of the files.

The PR naming issue seems to be because the functions module is new and so a scope doesn't exist for it. Added the copyright notice, thanks for mentioning it (didn't seem to cause a test to fail)

[BlackAsLight]

Why did you remove the importMap here for imports? This will probably need to be reverted.

[BlackAsLight]

A "@std/functions": "jsr:@std/functions@^0.1.0" will also probably need to be added to the importMap for the later lint error to fix itself.

[kt3k]

Please revert these changes as @BlackAsLight points. import_map.json is shared between deno.json and browser-compat.tsconfig.json. That is why we don't write these mappings here.

[guy-borderless]

added the
"importMap": "./import_map.json",
removed by mistake.
Is that all?

[BlackAsLight]

These exports are also going to need JSDoc comments to satisfy the linter. You can do deno task ok locally to check that it satisfies the requirements.

[BlackAsLight]

The PR naming issue seems to be because the functions module is new and so a scope doesn't exist for it.

I believe a change needs to happen in .github/workflows/title.yml to recognise the functions scope. Possibly other places in .github/ as well.

[kt3k]

This doesn't describe this module

[guy-borderless]

should I add the functions module to import_map.json here?

[BlackAsLight]

should I add the functions module to import_map.json here?

Yes