imapflow 1.0.192 → 1.0.193

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.0.193](https://github.com/postalsys/imapflow/compare/v1.0.192...v1.0.193) (2025-07-31)
+
+
+### Bug Fixes
+
+* Improved exception handling ([0eb77ac](https://github.com/postalsys/imapflow/commit/0eb77ac28a0f36b085769b6f9a20fd89d9214060))
+
 ## [1.0.192](https://github.com/postalsys/imapflow/compare/v1.0.191...v1.0.192) (2025-07-31)
 
 

package/lib/imap-flow.js

@@ -4,10 +4,6 @@
  * @module imapflow
  */
 
-// TODO:
-// * Use buffers for compiled commands
-// * OAuth2 authentication
-
 const tls = require('tls');
 const net = require('net');
 const crypto = require('crypto');
@@ -377,7 +373,6 @@ class ImapFlow extends EventEmitter {
             }
 
             this.log.error({ err, cid: this.id });
-            setImmediate(() => this.close());
             this.emitError(err);
         });
 
@@ -386,6 +381,12 @@ class ImapFlow extends EventEmitter {
     }
 
     emitError(err) {
+        if (!err) {
+            return;
+        }
+        err._connId = err._connId || this.id;
+
+        setImmediate(() => this.close());
         this.emit('error', err);
     }
 
@@ -761,7 +762,6 @@ class ImapFlow extends EventEmitter {
             this._socketError ||
             (err => {
                 this.log.error({ err, cid: this.id });
-                setImmediate(() => this.close());
                 this.emitError(err);
             });
         this._socketClose =
@@ -790,6 +790,10 @@ class ImapFlow extends EventEmitter {
                 err.code = 'ETIMEOUT';
 
                 if (this.idling) {
+                    if (!this.usable || !this.socket || this.socket.destroyed) {
+                        this.emitError(err);
+                        return;
+                    }
                     // Attempt to recover IDLE connections
                     this.run('NOOP')
                         .then(() => this.idle())
@@ -797,8 +801,7 @@ class ImapFlow extends EventEmitter {
                 } else {
                     // Close immediately for non-IDLE operations
                     this.log.debug({ msg: 'Socket timeout', cid: this.id });
-                    this.emit('error', err);
-                    this.close();
+                    this.emitError(err);
                 }
             });
 
@@ -1175,10 +1178,7 @@ class ImapFlow extends EventEmitter {
                 }
 
                 // ALWAYS emit the error so users can handle it
-                setImmediate(() => {
-                    this.emit('error', err);
-                    this.close();
-                });
+                this.emitError(err);
             });
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.192",
+    "version": "1.0.193",
     "description": "IMAP Client for Node",
     "main": "lib/imap-flow.js",
     "types": "lib/imap-flow.d.ts",

package/test/authentication-test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const { ImapFlow } = require('../lib/imap-flow');
+const { AuthenticationFailure } = require('../lib/tools');
+
+module.exports['Authentication: Password auth configuration'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: {
+            user: 'testuser',
+            pass: 'testpass'
+        }
+    });
+    
+    test.equal(client.options.auth.user, 'testuser');
+    test.equal(client.options.auth.pass, 'testpass');
+    test.done();
+};
+
+module.exports['Authentication: OAuth2 auth configuration'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: {
+            user: 'testuser',
+            accessToken: 'oauth2_token_here'
+        }
+    });
+    
+    test.equal(client.options.auth.user, 'testuser');
+    test.equal(client.options.auth.accessToken, 'oauth2_token_here');
+    test.done();
+};
+
+module.exports['Authentication: Login method specification'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: {
+            user: 'testuser',
+            pass: 'testpass',
+            loginMethod: 'AUTH=PLAIN'
+        }
+    });
+    
+    test.equal(client.options.auth.loginMethod, 'AUTH=PLAIN');
+    test.done();
+};
+
+module.exports['Authentication: AuthenticationFailure error structure'] = test => {
+    let error = new AuthenticationFailure('Invalid credentials');
+    
+    test.ok(error instanceof Error);
+    test.equal(error.constructor.name, 'AuthenticationFailure');
+    test.equal(error.message, 'Invalid credentials');
+    test.done();
+};
+
+module.exports['Authentication: Verify-only mode'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: {
+            user: 'testuser',
+            pass: 'testpass'
+        },
+        verifyOnly: true
+    });
+    
+    test.equal(client.options.verifyOnly, true);
+    test.done();
+};
+
+module.exports['Authentication: Disable auto IDLE'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: {
+            user: 'testuser',
+            pass: 'testpass'
+        },
+        disableAutoIdle: true
+    });
+    
+    test.equal(client.options.disableAutoIdle, true);
+    test.done();
+};

package/test/commands-test.js

@@ -0,0 +1,73 @@
+'use strict';
+
+const { ImapFlow } = require('../lib/imap-flow');
+
+module.exports['Commands: Client instantiation'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.ok(client);
+    test.equal(typeof client.exec, 'function');
+    test.done();
+};
+
+module.exports['Commands: Method availability'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    // Check that key IMAP methods exist
+    test.equal(typeof client.connect, 'function');
+    test.equal(typeof client.logout, 'function');
+    test.equal(typeof client.list, 'function');
+    test.equal(typeof client.mailboxOpen, 'function');
+    test.equal(typeof client.mailboxClose, 'function');
+    test.equal(typeof client.search, 'function');
+    test.equal(typeof client.fetch, 'function');
+    test.done();
+};
+
+module.exports['Commands: State management methods'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.equal(typeof client.mailboxCreate, 'function');
+    test.equal(typeof client.mailboxDelete, 'function');
+    test.equal(typeof client.mailboxRename, 'function');
+    test.equal(typeof client.mailboxSubscribe, 'function');
+    test.equal(typeof client.mailboxUnsubscribe, 'function');
+    test.done();
+};
+
+module.exports['Commands: Message operation methods'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.equal(typeof client.messageFlagsSet, 'function');
+    test.equal(typeof client.messageFlagsAdd, 'function');
+    test.equal(typeof client.messageFlagsRemove, 'function');
+    test.equal(typeof client.messageCopy, 'function');
+    test.equal(typeof client.messageMove, 'function');
+    test.equal(typeof client.messageDelete, 'function');
+    test.done();
+};
+
+module.exports['Commands: Utility methods'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.equal(typeof client.noop, 'function');
+    test.equal(typeof client.getQuota, 'function');
+    test.equal(typeof client.stats, 'function');
+    test.equal(typeof client.getRandomId, 'function');
+    test.done();
+};

package/test/connection-test.js

@@ -0,0 +1,162 @@
+'use strict';
+
+const { ImapFlow } = require('../lib/imap-flow');
+
+module.exports['Connection: Basic connection options'] = test => {
+    let client = new ImapFlow({ 
+        host: 'imap.example.com', 
+        port: 993,
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.equal(client.host, 'imap.example.com');
+    test.equal(client.port, 993);
+    test.done();
+};
+
+module.exports['Connection: Default options'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.equal(client.port, 110);
+    test.equal(client.secureConnection, false);
+    test.done();
+};
+
+module.exports['Connection: Secure connection defaults'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.equal(client.secureConnection, true);
+    test.done();
+};
+
+module.exports['Connection: TLS options'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' },
+        tls: {
+            rejectUnauthorized: false,
+            minVersion: 'TLSv1.3'
+        }
+    });
+    
+    test.equal(client.options.tls.rejectUnauthorized, false);
+    test.equal(client.options.tls.minVersion, 'TLSv1.3');
+    test.done();
+};
+
+module.exports['Connection: Authentication options'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: {
+            user: 'testuser',
+            pass: 'testpass',
+            accessToken: 'token123'
+        }
+    });
+    
+    test.equal(client.options.auth.user, 'testuser');
+    test.equal(client.options.auth.pass, 'testpass');
+    test.equal(client.options.auth.accessToken, 'token123');
+    test.done();
+};
+
+module.exports['Connection: Proxy configuration'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' },
+        proxy: 'socks5://proxy.example.com:1080'
+    });
+    
+    test.equal(client.options.proxy, 'socks5://proxy.example.com:1080');
+    test.done();
+};
+
+module.exports['Connection: Client info'] = test => {
+    let clientInfo = {
+        name: 'Test Client',
+        version: '1.0.0',
+        vendor: 'Test Corp'
+    };
+    
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' },
+        clientInfo
+    });
+    
+    test.equal(client.clientInfo.name, 'Test Client');
+    test.equal(client.clientInfo.version, '1.0.0');
+    test.equal(client.clientInfo.vendor, 'Test Corp');
+    test.done();
+};
+
+module.exports['Connection: Logger configuration'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' },
+        logger: false
+    });
+    
+    test.equal(client.options.logger, false);
+    test.done();
+};
+
+module.exports['Connection: Stats tracking'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    let stats = client.stats();
+    test.ok(Object.prototype.hasOwnProperty.call(stats, 'sent'));
+    test.ok(Object.prototype.hasOwnProperty.call(stats, 'received'));
+    test.equal(typeof stats.sent, 'number');
+    test.equal(typeof stats.received, 'number');
+    test.done();
+};
+
+module.exports['Connection: Random ID generation'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    let id1 = client.getRandomId();
+    let id2 = client.getRandomId();
+    
+    test.ok(typeof id1 === 'string' && id1.length > 0);
+    test.ok(typeof id2 === 'string' && id2.length > 0);
+    test.notEqual(id1, id2, 'IDs should be unique');
+    test.done();
+};
+
+module.exports['Connection: State management'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.equal(client.state, client.states.NOT_AUTHENTICATED);
+    test.equal(client.authenticated, false);
+    test.ok(client.capabilities instanceof Map);
+    test.done();
+};
+
+module.exports['Connection: Event emitter setup'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.equal(typeof client.on, 'function');
+    test.equal(typeof client.emit, 'function');
+    test.equal(typeof client.removeListener, 'function');
+    test.done();
+};

package/test/integration-test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const { ImapFlow } = require('../lib/imap-flow');
+
+module.exports['Integration: Basic client creation'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    test.ok(client);
+    test.equal(client.state, client.states.NOT_AUTHENTICATED);
+    test.equal(client.authenticated, false);
+    test.done();
+};
+
+module.exports['Integration: Multiple client instances'] = test => {
+    let client1 = new ImapFlow({
+        host: 'imap1.example.com',
+        auth: { user: 'test1', pass: 'test1' }
+    });
+    
+    let client2 = new ImapFlow({
+        host: 'imap2.example.com',
+        auth: { user: 'test2', pass: 'test2' }
+    });
+    
+    test.ok(client1);
+    test.ok(client2);
+    test.notEqual(client1.id, client2.id);
+    test.done();
+};
+
+module.exports['Integration: Client configuration'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        port: 993,
+        secure: true,
+        auth: { user: 'test', pass: 'test' },
+        logger: false
+    });
+    
+    test.equal(client.host, 'imap.example.com');
+    test.equal(client.port, 993);
+    test.equal(client.secureConnection, true);
+    test.done();
+};
+
+module.exports['Integration: Event emitter functionality'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    let eventFired = false;
+    client.on('test-event', () => {
+        eventFired = true;
+    });
+    
+    client.emit('test-event');
+    
+    setTimeout(() => {
+        test.ok(eventFired);
+        test.done();
+    }, 10);
+};
+
+module.exports['Integration: Stats functionality'] = test => {
+    let client = new ImapFlow({
+        host: 'imap.example.com',
+        auth: { user: 'test', pass: 'test' }
+    });
+    
+    let stats = client.stats();
+    test.ok(typeof stats === 'object');
+    test.ok(Object.prototype.hasOwnProperty.call(stats, 'sent'));
+    test.ok(Object.prototype.hasOwnProperty.call(stats, 'received'));
+    
+    // Reset stats
+    let resetStats = client.stats(true);
+    test.ok(typeof resetStats === 'object');
+    test.done();
+};

package/test/search-compiler-test.js

@@ -0,0 +1,81 @@
+'use strict';
+
+const { searchCompiler } = require('../lib/search-compiler');
+
+// Mock connection for testing
+let createMockConnection = () => ({
+    capabilities: new Map([
+        ['IMAP4rev1', true],
+        ['UTF8=ACCEPT', true]
+    ]),
+    enabled: new Set(['UTF8=ACCEPT'])
+});
+
+// Mock mailbox for testing
+let createMockMailbox = () => ({
+    flags: new Set(['\\Seen', '\\Answered', '\\Flagged', '\\Deleted', '\\Draft']),
+    permanentFlags: new Set(['\\*'])
+});
+
+module.exports['Search Compiler: Basic functionality'] = test => {
+    let connection = createMockConnection();
+    let mailbox = createMockMailbox();
+    
+    test.doesNotThrow(() => {
+        let compiled = searchCompiler(connection, { seen: false }, mailbox);
+        test.ok(Array.isArray(compiled));
+    });
+    
+    test.done();
+};
+
+module.exports['Search Compiler: Text searches'] = test => {
+    let connection = createMockConnection();
+    let mailbox = createMockMailbox();
+    
+    let compiled = searchCompiler(connection, { 
+        from: 'user@example.com',
+        subject: 'Test'
+    }, mailbox);
+    
+    test.ok(Array.isArray(compiled));
+    test.ok(compiled.length > 0);
+    test.done();
+};
+
+module.exports['Search Compiler: Flag searches'] = test => {
+    let connection = createMockConnection();
+    let mailbox = createMockMailbox();
+    
+    let compiled = searchCompiler(connection, { 
+        seen: true,
+        answered: false
+    }, mailbox);
+    
+    test.ok(Array.isArray(compiled));
+    test.ok(compiled.length > 0);
+    test.done();
+};
+
+module.exports['Search Compiler: Date searches'] = test => {
+    let connection = createMockConnection();
+    let mailbox = createMockMailbox();
+    
+    let compiled = searchCompiler(connection, { 
+        since: new Date('2023-01-01')
+    }, mailbox);
+    
+    test.ok(Array.isArray(compiled));
+    test.ok(compiled.length > 0);
+    test.done();
+};
+
+module.exports['Search Compiler: Empty query'] = test => {
+    let connection = createMockConnection();
+    let mailbox = createMockMailbox();
+    
+    let compiled = searchCompiler(connection, {}, mailbox);
+    
+    test.ok(Array.isArray(compiled));
+    test.done();
+};

package/test/special-use-test.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const specialUse = require('../lib/special-use');
+
+module.exports['Special Use: flags array'] = test => {
+    test.ok(Array.isArray(specialUse.flags));
+    test.ok(specialUse.flags.includes('\\Sent'));
+    test.ok(specialUse.flags.includes('\\Drafts'));
+    test.ok(specialUse.flags.includes('\\Trash'));
+    test.ok(specialUse.flags.includes('\\Archive'));
+    test.done();
+};
+
+module.exports['Special Use: names object'] = test => {
+    test.ok(typeof specialUse.names === 'object');
+    test.ok(specialUse.names['\\Sent']);
+    test.ok(Array.isArray(specialUse.names['\\Sent']));
+    test.ok(specialUse.names['\\Sent'].includes('sent'));
+    test.done();
+};
+
+module.exports['Special Use: Sent folder names'] = test => {
+    let sentNames = specialUse.names['\\Sent'];
+    test.ok(sentNames.includes('sent'));
+    test.ok(sentNames.includes('sent items'));
+    test.ok(sentNames.includes('sent messages'));
+    test.done();
+};
+
+module.exports['Special Use: Drafts folder names'] = test => {
+    let draftsNames = specialUse.names['\\Drafts'];
+    test.ok(draftsNames.includes('drafts'));
+    test.done();
+};
+
+module.exports['Special Use: Trash folder names'] = test => {
+    let trashNames = specialUse.names['\\Trash'];
+    test.ok(trashNames.includes('trash'));
+    test.ok(trashNames.includes('deleted items'));
+    test.ok(trashNames.includes('deleted messages'));
+    test.done();
+};
+
+module.exports['Special Use: Junk folder names'] = test => {
+    let junkNames = specialUse.names['\\Junk'];
+    test.ok(junkNames.includes('spam'));
+    test.ok(junkNames.includes('junk'));
+    test.done();
+};