ia-stream

Streams in Node.js don't have the ability to seek; and you can only read the data in them once. This is majorly inconvient for operations like random access to a file.

The obvious solution is to just use fs methods directly, but this isn't ideal either — what if you need an abstraction where the data behind the stream can come from a place other than a file?

This package provides streams that are modeled after Streams in .NET, allowing random access / seeking, reading data more than once, and providing a Promise-based API.

API

Docs generated using docts

Class FileStream

Source code: <>

Methods:

new( ) ^{⇒ FileStream} <>
 ▪ fd ^FileHandle
 ▪ options ^{FileStreamOptions}
.seek( ) ^{⇒ Promise<boolean>} <>
 Changes the position of the next read in the stream.
 ▪ position ^number
.read( ) ^{⇒ Promise<Buffer>} <>
 Reads some bytes from the stream.
 ▪ length ^number
 ▫ exact_? ^{undefined | true | false}
.readFrom( ) ^{⇒ Promise<Buffer>} <>
 Combines seek and read.
 ▪ position ^number
 ▪ length ^number
 ▫ exact_? ^{undefined | true | false}
.write( ) ^{⇒ Promise<number>} <>
 Writes some data to the stream.
 ▪ data ^Buffer
.resize( ) ^{⇒ Promise<boolean>} <>
 Resizes the source of this stream to a given number of bytes. Streams that
 cannot be written to cannot be resized.
 ▪ length ^number
.close( ) ^{⇒ Promise<void>} <>
 Closes this stream. Once it is closed, any underlying resources (memory buffers,
 file handles) will be freed and this Stream will no longer be usable.
.substream( ) ^{⇒ Promise<Stream>} <>
 Creates an independent Stream that operates on the same source material as this stream.
 This sub-stream will be read-only.
.substream( ) ^{⇒ Promise<Stream>} <>
 Creates an independent Stream that operates on the same source material as this stream.
 This sub-stream will be read-only.
 ▪ from ^number
 ▪ to ^number

Class MemoryStream

Source code: <>

Methods:

new( ) ^{⇒ MemoryStream} <>
 ▪ options ^{MemoryStreamOptionsWithData | MemoryStreamOptionsWithLength}
.seek( ) ^{⇒ Promise<boolean>} <>
 Changes the position of the next read in the stream.
 ▪ position ^number
.read( ) ^{⇒ Promise<Buffer>} <>
 Reads some bytes from the stream.
 ▪ length ^number
 ▫ exact_? ^{undefined | true | false}
.readFrom( ) ^{⇒ Promise<Buffer>} <>
 Combines seek and read.
 ▪ position ^number
 ▪ length ^number
 ▫ exact_? ^{undefined | true | false}
.write( ) ^{⇒ Promise<number>} <>
 Writes some data to the stream.
 ▪ data ^Buffer
.resize( ) ^{⇒ Promise<boolean>} <>
 Resizes the source of this stream to a given number of bytes. Streams that
 cannot be written to cannot be resized.
 ▪ length ^number
.close( ) ^{⇒ Promise<void>} <>
 Closes this stream. Once it is closed, any underlying resources (memory buffers,
 file handles) will be freed and this Stream will no longer be usable.
.substream( ) ^{⇒ Promise<Stream>} <>
 Creates an independent Stream that operates on the same source material as this stream.
 This sub-stream will be read-only.
.substream( ) ^{⇒ Promise<Stream>} <>
 Creates an independent Stream that operates on the same source material as this stream.
 This sub-stream will be read-only.
 ▪ from ^number
 ▪ to ^number

Interface Stream

Source code: <>

Methods:

.seek( ) ^{⇒ Promise<boolean>} <>
 Changes the position of the next read in the stream.
 ▪ position ^number The position to set the cursor to.
.read( ) ^{⇒ Promise<Buffer>} <>
 Reads some bytes from the stream.
 ▪ length ^number The maximum number of bytes to return.
 ▫ exact_? ^{undefined | true | false} If true, then this method will block until length bytes are available or fail.

.readFrom( ) ^{⇒ Promise<Buffer>} <>
 Combines seek and read.
 ▪ position ^number The starting position to read from.
 ▪ length ^number The maximum number of bytes to return.
 ▫ exact_? ^{undefined | true | false} If true, then this method will block until length bytes are available or fail.

.write( ) ^{⇒ Promise<number>} <>
 Writes some data to the stream.
 ▪ data ^Buffer A Buffer containing the data to write.
.resize( ) ^{⇒ Promise<boolean>} <>
 Resizes the source of this stream to a given number of bytes. Streams that
 cannot be written to cannot be resized.
 ▪ length ^number The new length of this stream.
.close( ) ^{⇒ Promise<void>} <>
 Closes this stream. Once it is closed, any underlying resources (memory buffers,
 file handles) will be freed and this Stream will no longer be usable.
.substream( ) ^{⇒ Promise<Stream>} <>
 Creates an independent Stream that operates on the same source material as this stream.
 This sub-stream will be read-only.
.substream( ) ^{⇒ Promise<Stream>} <>
 ▪ from ^number
 ▪ to ^number
.asNodeStream( ) ^{⇒ Duplex} <>
 Converts this stream into a Node.js-style stream.

Properties:

.position ^number
 The current position of the cursor in the stream.
.length ^number
 The length of the stream, in bytes.
.canWrite boolean
 true if this stream can be written to.
.canRead boolean
 true if this stream can be read from.
.canSeek boolean
 true if this stream can be seeked within.
.isOpen boolean
 true if this stream is currently open.

© 2019 Ibiyemi Abiodun (laptou) <[e-mail]>