Why are many APIs still containing legacy "generic" sub-APIs? (e.g. Buffer)

[cookiengineer]

Hey everyone,

I was wondering why many of the stable-declared APIs still contain legacy variants of themselves.
I think this is a critical issue when declaring a software stable, because the API should be declared stable and the variants from the past should be declared deprecated.

I'm refering mostly to the Buffer API, because you can see the point much easier there:
https:/iojs/io.js/blob/v1.x/lib/buffer.js#L29

I know; on one side you don't want to break compatibility with nodejs and on the other hand you have thousands of libraries using those "generically" designed APIs that accept pretty much any data type in their constructor. But from my view the potential issues in future when it comes to testing, verification and potential security leaks the chances get higher exponentially when using this type of API design.

In terms of performance and later releases, is this really wanted?

I mean, if there are methods existing like "Buffer.isBuffer" (that refers to util.isBuffer that refers to buffer instanceof Buffer) it is mostly an indicator that something went really wrong. Why, for example, not simply use "buffer instanceof Buffer" directly and simply not offering a public "isBuffer" method?

~Cheers

[mscdex]

Well, up until node v0.8, Buffer.isBuffer() performed an additional check. So there's that difference.

[Fishrock123]

Probably so we don't unnecessarily break past code all over yet. The jump from 0.10 -> 1.x is large enough as it is.

These legacy things could probably be deprecated in the future. If you'd like, you could make a PR. :)