chore: deprecate flat

[MarlonPassos-git]

Tip

The owner of this PR can publish a preview release by commenting /publish in this PR. Afterwards, anyone can try it out by running pnpm add radashi@pr<PR_NUMBER>.

Summary

Update the JSDOC and documentation about the function being deprecated.

Related issue, if any:

https://github.com/orgs/radashi-org/discussions/84

For any code change,

• Related documentation has been updated, if needed
• Related tests have been added or updated, if needed
• Related benchmarks have been added or updated, if needed

Does this PR introduce a breaking change?

Yes

Bundle impact

Status	File	Size 1	Difference (%)
M	src/array/flat.ts	49	-28 (-36%)

Footnotes

1. Function size includes the import dependencies of the function. ↩

[aleclarson]

Debating whether to merge this into the next minor or major version. 🤔

The SemVer spec states the following:

How should I handle deprecating functionality?

Deprecating existing functionality is a normal part of software development and is often required to make forward progress. When you deprecate part of your public API, you should do two things: (1) update your documentation to let users know about the change, (2) issue a new minor release with the deprecation in place. Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.

But, considering how VSCode does a "strike-through" of deprecated APIs, I wonder if saving deprecations for a major version isn't a more user-friendly policy.

Any thoughts, @radashi-org/core?

[MarlonPassos-git]

Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.

I prefer a minor release for the @deprecated in JSDOC and a major release for code remotion.
We can pass a long time to remove something if we wait for one major release to alert us about deprecation and another major release to remove.

[radashi-bot]

Benchmark Results

Name	Current	Baseline	Change
flat ▶︎ with non-empty input list	835,525.32 ops/sec ±0.18%	3,440,316.31 ops/sec ±0.19% 🔗	🐢 -75.71%

Performance regressions of 30% or more should be investigated, unless they were anticipated. Smaller regressions may be due to normal variability, as we don't use dedicated CI infrastructure.

[github-actions]

A new beta version 12.2.0-beta.6b76988 has been published to NPM. 🚀

To install:

pnpm add [email protected]

The radashi@beta tag also includes this PR.

[aleclarson]

Note: I replaced the old _.flat implementation with one that uses Array.prototype.flat instead, since they are equivalent behavior.

But somehow, I read the benchmark results as a +75% improvement, so I merged prematurely. Sadly, using Array.prototype.flat appears to be about 75% slower than the Radash implementation.

That's quite surprising, considering that Array.prototype.flat is a native method. 🤔

I wonder if we should revert the deprecation or should we assume that (1) Array.prototype.flat will get faster in time and (2) ~800K ops/sec is fast enough for most use cases. Thoughts, @radashi-org/core?

edit: I should note that the benchmark for _.flat includes the allocation of the array of nested arrays (see here). So 800K ops/sec is not actually how slow Array.prototype.flat is. Nonetheless, the performance gap between the Radash implementation and Array.prototype.flat is still accurate.

[aleclarson]

I'm gonna have to revert this, because Array.prototype.flat was added in ES2019, and we're going to support browsers as old as ES2017 (without legacy transforms).

I thought eslint-plugin-compat would catch this, but it (sadly) doesn't actually check method usage: amilajack/eslint-plugin-compat#258

I'm in the process of updating our tsconfig.json to use "es2017" instead of "esnext" so we can catch these issues with our pnpm lint script. I chose ES2017 because that's when async-await syntax was introduced.

[MarlonPassos-git]

What do you mean by keeping jsdoc saying that there is currently a native implementation in ES2019?

[aleclarson]

@MarlonPassos-git That's a good idea! PR welcome :)