imapflow 1.0.101 → 1.0.102

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+-   1.0.102 - 2022-08-18
+
+    -   Added new option `{statusQuery: {<statusOptions>}` for `list()` method
+    -   Added support for LIST-STATUS extension https://datatracker.ietf.org/doc/html/rfc5819
+
 -   1.0.100 - 2022-06-17
 
     -   Emit new message notification if appending to currently opened folder

package/lib/commands/list.js

@@ -14,8 +14,46 @@ module.exports = async (connection, reference, mailbox, options) => {
         let flagsSeen = new Set();
         let entries = [];
 
+        let statusMap = new Map();
+        let returnArgs = [];
+        let statusQueryAttributes = [];
+
+        if (options.statusQuery) {
+            Object.keys(options.statusQuery || {}).forEach(key => {
+                if (!options.statusQuery[key]) {
+                    return;
+                }
+
+                switch (key.toUpperCase()) {
+                    case 'MESSAGES':
+                    case 'RECENT':
+                    case 'UIDNEXT':
+                    case 'UIDVALIDITY':
+                    case 'UNSEEN':
+                        statusQueryAttributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                        break;
+
+                    case 'HIGHESTMODSEQ':
+                        if (connection.capabilities.has('CONDSTORE')) {
+                            statusQueryAttributes.push({ type: 'ATOM', value: key.toUpperCase() });
+                        }
+                        break;
+                }
+            });
+        }
+
         let runList = async (reference, mailbox) => {
-            response = await connection.exec(listCommand, [encodePath(connection, reference), encodePath(connection, mailbox)], {
+            const cmdArgs = [encodePath(connection, reference), encodePath(connection, mailbox)];
+
+            if (listCommand === 'LIST' && connection.capabilities.has('LIST-STATUS') && statusQueryAttributes.length) {
+                returnArgs.push({ type: 'ATOM', value: 'STATUS' }, statusQueryAttributes);
+            }
+
+            if (returnArgs.length) {
+                cmdArgs.push({ type: 'ATOM', value: 'RETURN' }, returnArgs);
+            }
+
+            response = await connection.exec(listCommand, cmdArgs, {
                 untagged: {
                     [listCommand]: async untagged => {
                         if (!untagged.attributes || !untagged.attributes.length) {
@@ -57,6 +95,67 @@ module.exports = async (connection, reference, mailbox, options) => {
                         }
 
                         entries.push(entry);
+                    },
+
+                    STATUS: async untagged => {
+                        let statusPath = normalizePath(connection, decodePath(connection, (untagged.attributes[0] && untagged.attributes[0].value) || ''));
+                        let statusList = untagged.attributes && Array.isArray(untagged.attributes[1]) ? untagged.attributes[1] : false;
+                        if (!statusList || !statusPath) {
+                            return;
+                        }
+
+                        let key;
+
+                        let map = { path: statusPath };
+
+                        statusList.forEach((entry, i) => {
+                            if (i % 2 === 0) {
+                                key = entry && typeof entry.value === 'string' ? entry.value : false;
+                                return;
+                            }
+                            if (!key || !entry || typeof entry.value !== 'string') {
+                                return;
+                            }
+                            let value = false;
+                            switch (key.toUpperCase()) {
+                                case 'MESSAGES':
+                                    key = 'messages';
+                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
+                                    break;
+
+                                case 'RECENT':
+                                    key = 'recent';
+                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
+                                    break;
+
+                                case 'UIDNEXT':
+                                    key = 'uidNext';
+                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
+                                    break;
+
+                                case 'UIDVALIDITY':
+                                    key = 'uidValidity';
+                                    value = !isNaN(entry.value) ? BigInt(entry.value) : false;
+                                    break;
+
+                                case 'UNSEEN':
+                                    key = 'unseen';
+                                    value = !isNaN(entry.value) ? Number(entry.value) : false;
+                                    break;
+
+                                case 'HIGHESTMODSEQ':
+                                    key = 'highestModseq';
+                                    value = !isNaN(entry.value) ? BigInt(entry.value) : false;
+                                    break;
+                            }
+                            if (value === false) {
+                                return;
+                            }
+
+                            map[key] = value;
+                        });
+
+                        statusMap.set(statusPath, map);
                     }
                 }
             });
@@ -66,6 +165,23 @@ module.exports = async (connection, reference, mailbox, options) => {
         let normalizedReference = normalizePath(connection, reference || '');
         await runList(normalizedReference, normalizePath(connection, mailbox || '', true));
 
+        if (options.statusQuery) {
+            for (let entry of entries) {
+                if (!entry.flags.has('\\Noselect') && !entry.flags.has('\\NonExistent')) {
+                    if (statusMap.has(entry.path)) {
+                        entry.status = statusMap.get(entry.path);
+                    } else if (!statusMap.size) {
+                        // run STATUS command
+                        try {
+                            entry.status = await connection.run('STATUS', entry.path, options.statusQuery);
+                        } catch (err) {
+                            entry.status = { error: err };
+                        }
+                    }
+                }
+            }
+        }
+
         if (options.listOnly) {
             return entries;
         }

package/lib/commands/select.js

@@ -47,9 +47,11 @@ module.exports = async (connection, path, options) => {
             map.qresync = true;
         }
 
+        let encodedPath = encodePath(connection, path);
+
         response = await connection.exec(
             !options.readOnly ? 'SELECT' : 'EXAMINE',
-            [{ type: 'ATOM', value: encodePath(connection, path) }].concat(extraArgs || []),
+            [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }].concat(extraArgs || []),
             {
                 untagged: {
                     OK: async untagged => {

package/lib/commands/status.js

@@ -10,8 +10,9 @@ module.exports = async (connection, path, query) => {
     }
 
     path = normalizePath(connection, path);
+    let encodedPath = encodePath(connection, path);
 
-    let attributes = [{ type: 'ATOM', value: encodePath(connection, path) }];
+    let attributes = [{ type: encodedPath.indexOf('&') >= 0 ? 'STRING' : 'ATOM', value: encodedPath }];
 
     let queryAttributes = [];
     Object.keys(query || {}).forEach(key => {

package/lib/imap-flow.js

@@ -1392,19 +1392,28 @@ class ImapFlow extends EventEmitter {
      * @property {String} specialUse one of special-use flags (if applicable): "\All", "\Archive", "\Drafts", "\Flagged", "\Junk", "\Sent", "\Trash". Additionally INBOX has non-standard "\Inbox" flag set
      * @property {Boolean} listed `true` if mailbox was found from the output of LIST command
      * @property {Boolean} subscribed `true` if mailbox was found from the output of LSUB command
+     * @property {StatusObject} [status] If `statusQuery` was used, then this value includes the status response
      */
 
     /**
      * Lists available mailboxes as an Array
      *
+     * @param {Object} [options] defines additional listing options
+     * @param {Object} [options.statusQuery] request status items for every listed entry
+     * @param {Boolean} [options.statusQuery.messages] if `true` request count of messages
+     * @param {Boolean} [options.statusQuery.recent] if `true` request count of messages with \\Recent tag
+     * @param {Boolean} [options.statusQuery.uidNext] if `true` request predicted next UID
+     * @param {Boolean} [options.statusQuery.uidValidity] if `true` request mailbox `UIDVALIDITY` value
+     * @param {Boolean} [options.statusQuery.unseen] if `true` request count of unseen messages
+     * @param {Boolean} [options.statusQuery.highestModseq] if `true` request last known modseq value
      * @returns {Promise<ListResponse[]>} An array of ListResponse objects
      *
      * @example
      * let list = await client.list();
      * list.forEach(mailbox=>console.log(mailbox.path));
      */
-    async list() {
-        let folders = await this.run('LIST', '', '*');
+    async list(options) {
+        let folders = await this.run('LIST', '', '*', options);
         this.folders = new Map(folders.map(folder => [folder.path, folder]));
         return folders;
     }

package/lib/types.d.ts

@@ -151,9 +151,26 @@ declare module "imapflow" {
          * @example
          * let list = await client.list();
          * list.forEach(mailbox=>console.log(mailbox.path));
+         * @param [options] - defines additional listing options
+         * @param [options.statusQuery] - request status items for every listed entry
+         * @param [options.statusQuery.messages] - if `true` request count of messages
+         * @param [options.statusQuery.recent] - if `true` request count of messages with \\Recent tag
+         * @param [options.statusQuery.uidNext] - if `true` request predicted next UID
+         * @param [options.statusQuery.uidValidity] - if `true` request mailbox `UIDVALIDITY` value
+         * @param [options.statusQuery.unseen] - if `true` request count of unseen messages
+         * @param [options.statusQuery.highestModseq] - if `true` request last known modseq value
          * @returns An array of ListResponse objects
          */
-        list(): Promise<ListResponse[]>;
+        list(options?: {
+            statusQuery?: {
+                messages?: boolean;
+                recent?: boolean;
+                uidNext?: boolean;
+                uidValidity?: boolean;
+                unseen?: boolean;
+                highestModseq?: boolean;
+            };
+        }): Promise<ListResponse[]>;
         /**
          * Lists available mailboxes as a tree structured object
          * @example
@@ -581,6 +598,7 @@ declare type QuotaResponse = {
  * @property specialUse - one of special-use flags (if applicable): "\All", "\Archive", "\Drafts", "\Flagged", "\Junk", "\Sent", "\Trash". Additionally INBOX has non-standard "\Inbox" flag set
  * @property listed - `true` if mailbox was found from the output of LIST command
  * @property subscribed - `true` if mailbox was found from the output of LSUB command
+ * @property [status] - If `statusQuery` was used, then this value includes the status response
  */
 declare type ListResponse = {
     path: string;
@@ -593,6 +611,7 @@ declare type ListResponse = {
     specialUse: string;
     listed: boolean;
     subscribed: boolean;
+    status?: StatusObject;
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.101",
+    "version": "1.0.102",
     "description": "IMAP Client for Node",
     "main": "./lib/imap-flow.js",
     "scripts": {
@@ -31,9 +31,9 @@
         "@babel/eslint-plugin": "7.18.10",
         "@babel/plugin-syntax-class-properties": "7.12.13",
         "@babel/preset-env": "7.18.10",
-        "@types/node": "18.6.5",
+        "@types/node": "18.7.6",
         "braintree-jsdoc-template": "3.3.0",
-        "eslint": "8.21.0",
+        "eslint": "8.22.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "8.5.0",
         "grunt": "1.5.3",
@@ -51,8 +51,8 @@
         "libmime": "5.1.0",
         "libqp": "1.1.0",
         "mailsplit": "5.3.2",
-        "nodemailer": "6.7.7",
-        "pino": "8.4.0",
+        "nodemailer": "6.7.8",
+        "pino": "8.4.1",
         "socks": "2.7.0"
     }
 }