@zone-eu/mailsplit 5.4.9 → 5.4.11

package/lib/node-rewriter.js

@@ -5,14 +5,26 @@
 const Transform = require('stream').Transform;
 const FlowedDecoder = require('./flowed-decoder');
 
+/** @typedef {import('..').MimeNode} MimeNode */
+/** @typedef {import('..').RewriterInput} RewriterInput */
+/** @typedef {import('..').FilterFunc} FilterFunc */
+/** @typedef {import('..').RewriterNode} RewriterNode */
+/** @typedef {import('..').DecoderStream} DecoderStream */
+/** @typedef {import('..').ContentStream} ContentStream */
+/** @typedef {import('..').ContinueCallback} ContinueCallback */
+
 /**
- * NodeRewriter Transform stream. Updates content for all nodes with specified mime type
+ * NodeRewriter Transform stream. Updates content for all nodes selected by the
+ * filter function.
  *
- * @constructor
- * @param {String} mimeType Define the Mime-Type to look for
- * @param {Function} rewriteAction Function to run with the node content
+ * @param {FilterFunc} filterFunc Function that receives a MIME node and returns true to rewrite it.
+ * @param {Function} [rewriteAction] Optional compatibility hook stored on the instance.
  */
 class NodeRewriter extends Transform {
+    /**
+     * @param {FilterFunc} filterFunc Function that receives a MIME node and returns true to rewrite it.
+     * @param {Function} [rewriteAction] Optional compatibility hook stored on the instance.
+     */
     constructor(filterFunc, rewriteAction) {
         let options = {
             readableObjectMode: true,
@@ -23,15 +35,28 @@ class NodeRewriter extends Transform {
         this.filterFunc = filterFunc;
         this.rewriteAction = rewriteAction;
 
+        /** @type {DecoderStream | false} */
         this.decoder = false;
+        /** @type {ContentStream | false} */
         this.encoder = false;
+        /** @type {ContinueCallback | false} */
         this.continue = false;
     }
 
+    /**
+     * @param {RewriterInput} data
+     * @param {BufferEncoding} encoding
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _transform(data, encoding, callback) {
         this.processIncoming(data, callback);
     }
 
+    /**
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _flush(callback) {
         if (this.decoder) {
             // emit an empty node just in case there is pending data to end
@@ -45,11 +70,17 @@ class NodeRewriter extends Transform {
         return callback();
     }
 
+    /**
+     * @param {RewriterInput} data
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     processIncoming(data, callback) {
         if (this.decoder && data.type === 'body') {
             // data to parse
             if (!this.decoder.write(data.value)) {
-                return this.decoder.once('drain', callback);
+                this.decoder.once('drain', callback);
+                return;
             } else {
                 return callback();
             }
@@ -64,7 +95,8 @@ class NodeRewriter extends Transform {
                 this.encoder = false;
                 this.processIncoming(data, callback);
             };
-            return this.decoder.end();
+            this.decoder.end();
+            return;
         } else if (data.type === 'node' && this.filterFunc(data)) {
             // found matching node, create new handler
             this.emit('node', this.createDecodePair(data));
@@ -75,22 +107,32 @@ class NodeRewriter extends Transform {
         callback();
     }
 
+    /**
+     * @param {MimeNode} node
+     * @returns {RewriterNode}
+     */
     createDecodePair(node) {
-        this.decoder = node.getDecoder();
+        this.decoder = /** @type {DecoderStream} */ (node.getDecoder());
 
-        if (['base64', 'quoted-printable'].includes(node.encoding)) {
+        if (['base64', 'quoted-printable'].includes(node.encoding || '')) {
             this.encoder = node.getEncoder();
         } else {
             this.encoder = node.getEncoder('quoted-printable');
         }
 
+        /** @type {number | false} */
         let lastByte = false;
 
-        let decoder = this.decoder;
-        let encoder = this.encoder;
+        let decoder = /** @type {DecoderStream} */ (this.decoder);
+        let encoder = /** @type {ContentStream} */ (this.encoder);
         let firstChunk = true;
         decoder.$reading = false;
 
+        /**
+         * Reads encoded replacement bytes and forwards them as body chunks.
+         *
+         * @returns {void | NodeJS.Immediate}
+         */
         let readFromEncoder = () => {
             decoder.$reading = true;
 
@@ -104,9 +146,6 @@ class NodeRewriter extends Transform {
                 firstChunk = false;
                 if (this.readable) {
                     this.push(node);
-                    if (node.type === 'body') {
-                        lastByte = node.value && node.value.length && node.value[node.value.length - 1];
-                    }
                 }
             }
 
@@ -144,9 +183,6 @@ class NodeRewriter extends Transform {
                 firstChunk = false;
                 if (this.readable) {
                     this.push(node);
-                    if (node.type === 'body') {
-                        lastByte = node.value && node.value.length && node.value[node.value.length - 1];
-                    }
                 }
             }
 
@@ -164,16 +200,25 @@ class NodeRewriter extends Transform {
             }
         });
 
-        if (/^text\//.test(node.contentType) && node.flowed) {
+        if (/^text\//.test(node.contentType || '') && node.flowed) {
             // text/plain; format=flowed is a special case
             let flowDecoder = decoder;
             decoder = new FlowedDecoder({
                 delSp: node.delSp,
-                encoding: node.encoding
-            });
-            flowDecoder.on('error', err => {
-                decoder.emit('error', err);
+                encoding: node.encoding || false
             });
+            flowDecoder.on(
+                'error',
+                /**
+                 * Forwards flowed decoder errors to the replacement decoder.
+                 *
+                 * @param {Error} err Decoder error to forward.
+                 * @returns {void}
+                 */
+                err => {
+                    decoder.emit('error', err);
+                }
+            );
             flowDecoder.pipe(decoder);
 
             // we don't know what kind of data we are going to get, does it comply with the

package/lib/node-streamer.d.ts

@@ -0,0 +1,105 @@
+import { Transform } from 'node:stream';
+import type { FilterFunc, SplitterChunk, StreamerNode } from './types';
+
+/** Transform stream that exposes decoded body streams for selected MIME nodes without replacing them. */
+declare class NodeStreamer extends Transform {
+    /**
+     * Creates a node streamer that accepts splitter chunks and passes them through unchanged.
+     *
+     * @param filterFunc Predicate that selects MIME nodes to stream.
+     * @param streamAction Optional compatibility hook stored on the instance; consumers usually handle the `node` event.
+     */
+    constructor(filterFunc: FilterFunc, streamAction?: Function);
+
+    /**
+     * Registers a listener for passed-through splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each outgoing MIME node, data chunk, or body chunk.
+     * @returns This streamer instance.
+     */
+    on(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Registers a listener for selected nodes.
+     *
+     * @param event Event name.
+     * @param listener Receives a decoder stream and completion callback for a selected node.
+     * @returns This streamer instance.
+     */
+    on(event: 'node', listener: (data: StreamerNode) => void): this;
+
+    /**
+     * Registers a one-time listener for the next passed-through splitter chunk.
+     *
+     * @param event Event name.
+     * @param listener Receives the next outgoing MIME node, data chunk, or body chunk.
+     * @returns This streamer 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 a decoder stream and completion callback for the next selected node.
+     * @returns This streamer instance.
+     */
+    once(event: 'node', listener: (data: StreamerNode) => void): this;
+
+    /**
+     * Adds a listener for passed-through splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each outgoing MIME node, data chunk, or body chunk.
+     * @returns This streamer instance.
+     */
+    addListener(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Adds a listener for selected nodes.
+     *
+     * @param event Event name.
+     * @param listener Receives a decoder stream and completion callback for a selected node.
+     * @returns This streamer instance.
+     */
+    addListener(event: 'node', listener: (data: StreamerNode) => void): this;
+
+    /**
+     * Prepends a listener for passed-through splitter chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each outgoing MIME node, data chunk, or body chunk.
+     * @returns This streamer instance.
+     */
+    prependListener(event: 'data', listener: (data: SplitterChunk) => void): this;
+
+    /**
+     * Prepends a listener for selected nodes.
+     *
+     * @param event Event name.
+     * @param listener Receives a decoder stream and completion callback for a selected node.
+     * @returns This streamer instance.
+     */
+    prependListener(event: 'node', listener: (data: StreamerNode) => void): this;
+
+    /**
+     * Emits a passed-through 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 stream and completion callback.
+     * @returns `true` when the event had listeners.
+     */
+    emit(event: 'node', data: StreamerNode): boolean;
+}
+
+export = NodeStreamer;

package/lib/node-streamer.js

@@ -1,18 +1,29 @@
 'use strict';
 
-// Helper class to rewrite nodes with specific mime type
+// Helper class to stream selected nodes by MIME metadata
 
 const Transform = require('stream').Transform;
 const FlowedDecoder = require('./flowed-decoder');
 
+/** @typedef {import('..').MimeNode} MimeNode */
+/** @typedef {import('..').RewriterInput} RewriterInput */
+/** @typedef {import('..').FilterFunc} FilterFunc */
+/** @typedef {import('..').StreamerNode} StreamerNode */
+/** @typedef {import('..').DecoderStream} DecoderStream */
+/** @typedef {import('..').ContinueCallback} ContinueCallback */
+
 /**
- * NodeRewriter Transform stream. Updates content for all nodes with specified mime type
+ * NodeStreamer Transform stream. Exposes decoded content for nodes selected by
+ * the filter function while passing the original message through unchanged.
  *
- * @constructor
- * @param {String} mimeType Define the Mime-Type to look for
- * @param {Function} streamAction Function to run with the node content
+ * @param {FilterFunc} filterFunc Function that receives a MIME node and returns true to stream it.
+ * @param {Function} [streamAction] Optional compatibility hook stored on the instance.
  */
 class NodeStreamer extends Transform {
+    /**
+     * @param {FilterFunc} filterFunc Function that receives a MIME node and returns true to stream it.
+     * @param {Function} [streamAction] Optional compatibility hook stored on the instance.
+     */
     constructor(filterFunc, streamAction) {
         let options = {
             readableObjectMode: true,
@@ -23,15 +34,27 @@ class NodeStreamer extends Transform {
         this.filterFunc = filterFunc;
         this.streamAction = streamAction;
 
+        /** @type {DecoderStream | false} */
         this.decoder = false;
         this.canContinue = false;
+        /** @type {ContinueCallback | false} */
         this.continue = false;
     }
 
+    /**
+     * @param {RewriterInput} data
+     * @param {BufferEncoding} encoding
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _transform(data, encoding, callback) {
         this.processIncoming(data, callback);
     }
 
+    /**
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _flush(callback) {
         if (this.decoder) {
             // emit an empty node just in case there is pending data to end
@@ -45,12 +68,18 @@ class NodeStreamer extends Transform {
         return callback();
     }
 
+    /**
+     * @param {RewriterInput} data
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     processIncoming(data, callback) {
         if (this.decoder && data.type === 'body') {
             // data to parse
             this.push(data);
             if (!this.decoder.write(data.value)) {
-                return this.decoder.once('drain', callback);
+                this.decoder.once('drain', callback);
+                return;
             } else {
                 return callback();
             }
@@ -60,6 +89,11 @@ class NodeStreamer extends Transform {
             // the parsed data is completely processed, so we store a reference to the
             // continue callback
 
+            /**
+             * Resumes processing with the first chunk after the streamed node.
+             *
+             * @returns {void}
+             */
             let doContinue = () => {
                 this.continue = false;
                 this.decoder = false;
@@ -73,7 +107,8 @@ class NodeStreamer extends Transform {
                 this.continue = () => doContinue();
             }
 
-            return this.decoder.end();
+            this.decoder.end();
+            return;
         } else if (data.type === 'node' && this.filterFunc(data)) {
             this.push(data);
             // found matching node, create new handler
@@ -85,26 +120,44 @@ class NodeStreamer extends Transform {
         callback();
     }
 
+    /**
+     * @param {MimeNode} node
+     * @returns {StreamerNode}
+     */
     createDecoder(node) {
-        this.decoder = node.getDecoder();
+        this.decoder = /** @type {DecoderStream} */ (node.getDecoder());
 
-        let decoder = this.decoder;
+        let decoder = /** @type {DecoderStream} */ (this.decoder);
         decoder.$reading = false;
 
-        if (/^text\//.test(node.contentType) && node.flowed) {
+        if (/^text\//.test(node.contentType || '') && node.flowed) {
             let flowDecoder = decoder;
             decoder = new FlowedDecoder({
                 delSp: node.delSp
             });
-            flowDecoder.on('error', err => {
-                decoder.emit('error', err);
-            });
+            flowDecoder.on(
+                'error',
+                /**
+                 * Forwards flowed decoder errors to the output decoder.
+                 *
+                 * @param {Error} err Decoder error to forward.
+                 * @returns {void}
+                 */
+                err => {
+                    decoder.emit('error', err);
+                }
+            );
             flowDecoder.pipe(decoder);
         }
 
         return {
             node,
             decoder,
+            /**
+             * Marks the selected node stream as consumed so the passthrough can continue.
+             *
+             * @returns {void}
+             */
             done: () => {
                 if (typeof this.continue === 'function') {
                     // called once input stream is processed