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) <[email protected]>