Module

Node.Stream.Aff

Package
purescript-node-streams
Repository
purescript-node/purescript-node-streams

Asynchronous I/O with the Node.js Stream API.

Open file streams with Node.FS.Stream.

Open process streams with Node.Process.

All I/O errors will be thrown through the Aff MonadError class instance.

Aff cancellation will clean up all Node.js event listeners.

All of these Aff functions will prevent the Node.js event loop from exiting until the Aff function completes.

Reading

Implementation

The read* functions (not to be confused with the readable* functions) in this module all operate on a Readable stream in “paused mode”.

Internally the reading functions use the readable.read([size]) function and are subject to the caveats of that function.

Result Buffers

The result of a reading function may be chunked into more than one Buffer. The buffers element of the result is an Array Buffer of what was read. To concatenate the result into a single Buffer, use Node.Buffer.concat :: Array Buffer -> m Buffer.

input :: Buffer
    <- liftEffect <<< concat <<< _.buffers =<< readSome stdin

To calculate the number of bytes read, use Node.Buffer.size :: Buffer -> m Int.

{ buffers } :: Array Buffer <- readSome stdin
bytesRead :: Int
    <- liftEffect $ Array.foldM (\a b -> (a+_) <$> size b) 0 buffers

Result readagain flag

The readagain field of the result is a Boolean flag which is true if the stream has not reached End-Of-File (and also if the stream has not errored or been destroyed), so we know we can read again. If the flag is false then the stream is not readable; no more bytes will ever be produced by the stream.

Reading from an ended, closed, errored, or destroyed stream will complete immediately with { buffers: [], readagain: false }.

The readagain flag will give the same answer as a subsequent call to readable.

Writing

Implementation

The writing functions in this module all operate on a Writeable stream.

Internally the writing functions will call the writable.write(chunk[, encoding][, callback]) function on each of the Buffers, and will asychronously wait if there is “backpressure” from the stream.

Result

The writing functions will complete after all the data is flushed to the stream.

If a write fails then it will throwError in the Aff.

#readableToStringUtf8 Source

readableToStringUtf8 :: forall m w. MonadAff m => Readable w -> m String

Works on streams in "flowing" mode. Reads all of the stream's contents into a buffer and converts the result into a UTF8-encoded String.

#readableToString Source

readableToString :: forall m w. MonadAff m => Readable w -> Encoding -> m String

Works on streams in "flowing" mode. Reads all of the stream's contents into a buffer and converts the result into a String using the provided encoding.

#readableToBuffers Source

readableToBuffers :: forall m w. MonadAff m => Readable w -> m (Array Buffer)

Works on streams in "flowing" mode. Reads all of the stream's buffered contents into an array.

#readSome Source

readSome :: forall m r. MonadAff m => Readable r -> m { buffers :: Array Buffer, readagain :: Boolean }

Works on streams in "paused" mode. Wait until there is some data available from the stream, then read it.

This function is useful for streams like stdin which never reach End-Of-File.

#readAll Source

readAll :: forall m r. MonadAff m => Readable r -> m (Array Buffer)

Works on streams in "paused" mode. Read all data until the end of the stream. After completion the stream will no longer be readable.

Note that stdin will never end.

#readN Source

readN :: forall m r. MonadAff m => Readable r -> Int -> m { buffers :: Array Buffer, readagain :: Boolean }

Works on streams in "paused" mode. Wait for N bytes to become available from the stream.

If more than N bytes are available on the stream, then completes with N bytes and leaves the rest in the stream’s internal buffer.

If the end of the stream is reached before N bytes are available, then completes with less than N bytes.

#write Source

write :: forall m w. MonadAff m => Writable w -> Array Buffer -> m Unit

Write to a stream.

Will complete after the data is flushed to the stream.

#end Source

end :: forall m w. MonadAff m => Writable w -> m Unit

Signal that no more data will be written to the Writable. Will complete after all data is written and flushed.

When the Writable is an fs.WriteStream then this will close the file descriptor because

“If autoClose is set to true (default behavior) on 'error' or 'finish' the file descriptor will be closed automatically.”

#toStringUTF8 Source

toStringUTF8 :: forall m. MonadEffect m => Array Buffer -> m String

Concatenate an Array of UTF-8 encoded Buffers into a String.

Example:

inputstring <- toStringUTF8 =<< readAll stream

#fromStringUTF8 Source

fromStringUTF8 :: forall m. MonadEffect m => String -> m (Array Buffer)

Encode a String as an Array containing one UTF-8 encoded Buffer.

Example:

write stream =<< fromStringUTF8 "outputstring"
Modules
Node.Stream
Node.Stream.Aff