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) \