Debian Codegraph @

isaacs-fs-minipass/README.md

raw
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.