0.1.3 • Published 7 years ago
imapfetch-collect v0.1.3
imapfetch-collect
Simplified abstraction for the fetch
method of the imap
module. Get a
callback instead of streams within streams.
API
This module exports one function:
imapFetchCollect(fetcher, opts, whenFetched)
fetcher
: TheImapFetch
object returned by theimap
module'sfetch
method.opts
: Optional options object, see below.whenFetched
: Your callback (nodeback). It will receive two arguments:(err, msgs)
, wheremsgs
is an Array of messages that were received successfully (example data), anderr
is the first error that was encountered, or some false-y value on success.
If you need progress information, you can add your own event listeners to
the fetcher
. imapFetchCollect
's event handlers shouldn't interfere
with others.
Options
translateHeaderNames
: Whether and how to rewrite header field names, using thetranskey
module.false
,null
,undefined
(default): Don't.- a Function: Custom synchronous translater function.
"dash2camel"
: Translate to camelCase, e.g.from
,to
,xOriginalTo
,messageId
,contentTransferEncoding
maxDecodeBytes
: How much of a text buffer to decode automatically. Can be- any false-y value (e.g.
0
): Use some default value of a few megabytes. - a positive Number: Up to that many bytes.
true
: Decode ALL the text.
- any false-y value (e.g.
simpleUniqueHeaders
: Whether to unpack header value arrays that contain only one value. Boolean, default:true
Usage
var ImapConnection = require('imap'),
imapFetchCollect = require('imapfetch-collect');
function onMailFetched(err, msgs) {
if (err) { throw err; }
console.log('fetched', msgs.length, 'message(s)');
var msg1 = msgs[0];
console.log('first mail headers:', Object.keys(msg1.rawHeaders));
console.log('first body:', msg1.bodies[0].text);
}
function checkMail() {
// … login, search, …
function onSearchSuccess(foundUIDs) {
var fetcher = imapConn.fetch(foundUIDs, fetchOpts);
imapFetchCollect(fetcher, onMailFetched);
}
}
Simplification drawbacks
- In case of multiple errors within the same fetch attempt, all but one are silently ignored.
- All messages are buffered into memory. You don't get a chance to ignore some message body based on the message's size or headers.
- Only the first message body is auto-decoded, because I haven't encountered any mail with multiple (top-level) message bodies yet. If you have more complicated mail, you can work with raw headers and bodies.
Working with raw headers and bodies
Each message object has the methods getRawHeaders
and getRawBodies
which
understand optional arguments, ([n[, enc[, maxBytes]]])
.
- When
n
is not a number (e.g. undefined / missing), they'll return an Array whose items each have agetRawBuffer
method. - With a number
n
, they'll return then
-th item (starting at index 0) orfalse
.- If you also set
enc
to eithernull
or"buffer"
, they'll return that item's original (entire) buffer. (Regardless ofmaxDecodeBytes
, since there's no decoding.) - If you set
enc
to some other non-empty string, they'll attempt to decode up tomaxDecodeBytes
of that buffer into a string using encodingenc
. maxBytes
should be either:- missing,
undefined
,0
,false
: No override. - a positive number: Temporarily override the
maxDecodeBytes
option. true
: Override: Decode entire buffer.
- missing,
- If you also set
Known issues
- needs more/better tests and docs
License
ISC