| 1 | # fs-minipass
|
|---|
| 2 |
|
|---|
| 3 | Filesystem streams based on [minipass](http://npm.im/minipass).
|
|---|
| 4 |
|
|---|
| 5 | 4 classes are exported:
|
|---|
| 6 |
|
|---|
| 7 | - ReadStream
|
|---|
| 8 | - ReadStreamSync
|
|---|
| 9 | - WriteStream
|
|---|
| 10 | - WriteStreamSync
|
|---|
| 11 |
|
|---|
| 12 | When using `ReadStreamSync`, all of the data is made available
|
|---|
| 13 | immediately upon consuming the stream. Nothing is buffered in memory
|
|---|
| 14 | when the stream is constructed. If the stream is piped to a writer,
|
|---|
| 15 | then it will synchronously `read()` and emit data into the writer as
|
|---|
| 16 | fast as the writer can consume it. (That is, it will respect
|
|---|
| 17 | backpressure.) If you call `stream.read()` then it will read the
|
|---|
| 18 | entire file and return the contents.
|
|---|
| 19 |
|
|---|
| 20 | When using `WriteStreamSync`, every write is flushed to the file
|
|---|
| 21 | synchronously. If your writes all come in a single tick, then it'll
|
|---|
| 22 | write it all out in a single tick. It's as synchronous as you are.
|
|---|
| 23 |
|
|---|
| 24 | The async versions work much like their node builtin counterparts,
|
|---|
| 25 | with the exception of introducing significantly less Stream machinery
|
|---|
| 26 | overhead.
|
|---|
| 27 |
|
|---|
| 28 | ## USAGE
|
|---|
| 29 |
|
|---|
| 30 | It's just streams, you pipe them or read() them or write() to them.
|
|---|
| 31 |
|
|---|
| 32 | ```js
|
|---|
| 33 | const fsm = require('fs-minipass')
|
|---|
| 34 | const readStream = new fsm.ReadStream('file.txt')
|
|---|
| 35 | const writeStream = new fsm.WriteStream('output.txt')
|
|---|
| 36 | writeStream.write('some file header or whatever\n')
|
|---|
| 37 | readStream.pipe(writeStream)
|
|---|
| 38 | ```
|
|---|
| 39 |
|
|---|
| 40 | ## ReadStream(path, options)
|
|---|
| 41 |
|
|---|
| 42 | Path string is required, but somewhat irrelevant if an open file
|
|---|
| 43 | descriptor is passed in as an option.
|
|---|
| 44 |
|
|---|
| 45 | Options:
|
|---|
| 46 |
|
|---|
| 47 | - `fd` Pass in a numeric file descriptor, if the file is already open.
|
|---|
| 48 | - `readSize` The size of reads to do, defaults to 16MB
|
|---|
| 49 | - `size` The size of the file, if known. Prevents zero-byte read()
|
|---|
| 50 | call at the end.
|
|---|
| 51 | - `autoClose` Set to `false` to prevent the file descriptor from being
|
|---|
| 52 | closed when the file is done being read.
|
|---|
| 53 |
|
|---|
| 54 | ## WriteStream(path, options)
|
|---|
| 55 |
|
|---|
| 56 | Path string is required, but somewhat irrelevant if an open file
|
|---|
| 57 | descriptor is passed in as an option.
|
|---|
| 58 |
|
|---|
| 59 | Options:
|
|---|
| 60 |
|
|---|
| 61 | - `fd` Pass in a numeric file descriptor, if the file is already open.
|
|---|
| 62 | - `mode` The mode to create the file with. Defaults to `0o666`.
|
|---|
| 63 | - `start` The position in the file to start reading. If not
|
|---|
| 64 | specified, then the file will start writing at position zero, and be
|
|---|
| 65 | truncated by default.
|
|---|
| 66 | - `autoClose` Set to `false` to prevent the file descriptor from being
|
|---|
| 67 | closed when the stream is ended.
|
|---|
| 68 | - `flags` Flags to use when opening the file. Irrelevant if `fd` is
|
|---|
| 69 | passed in, since file won't be opened in that case. Defaults to
|
|---|
| 70 | `'a'` if a `pos` is specified, or `'w'` otherwise.
|
|---|
