denoland / denoland/std

Proposal: deprecate `@std/io`

Open
#7,258 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
3.6k
Forks
681
PR merge metrics
No merged PRs in 30d

Description

## Summary

I propose we formally deprecate `@std/io`: `@deprecated` tags on every export with a migration target, a notice in the module docs and README, and JSR archival once the one real migration gap closes. This isn't a new decision. When #5003 was closed, the stated plan was to stop stabilizing the package and "nudge people to use `@std/streams` instead", with a detailed follow-up issue to come. That issue never landed. Today nothing in the package tells users any of this.

## Current state

- The package sits at 0.225.3 with no path to 1.0, per #5003.
- The module doc says "many of these utilities are also deprecated", but zero exports carry a `@deprecated` JSDoc tag. Editors and JSR docs surface nothing.
- JSR lists 131 dependent packages, so people keep adopting it without knowing its status.
- Piecemeal removal already started: `StringReader` (#6062), `StringWriter` (#6061), and `MultiReader` (#6059) are gone.

## Migration targets

| Export | Replacement |
| --- | --- |
| `Buffer` | `Buffer` from `@std/streams` |
| `copy` | `readable.pipeTo(writable)` |
| `iterateReader` | `ReadableStream` is async iterable |
| `readAll` | `toBytes` from `@std/streams` |
| `toReadableStream` / `toWritableStream` / `readerFromStreamReader` | Deno 2 resources expose `.readable` / `.writable` natively |
| `writeAll` | `ReadableStream.from([data]).pipeTo(writable, { preventClose: true })` |
| `readAllSync` / `writeAllSync` | none yet, see below |

## The sync gap

Web streams are async only, so `readAllSync` and `writeAllSync` have no replacement today. #6284 tracks the main use case (fully written sync output to stdout/stderr), and the suggested fix lives in the runtime, not std. I'd deprecate everything now, point the sync functions' `@deprecated` notes at #6284, and gate removal and JSR archival on that resolving.

## Proposed steps

1. Add `@deprecated` tags to all exports with the targets above. Happy to send the PR.
2. Add the deprecation notice to the module doc and the README package table.
3. Once #6284 resolves: archive on JSR and remove from the workspace.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.