@zone-eu/mailsplit 5.4.9 → 5.4.11

package/index.d.ts

@@ -0,0 +1,100 @@
+/// <reference types="node" />
+
+import Splitter = require('./lib/message-splitter');
+import Joiner = require('./lib/message-joiner');
+import Rewriter = require('./lib/node-rewriter');
+import Streamer = require('./lib/node-streamer');
+import ChunkedPassthrough = require('./lib/chunked-passthrough');
+import Headers = require('./lib/headers');
+import MimeNode = require('./lib/mime-node');
+
+export {
+    /** Splits raw message bytes into MIME node and content chunks. */
+    Splitter,
+
+    /** Joins MIME node and content chunks back into raw message bytes. */
+    Joiner,
+
+    /** Rewrites body content for MIME nodes selected by a filter function. */
+    Rewriter,
+
+    /** Streams decoded body content for MIME nodes selected by a filter function. */
+    Streamer,
+
+    /** Buffers byte input and emits larger Buffer chunks. */
+    ChunkedPassthrough,
+
+    /** Parses, mutates, and rebuilds message header blocks. */
+    Headers,
+
+    /** Represents one parsed MIME node and its header/body metadata. */
+    MimeNode
+};
+
+export type {
+    /** Value that is either present as `T` or explicitly unavailable as `false`. */
+    Maybe,
+
+    /** Single item in an IMAP-style MIME part number. */
+    PartNumberItem,
+
+    /** IMAP-style path to a MIME part. */
+    PartNumber,
+
+    /** Options passed through to libmime instances. */
+    LibmimeOptions,
+
+    /** Configuration for `Splitter` and MIME node parsing. */
+    SplitterOptions,
+
+    /** Configuration for `ChunkedPassthrough`. */
+    ChunkedPassthroughOptions,
+
+    /** Configuration for format=flowed decoding. */
+    FlowedDecoderOptions,
+
+    /** Parsed raw header line with a normalized lookup key. */
+    HeaderLine,
+
+    /** Decoded structured header value. */
+    DecodedHeader,
+
+    /** MIME node shape emitted by `Splitter`. */
+    MimeNode,
+
+    /** Data or body bytes emitted by `Splitter`. */
+    MessageChunk,
+
+    /** Sentinel input used internally by rewriter/streamer transforms. */
+    EmptyChunk,
+
+    /** Object emitted by `Splitter`. */
+    SplitterChunk,
+
+    /** Object accepted by rewriter and streamer transforms. */
+    RewriterInput,
+
+    /** Predicate used to select MIME nodes. */
+    FilterFunc,
+
+    /** Error object that may include a Node-style string code. */
+    ErrorWithCode,
+
+    /** Callback that resumes processing after a selected node stream ends. */
+    ContinueCallback,
+
+    /** Content transform stream used for decoded or encoded node bodies. */
+    ContentStream,
+
+    /** Decoder stream with an internal readable-state guard. */
+    DecoderStream,
+
+    /** Internal splitter grouping state. */
+    SplitterGroup,
+
+    /** Payload emitted with `Rewriter`'s `node` event. */
+    RewriterNode,
+
+    /** Payload emitted with `Streamer`'s `node` event. */
+    StreamerNode
+} from './lib/types';

package/index.js

@@ -6,12 +6,15 @@ const NodeRewriter = require('./lib/node-rewriter');
 const NodeStreamer = require('./lib/node-streamer');
 const Headers = require('./lib/headers');
 const ChunkedPassthrough = require('./lib/chunked-passthrough');
+const MimeNode = require('./lib/mime-node');
 
+/** @type {typeof import('.')} */
 module.exports = {
     Splitter: MessageSplitter,
     Joiner: MessageJoiner,
     Rewriter: NodeRewriter,
     Streamer: NodeStreamer,
     ChunkedPassthrough,
-    Headers
+    Headers,
+    MimeNode
 };

package/lib/chunked-passthrough.d.ts

@@ -0,0 +1,59 @@
+import { Transform } from 'node:stream';
+import type { ChunkedPassthroughOptions } from './types';
+
+/** Transform stream that buffers byte input and emits larger Buffer chunks. */
+declare class ChunkedPassthrough extends Transform {
+    /**
+     * Creates a chunking passthrough transform that accepts Buffer input and emits Buffer chunks.
+     *
+     * @param options Optional chunk size configuration.
+     */
+    constructor(options?: ChunkedPassthroughOptions);
+
+    /**
+     * Registers a listener for buffered byte chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each buffered Buffer chunk.
+     * @returns This passthrough instance.
+     */
+    on(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Registers a one-time listener for the next buffered byte chunk.
+     *
+     * @param event Event name.
+     * @param listener Receives the next buffered Buffer chunk.
+     * @returns This passthrough instance.
+     */
+    once(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Adds a listener for buffered byte chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each buffered Buffer chunk.
+     * @returns This passthrough instance.
+     */
+    addListener(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Prepends a listener for buffered byte chunks.
+     *
+     * @param event Event name.
+     * @param listener Receives each buffered Buffer chunk.
+     * @returns This passthrough instance.
+     */
+    prependListener(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Emits a buffered 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 = ChunkedPassthrough;

package/lib/chunked-passthrough.js

@@ -2,7 +2,13 @@
 
 const { Transform } = require('stream');
 
+/**
+ * Transform stream that buffers byte input and emits larger Buffer chunks.
+ */
 class ChunkedPassthrough extends Transform {
+    /**
+     * @param {import('..').ChunkedPassthroughOptions} [options]
+     */
     constructor(options = {}) {
         let config = {
             readableObjectMode: true,
@@ -13,6 +19,12 @@ class ChunkedPassthrough extends Transform {
         this.buffer = Buffer.alloc(0);
     }
 
+    /**
+     * @param {Buffer} chunk
+     * @param {BufferEncoding} encoding
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _transform(chunk, encoding, callback) {
         this.buffer = Buffer.concat([this.buffer, chunk]);
 
@@ -24,6 +36,10 @@ class ChunkedPassthrough extends Transform {
         callback();
     }
 
+    /**
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _flush(callback) {
         // Send remaining data
         if (this.buffer.length > 0) {

package/lib/flowed-decoder.d.ts

@@ -0,0 +1,59 @@
+import { Transform } from 'node:stream';
+import type { FlowedDecoderOptions } from './types';
+
+/** Transform stream that decodes `text/plain; format=flowed` content. */
+declare class FlowedDecoder extends Transform {
+    /**
+     * Creates a flowed text decoder that accepts encoded text bytes and emits decoded Buffer chunks.
+     *
+     * @param config Optional flowed text and charset decoding settings.
+     */
+    constructor(config?: FlowedDecoderOptions);
+
+    /**
+     * Registers a listener for decoded flowed text bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives decoded Buffer chunks.
+     * @returns This decoder instance.
+     */
+    on(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Registers a one-time listener for the next decoded flowed text chunk.
+     *
+     * @param event Event name.
+     * @param listener Receives the next decoded Buffer chunk.
+     * @returns This decoder instance.
+     */
+    once(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Adds a listener for decoded flowed text bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives decoded Buffer chunks.
+     * @returns This decoder instance.
+     */
+    addListener(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Prepends a listener for decoded flowed text bytes.
+     *
+     * @param event Event name.
+     * @param listener Receives decoded Buffer chunks.
+     * @returns This decoder instance.
+     */
+    prependListener(event: 'data', listener: (data: Buffer) => void): this;
+
+    /**
+     * Emits a decoded flowed text 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 = FlowedDecoder;

package/lib/flowed-decoder.js

@@ -1,33 +1,46 @@
 'use strict';
 
-// Helper class to rewrite nodes with specific mime type
+// Helper class to decode format=flowed text nodes
 
 const Transform = require('stream').Transform;
 const libmime = require('libmime');
 
+/** @typedef {import('..').FlowedDecoderOptions} FlowedDecoderOptions */
+
+const Libmime = /** @type {any} */ (libmime.Libmime);
+
 /**
- * Really bad "stream" transform to parse format=flowed content
+ * Transform stream that decodes text/plain format=flowed content.
  *
- * @constructor
- * @param {String} delSp True if delsp option was used
+ * @param {FlowedDecoderOptions} [config] Flowed text and charset decoding settings.
  */
 class FlowedDecoder extends Transform {
+    /**
+     * @param {FlowedDecoderOptions} [config] Flowed text and charset decoding settings.
+     */
     constructor(config) {
         super();
         this.config = config || {};
 
+        /** @type {Buffer[]} */
         this.chunks = [];
         this.chunklen = 0;
 
-        this.libmime = new libmime.Libmime({ Iconv: config.Iconv });
+        this.libmime = new Libmime({ Iconv: this.config.Iconv });
     }
 
+    /**
+     * @param {Buffer | string} chunk
+     * @param {BufferEncoding} encoding
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _transform(chunk, encoding, callback) {
         if (!chunk || !chunk.length) {
             return callback();
         }
 
-        if (!encoding !== 'buffer') {
+        if (typeof chunk === 'string') {
             chunk = Buffer.from(chunk, encoding);
         }
 
@@ -37,6 +50,10 @@ class FlowedDecoder extends Transform {
         callback();
     }
 
+    /**
+     * @param {import('stream').TransformCallback} callback
+     * @returns {void}
+     */
     _flush(callback) {
         if (this.chunklen) {
             let currentBody = Buffer.concat(this.chunks, this.chunklen);

package/lib/headers.d.ts

@@ -0,0 +1,117 @@
+import type { DecodedHeader, HeaderLine, LibmimeOptions } from './types';
+
+/** Mutable parser and builder for RFC-style message header blocks. */
+declare class Headers {
+    /** Whether header lines have been modified after construction. */
+    changed: boolean;
+
+    /** Original unparsed header source, or `false` when constructed from parsed lines. */
+    headers: string | Buffer | false;
+
+    /** Whether `headers` has been parsed into `lines`. */
+    parsed: boolean;
+
+    /** Parsed header lines, or `false` until parsing occurs. */
+    lines: HeaderLine[] | false;
+
+    /** MBOX `From ` prefix line, or `false` when absent. */
+    mbox: string | false;
+
+    /** HTTP request prefix line, or `false` when absent. */
+    http: string | false;
+
+    /**
+     * Creates a mutable header collection.
+     *
+     * @param headers Raw header bytes/string, already parsed header lines, or `false` for an empty collection.
+     * @param config Optional libmime configuration.
+     */
+    constructor(headers?: string | Buffer | HeaderLine[] | false, config?: LibmimeOptions);
+
+    /**
+     * Checks whether at least one header with the requested key exists.
+     *
+     * @param key Header field name to find, case-insensitively.
+     * @returns `true` when the header exists.
+     */
+    hasHeader(key: string): boolean;
+
+    /**
+     * Gets all raw header lines for a key.
+     *
+     * @param key Header field name to find, case-insensitively.
+     * @returns Full decoded header lines, including field names.
+     */
+    get(key: string): string[];
+
+    /**
+     * Gets all decoded structured header values for a key.
+     *
+     * @param key Header field name to decode, case-insensitively.
+     * @returns Decoded header entries with key and value fields.
+     */
+    getDecoded(key: string): DecodedHeader[];
+
+    /**
+     * Gets the first decoded header value for a key.
+     *
+     * @param key Header field name to find, case-insensitively.
+     * @returns Trimmed decoded value, or an empty string when the header is absent.
+     */
+    getFirst(key: string): string;
+
+    /**
+     * Gets the mutable parsed header list.
+     *
+     * @returns Parsed header lines in message order.
+     */
+    getList(): HeaderLine[];
+
+    /**
+     * Adds a folded header line.
+     *
+     * @param key Header field name to add.
+     * @param value Header value; `undefined` leaves the collection unchanged.
+     * @param index Insertion index, where omitted or less than 1 inserts at the top.
+     * @returns Nothing.
+     */
+    add(key: string, value?: string | number | Buffer, index?: number): void;
+
+    /**
+     * Adds a preformatted header line.
+     *
+     * @param key Header field name used for normalized lookup.
+     * @param line Full header line to insert; falsy values leave the collection unchanged.
+     * @param index Insertion index, where omitted or less than 1 inserts at the top.
+     * @returns Nothing.
+     */
+    addFormatted(key: string, line?: string | Buffer | false, index?: number): void;
+
+    /**
+     * Removes all headers matching a key.
+     *
+     * @param key Header field name to remove, case-insensitively.
+     * @returns Nothing.
+     */
+    remove(key: string): void;
+
+    /**
+     * Replaces matching headers with a new folded header value.
+     *
+     * @param key Header field name to update.
+     * @param value Header value to write; `undefined` removes matching values without adding a replacement.
+     * @param relativeIndex Optional zero-based index among headers with the same key.
+     * @returns Nothing.
+     */
+    update(key: string, value?: string | number | Buffer, relativeIndex?: number): void;
+
+    /**
+     * Builds a raw header block.
+     *
+     * @param lineEnd Line ending to use when rebuilding changed headers; defaults to CRLF.
+     * @returns Header bytes ending with an empty header/body separator line.
+     */
+    build(lineEnd?: string | false): Buffer;
+}
+
+export = Headers;