diff --git a/Roadmap.md b/Roadmap.md index 69af482e05d822..2a6f614b7ec2cb 100644 --- a/Roadmap.md +++ b/Roadmap.md @@ -243,3 +243,101 @@ Fetch API: ```ts fetch(input?: Request | string, init?: RequestInit): Promise; ``` + +#### I/O + +There will be two API layers for I/O: +1. A low-level abstraction with (for sockets) non-blocking read/writes operating +on FDs. (Yet unspecified - but probably very similar to the unix syscalls.) + +2. A high-level API that will closely follow Go's I/O interfaces. The tentative +intrefaces are outlined below: +```ts +interface Reader { + // Reader is the interface that wraps the basic Read method. + // + // Read reads up to p.byteLength bytes into p. It returns the number of bytes + // read (0 <= n <= p.byteLength) and any error encountered. Even if Read + // returns n < p.byteLength, it may use all of p as scratch space during the + // call. If some data is available but not p.byteLength bytes, Read + // conventionally returns what is available instead of waiting for more. + // + // When Read encounters an error or end-of-file condition after successfully + // reading n > 0 bytes, it returns the number of bytes read. It may return the + // (non-nil) error from the same call or return the error (and n == 0) from a + // subsequent call. An instance of this general case is that a Reader + // returning a non-zero number of bytes at the end of the input stream may + // return either err == EOF or err == nil. The next Read should return 0, EOF. + // + // Callers should always process the n > 0 bytes returned before considering + // the error err. Doing so correctly handles I/O errors that happen after + // reading some bytes and also both of the allowed EOF behaviors. + // + // Implementations of Read are discouraged from returning a zero byte count + // with a nil error, except when p.byteLength == 0. Callers should treat a + // return of 0 and nil as indicating that nothing happened; in particular it + // does not indicate EOF. + // + // Implementations must not retain p. + // + // Copied from Go https://golang.org/pkg/io/#Reader + async read(p: Uint8Array): [number, IOError]; +} + +interface Writer { + // Writer is the interface that wraps the basic Write method. + // + // Write writes p.byteLength bytes from p to the underlying data stream. It + // returns the number of bytes written from p (0 <= n <= p.byteLength) and any + // error encountered that caused the write to stop early. Write must return a + // non-nil error if it returns n < p.byteLength. Write must not modify the + // slice data, even temporarily. + // + // Implementations must not retain p. + // + // Copied from Go https://golang.org/pkg/io/#Writer + async write(p: Uint8Array): [number, IOError]; +} + +interface Closer { + // The behavior of Close after the first call is undefined. Specific + // implementations may document their own behavior. + // Copied from Go https://golang.org/pkg/io/#Closer + close(): IOError; +} + +interface Seeker { + // Seek sets the offset for the next Read or Write to offset, interpreted + // according to whence: SeekStart means relative to the start of the file, + // SeekCurrent means relative to the current offset, and SeekEnd means + // relative to the end. Seek returns the new offset relative to the start of + // the file and an error, if any. + // + // Seeking to an offset before the start of the file is an error. Seeking to + // any positive offset is legal, but the behavior of subsequent I/O operations + // on the underlying object is implementation-dependent. + // + // Copied from Go https://golang.org/pkg/io/#Seeker + seek(offset: number, whence: number): [number, IOError]; +} + +// https://golang.org/pkg/io/#ReadCloser +interface ReaderCloser extends Reader, Closer { } + +// https://golang.org/pkg/io/#WriteCloser +interface WriteCloser extends Writer, Closer { } + +// https://golang.org/pkg/io/#ReadSeeker +interface ReadSeeker extends Reader, Seeker { } + +// https://golang.org/pkg/io/#WriteSeeker +interface WriteSeeker extends Writer, Seeker { } + +// https://golang.org/pkg/io/#ReadWriteCloser +interface ReadWriteCloser extends Reader, Writer, Closer { } + +// https://golang.org/pkg/io/#ReadWriteSeeker +interface ReadWriteSeeker extends Reader, Writer, Seeker { } +``` + +