Grouping data format modules under one namespace

[not-my-profile]

The first page of the std documentation currently lists 33 directories:

archive, async, bytes, collections, console, crypto, csv, datetime, dotenv, encoding, examples, flags, fmt, front_matter, fs, html, http, io, json, jsonc, log, media_types, path, permissions, regexp, semver, signal, streams, testing, toml, uuid, wasi, yaml

I think this makes the standard library a bit hard to grasp. I think it would be better to group all data format modules (csv, json, jsonc, toml, yaml) together under one directory.

According to the README "deno_std is a loose port of Go's standard library", so we could do what the Go standard library does and have these under the "encoding" namespace. Note that we already have an encoding directory, but currently it only contains modules for ascii85, base32, base58, base64, base64url, binary, hex and varint.

What do you think about this idea?

[not-my-profile]

Ah I just saw that they were previously under encoding and have been moved to the top-level (#3123) this year :/

But the reasoning really seems flawed to me ... I really don't think that it makes sense for a standard library to abandon organization just to cater to the poor search implementation of tooling (the deno.land website and the language server) when these shortcomings could very well be addressed by those tools without resorting to having all modules at the top-level.

[lino-levan]

when these shortcomings could very well be addressed by those tools without resorting to having all modules at the top-level.

Agreed, but I think we just have to wait until those shortcomings are fixed before we try to organize std any differently.

[iuioiua]

But the reasoning really seems flawed to me ... I really don't think that it makes sense for a standard library to abandon organization just to cater to the poor search implementation of tooling (the deno.land website and the language server) when these shortcomings could very well be addressed by those tools without resorting to having all modules at the top-level.

I'd agree if that were the case, but the restructuring wasn't done just to cater to a poor search implementation if it is, in fact, poor. It was mostly done because the sub-modules within std/encoding were of sufficient size and complexity that they justified instead being moved to modules and being made more discoverable from a file-structure point of view.

[not-my-profile]

because the sub-modules within std/encoding

I think technically std/encoding isn't a module because it doesn't contain a mod.ts but I'd still make the same argument even if std/encoding/mod.ts existed.

of sufficient size and complexity that they justified instead being moved to modules

I see absolutely no reason to determine the location of a module by its size and complexity. I think that organizing modules by topic makes much more sense and it's also what the standard libraries of Go and Rust do (e.g. Go has encoding/csv, encoding/json, encoding/xml, net/http, Rust has std::os::unix, std::os::windows, etc.). For example if the Deno standard library were to gain a MIME multipart parser, it should surely be under std/media_types no matter how complex it is.

and being made more discoverable from a file-structure point of view

That depends on where you are in the file structure. If you're looking at the encoding directory, the json module would be more discoverable if it was there. So you're specifically referring to the top-level directory. That directory currently already contains so many entries that when viewed via GitHub or deno.land you have to scroll to view all of its entries, and it will only get longer as more top-level modules are added. Scrolling and manually reading is already slower than simply searching the page with Ctrl+F, however that will of course only find what's present on the page and won't find e.g. the base64.ts module.

The best way to search an API for a module is to use a search function that will find the module no matter where it is in the directory structure. And when it comes to the discoverability of Deno modules the single two most important user interfaces quite clearly are the Deno language server and the deno.land website. If their respective autocompletion and search implementations would be able to look beyond the top-level, there would be absolutely no discoverability problem with modules like encoding/json.

Agreed, but I think we just have to wait until those shortcomings are fixed

I'll look into fixing these shortcomings.

[kt3k]

Closing due to the inactivity

[kt3k]

A few notes:

• We now have encoding/mod.ts.
• We have now 2 other data formats: msgpack and ini.