imapkit 4.0.3 → 4.1.1

package/README.md

@@ -42,11 +42,21 @@ npm install imapkit
 Create and start an IMAP server
 
 ```javascript
-const imapkit = require('imapkit');
+import imapkit from 'imapkit';
+// or with CommonJS: const imapkit = require('imapkit');
+
 const server = imapkit(options);
 server.listen(1143);
 ```
 
+ImapKit is written in TypeScript and ships both ES modules and CommonJS, each with type declarations. The package exports the `imapkit(options)` factory as its default export, the `IMAPServer` and `IMAPConnection` classes, and types such as `IMAPServerOptions`, `Plugin`, `CommandHandler`, `Mailbox` and `Message` for writing plugins:
+
+```typescript
+import imapkit, { type IMAPServerOptions, type Plugin } from 'imapkit';
+```
+
+ImapKit needs Node.js 20 or newer. It also runs on the latest [Bun](https://bun.sh/) and [Deno](https://deno.com/) releases (`npm:imapkit` in Deno), CI runs the whole test suite on both.
+
 See [complete.js](https://github.com/postalsys/imapkit/blob/master/examples/complete.js) for an example.
 
 ## Scope
@@ -55,7 +65,7 @@ ImapKit is a single user, multiple connection IMAP server. Changes made over IMA
 
 Several clients can connect to the server simultaneously but all the clients share the same user account, even if login credentials are different. The ACL plugin can limit what users other than the owner can do (see [ACL](#acl)).
 
-ImapKit is extendable: any command can be overridden and plugins can be added (see [Creating custom plugins](#creating-custom-plugins), and `lib/commands` and `lib/plugins` for the built-in commands and plugins).
+ImapKit is extendable: any command can be overridden and plugins can be added (see [Creating custom plugins](#creating-custom-plugins), and `src/commands` and `src/plugins` for the built-in commands and plugins).
 
 ## Strict by design
 
@@ -273,14 +283,16 @@ S: A1 OK XTOYBIRD Completed
 
 # Running tests
 
-Tests use the built-in Node.js test runner, linting uses ESLint and formatting uses Prettier.
+The source is TypeScript in `src/`, `npm run build` compiles it into `dist/esm` (ES modules) and `dist/cjs` (CommonJS). Tests use the built-in Node.js test runner (TypeScript test files run through [tsx](https://tsx.is/)), linting uses ESLint and the TypeScript compiler, and formatting uses Prettier.
 
     npm install
-    npm test                    # lint + all tests
-    npm run test:unit           # tests only
-    npm run test:coverage       # tests with coverage (Node.js 22.8 or newer)
-    node --test test/fetch.js   # a single test file
-    npm run format              # apply Prettier formatting
+    npm test                                       # lint, type check, build and all tests
+    npm run test:unit                              # tests only
+    npm run test:coverage                          # tests with coverage (Node.js 22.8 or newer)
+    npm run test:bun                               # tests under Bun
+    npm run test:deno                              # tests under Deno
+    node --import tsx --test test/fetch.test.ts    # a single test file
+    npm run format                                 # apply Prettier formatting
 
 `compare/` holds a development tool that replays the same IMAP commands against ImapKit and a Dovecot server running in Docker and shows where the responses differ (`npm run dovecot:start`, then `npm run compare -- compare/scenarios/fetch.txt`). See [CLAUDE.md](CLAUDE.md#comparing-with-dovecot) for details.
 
@@ -351,24 +363,25 @@ storage.json:
 Creating your tests in Node.js is a piece of cake, you do not even need to run the `imapkit` command. Here is a sample test using the built-in [Node.js test runner](https://nodejs.org/api/test.html).
 
 ```javascript
-const { describe, it, beforeEach, afterEach } = require('node:test');
-const imapkit = require('imapkit');
-const myIMAPClient = require('../my-imap-client');
+import { describe, it, beforeEach, afterEach } from 'node:test';
+import imapkit from 'imapkit';
+import myIMAPClient from '../my-imap-client.js';
 
 describe('IMAP tests', () => {
     let server;
 
     // Executed before every test, creates a new blank IMAP server
     // on a random free port
-    beforeEach((t, done) => {
-        server = imapkit();
-        server.listen(0, done);
-    });
+    beforeEach(
+        () =>
+            new Promise(resolve => {
+                server = imapkit();
+                server.listen(0, resolve);
+            })
+    );
 
     // Executed after every test, closes the IMAP server created for the test
-    afterEach((t, done) => {
-        server.close(done);
-    });
+    afterEach(() => new Promise(resolve => server.close(resolve)));
 
     // A new IMAP client is instantiated that tries to connect to the
     // IMAP server. If the client is connected the test is considered as passed.
@@ -558,7 +571,7 @@ connection.inputHandler = function(line){
 }
 ```
 
-See [idle.js](https://github.com/postalsys/imapkit/blob/master/lib/plugins/idle.js) for an example
+See [idle.ts](https://github.com/postalsys/imapkit/blob/master/src/plugins/idle.ts) for an example
 
 Raw output, such as a `+` continuation request, goes through `connection.write(data)`, and `connection.end()` closes the connection once all output is written. Do not use `connection.socket` for this, a COMPRESS layer (`connection.transport`) sits between the protocol and the socket.
 

package/bin/imapkit.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
-'use strict';
 
-const fs = require('node:fs');
-const path = require('node:path');
-const { parseArgs } = require('node:util');
-const imapkit = require('../lib/server');
-const packageData = require('../package.json');
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import imapkit from '../dist/esm/index.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageData = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
 
 // Non-strict so that boolean flags also accept an explicit value (`--secure=true`)
 const { values: argv } = parseArgs({
@@ -65,15 +67,9 @@ const port = argv.port || process.env.IMAPKIT_PORT || config.port || (secure ? 9
 
 if (argv.help) {
     const help = fs.readFileSync(path.join(__dirname, 'help.txt'), 'utf-8');
-    const pluginsDir = path.join(__dirname, '..', 'lib', 'plugins');
-
-    const plugins = fs.readdirSync(pluginsDir).map(fileName => {
-        const file = fs.readFileSync(path.join(pluginsDir, fileName), 'utf-8');
-        return {
-            key: fileName.replace(/\.js$/i, '').toUpperCase(),
-            value: Array.from(file.matchAll(/@help (.*)/gim), match => match[1])
-        };
-    });
+    // the @help lines of every plugin, collected by the build (scripts/build.js)
+    const pluginHelp = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'dist', 'plugin-help.json'), 'utf-8'));
+    const plugins = Object.keys(pluginHelp).map(key => ({ key, value: pluginHelp[key] }));
 
     const indent = Math.max(0, ...plugins.map(plugin => plugin.key.length)) + 2;
     const pluginText = plugins.flatMap(plugin => [
@@ -103,6 +99,6 @@ if (argv.help) {
 
     if (smtpPort) {
         // loaded on demand, smtp-server is only needed when SMTP is enabled
-        require('../lib/smtp-listener').startSMTPServer(smtpPort, server);
+        import('../dist/esm/smtp-listener.js').then(({ startSMTPServer }) => startSMTPServer(smtpPort, server));
     }
 }

package/dist/cjs/addressparser.d.ts

@@ -0,0 +1,21 @@
+/** An address, or a group with its member addresses */
+export interface ParsedAddress {
+    name: string;
+    address?: string;
+    group?: ParsedAddress[];
+}
+/**
+ * Parses structured e-mail addresses from an address field
+ *
+ * Example:
+ *
+ *    "Name <address@domain>"
+ *
+ * will be converted to
+ *
+ *     [{name: "Name", address: "address@domain"}]
+ *
+ * @param {String} str Address field
+ * @return {Array} An array of address objects
+ */
+export default function parse(str: string, inGroup?: boolean): ParsedAddress[];

package/dist/cjs/addressparser.js

@@ -0,0 +1,271 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = parse;
+/**
+ * Parses structured e-mail addresses from an address field
+ *
+ * Example:
+ *
+ *    "Name <address@domain>"
+ *
+ * will be converted to
+ *
+ *     [{name: "Name", address: "address@domain"}]
+ *
+ * @param {String} str Address field
+ * @return {Array} An array of address objects
+ */
+function parse(str, inGroup) {
+    const tokenizer = new Tokenizer(str);
+    const tokens = tokenizer.tokenize();
+    const 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(address => {
+        const handled = _handleAddress(address, inGroup);
+        if (handled.length) {
+            parsedAddresses = parsedAddresses.concat(handled);
+        }
+    });
+    return parsedAddresses;
+}
+/**
+ * Converts tokens for a single address into an address object
+ *
+ * @param {Array} tokens Tokens object
+ * @param {Boolean} [inGroup] If true, the tokens are a member of a group. Groups do not nest
+ *        (RFC 5322 3.4), so a colon is not a group separator here
+ * @return {Object} Address object
+ */
+function _handleAddress(tokens, inGroup) {
+    let token;
+    let isGroup = false;
+    let state = 'text';
+    const addresses = [];
+    const data = {
+        address: [],
+        comment: [],
+        group: [],
+        text: []
+    };
+    let i;
+    let len;
+    // Filter out <addresses>, (comments) and regular text
+    for (i = 0, len = tokens.length; i < len; i++) {
+        token = tokens[i];
+        if (token.type === 'operator') {
+            switch (token.value) {
+                case '<':
+                    state = 'address';
+                    break;
+                case '(':
+                    state = 'comment';
+                    break;
+                case ':':
+                    if (inGroup) {
+                        state = 'text';
+                        break;
+                    }
+                    state = 'group';
+                    isGroup = true;
+                    break;
+                default:
+                    state = 'text';
+            }
+        }
+        else {
+            if (token.value) {
+                data[state].push(token.value);
+            }
+        }
+    }
+    // If there is no text but a comment, replace the two
+    if (!data.text.length && data.comment.length) {
+        data.text = data.comment;
+        data.comment = [];
+    }
+    if (isGroup) {
+        // http://tools.ietf.org/html/rfc2822#appendix-A.1.3
+        const text = data.text.join(' ');
+        addresses.push({
+            // RFC 5322 section 3.4 requires a display name, but a group like ":a@b;" still parses, with an empty name
+            name: text,
+            group: data.group.length ? parse(data.group.join(','), true) : []
+        });
+    }
+    else {
+        // If no address was found, try to detect one from regular text
+        if (!data.address.length && data.text.length) {
+            for (i = data.text.length - 1; i >= 0; i--) {
+                if (data.text[i].match(/^[^@\s]+@[^@\s]+$/)) {
+                    data.address = data.text.splice(i, 1);
+                    break;
+                }
+            }
+            const _regexHandler = function (address) {
+                if (!data.address.length) {
+                    data.address = [address.trim()];
+                    return ' ';
+                }
+                else {
+                    return address;
+                }
+            };
+            // still no address
+            if (!data.address.length) {
+                for (i = data.text.length - 1; i >= 0; i--) {
+                    data.text[i] = data.text[i].replace(/\s*\b[^@\s]+@[^@\s]+\b\s*/, _regexHandler).trim();
+                    if (data.address.length) {
+                        break;
+                    }
+                }
+            }
+        }
+        // If there's still is no text but a comment exixts, replace the two
+        if (!data.text.length && data.comment.length) {
+            data.text = data.comment;
+            data.comment = [];
+        }
+        // Keep only the first address occurence, push others to regular text
+        if (data.address.length > 1) {
+            data.text = data.text.concat(data.address.splice(1));
+        }
+        // Join values with spaces
+        const text = data.text.join(' ');
+        const addressText = data.address.join(' ');
+        const address = {
+            address: addressText || text || '',
+            name: text || addressText || ''
+        };
+        if (address.address === address.name) {
+            if ((address.address || '').match(/@/)) {
+                address.name = '';
+            }
+            else {
+                address.address = '';
+            }
+        }
+        addresses.push(address);
+    }
+    return addresses;
+}
+/**
+ * Creates a Tokenizer object for tokenizing address field strings
+ *
+ * @constructor
+ * @param {String} str Address field string
+ */
+class Tokenizer {
+    constructor(str) {
+        this.str = (str || '').toString();
+        this.operatorCurrent = '';
+        this.operatorExpecting = '';
+        this.node = null;
+        this.escaped = false;
+        this.list = [];
+    }
+    /**
+     * Tokenizes the original input string
+     *
+     * @return {Array} An array of operator|text tokens
+     */
+    tokenize() {
+        let chr;
+        const list = [];
+        for (let i = 0, len = this.str.length; i < len; i++) {
+            chr = this.str.charAt(i);
+            this.checkChar(chr);
+        }
+        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) {
+        if ((chr in this.operators || chr === '\\') && this.escaped) {
+            this.escaped = false;
+        }
+        else if (this.operatorExpecting && chr === this.operatorExpecting) {
+            this.node = {
+                type: 'operator',
+                value: chr
+            };
+            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;
+        }
+        if (!this.escaped && chr === '\\') {
+            this.escaped = true;
+            return;
+        }
+        if (!this.node) {
+            this.node = {
+                type: 'text',
+                value: ''
+            };
+            this.list.push(this.node);
+        }
+        if (this.escaped && chr !== '\\') {
+            this.node.value += '\\';
+        }
+        this.node.value += chr;
+        this.escaped = false;
+    }
+}
+/**
+ * Operator tokens and which tokens are expected to end the sequence
+ */
+Tokenizer.prototype.operators = {
+    '"': '"',
+    '(': ')',
+    '<': '>',
+    ',': '',
+    ':': ';'
+};
+{
+    const defaultExport = exports.default;
+    if (defaultExport && (typeof defaultExport === 'function' || typeof defaultExport === 'object')) {
+        for (const key of Object.keys(exports)) {
+            if (key !== 'default' && !(key in defaultExport)) {
+                defaultExport[key] = exports[key];
+            }
+        }
+        Object.defineProperty(defaultExport, 'default', { value: defaultExport, enumerable: false, writable: true, configurable: true });
+        module.exports = defaultExport;
+    }
+}

package/dist/cjs/arguments.d.ts

@@ -0,0 +1,31 @@
+import type { Attribute, ParsedCommand } from './types.js';
+/**
+ * Checks if a parsed argument is an atom, optionally a specific one
+ *
+ * @param {Object} value Parsed argument
+ * @param {String} [name] Upper case atom to match, the value is compared case-insensitively
+ * @return {Boolean} true for an atom (with that name)
+ */
+declare function isAtom(value: Attribute, name?: string): boolean;
+/**
+ * Checks if a parsed argument is an astring (RFC 3501 section 9): an atom, a quoted string or a literal. An
+ * atom the parser split into a section or partial range (like BODY[1]<0.5>) is not
+ *
+ * @param {Object} value Parsed argument
+ * @return {Boolean} true for an astring
+ */
+declare function isAstring(value: Attribute): boolean;
+/**
+ * The parser turns every NIL atom into null, as in an nstring. Where the grammar has an astring (mailbox names, user
+ * names, search strings, ...) NIL is an ordinary atom, so these nulls are turned back into atoms with the spelling
+ * the client used
+ *
+ * @param {Object} parsed Parsed command, changed in place
+ * @param {String} data Raw command line with its literals
+ * @param {Function} select `(path)` returns true for the nulls to restore, `path` lists the indexes from the
+ *   top-level arguments down, e.g. [2, 0] for the first item of a list in the third argument
+ */
+/** Indexes from the top-level arguments down to a nested value, `'section'` steps into the section of an atom */
+export type ArgumentPath = (number | string)[];
+declare function restoreNilAtoms(parsed: ParsedCommand, data: string, select: (path: ArgumentPath) => boolean): void;
+export { isAtom, isAstring, restoreNilAtoms };

package/{lib → dist/cjs}/arguments.js

@@ -1,7 +1,9 @@
-'use strict';
-
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isAtom = isAtom;
+exports.isAstring = isAstring;
+exports.restoreNilAtoms = restoreNilAtoms;
 // Checks of parsed command arguments (imap-handler parser output)
-
 /**
  * Checks if a parsed argument is an atom, optionally a specific one
  *
@@ -12,7 +14,6 @@
 function isAtom(value, name) {
     return !!value && !Array.isArray(value) && value.type === 'ATOM' && (name === undefined || String(value.value).toUpperCase() === name);
 }
-
 /**
  * Checks if a parsed argument is an astring (RFC 3501 section 9): an atom, a quoted string or a literal. An
  * atom the parser split into a section or partial range (like BODY[1]<0.5>) is not
@@ -23,10 +24,8 @@ function isAtom(value, name) {
 function isAstring(value) {
     return !!value && !Array.isArray(value) && ['ATOM', 'STRING', 'LITERAL'].indexOf(value.type) >= 0 && !value.section && !value.partial;
 }
-
 // characters that end an atom in a command line (RFC 3501 section 9 atom-specials, and "[" "]" of sections)
 const ATOM_END = /[\s()[\]{"%*\\<]/;
-
 /**
  * Lists how the client spelled the NIL atoms of a command line, in order. Quoted strings and literals are skipped
  *
@@ -68,17 +67,6 @@ function nilSpellings(data) {
     }
     return result;
 }
-
-/**
- * The parser turns every NIL atom into null, as in an nstring. Where the grammar has an astring (mailbox names, user
- * names, search strings, ...) NIL is an ordinary atom, so these nulls are turned back into atoms with the spelling
- * the client used
- *
- * @param {Object} parsed Parsed command, changed in place
- * @param {String} data Raw command line with its literals
- * @param {Function} select `(path)` returns true for the nulls to restore, `path` lists the indexes from the
- *   top-level arguments down, e.g. [2, 0] for the first item of a list in the third argument
- */
 function restoreNilAtoms(parsed, data, select) {
     if (!parsed.attributes || !/nil/i.test(data || '')) {
         return;
@@ -89,9 +77,11 @@ function restoreNilAtoms(parsed, data, select) {
         list.forEach((item, i) => {
             if (item === null) {
                 nulls.push({ list, index: i, path: path.concat(i) });
-            } else if (Array.isArray(item)) {
+            }
+            else if (Array.isArray(item)) {
                 walk(item, path.concat(i));
-            } else if (item && Array.isArray(item.section)) {
+            }
+            else if (item && Array.isArray(item.section)) {
                 walk(item.section, path.concat(i, 'section'));
             }
         });
@@ -108,5 +98,3 @@ function restoreNilAtoms(parsed, data, select) {
         }
     });
 }
-
-module.exports = { isAtom, isAstring, restoreNilAtoms };

package/dist/cjs/bodystructure.d.ts

@@ -0,0 +1,25 @@
+import type { MimeNode } from './mimeparser.js';
+import type { Attribute } from './types.js';
+/** Options of createBodystructure() */
+export interface BodystructureOptions {
+    upperCaseKeys?: boolean | undefined;
+    skipContentLocation?: boolean | undefined;
+    body?: boolean | undefined;
+    messageGlobal?: boolean | undefined;
+}
+/** A BODY or BODYSTRUCTURE list, nested lists for the parts, compiled by imap-handler */
+export type Bodystructure = Attribute[];
+export default createBodystructure;
+/**
+ * Generates an object out of parsed mime tree, that can be
+ * serialized into a BODYSTRUCTURE string
+ *
+ * @param {Object} tree Parsed mime tree (see mimeparser.ts for input)
+ * @param {Object} [options] Optional options object
+ * @param {Boolean} [options.upperCaseKeys] If true, use only upper case key names
+ * @param {Boolean} [options.skipContentLocation] If true, do not include Content-Location in the output
+ * @param {Boolean} [options.body] If true, skip extension fields (needed for BODY)
+ * @param {Boolean} [options.messageGlobal] If true, describe message/global like message/rfc822 (IMAP4rev2, RFC 9051 section 7.5.2)
+ * @return {Array} Object structure in the form of BODYSTRUCTURE
+ */
+declare function createBodystructure(tree: MimeNode, options?: BodystructureOptions | null): Bodystructure;