| 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 |
import { ReadStream, WriteStream } from 'fs-minipass' |
| 34 |
// or: const { ReadStream, WriteStream } = require('fs-minipass') |
| 35 |
const readStream = new ReadStream('file.txt') |
| 36 |
const writeStream = new WriteStream('output.txt') |
| 37 |
writeStream.write('some file header or whatever\n') |
| 38 |
readStream.pipe(writeStream) |
| 39 |
``` |
| 40 |
|
| 41 |
## ReadStream(path, options) |
| 42 |
|
| 43 |
Path string is required, but somewhat irrelevant if an open file |
| 44 |
descriptor is passed in as an option. |
| 45 |
|
| 46 |
Options: |
| 47 |
|
| 48 |
- `fd` Pass in a numeric file descriptor, if the file is already open. |
| 49 |
- `readSize` The size of reads to do, defaults to 16MB |
| 50 |
- `size` The size of the file, if known. Prevents zero-byte read() |
| 51 |
call at the end. |
| 52 |
- `autoClose` Set to `false` to prevent the file descriptor from being |
| 53 |
closed when the file is done being read. |
| 54 |
|
| 55 |
## WriteStream(path, options) |
| 56 |
|
| 57 |
Path string is required, but somewhat irrelevant if an open file |
| 58 |
descriptor is passed in as an option. |
| 59 |
|
| 60 |
Options: |
| 61 |
|
| 62 |
- `fd` Pass in a numeric file descriptor, if the file is already open. |
| 63 |
- `mode` The mode to create the file with. Defaults to `0o666`. |
| 64 |
- `start` The position in the file to start reading. If not |
| 65 |
specified, then the file will start writing at position zero, and be |
| 66 |
truncated by default. |
| 67 |
- `autoClose` Set to `false` to prevent the file descriptor from being |
| 68 |
closed when the stream is ended. |
| 69 |
- `flags` Flags to use when opening the file. Irrelevant if `fd` is |
| 70 |
passed in, since file won't be opened in that case. Defaults to |
| 71 |
`'a'` if a `pos` is specified, or `'w'` otherwise. |