The Road to Stabilizing the Standard Library

[iuioiua]

The Standard Library (std) aims to provide high-quality, reliable APIs for fearless use in JavaScript and TypeScript projects. For some time, how and when std would reach stability has been in question. Now, thanks to JSR and workspaces functionality in the Deno runtime, we have a path forward.

What stabilization will look like

Currently, std acts as a single module with a single version, meaning a user may be inclined to upgrade, even if a release doesn’t affect the sub-module they use.

After stabilization, new std packages will be exclusively hosted on JSR as separate packages with independent versions. Deno’s workspaces functionality allows us to treat each top-level subdirectory as its own package and better adhere to Semantic Versioning. Dependencies become more manageable by only requiring an upgrade for the packages you use, not the entire std module.

More importantly, independent versioning allows us to work on stabilizing packages asynchronously. We can stabilize more established packages while preparing other packages for stabilization. In other words, we can progressively deliver stable packages for the community sooner rather than later.

These changes will also mean we will release std packages independently of Deno runtime releases.

How we’ll achieve stability

Step 1 - Decouple std from the runtime (complete)

deno and deno_std are now effectively decoupled, so releasing them in tandem is not required. The remaining point of friction is apiland_scripts, which generates docs. We now have two separate GH Actions in apiland_scripts that can be run independently (release CLI and release STD). These actions can be run independently, and it’s a matter of deciding if we do the “split”.

Step 2 - Publish exclusively to JSR (complete)

At the moment, std is published to deno.land/std as-is, then converted into a JSR-compatible form in CI and published to JSR as separate packages under the @std scope. Once the previous step is complete, the codebase can be permanently converted into its JSR-compatible form, providing the granular package versioning for the next step.

Note: For the foreseeable future, deno.land/std will remain online and accessible until the version before the JSR cutover is complete.

Step 3 - Stabilize packages asynchronously (in progress)

Once std is entirely cut over to JSR and packages become more stable, we can begin stabilizing packages. While the specifics have yet to be defined, a package will only be stabilized once strict criteria are met that guarantee its quality. These will require that each package is:

1. Reviewed and approved with sufficient consensus
2. Tested for maximum coverage
3. Fully documented and well-designed
4. Void of any ongoing issues or known bugs
5. Well supported across many versions of the Deno runtime

Current work

Work towards stabilizing each package is already in progress. This work includes:

• Completing documentation (tracking: complete documentation #3764)
• Increasing test coverage (tracking: improve test coverage #3713)
• Fixing bugs and adding missing features
• Closing issues and PRs
• Improving API design

You can track the stability status of each package here:

• archive
• proposal: stabilize std/assert #4717
• async
• proposal: stabilize std/bytes #4629
• cli
• proposal: stabilize std/collections #4647
• console
• crypto
• csv
• data_structures
• datetime
• dotenv
• encoding
• expect
• fmt
• front_matter
• fs
• html
• http
• ini
• feat(internal): internal@1.0.0 #4706
• io
• json
• jsonc
• log
• media_types
• msgpack
• net
• path
• regexp
• semver
• streams
• testing
• text
• toml
• ulid
• url
• uuid
• webgpu
• yaml

If you’d like to contribute to stabilizing the Standard Library in any of this work, please feel free to let us know, either on GitHub or Discord. All contributions are welcome and very much appreciated.

[jollytoad]

I'd love to see this become the gold standard of JSR packaging, esp multi-package libraries, and ideally see all scripts/tooling/cross-runtime testing used by the lib become a first class set of modules within the library itself, so that other authors can model their libraries on @std, and benefit from its tooling. I want you follow your model closely in my own library and would be more than happy to contribute to generic tooling and @std itself.

[iuioiua]

That'd be great! Improving test coverage is one of the valuable contributions that can be made right now. If you're willing and able, please let us know which package(s) you'd like to look at in #3713. I'll keep you in mind when tooling is needed.

[KnorpelSenf]

I agree that it makes sense to stabilise the different parts of the standard library at different points in time. However, it is rather annoying to have independent versions for each module.

Currently, we're moving towards a myriad of independent modules, and it adds a fair bit of accidental complexity to let the combinations of (#modules * #versions) explode like that.

I believe that it is a good idea to version the modules independently for the transitional period until almost everything is stable. After that, it would be best to sync up the versions again so that we can return to having The Standard Library again.

[iuioiua]

If all packages share a common, synced version, how should the versions of other packages be affected if a single package needs a release?

so that we can return to having The Standard Library again.

I'm unsure what you mean here. Can you please clarify?