File and stream concatenation the right way.
A simple module that concatenates files and binary streams with some extras.
var Kat = require'kat';var readstream = ;readstreamadd'file1.txt';readstreamadd'file2.txt';readstreamaddanotherReadableStream;readstreampipefscreateWriteStream'file1n2.txt';
readstream will emit
end events like a regular readstream should.
resume() can also be called on it.
You might be thinking this module is way too simple to even be a module. I was thinking the same thing until I thought about how this type of module should really work.
There are several node modules where their API allow developers to pass in file data by passing in a file path to a method.
fooread'myfile.json'// do something with result;
These modules are doing it wrong. (With the exception of modules that are used in setup)
In many cases, you will want to have the option to pass in a readable stream of the file. Why? Because with a stream, not only can you give it a local file stream, but it can also be a stream from a remote request. Or even a stream that parses or uncompresses another stream.
// local filevar fs = require'fs';fooreadfscreateReadStream'myfile.json';// remote file// request conveniently returns a readable streamvar request = require'request';fooreadrequest'';// compressed filevar fs = require'fs';var zlib = require'zlib';var stream = fscreateReadStream'myfile.json'pipezlibcreateDeflate;fooreadstream;
The module could even be used in a server that allows file uploads without the server having to save the entire file to disc.
require'http'createServerfooreadreq// respond to res;;
But ideally, we want to make our module APIs as convenient as possible for other developers. It's really common for a module to receive streams that are local file read streams made with
fs.createReadStream. Thus it would be convenient to allow its users to give the module a file path OR a readable stream.
// pass in a file pathfooread'myfile.json';// pass in a streamfooreadfscreateReadStream'myfile.json';
But what if your module is the type that allows its users to add multiple files to it?
var bar = foocreateBar;baradd'file1.json';baradd'file2.json';
This is where node-kat shines. It easily allows you to convenielize (yes convenielize) your API by allowing users to input file paths, readable streams, and even paths to directories.
var bar = foocreateBar;var request = require'request';baradd'file1.json';baraddrequest'file2.json';baradd'a/local/dir';
Now the bar instance will get all the data from the files it needs, in order, and aware of what file or stream it's coming from.
Creates a new instance of Kat. Passing in files to the constructor is a shortcut to the
Kat#add() method. Last argument will be considered options object if not a string or a stream. Options defaults to
// will be used whenever a file is openedflags: 'r'encoding: nullmode: 438bufferSize: 64 * 1024// can be used to select what part of the concatenated file will be read// even if that means skipping files entirelystart: 0end: Infinity// if true, will keep reading any additional streams if there is an error// if false, will stop and destroy all streams as soon as there is one errorcontinueOnErr: falseallowFiles: trueallowDirs: trueallowStreams: trueconcurrency: 250// if true, will emit `end` when it finishes reading all streamsautoEnd: true
Adds argument list to the list of files that will be concatenated.
file can be a string to a path of a file, a folder, or a readable stream. If it's a folder, all files in it will be recursively added alphabetically.
number- File descriptor.
string- File path.
When a file descriptor is opened, this will be emitted. In case a non-file readable stream is added,
filepath will be the item index relative to all other items in the list.
string- File path.
Emitted when a file descriptor is closed.
string- File path.
Emitted when the Kat instance starts reading from a stream.
Emitted when all streams have been read.
Array.Object- Will be an array of objects containing a
Emitted right before the
path: "/home/user/files/somefile.txt" size: 324path: 1 size: 4459
When there is an error opening a file, reading from it, or with a stream.
npm install kat
Tests are written with mocha