postal-mime 2.4.7 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [2.6.0](https://github.com/postalsys/postal-mime/compare/v2.5.0...v2.6.0) (2025-10-24)
+
+
+### Features
+
+* add CommonJS build support for dual package compatibility ([0ea3de3](https://github.com/postalsys/postal-mime/commit/0ea3de39c713aac2bc79218dfb496c0e2ff4b0b8))
+
+## [2.5.0](https://github.com/postalsys/postal-mime/compare/v2.4.7...v2.5.0) (2025-10-07)
+
+
+### Features
+
+* add comprehensive type validation and TypeScript support ([81a6467](https://github.com/postalsys/postal-mime/commit/81a6467b6c5379c502bac9ee7023e2c2dee976cb))
+
 ## [2.4.7](https://github.com/postalsys/postal-mime/compare/v2.4.6...v2.4.7) (2025-10-07)
 
 

package/README.md

@@ -2,9 +2,18 @@
 
 **postal-mime** is an email parsing library that runs in browser environments (including Web Workers) and serverless functions (like Cloudflare Email Workers). It takes in a raw email message (RFC822 format) and outputs a structured object containing headers, recipients, attachments, and more.
 
-> **Tip**  
+> [!TIP]
 > PostalMime is developed by the makers of [EmailEngine](https://emailengine.app/?utm_source=github&utm_campaign=imapflow&utm_medium=readme-link)—a self-hosted email gateway that provides a REST API for IMAP and SMTP servers and sends webhooks whenever something changes in registered accounts.
 
+## Features
+
+-   **Browser & Node.js compatible** - Works in browsers, Web Workers, Node.js, and serverless environments
+-   **TypeScript support** - Fully typed with comprehensive type definitions
+-   **Zero dependencies** - No external dependencies
+-   **RFC compliant** - Follows RFC 2822/5322 email standards
+-   **Handles complex MIME structures** - Multipart messages, nested parts, attachments
+-   **Security limits** - Built-in protection against deeply nested messages and oversized headers
+
 ## Table of Contents
 
 -   [Source](#source)
@@ -14,6 +23,7 @@
     -   [Browser](#browser)
     -   [Node.js](#nodejs)
     -   [Cloudflare Email Workers](#cloudflare-email-workers)
+-   [TypeScript Support](#typescript-support)
 -   [API](#api)
     -   [PostalMime.parse()](#postalmimeparse)
     -   [Utility Functions](#utility-functions)
@@ -58,6 +68,23 @@ Content-Type: text/html; charset=utf-8
 console.log(email.subject); // "My awesome email 🤓"
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import PostalMime from './node_modules/postal-mime/src/postal-mime.js';
+import type { Email } from 'postal-mime';
+
+const email: Email = await PostalMime.parse(`Subject: My awesome email 🤓
+Content-Type: text/html; charset=utf-8
+
+<p>Hello world 😵‍💫</p>`);
+
+console.log(email.subject); // "My awesome email 🤓"
+```
+
+</details>
+
 ### Node.js
 
 In Node.js (including serverless functions), import it directly from `postal-mime`:
@@ -75,6 +102,48 @@ Content-Type: text/html; charset=utf-8
 console.log(util.inspect(email, false, 22, true));
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import PostalMime from 'postal-mime';
+import type { Email, PostalMimeOptions } from 'postal-mime';
+import util from 'node:util';
+
+const options: PostalMimeOptions = {
+    attachmentEncoding: 'base64'
+};
+
+const email: Email = await PostalMime.parse(`Subject: My awesome email 🤓
+Content-Type: text/html; charset=utf-8
+
+<p>Hello world 😵‍💫</p>`, options);
+
+// Use 'util.inspect' for pretty-printing
+console.log(util.inspect(email, false, 22, true));
+```
+
+</details>
+
+### CommonJS
+
+For projects using CommonJS (with `require()`), postal-mime automatically provides the CommonJS build:
+
+```js
+const PostalMime = require('postal-mime');
+const { addressParser, decodeWords } = require('postal-mime');
+
+const email = await PostalMime.parse(`Subject: My awesome email 🤓
+Content-Type: text/html; charset=utf-8
+
+<p>Hello world 😵‍💫</p>`);
+
+console.log(email.subject); // "My awesome email 🤓"
+```
+
+> [!NOTE]
+> The CommonJS build is automatically generated from the ESM source code during the build process. The package supports dual module format, so both `import` and `require()` work seamlessly.
+
 ### Cloudflare Email Workers
 
 Use the `message.raw` as the raw email data for parsing:
@@ -93,6 +162,77 @@ export default {
 };
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import PostalMime from 'postal-mime';
+import type { Email } from 'postal-mime';
+
+export default {
+    async email(message: ForwardableEmailMessage, env: Env, ctx: ExecutionContext): Promise<void> {
+        const email: Email = await PostalMime.parse(message.raw);
+
+        console.log('Subject:', email.subject);
+        console.log('HTML:', email.html);
+        console.log('Text:', email.text);
+    }
+};
+```
+
+</details>
+
+---
+
+## TypeScript Support
+
+PostalMime includes comprehensive TypeScript type definitions. All types are exported and can be imported from the main package:
+
+```typescript
+import PostalMime, { addressParser, decodeWords } from 'postal-mime';
+import type {
+    Email,
+    Address,
+    Mailbox,
+    Header,
+    Attachment,
+    PostalMimeOptions,
+    AddressParserOptions,
+    RawEmail
+} from 'postal-mime';
+```
+
+> [!NOTE]
+> PostalMime is written in JavaScript but provides comprehensive TypeScript type definitions. All types are validated through both compile-time type checking and runtime type validation tests to ensure accuracy.
+
+### Available Types
+
+-   **`Email`** - The main parsed email object returned by `PostalMime.parse()`
+-   **`Address`** - Union type representing either a `Mailbox` or an address group
+-   **`Mailbox`** - Individual email address with name and address fields
+-   **`Header`** - Email header with key and value
+-   **`Attachment`** - Email attachment with metadata and content
+-   **`PostalMimeOptions`** - Configuration options for parsing
+-   **`AddressParserOptions`** - Configuration options for address parsing
+-   **`RawEmail`** - Union type for all accepted email input formats
+
+### Type Narrowing
+
+TypeScript users can use type guards to narrow address types:
+
+```typescript
+import type { Address, Mailbox } from 'postal-mime';
+
+function isMailbox(addr: Address): addr is Mailbox {
+    return !('group' in addr) || addr.group === undefined;
+}
+
+// Usage
+if (email.from && isMailbox(email.from)) {
+    console.log(email.from.address); // TypeScript knows this is a Mailbox
+}
+```
+
 ---
 
 ## API
@@ -100,7 +240,7 @@ export default {
 ### PostalMime.parse()
 
 ```js
-PostalMime.parse(email, options) -> Promise<ParsedEmail>
+PostalMime.parse(email, options) -> Promise<Email>
 ```
 
 -   **email**: An RFC822 formatted email. This can be a `string`, `ArrayBuffer/Uint8Array`, `Blob` (browser only), `Buffer` (Node.js), or a [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream).
@@ -114,29 +254,86 @@ PostalMime.parse(email, options) -> Promise<ParsedEmail>
     -   **maxNestingDepth** (number, default: `256`): Maximum allowed MIME part nesting depth. Throws an error if exceeded.
     -   **maxHeadersSize** (number, default: `2097152`): Maximum allowed total header size in bytes (default 2MB). Throws an error if exceeded.
 
-**Returns**: A Promise that resolves to a structured object with the following properties:
+> [!IMPORTANT]
+> The `maxNestingDepth` and `maxHeadersSize` options provide built-in security against malicious emails with deeply nested MIME structures or oversized headers that could cause performance issues or memory exhaustion.
+
+**Returns**: A Promise that resolves to a structured `Email` object with the following properties:
 
--   **headers**: An array of header objects, each containing:
+-   **headers**: An array of `Header` objects, each containing:
     -   `key`: Lowercase header name (e.g., `"dkim-signature"`).
     -   `value`: Unprocessed header value as a string.
--   **from**, **sender**: Processed address objects:
+-   **from**, **sender**: Processed `Address` objects (can be a `Mailbox` or address group):
     -   `name`: Decoded display name, or an empty string if not set.
     -   `address`: Email address.
+    -   `group`: Array of `Mailbox` objects (only for address groups).
 -   **deliveredTo**, **returnPath**: Single email addresses as strings.
--   **to**, **cc**, **bcc**, **replyTo**: Arrays of processed address objects (same structure as `from`).
+-   **to**, **cc**, **bcc**, **replyTo**: Arrays of `Address` objects (same structure as `from`).
 -   **subject**: Subject line of the email.
 -   **messageId**, **inReplyTo**, **references**: Values from their corresponding headers.
--   **date**: The email’s sending time in ISO 8601 format (or the original string if parsing fails).
+-   **date**: The email's sending time in ISO 8601 format (or the original string if parsing fails).
 -   **html**: String containing the HTML content of the email.
 -   **text**: String containing the plain text content of the email.
--   **attachments**: Array of attachment objects:
-    -   `filename`
-    -   `mimeType`
-    -   `disposition` (e.g., `"attachment"`, `"inline"`, or `null`)
-    -   `related` (boolean, `true` if it’s an inline image)
-    -   `contentId`
-    -   `content` (array buffer or string, depending on `attachmentEncoding`)
-    -   `encoding` (e.g., `"base64"`)
+-   **attachments**: Array of `Attachment` objects:
+    -   `filename`: String or `null`
+    -   `mimeType`: String
+    -   `disposition`: `"attachment"`, `"inline"`, or `null`
+    -   `related`: Boolean (optional, `true` if it's an inline image)
+    -   `contentId`: String (optional)
+    -   `content`: `ArrayBuffer` or string, depending on `attachmentEncoding`
+    -   `encoding`: `"base64"` or `"utf8"` (optional)
+
+<details>
+<summary><strong>TypeScript Types</strong></summary>
+
+```typescript
+import type {
+    Email,
+    Address,
+    Mailbox,
+    Header,
+    Attachment,
+    PostalMimeOptions,
+    RawEmail
+} from 'postal-mime';
+
+// Main email parsing
+const email: Email = await PostalMime.parse(rawEmail);
+
+// With options
+const options: PostalMimeOptions = {
+    attachmentEncoding: 'base64',
+    maxNestingDepth: 100
+};
+const email: Email = await PostalMime.parse(rawEmail, options);
+
+// Working with addresses
+if (email.from) {
+    // Address can be either a Mailbox or a Group
+    if ('group' in email.from && email.from.group) {
+        // It's a group
+        email.from.group.forEach((member: Mailbox) => {
+            console.log(member.address);
+        });
+    } else {
+        // It's a mailbox
+        const mailbox = email.from as Mailbox;
+        console.log(mailbox.address);
+    }
+}
+
+// Working with attachments
+email.attachments.forEach((att: Attachment) => {
+    if (att.encoding === 'base64') {
+        // content is a string
+        const base64Content: string = att.content as string;
+    } else {
+        // content is ArrayBuffer (default)
+        const buffer: ArrayBuffer = att.content as ArrayBuffer;
+    }
+});
+```
+
+</details>
 
 ---
 
@@ -147,23 +344,42 @@ PostalMime.parse(email, options) -> Promise<ParsedEmail>
 ```js
 import { addressParser } from 'postal-mime';
 
-addressParser(addressStr, opts) -> Array
+addressParser(addressStr, opts) -> Address[]
 ```
 
 -   **addressStr**: A raw address header string.
 -   **opts**: Optional configuration:
     -   **flatten** (boolean, default: `false`): If `true`, ignores address groups and returns a flat array of addresses.
 
-**Returns**: An array of address objects, which can be nested if address groups are present.
+**Returns**: An array of `Address` objects, which can be nested if address groups are present.
 
 **Example**:
 
 ```js
+import { addressParser } from 'postal-mime';
+
 const addressStr = '=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@example.com>';
 console.log(addressParser(addressStr));
 // [ { name: 'エポスカード', address: 'support@example.com' } ]
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import { addressParser } from 'postal-mime';
+import type { Address, AddressParserOptions } from 'postal-mime';
+
+const addressStr = '=?utf-8?B?44Ko44Od44K544Kr44O844OJ?= <support@example.com>';
+const addresses: Address[] = addressParser(addressStr);
+
+// With options
+const options: AddressParserOptions = { flatten: true };
+const flatAddresses: Address[] = addressParser(addressStr, options);
+```
+
+</details>
+
 #### decodeWords()
 
 ```js
@@ -179,11 +395,26 @@ decodeWords(encodedStr) -> string
 **Example**:
 
 ```js
+import { decodeWords } from 'postal-mime';
+
 const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?=';
 console.log(decodeWords(encodedStr));
 // Hello, エポスカード
 ```
 
+<details>
+<summary><strong>TypeScript</strong></summary>
+
+```typescript
+import { decodeWords } from 'postal-mime';
+
+const encodedStr = 'Hello, =?utf-8?B?44Ko44Od44K544Kr44O844OJ?=';
+const decoded: string = decodeWords(encodedStr);
+console.log(decoded); // Hello, エポスカード
+```
+
+</details>
+
 ---
 
 ## License

package/dist/address-parser.cjs

@@ -0,0 +1,317 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var address_parser_exports = {};
+__export(address_parser_exports, {
+  default: () => address_parser_default
+});
+module.exports = __toCommonJS(address_parser_exports);
+var import_decode_strings = require("./decode-strings.cjs");
+function _handleAddress(tokens) {
+  let isGroup = false;
+  let state = "text";
+  let address;
+  let addresses = [];
+  let data = {
+    address: [],
+    comment: [],
+    group: [],
+    text: [],
+    textWasQuoted: []
+    // Track which text tokens came from inside quotes
+  };
+  let i;
+  let len;
+  let insideQuotes = false;
+  for (i = 0, len = tokens.length; i < len; i++) {
+    let token = tokens[i];
+    let prevToken = i ? tokens[i - 1] : null;
+    if (token.type === "operator") {
+      switch (token.value) {
+        case "<":
+          state = "address";
+          insideQuotes = false;
+          break;
+        case "(":
+          state = "comment";
+          insideQuotes = false;
+          break;
+        case ":":
+          state = "group";
+          isGroup = true;
+          insideQuotes = false;
+          break;
+        case '"':
+          insideQuotes = !insideQuotes;
+          state = "text";
+          break;
+        default:
+          state = "text";
+          insideQuotes = false;
+          break;
+      }
+    } else if (token.value) {
+      if (state === "address") {
+        token.value = token.value.replace(/^[^<]*<\s*/, "");
+      }
+      if (prevToken && prevToken.noBreak && data[state].length) {
+        data[state][data[state].length - 1] += token.value;
+        if (state === "text" && insideQuotes) {
+          data.textWasQuoted[data.textWasQuoted.length - 1] = true;
+        }
+      } else {
+        data[state].push(token.value);
+        if (state === "text") {
+          data.textWasQuoted.push(insideQuotes);
+        }
+      }
+    }
+  }
+  if (!data.text.length && data.comment.length) {
+    data.text = data.comment;
+    data.comment = [];
+  }
+  if (isGroup) {
+    data.text = data.text.join(" ");
+    let groupMembers = [];
+    if (data.group.length) {
+      let parsedGroup = addressParser(data.group.join(","));
+      parsedGroup.forEach((member) => {
+        if (member.group) {
+          groupMembers = groupMembers.concat(member.group);
+        } else {
+          groupMembers.push(member);
+        }
+      });
+    }
+    addresses.push({
+      name: (0, import_decode_strings.decodeWords)(data.text || address && address.name),
+      group: groupMembers
+    });
+  } else {
+    if (!data.address.length && data.text.length) {
+      for (i = data.text.length - 1; i >= 0; i--) {
+        if (!data.textWasQuoted[i] && data.text[i].match(/^[^@\s]+@[^@\s]+$/)) {
+          data.address = data.text.splice(i, 1);
+          data.textWasQuoted.splice(i, 1);
+          break;
+        }
+      }
+      let _regexHandler = function(address2) {
+        if (!data.address.length) {
+          data.address = [address2.trim()];
+          return " ";
+        } else {
+          return address2;
+        }
+      };
+      if (!data.address.length) {
+        for (i = data.text.length - 1; i >= 0; i--) {
+          if (!data.textWasQuoted[i]) {
+            data.text[i] = data.text[i].replace(/\s*\b[^@\s]+@[^\s]+\b\s*/, _regexHandler).trim();
+            if (data.address.length) {
+              break;
+            }
+          }
+        }
+      }
+    }
+    if (!data.text.length && data.comment.length) {
+      data.text = data.comment;
+      data.comment = [];
+    }
+    if (data.address.length > 1) {
+      data.text = data.text.concat(data.address.splice(1));
+    }
+    data.text = data.text.join(" ");
+    data.address = data.address.join(" ");
+    if (!data.address && /^=\?[^=]+?=$/.test(data.text.trim())) {
+      const parsedSubAddresses = addressParser((0, import_decode_strings.decodeWords)(data.text));
+      if (parsedSubAddresses && parsedSubAddresses.length) {
+        return parsedSubAddresses;
+      }
+    }
+    if (!data.address && isGroup) {
+      return [];
+    } else {
+      address = {
+        address: data.address || data.text || "",
+        name: (0, import_decode_strings.decodeWords)(data.text || data.address || "")
+      };
+      if (address.address === address.name) {
+        if ((address.address || "").match(/@/)) {
+          address.name = "";
+        } else {
+          address.address = "";
+        }
+      }
+      addresses.push(address);
+    }
+  }
+  return addresses;
+}
+class Tokenizer {
+  constructor(str) {
+    this.str = (str || "").toString();
+    this.operatorCurrent = "";
+    this.operatorExpecting = "";
+    this.node = null;
+    this.escaped = false;
+    this.list = [];
+    this.operators = {
+      '"': '"',
+      "(": ")",
+      "<": ">",
+      ",": "",
+      ":": ";",
+      // Semicolons are not a legal delimiter per the RFC2822 grammar other
+      // than for terminating a group, but they are also not valid for any
+      // other use in this context.  Given that some mail clients have
+      // historically allowed the semicolon as a delimiter equivalent to the
+      // comma in their UI, it makes sense to treat them the same as a comma
+      // when used outside of a group.
+      ";": ""
+    };
+  }
+  /**
+   * Tokenizes the original input string
+   *
+   * @return {Array} An array of operator|text tokens
+   */
+  tokenize() {
+    let list = [];
+    for (let i = 0, len = this.str.length; i < len; i++) {
+      let chr = this.str.charAt(i);
+      let nextChr = i < len - 1 ? this.str.charAt(i + 1) : null;
+      this.checkChar(chr, nextChr);
+    }
+    this.list.forEach((node) => {
+      node.value = (node.value || "").toString().trim();
+      if (node.value) {
+        list.push(node);
+      }
+    });
+    return list;
+  }
+  /**
+   * Checks if a character is an operator or text and acts accordingly
+   *
+   * @param {String} chr Character from the address field
+   */
+  checkChar(chr, nextChr) {
+    if (this.escaped) {
+    } else if (chr === this.operatorExpecting) {
+      this.node = {
+        type: "operator",
+        value: chr
+      };
+      if (nextChr && ![" ", "	", "\r", "\n", ",", ";"].includes(nextChr)) {
+        this.node.noBreak = true;
+      }
+      this.list.push(this.node);
+      this.node = null;
+      this.operatorExpecting = "";
+      this.escaped = false;
+      return;
+    } else if (!this.operatorExpecting && chr in this.operators) {
+      this.node = {
+        type: "operator",
+        value: chr
+      };
+      this.list.push(this.node);
+      this.node = null;
+      this.operatorExpecting = this.operators[chr];
+      this.escaped = false;
+      return;
+    } else if (['"', "'"].includes(this.operatorExpecting) && chr === "\\") {
+      this.escaped = true;
+      return;
+    }
+    if (!this.node) {
+      this.node = {
+        type: "text",
+        value: ""
+      };
+      this.list.push(this.node);
+    }
+    if (chr === "\n") {
+      chr = " ";
+    }
+    if (chr.charCodeAt(0) >= 33 || [" ", "	"].includes(chr)) {
+      this.node.value += chr;
+    }
+    this.escaped = false;
+  }
+}
+function addressParser(str, options) {
+  options = options || {};
+  let tokenizer = new Tokenizer(str);
+  let tokens = tokenizer.tokenize();
+  let addresses = [];
+  let address = [];
+  let parsedAddresses = [];
+  tokens.forEach((token) => {
+    if (token.type === "operator" && (token.value === "," || token.value === ";")) {
+      if (address.length) {
+        addresses.push(address);
+      }
+      address = [];
+    } else {
+      address.push(token);
+    }
+  });
+  if (address.length) {
+    addresses.push(address);
+  }
+  addresses.forEach((address2) => {
+    address2 = _handleAddress(address2);
+    if (address2.length) {
+      parsedAddresses = parsedAddresses.concat(address2);
+    }
+  });
+  if (options.flatten) {
+    let addresses2 = [];
+    let walkAddressList = (list) => {
+      list.forEach((address2) => {
+        if (address2.group) {
+          return walkAddressList(address2.group);
+        } else {
+          addresses2.push(address2);
+        }
+      });
+    };
+    walkAddressList(parsedAddresses);
+    return addresses2;
+  }
+  return parsedAddresses;
+}
+var address_parser_default = addressParser;
+
+// Make default export work naturally with require()
+if (module.exports.default) {
+    var defaultExport = module.exports.default;
+    var namedExports = {};
+    for (var key in module.exports) {
+        if (key !== 'default') {
+            namedExports[key] = module.exports[key];
+        }
+    }
+    module.exports = defaultExport;
+    Object.assign(module.exports, namedExports);
+}
+