postal-mime 2.4.7 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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,29 @@ 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>
+
 ### Cloudflare Email Workers
 
 Use the `message.raw` as the raw email data for parsing:
@@ -93,6 +143,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 +221,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 +235,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 +325,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 +376,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "postal-mime",
-    "version": "2.4.7",
+    "version": "2.5.0",
     "description": "Email parser for browser environments",
     "main": "./src/postal-mime.js",
     "exports": {
@@ -11,8 +11,9 @@
     "type": "module",
     "types": "postal-mime.d.ts",
     "scripts": {
-        "test": "npm run lint && node --test",
+        "test": "npm run lint && npm run type-check && node --test",
         "lint": "eslint",
+        "type-check": "tsc --noEmit",
         "update": "rm -rf node_modules package-lock.json && ncu -u && npm install",
         "format": "prettier --write \"**/*.{js,mjs,json}\" --ignore-path .prettierignore",
         "format:check": "prettier --check \"**/*.{js,mjs,json}\" --ignore-path .prettierignore"
@@ -37,6 +38,7 @@
         "eslint": "8.57.0",
         "eslint-cli": "1.1.1",
         "iframe-resizer": "4.3.6",
-        "prettier": "^3.6.2"
+        "prettier": "^3.6.2",
+        "typescript": "^5.9.3"
     }
 }

package/postal-mime.d.ts

@@ -51,20 +51,20 @@ export type Email = {
     attachments: Attachment[];
 };
 
-declare type AddressParserOptions = {
+export type AddressParserOptions = {
     flatten?: boolean
 }
 
-declare function addressParser (
+export function addressParser (
     str: string,
     options?: AddressParserOptions
 ): Address[];
 
-declare function decodeWords (
+export function decodeWords (
     str: string
 ): string;
 
-declare type PostalMimeOptions = {
+export type PostalMimeOptions = {
     rfc822Attachments?: boolean,
     forceRfc822Attachments?: boolean,
     attachmentEncoding?: "base64" | "utf8" | "arraybuffer",
@@ -72,7 +72,7 @@ declare type PostalMimeOptions = {
     maxHeadersSize?: number
 }
 
-declare class PostalMime {
+export default class PostalMime {
     constructor(options?: PostalMimeOptions);
     static parse(
         email: RawEmail,
@@ -80,6 +80,3 @@ declare class PostalMime {
     ): Promise<Email>;
     parse(email: RawEmail): Promise<Email>;
 }
-
-export { addressParser, decodeWords };
-export default PostalMime;

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ES2022",
+        "lib": ["ES2022", "DOM"],
+        "moduleResolution": "bundler",
+        "strict": true,
+        "noEmit": true,
+        "skipLibCheck": true,
+        "esModuleInterop": true,
+        "allowSyntheticDefaultImports": true,
+        "forceConsistentCasingInFileNames": true,
+        "types": ["node"]
+    },
+    "include": ["test/type-check.test.ts"],
+    "exclude": ["node_modules"]
+}