Rename front-matter/any.ts to front-matter/extract.ts

[timreichen]

Is your feature request related to a problem? Please describe.

Lots (if not most) of @std files are single export files wich only export one function or class.
The file name is normally the same as the exported thing (case may be adjusted, prefixed files with unstable are special treated).
Files that differ from that pattern are mostly multi export files (for example fmt/colors.ts).

There are multiple files in @std/front-matter that do not conform to any of these conventions:

• front-matter/any.ts exports extract()
• front-matter/json.ts exports extract()
• front-matter/toml.ts exports extract()
• front-matter/yaml.ts exports extract()
• front-matter/unstable_yaml.ts exports extract()

In front-matter/mod.ts the extract() functions even have aliases because their names overlap.

Describe the solution you'd like

I think we should enforce any apply that convention to front-matter:

• rename front-matter/any.ts to front-matter/extract.ts
• rename front-matter/json.ts to front-matter/extract_json.ts, rename exported function from extract() to extractJson()
• rename front-matter/toml.ts to front-matter/extract_toml.ts, rename exported function from extract() to extractToml()
• rename front-matter/json.ts to front-matter/extract_yaml.ts, rename exported function from extract() to extractYaml()

I am aware that front-matter is stable, but this issue may be part of 2.0 which I imagine would allow for breaking changes.
(@kt3k Is there a roadmap for 2.0 mods?)

In the meantime, We could add aliases for a smooth transition.

Describe alternatives you've considered

Don't enforce convention.

[kt3k]

This needs consensus in both core team and community.

I'm personally not in favor of this change. I've never heard of the user feedbacks of getting confused by this structure. On the other hand, there are many usages in github search https://github.com/search?q=std%2Ffront-matter&type=code . Many of them import extract from ./any or ./yaml. I think the current structure is already reasonably accepted by the community. So I don't see much value to this change, rather I only see the negative effect of disrupting the existing usages.

[timreichen]

I feel very strongly about this, there is much to gain:

• enforcement of the convention
• removal of these files on the skip list in _tools/check_mod_exports.ts (which shows imo that this is not as it should be as the other files on that list are dotenv/load.ts which executes code on import, uuid version files or std conventional or deno special files)
• Avoidance of the same function by different names (extract() in json.ts === extractJson() in mod.ts, same with yaml and toml)

I think calling the functions and files what they are now was a overlooked mistake in hindsight and should definitely be corrected now before it might come back later to haunt us.
I don't think this would be too disrupting as it will be a breaking change only with the next major version and the community that is prepared by deprecation notes.