@zone-eu/mailsplit 5.4.9 → 5.4.11

package/lib/headers.js

@@ -2,76 +2,120 @@
 
 const libmime = require('libmime');
 
+/** @typedef {import('..').HeaderLine} HeaderLine */
+/** @typedef {import('..').LibmimeOptions} LibmimeOptions */
+/** @typedef {import('..').DecodedHeader} DecodedHeader */
+
+const Libmime = /** @type {any} */ (libmime.Libmime);
+
 /**
- * Class Headers to parse and handle message headers. Headers instance allows to
- * check existing, delete or add new headers
+ * Parses and builds message headers. A Headers instance allows callers to
+ * inspect, delete, update, and add header lines.
  */
 class Headers {
+    /**
+     * @param {string | Buffer | HeaderLine[] | false} [headers] Raw header source or already parsed lines.
+     * @param {LibmimeOptions} [config] Optional libmime configuration.
+     */
     constructor(headers, config) {
         config = config || {};
 
         if (Array.isArray(headers)) {
             // already using parsed headers
             this.changed = true;
+            /** @type {string | Buffer | false} */
             this.headers = false;
             this.parsed = true;
+            /** @type {HeaderLine[] | false} */
             this.lines = headers;
         } else {
             // using original string/buffer headers
             this.changed = false;
-            this.headers = headers;
+            /** @type {string | Buffer | false} */
+            this.headers = headers || false;
             this.parsed = false;
+            /** @type {HeaderLine[] | false} */
             this.lines = false;
         }
+        /** @type {string | false} */
         this.mbox = false;
+        /** @type {string | false} */
         this.http = false;
 
-        this.libmime = new libmime.Libmime({ Iconv: config.Iconv });
+        this.libmime = new Libmime({ Iconv: config.Iconv });
     }
 
+    /**
+     * @param {string} key
+     * @returns {boolean}
+     */
     hasHeader(key) {
         if (!this.parsed) {
             this._parseHeaders();
         }
+        let lines = this._getLines();
         key = this._normalizeHeader(key);
-        return typeof this.lines.find(line => line.key === key) === 'object';
+        return typeof lines.find(line => line.key === key) === 'object';
     }
 
+    /**
+     * @param {string} key
+     * @returns {string[]}
+     */
     get(key) {
         if (!this.parsed) {
             this._parseHeaders();
         }
+        let headerLines = this._getLines();
         key = this._normalizeHeader(key);
-        let lines = this.lines.filter(line => line.key === key).map(line => this._decodeHeaderValue(line.line));
+        let lines = headerLines.filter(line => line.key === key).map(line => this._decodeHeaderValue(line.line));
 
         return lines;
     }
 
+    /**
+     * @param {string} key
+     * @returns {DecodedHeader[]}
+     */
     getDecoded(key) {
         return this.get(key)
             .map(line => this.libmime.decodeHeader(line))
             .filter(line => line && line.value);
     }
 
+    /**
+     * @param {string} key
+     * @returns {string}
+     */
     getFirst(key) {
         if (!this.parsed) {
             this._parseHeaders();
         }
+        let lines = this._getLines();
         key = this._normalizeHeader(key);
-        let header = this.lines.find(line => line.key === key);
+        let header = lines.find(line => line.key === key);
         if (!header) {
             return '';
         }
         return ((this.libmime.decodeHeader(this._decodeHeaderValue(header.line)) || {}).value || '').toString().trim();
     }
 
+    /**
+     * @returns {HeaderLine[]}
+     */
     getList() {
         if (!this.parsed) {
             this._parseHeaders();
         }
-        return this.lines;
+        return this._getLines();
     }
 
+    /**
+     * @param {string} key
+     * @param {string | number | Buffer} [value]
+     * @param {number} [index]
+     * @returns {void}
+     */
     add(key, value, index) {
         if (typeof value === 'undefined') {
             return;
@@ -89,10 +133,17 @@ class Headers {
         this.addFormatted(key, this.libmime.foldLines(key + ': ' + value.replace(/\r?\n/g, ''), 76, false), index);
     }
 
+    /**
+     * @param {string} key
+     * @param {string | Buffer | false} [line]
+     * @param {number} [index]
+     * @returns {void}
+     */
     addFormatted(key, line, index) {
         if (!this.parsed) {
             this._parseHeaders();
         }
+        let lines = this._getLines();
         index = index || 0;
         this.changed = true;
 
@@ -110,45 +161,57 @@ class Headers {
         };
 
         if (index < 1) {
-            this.lines.unshift(header);
-        } else if (index >= this.lines.length) {
-            this.lines.push(header);
+            lines.unshift(header);
+        } else if (index >= lines.length) {
+            lines.push(header);
         } else {
-            this.lines.splice(index, 0, header);
+            lines.splice(index, 0, header);
         }
     }
 
+    /**
+     * @param {string} key
+     * @returns {void}
+     */
     remove(key) {
         if (!this.parsed) {
             this._parseHeaders();
         }
+        let lines = this._getLines();
         key = this._normalizeHeader(key);
-        for (let i = this.lines.length - 1; i >= 0; i--) {
-            if (this.lines[i].key === key) {
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (lines[i].key === key) {
                 this.changed = true;
-                this.lines.splice(i, 1);
+                lines.splice(i, 1);
             }
         }
     }
 
+    /**
+     * @param {string} key
+     * @param {string | number | Buffer} [value]
+     * @param {number} [relativeIndex]
+     * @returns {void}
+     */
     update(key, value, relativeIndex) {
         if (!this.parsed) {
             this._parseHeaders();
         }
+        let lines = this._getLines();
         let keyName = key;
         let index = 0;
         key = this._normalizeHeader(key);
         let relativeIndexCount = 0;
         let relativeMatchFound = false;
-        for (let i = this.lines.length - 1; i >= 0; i--) {
-            if (this.lines[i].key === key) {
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (lines[i].key === key) {
                 if (relativeIndex && relativeIndex !== relativeIndexCount) {
                     relativeIndexCount++;
                     continue;
                 }
                 index = i;
                 this.changed = true;
-                this.lines.splice(i, 1);
+                lines.splice(i, 1);
                 if (relativeIndex) {
                     relativeMatchFound = true;
                     break;
@@ -163,18 +226,23 @@ class Headers {
         this.add(keyName, value, index);
     }
 
+    /**
+     * @param {string | false} [lineEnd]
+     * @returns {Buffer}
+     */
     build(lineEnd) {
         if (!this.changed && !lineEnd) {
-            return typeof this.headers === 'string' ? Buffer.from(this.headers, 'binary') : this.headers;
+            return typeof this.headers === 'string' ? Buffer.from(this.headers, 'binary') : this.headers || Buffer.alloc(0);
         }
 
         if (!this.parsed) {
             this._parseHeaders();
         }
+        let lines = this._getLines();
 
         lineEnd = lineEnd || '\r\n';
 
-        let headers = this.lines
+        let headers = lines
             .map(line => this._buildHeaderLine(line.line.replace(/\r?\n/g, lineEnd)))
             .reduce((joined, line, idx) => {
                 if (idx) {
@@ -182,7 +250,7 @@ class Headers {
                 }
                 joined.push(line);
                 return joined;
-            }, []);
+            }, /** @type {Buffer[]} */ ([]));
 
         headers.push(Buffer.from(lineEnd + lineEnd, 'binary'));
 
@@ -197,10 +265,27 @@ class Headers {
         return Buffer.concat(headers);
     }
 
+    /**
+     * @param {string} key
+     * @returns {string}
+     */
     _normalizeHeader(key) {
         return (key || '').toLowerCase().trim();
     }
 
+    /**
+     * @returns {HeaderLine[]}
+     */
+    _getLines() {
+        if (!this.lines) {
+            this.lines = [];
+        }
+        return this.lines;
+    }
+
+    /**
+     * @returns {void}
+     */
     _parseHeaders() {
         if (!this.headers) {
             this.lines = [];
@@ -208,18 +293,20 @@ class Headers {
             return;
         }
 
+        /** @type {Array<string | HeaderLine>} */
         let lines = this.headers
             .toString('binary')
             .replace(/[\r\n]+$/, '')
             .split(/\r?\n/);
 
         for (let i = lines.length - 1; i >= 0; i--) {
-            let chr = lines[i].charAt(0);
+            let currentLine = /** @type {string} */ (lines[i]);
+            let chr = currentLine.charAt(0);
             if (i && (chr === ' ' || chr === '\t')) {
-                lines[i - 1] += '\r\n' + lines[i];
+                lines[i - 1] = /** @type {string} */ (lines[i - 1]) + '\r\n' + currentLine;
                 lines.splice(i, 1);
             } else {
-                let line = lines[i];
+                let line = currentLine;
                 if (!i && /^From /i.test(line)) {
                     // mbox file
                     this.mbox = line;
@@ -239,15 +326,23 @@ class Headers {
             }
         }
 
-        this.lines = lines;
+        this.lines = /** @type {HeaderLine[]} */ (lines);
         this.parsed = true;
     }
 
+    /**
+     * @param {string} line
+     * @returns {Buffer}
+     */
     _buildHeaderLine(line) {
         let value = this._decodeHeaderValue(line);
         return Buffer.from(value, value === line ? 'binary' : 'utf8');
     }
 
+    /**
+     * @param {string} str
+     * @returns {string}
+     */
     _decodeHeaderValue(str) {
         if (!str) {
             return str;

package/lib/message-joiner.d.ts

@@ -0,0 +1,56 @@
+import { Transform } from 'node:stream';
+
+/** Transform stream that joins splitter objects back into raw email bytes. */
+declare class MessageJoiner extends Transform {
+    /**
+     * Creates a joiner that accepts splitter objects and emits Buffer chunks.
+     */
+    constructor();
+
+    /**
+     * Registers a listener for generated message bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives each generated Buffer chunk.
+     * @returns This joiner instance.
+     */
+    on(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Registers a one-time listener for generated message bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives the next generated Buffer chunk.
+     * @returns This joiner instance.
+     */
+    once(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Adds a listener for generated message bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives each generated Buffer chunk.
+     * @returns This joiner instance.
+     */
+    addListener(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Prepends a listener for generated message bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives each generated Buffer chunk.
+     * @returns This joiner instance.
+     */
+    prependListener(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Emits a generated message byte chunk.
+     *
+     * @param event Event name.
+     * @param data Buffer chunk to emit.
+     * @returns `true` when the event had listeners.
+     */
+    emit(event: 'data', data: Buffer): boolean;
+}
+
+export = MessageJoiner;

package/lib/message-joiner.js

@@ -2,7 +2,15 @@
 
 const Transform = require('stream').Transform;
 
+/** @typedef {import('..').SplitterChunk} SplitterChunk */
+
+/**
+ * Transform stream that joins splitter objects back into raw message bytes.
+ */
 class MessageJoiner extends Transform {
+    /**
+     * Creates a joiner that accepts splitter objects and emits Buffer chunks.
+     */
     constructor() {
         let options = {
             readableObjectMode: false,
@@ -11,6 +19,12 @@ class MessageJoiner extends Transform {
         super(options);
     }
 
+    /**
+     * @param {SplitterChunk | Buffer} obj
+     * @param {BufferEncoding} encoding
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _transform(obj, encoding, callback) {
         if (Buffer.isBuffer(obj)) {
             this.push(obj);
@@ -22,6 +36,10 @@ class MessageJoiner extends Transform {
         return callback();
     }
 
+    /**
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _flush(callback) {
         return callback();
     }

package/lib/message-splitter.d.ts

@@ -0,0 +1,59 @@
+import { Transform } from 'node:stream';
+import type { SplitterChunk, SplitterOptions } from './types';
+
+/** Transform stream that splits raw email bytes into MIME node and content chunks. */
+declare class MessageSplitter extends Transform {
+    /**
+     * Creates a splitter that accepts Buffer input and emits `SplitterChunk` objects.
+     *
+     * @param config Optional parser limits and embedded-message behavior.
+     */
+    constructor(config?: SplitterOptions);
+
+    /**
+     * Registers a listener for parsed splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each parsed MIME node, data chunk, or body chunk.
+     * @returns This splitter instance.
+     */
+    on(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Registers a one-time listener for the next parsed splitter chunk.
+     *
+     * @param event Event name.
+     * @param listener Receives the next parsed MIME node, data chunk, or body chunk.
+     * @returns This splitter instance.
+     */
+    once(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Adds a listener for parsed splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each parsed MIME node, data chunk, or body chunk.
+     * @returns This splitter instance.
+     */
+    addListener(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Prepends a listener for parsed splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each parsed MIME node, data chunk, or body chunk.
+     * @returns This splitter instance.
+     */
+    prependListener(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Emits a parsed splitter chunk.
+     *
+     * @param event Event name.
+     * @param data MIME node, data chunk, or body chunk to emit.
+     * @returns `true` when the event had listeners.
+     */
+    emit(event: 'data', data: SplitterChunk): boolean;
+}
+
+export = MessageSplitter;

package/lib/message-splitter.js

@@ -3,13 +3,26 @@
 const Transform = require('stream').Transform;
 const MimeNode = require('./mime-node');
 
+/** @typedef {import('..').MimeNode} MimeNodeType */
+/** @typedef {import('..').MessageChunk} MessageChunk */
+/** @typedef {import('..').SplitterChunk} SplitterChunk */
+/** @typedef {import('..').SplitterGroup} SplitterGroup */
+/** @typedef {import('..').SplitterOptions} SplitterOptions */
+/** @typedef {(err?: (Error & {code?: string}) | null, data?: SplitterChunk | MessageChunk | false, flush?: boolean) => void} ProcessLineCallback */
+
 const MAX_HEAD_SIZE = 1 * 1024 * 1024;
 const MAX_CHILD_NODES = 1000;
 
 const HEAD = 0x01;
 const BODY = 0x02;
 
+/**
+ * Transform stream that splits raw email bytes into MIME node and content chunks.
+ */
 class MessageSplitter extends Transform {
+    /**
+     * @param {SplitterOptions} [config]
+     */
     constructor(config) {
         let options = {
             readableObjectMode: true,
@@ -20,25 +33,41 @@ class MessageSplitter extends Transform {
         this.config = config || {};
         this.maxHeadSize = this.config.maxHeadSize || MAX_HEAD_SIZE;
         this.maxChildNodes = this.config.maxChildNodes || MAX_CHILD_NODES;
+        /** @type {MimeNodeType[]} */
         this.tree = [];
         this.nodeCounter = 0;
+        this.node = /** @type {MimeNodeType} */ (/** @type {unknown} */ (null));
         this.newNode();
         this.tree.push(this.node);
+        /** @type {Buffer | false} */
         this.line = false;
         this.hasFailed = false;
     }
 
+    /**
+     * @param {Buffer} chunk
+     * @param {BufferEncoding} encoding
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _transform(chunk, encoding, callback) {
         // process line by line
         // find next line ending
         let pos = 0;
         let i = 0;
+        /** @type {SplitterGroup} */
         let group = {
             type: 'none'
         };
         let groupstart = this.line ? -this.line.length : 0;
         let groupend = 0;
 
+        /**
+         * Removes a pending line break from body data that belongs to a following boundary.
+         *
+         * @param {MessageChunk} data Body chunk to adjust in place.
+         * @returns {void}
+         */
         let checkTrailingLinebreak = data => {
             if (data.type === 'body' && data.node.parentNode && data.value && data.value.length) {
                 if (data.value[data.value.length - 1] === 0x0a) {
@@ -67,6 +96,11 @@ class MessageSplitter extends Transform {
             }
         };
 
+        /**
+         * Iterates the current input chunk line by line and emits parsed groups.
+         *
+         * @returns {void}
+         */
         let iterateData = () => {
             for (let len = chunk.length; i < len; i++) {
                 // find next <LF>
@@ -88,7 +122,7 @@ class MessageSplitter extends Transform {
 
                         if (flush) {
                             if (group && group.type !== 'none') {
-                                if (group.type === 'body' && groupend >= groupstart && group.node.parentNode) {
+                                if (group.type === 'body' && groupend >= groupstart && group.node && group.node.parentNode) {
                                     // do not include the last line ending for body
                                     if (chunk[groupend - 1] === 0x0a) {
                                         groupend--;
@@ -99,7 +133,7 @@ class MessageSplitter extends Transform {
                                 }
                                 if (groupstart !== groupend) {
                                     group.value = chunk.slice(groupstart, groupend);
-                                    if (groupend < i) {
+                                    if (groupend < i && 'value' in data) {
                                         data.value = chunk.slice(groupend, i);
                                     }
                                 }
@@ -118,7 +152,7 @@ class MessageSplitter extends Transform {
                             // shift slice end position forward
                             groupend = i;
                         } else {
-                            if (group.type === 'body' && groupend >= groupstart && group.node.parentNode) {
+                            if (group.type === 'body' && groupend >= groupstart && group.node && group.node.parentNode) {
                                 // do not include the last line ending for body
                                 if (chunk[groupend - 1] === 0x0a) {
                                     groupend--;
@@ -165,7 +199,7 @@ class MessageSplitter extends Transform {
             }
 
             // skip last linebreak for body
-            if (pos >= groupstart + 1 && group.type === 'body' && group.node.parentNode) {
+            if (pos >= groupstart + 1 && group.type === 'body' && group.node && group.node.parentNode) {
                 // do not include the last line ending for body
                 if (chunk[pos - 1] === 0x0a) {
                     pos--;
@@ -200,6 +234,10 @@ class MessageSplitter extends Transform {
         setImmediate(iterateData);
     }
 
+    /**
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _flush(callback) {
         if (this.hasFailed) {
             return callback();
@@ -215,6 +253,12 @@ class MessageSplitter extends Transform {
         });
     }
 
+    /**
+     * @param {Buffer} line
+     * @param {number} startpos
+     * @param {Buffer} boundary
+     * @returns {1 | 2 | false}
+     */
     compareBoundary(line, startpos, boundary) {
         // --{boundary}\r\n or --{boundary}--\r\n
         if (line.length < boundary.length + 3 + startpos || line.length > boundary.length + 6 + startpos) {
@@ -256,6 +300,10 @@ class MessageSplitter extends Transform {
         return 2;
     }
 
+    /**
+     * @param {Buffer} line
+     * @returns {1 | 2 | 3 | 4 | false}
+     */
     checkBoundary(line) {
         let startpos = 0;
         if (line.length >= 1 && (line[0] === 0x0d || line[0] === 0x0a)) {
@@ -269,6 +317,7 @@ class MessageSplitter extends Transform {
             return false;
         }
 
+        /** @type {1 | 2 | false} */
         let boundary;
         if (this.node._boundary && (boundary = this.compareBoundary(line, startpos, this.node._boundary))) {
             // 1: next child
@@ -279,12 +328,18 @@ class MessageSplitter extends Transform {
         if (this.node._parentBoundary && (boundary = this.compareBoundary(line, startpos, this.node._parentBoundary))) {
             // 3: next sibling
             // 4: parent end
-            return boundary + 2;
+            return /** @type {3 | 4} */ (boundary + 2);
         }
 
         return false;
     }
 
+    /**
+     * @param {Buffer | false} line
+     * @param {boolean} final
+     * @param {ProcessLineCallback} next
+     * @returns {void}
+     */
     processLine(line, final, next) {
         let flush = false;
 
@@ -301,7 +356,7 @@ class MessageSplitter extends Transform {
         }
 
         if (this.nodeCounter > this.maxChildNodes) {
-            let err = new Error('Max allowed child nodes exceeded');
+            let err = /** @type {Error & {code?: string}} */ (new Error('Max allowed child nodes exceeded'));
             err.code = 'EMAXLEN';
             return next(err);
         }
@@ -339,7 +394,7 @@ class MessageSplitter extends Transform {
                     }
                     // move up
                     if (this.tree.length) {
-                        this.node = this.tree.pop();
+                        this.node = /** @type {MimeNodeType} */ (this.tree.pop());
                     }
                     this.state = BODY;
                     break;
@@ -360,7 +415,7 @@ class MessageSplitter extends Transform {
             case HEAD: {
                 this.node.addHeaderChunk(line);
                 if (this.node._headerlen > this.maxHeadSize) {
-                    let err = new Error('Max header size for a MIME node exceeded');
+                    let err = /** @type {Error & {code?: string}} */ (new Error('Max header size for a MIME node exceeded'));
                     err.code = 'EMAXLEN';
                     return next(err);
                 }
@@ -412,8 +467,12 @@ class MessageSplitter extends Transform {
         next(null, false);
     }
 
+    /**
+     * @param {MimeNodeType | false} [parent]
+     * @returns {void}
+     */
     newNode(parent) {
-        this.node = new MimeNode(parent || false, this.config);
+        this.node = /** @type {MimeNodeType} */ (new MimeNode(parent || false, this.config));
         this.state = HEAD;
         this.nodeCounter++;
     }