@zone-eu/mailsplit 5.4.9 → 5.4.11

package/lib/mime-node.d.ts

@@ -0,0 +1,144 @@
+import type { ContentStream, MimeNode as MimeNodeShape, PartNumber, PartNumberItem, SplitterOptions } from './types';
+import type Headers = require('./headers');
+
+/** Parsed MIME node with mutable headers and content encoding helpers. */
+declare class MimeNode implements MimeNodeShape {
+    /** Discriminator identifying this chunk as a MIME node. */
+    type: 'node';
+
+    /** Whether this node is the root message node. */
+    root: boolean;
+
+    /** Parent MIME node, or `false` for the root node. */
+    parentNode: MimeNodeShape | false;
+
+    /** Boundary used by this multipart node, or `false` when not multipart. */
+    _boundary: Buffer | false;
+
+    /** Boundary inherited from the parent multipart node, or `false` when absent. */
+    _parentBoundary: Buffer | false;
+
+    /** Length, in bytes, of the raw header block collected for this node. */
+    _headerlen: number;
+
+    /** Multipart subtype such as `mixed` or `alternative`, or `false` for leaf nodes. */
+    multipart: string | false;
+
+    /** Content-Transfer-Encoding value, normalized to lower case, or `false` when absent. */
+    encoding: string | false;
+
+    /** Parsed and mutable header collection, available after headers are parsed. */
+    headers: Headers | false;
+
+    /** MIME content type such as `text/plain`, or `false` when unavailable. */
+    contentType: string | false;
+
+    /** Charset parameter from Content-Type, or `false` when absent. */
+    charset: string | false;
+
+    /** Content-Disposition value such as `inline` or `attachment`, or `false` when absent. */
+    disposition: string | false;
+
+    /** Decoded filename from Content-Disposition or Content-Type parameters, or `false` when absent. */
+    filename: string | false;
+
+    /** Whether this node is `text/*` with `format=flowed`. */
+    flowed: boolean;
+
+    /** Whether flowed text uses `delsp=yes`. */
+    delSp: boolean;
+
+    /** Splitter configuration used when parsing this node. */
+    config: SplitterOptions;
+
+    /** Resolved IMAP-style part number for this node, or `false` before resolution. */
+    partNr: PartNumber | false;
+
+    /** Number of child part numbers allocated by this node. */
+    childPartNumbers: number;
+
+    /** Whether this node's content type is `message/rfc822`. */
+    rfc822: boolean;
+
+    /** Whether an embedded `message/rfc822` node was parsed as a nested message. */
+    messageNode?: boolean;
+
+    /**
+     * Creates a MIME node with empty header state.
+     *
+     * @param parentNode Parent node, or `false`/omitted for the root node.
+     * @param config Optional splitter and libmime configuration.
+     */
+    constructor(parentNode?: MimeNodeShape | false, config?: SplitterOptions);
+
+    /**
+     * Builds the next child part number for this node.
+     *
+     * @param provided Optional explicit part number item to append.
+     * @returns Resolved MIME part number.
+     */
+    getPartNr(provided?: PartNumberItem): PartNumber;
+
+    /**
+     * Appends one raw header line to this node while parsing.
+     *
+     * @param line Raw header line bytes; falsy values are ignored.
+     * @returns Nothing.
+     */
+    addHeaderChunk(line?: Buffer | false): void;
+
+    /**
+     * Parses collected header bytes and populates MIME metadata fields.
+     *
+     * @returns Nothing.
+     */
+    parseHeaders(): void;
+
+    /**
+     * Builds this node's header block.
+     *
+     * @returns Header bytes ending with an empty header/body separator line.
+     */
+    getHeaders(): Buffer;
+
+    /**
+     * Sets or updates the Content-Type header value.
+     *
+     * @param contentType MIME content type to set; falsy keeps the current type.
+     * @returns Nothing.
+     */
+    setContentType(contentType?: string | false): void;
+
+    /**
+     * Sets, updates, or removes the Content-Type charset parameter.
+     *
+     * @param charset Charset to set; falsy removes it when possible.
+     * @returns Nothing.
+     */
+    setCharset(charset?: string | false): void;
+
+    /**
+     * Sets, updates, or removes the filename parameter.
+     *
+     * @param filename Filename to set; falsy removes it when possible.
+     * @returns Nothing.
+     */
+    setFilename(filename?: string | false): void;
+
+    /**
+     * Creates a decoder stream for this node's transfer encoding.
+     *
+     * @returns Transform stream that outputs decoded content bytes.
+     */
+    getDecoder(): ContentStream;
+
+    /**
+     * Creates an encoder stream and updates the Content-Transfer-Encoding header when needed.
+     *
+     * @param encoding Target transfer encoding; defaults to the node's current encoding.
+     * @returns Transform stream that outputs encoded content bytes.
+     */
+    getEncoder(encoding?: string | false): ContentStream;
+}
+
+export = MimeNode;

package/lib/mime-node.js

@@ -3,52 +3,97 @@
 const Headers = require('./headers');
 const libmime = require('libmime');
 const libqp = require('libqp');
+// @ts-ignore
 const libbase64 = require('libbase64');
 const PassThrough = require('stream').PassThrough;
 const pathlib = require('path');
 
+/** @typedef {import('..').Headers} HeadersType */
+/** @typedef {import('..').PartNumberItem} PartNumberItem */
+/** @typedef {import('..').PartNumber} PartNumber */
+/** @typedef {import('..').SplitterOptions} SplitterOptions */
+/** @typedef {import('libmime').StructuredHeader} StructuredHeader */
+/** @typedef {import('stream').Transform | import('stream').PassThrough} ContentStream */
+/** @typedef {import('..').MimeNode} MimeNodeType */
+
+const Libmime = /** @type {any} */ (libmime.Libmime);
+
+/**
+ * Parsed MIME node with mutable headers and transfer-encoding helpers.
+ */
 class MimeNode {
+    /**
+     * @param {MimeNodeType | false} parentNode Parent node, or false for the root node.
+     * @param {SplitterOptions} [config] Splitter and libmime configuration.
+     */
     constructor(parentNode, config) {
+        /** @type {'node'} */
         this.type = 'node';
         this.root = !parentNode;
+        /** @type {MimeNodeType | false} */
         this.parentNode = parentNode;
 
+        /** @type {Buffer | false} */
         this._parentBoundary = this.parentNode && this.parentNode._boundary;
+        /** @type {Buffer[]} */
         this._headersLines = [];
         this._headerlen = 0;
 
+        /** @type {StructuredHeader | false} */
         this._parsedContentType = false;
+        /** @type {StructuredHeader | false} */
+        this._parsedContentDisposition = false;
+        /** @type {Buffer | false} */
         this._boundary = false;
 
+        /** @type {string | false} */
         this.multipart = false;
+        /** @type {string | false} */
         this.encoding = false;
+        /** @type {HeadersType | false} */
         this.headers = false;
+        /** @type {string | false} */
         this.contentType = false;
+        /** @type {string | false} */
+        this.charset = false;
+        /** @type {string | false} */
+        this.disposition = false;
+        /** @type {string | false} */
+        this.filename = false;
         this.flowed = false;
         this.delSp = false;
 
         this.config = config || {};
-        this.libmime = new libmime.Libmime({ Iconv: this.config.Iconv });
+        this.libmime = new Libmime({ Iconv: this.config.Iconv });
 
-        this.parentPartNumber = (parentNode && this.partNr) || [];
+        /** @type {PartNumber} */
+        this.parentPartNumber = [];
+        /** @type {PartNumber | false} */
         this.partNr = false; // resolved later
         this.childPartNumbers = 0;
+        this.rfc822 = false;
+        /** @type {boolean | undefined} */
+        this.messageNode = undefined;
     }
 
+    /**
+     * @param {PartNumberItem} [provided]
+     * @returns {PartNumber}
+     */
     getPartNr(provided) {
+        /** @type {PartNumber} */
+        let partNr = this.partNr || [];
         if (provided) {
-            return []
-                .concat(this.partNr || [])
-                .filter(nr => !isNaN(nr))
-                .concat(provided);
+            return partNr.filter(nr => !isNaN(Number(nr))).concat(provided);
         }
         let childPartNr = ++this.childPartNumbers;
-        return []
-            .concat(this.partNr || [])
-            .filter(nr => !isNaN(nr))
-            .concat(childPartNr);
+        return partNr.filter(nr => !isNaN(Number(nr))).concat(childPartNr);
     }
 
+    /**
+     * @param {Buffer | false} [line]
+     * @returns {void}
+     */
     addHeaderChunk(line) {
         if (!line) {
             return;
@@ -57,27 +102,32 @@ class MimeNode {
         this._headerlen += line.length;
     }
 
+    /**
+     * @returns {void}
+     */
     parseHeaders() {
         if (this.headers) {
             return;
         }
         this.headers = new Headers(Buffer.concat(this._headersLines, this._headerlen), this.config);
+        let headers = this.headers;
 
-        this._parsedContentDisposition = this.libmime.parseHeaderValue(this.headers.getFirst('Content-Disposition'));
+        this._parsedContentDisposition = this.libmime.parseHeaderValue(headers.getFirst('Content-Disposition'));
+        let parsedContentDisposition = /** @type {StructuredHeader} */ (this._parsedContentDisposition);
 
         // if content-type is missing default to plaintext
         let contentHeader;
-        if (this.headers.get('Content-Type').length) {
-            contentHeader = this.headers.getFirst('Content-Type');
+        if (headers.get('Content-Type').length) {
+            contentHeader = headers.getFirst('Content-Type');
         } else {
-            if (this._parsedContentDisposition.params.filename) {
-                let extension = pathlib.parse(this._parsedContentDisposition.params.filename).ext.replace(/^\./, '');
+            if (parsedContentDisposition.params.filename) {
+                let extension = pathlib.parse(parsedContentDisposition.params.filename).ext.replace(/^\./, '');
                 if (extension) {
                     contentHeader = libmime.detectMimeType(extension);
                 }
             }
             if (!contentHeader) {
-                if (/^attachment$/i.test(this._parsedContentDisposition.value)) {
+                if (/^attachment$/i.test(parsedContentDisposition.value)) {
                     contentHeader = 'application/octet-stream';
                 } else {
                     contentHeader = 'text/plain';
@@ -86,15 +136,16 @@ class MimeNode {
         }
 
         this._parsedContentType = this.libmime.parseHeaderValue(contentHeader);
+        let parsedContentType = /** @type {StructuredHeader} */ (this._parsedContentType);
 
-        this.encoding = this.headers
+        this.encoding = headers
             .getFirst('Content-Transfer-Encoding')
             .replace(/\(.*\)/g, '')
             .toLowerCase()
             .trim();
-        this.contentType = (this._parsedContentType.value || '').toLowerCase().trim() || false;
-        this.charset = this._parsedContentType.params.charset || false;
-        this.disposition = (this._parsedContentDisposition.value || '').toLowerCase().trim() || false;
+        this.contentType = (parsedContentType.value || '').toLowerCase().trim() || false;
+        this.charset = parsedContentType.params.charset || false;
+        this.disposition = (parsedContentDisposition.value || '').toLowerCase().trim() || false;
 
         // fix invalidly encoded disposition values
         if (this.disposition) {
@@ -105,11 +156,11 @@ class MimeNode {
             }
         }
 
-        this.filename = this._parsedContentDisposition.params.filename || this._parsedContentType.params.name || false;
+        this.filename = parsedContentDisposition.params.filename || parsedContentType.params.name || false;
 
-        if (this._parsedContentType.params.format && this._parsedContentType.params.format.toLowerCase().trim() === 'flowed') {
+        if (parsedContentType.params.format && parsedContentType.params.format.toLowerCase().trim() === 'flowed') {
             this.flowed = true;
-            if (this._parsedContentType.params.delsp && this._parsedContentType.params.delsp.toLowerCase().trim() === 'yes') {
+            if (parsedContentType.params.delsp && parsedContentType.params.delsp.toLowerCase().trim() === 'yes') {
                 this.delSp = true;
             }
         }
@@ -127,7 +178,7 @@ class MimeNode {
                 this.contentType.substr(0, this.contentType.indexOf('/')) === 'multipart' &&
                 this.contentType.substr(this.contentType.indexOf('/') + 1)) ||
             false;
-        this._boundary = (this._parsedContentType.params.boundary && Buffer.from(this._parsedContentType.params.boundary)) || false;
+        this._boundary = (parsedContentType.params.boundary && Buffer.from(parsedContentType.params.boundary)) || false;
 
         this.rfc822 = this.contentType === 'message/rfc822';
 
@@ -138,38 +189,54 @@ class MimeNode {
         }
     }
 
+    /**
+     * @returns {Buffer}
+     */
     getHeaders() {
         if (!this.headers) {
             this.parseHeaders();
         }
-        return this.headers.build();
+        let headers = /** @type {HeadersType} */ (this.headers);
+        return headers.build();
     }
 
+    /**
+     * @param {string | false} [contentType]
+     * @returns {void}
+     */
     setContentType(contentType) {
         if (!this.headers) {
             this.parseHeaders();
         }
+        let headers = /** @type {HeadersType} */ (this.headers);
+        let parsedContentType = /** @type {StructuredHeader} */ (this._parsedContentType);
 
         contentType = (contentType || '').toLowerCase().trim();
         if (contentType) {
-            this._parsedContentType.value = contentType;
+            parsedContentType.value = contentType;
         }
 
-        if (!this.flowed && this._parsedContentType.params.format) {
-            delete this._parsedContentType.params.format;
+        if (!this.flowed && parsedContentType.params.format) {
+            delete parsedContentType.params.format;
         }
 
-        if (!this.delSp && this._parsedContentType.params.delsp) {
-            delete this._parsedContentType.params.delsp;
+        if (!this.delSp && parsedContentType.params.delsp) {
+            delete parsedContentType.params.delsp;
         }
 
-        this.headers.update('Content-Type', this.libmime.buildHeaderValue(this._parsedContentType));
+        headers.update('Content-Type', this.libmime.buildHeaderValue(parsedContentType));
     }
 
+    /**
+     * @param {string | false} [charset]
+     * @returns {void}
+     */
     setCharset(charset) {
         if (!this.headers) {
             this.parseHeaders();
         }
+        let headers = /** @type {HeadersType} */ (this.headers);
+        let parsedContentType = /** @type {StructuredHeader} */ (this._parsedContentType);
 
         charset = (charset || '').toLowerCase().trim();
 
@@ -178,51 +245,61 @@ class MimeNode {
         }
 
         if (!charset) {
-            if (!this._parsedContentType.value) {
+            if (!parsedContentType.value) {
                 // nothing to set or update
                 return;
             }
-            delete this._parsedContentType.params.charset;
+            delete parsedContentType.params.charset;
         } else {
-            this._parsedContentType.params.charset = charset;
+            parsedContentType.params.charset = charset;
         }
 
-        if (!this._parsedContentType.value) {
-            this._parsedContentType.value = 'text/plain';
+        if (!parsedContentType.value) {
+            parsedContentType.value = 'text/plain';
         }
 
-        this.headers.update('Content-Type', this.libmime.buildHeaderValue(this._parsedContentType));
+        headers.update('Content-Type', this.libmime.buildHeaderValue(parsedContentType));
     }
 
+    /**
+     * @param {string | false} [filename]
+     * @returns {void}
+     */
     setFilename(filename) {
         if (!this.headers) {
             this.parseHeaders();
         }
+        let headers = /** @type {HeadersType} */ (this.headers);
+        let parsedContentType = /** @type {StructuredHeader} */ (this._parsedContentType);
+        let parsedContentDisposition = /** @type {StructuredHeader} */ (this._parsedContentDisposition);
 
         this.filename = (filename || '').toLowerCase().trim();
 
-        if (this._parsedContentType.params.name) {
-            delete this._parsedContentType.params.name;
-            this.headers.update('Content-Type', this.libmime.buildHeaderValue(this._parsedContentType));
+        if (parsedContentType.params.name) {
+            delete parsedContentType.params.name;
+            headers.update('Content-Type', this.libmime.buildHeaderValue(parsedContentType));
         }
 
         if (!this.filename) {
-            if (!this._parsedContentDisposition.value) {
+            if (!parsedContentDisposition.value) {
                 // nothing to set or update
                 return;
             }
-            delete this._parsedContentDisposition.params.filename;
+            delete parsedContentDisposition.params.filename;
         } else {
-            this._parsedContentDisposition.params.filename = this.filename;
+            parsedContentDisposition.params.filename = this.filename;
         }
 
-        if (!this._parsedContentDisposition.value) {
-            this._parsedContentDisposition.value = 'attachment';
+        if (!parsedContentDisposition.value) {
+            parsedContentDisposition.value = 'attachment';
         }
 
-        this.headers.update('Content-Disposition', this.libmime.buildHeaderValue(this._parsedContentDisposition));
+        headers.update('Content-Disposition', this.libmime.buildHeaderValue(parsedContentDisposition));
     }
 
+    /**
+     * @returns {import('stream').Transform | import('stream').PassThrough}
+     */
     getDecoder() {
         if (!this.headers) {
             this.parseHeaders();
@@ -238,15 +315,20 @@ class MimeNode {
         }
     }
 
+    /**
+     * @param {string | false} [encoding]
+     * @returns {import('stream').Transform | import('stream').PassThrough}
+     */
     getEncoder(encoding) {
         if (!this.headers) {
             this.parseHeaders();
         }
+        let headers = /** @type {HeadersType} */ (this.headers);
 
         encoding = (encoding || '').toString().toLowerCase().trim();
 
         if (encoding && encoding !== this.encoding) {
-            this.headers.update('Content-Transfer-Encoding', encoding);
+            headers.update('Content-Transfer-Encoding', encoding);
         } else {
             encoding = this.encoding;
         }

package/lib/node-rewriter.d.ts

@@ -0,0 +1,105 @@
+import { Transform } from 'node:stream';
+import type { FilterFunc, RewriterNode, SplitterChunk } from './types';
+
+/** Transform stream that replaces the body content of selected MIME nodes. */
+declare class NodeRewriter extends Transform {
+    /**
+     * Creates a node rewriter that accepts splitter chunks and emits rewritten splitter chunks.
+     *
+     * @param filterFunc Predicate that selects MIME nodes to rewrite.
+     * @param rewriteAction Optional compatibility hook stored on the instance; consumers usually handle the `node` event.
+     */
+    constructor(filterFunc: FilterFunc, rewriteAction?: Function);
+
+    /**
+     * Registers a listener for rewritten splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each outgoing MIME node, data chunk, or body chunk.
+     * @returns This rewriter instance.
+     */
+    on(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Registers a listener for selected nodes.
+     *
+     * @param event Event name.
+     * @param listener Receives decoder and encoder streams for a selected node.
+     * @returns This rewriter instance.
+     */
+    on(event: 'node', listener: (data: RewriterNode) => void): this;
+
+    /**
+     * Registers a one-time listener for the next rewritten splitter chunk.
+     *
+     * @param event Event name.
+     * @param listener Receives the next outgoing MIME node, data chunk, or body chunk.
+     * @returns This rewriter instance.
+     */
+    once(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Registers a one-time listener for the next selected node.
+     *
+     * @param event Event name.
+     * @param listener Receives decoder and encoder streams for the next selected node.
+     * @returns This rewriter instance.
+     */
+    once(event: 'node', listener: (data: RewriterNode) => void): this;
+
+    /**
+     * Adds a listener for rewritten splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each outgoing MIME node, data chunk, or body chunk.
+     * @returns This rewriter instance.
+     */
+    addListener(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Adds a listener for selected nodes.
+     *
+     * @param event Event name.
+     * @param listener Receives decoder and encoder streams for a selected node.
+     * @returns This rewriter instance.
+     */
+    addListener(event: 'node', listener: (data: RewriterNode) => void): this;
+
+    /**
+     * Prepends a listener for rewritten splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each outgoing MIME node, data chunk, or body chunk.
+     * @returns This rewriter instance.
+     */
+    prependListener(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Prepends a listener for selected nodes.
+     *
+     * @param event Event name.
+     * @param listener Receives decoder and encoder streams for a selected node.
+     * @returns This rewriter instance.
+     */
+    prependListener(event: 'node', listener: (data: RewriterNode) => void): this;
+
+    /**
+     * Emits a rewritten 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;
+
+    /**
+     * Emits a selected-node payload.
+     *
+     * @param event Event name.
+     * @param data Selected node payload containing decoder and encoder streams.
+     * @returns `true` when the event had listeners.
+     */
+    emit(event: 'node', data: RewriterNode): boolean;
+}
+
+export = NodeRewriter;