imapflow 1.0.117 → 1.0.119

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+-   1.0.118 - 2022-12-22
+
+    -   Refactored detecting special use folders
+
 -   1.0.117 - 2022-12-05
 
     -   Updated command compiling. The command compiler returns a Buffer, not a "binary" string.

package/lib/commands/list.js

@@ -7,11 +7,13 @@ const { specialUse } = require('../special-use');
 module.exports = async (connection, reference, mailbox, options) => {
     options = options || {};
 
+    const FLAG_SORT_ORDER = ['\\Inbox', '\\Flagged', '\\Sent', '\\Drafts', '\\All', '\\Archive', '\\Junk', '\\Trash'];
+    const SOURCE_SORT_ORDER = ['user', 'extension', 'name'];
+
     let listCommand = connection.capabilities.has('XLIST') && !connection.capabilities.has('SPECIAL-USE') ? 'XLIST' : 'LIST';
 
     let response;
     try {
-        let flagsSeen = new Set();
         let entries = [];
 
         let statusMap = new Map();
@@ -49,6 +51,23 @@ module.exports = async (connection, reference, mailbox, options) => {
             }
         }
 
+        let specialUseMatches = {};
+        let addSpecialUseMatch = (entry, type, source) => {
+            if (!specialUseMatches[type]) {
+                specialUseMatches[type] = [];
+            }
+            specialUseMatches[type].push({ entry, source });
+        };
+
+        let specialUseHints = {};
+        if (options.specialUseHints && typeof options.specialUseHints === 'object') {
+            for (let type of Object.keys(options.specialUseHints)) {
+                if (['sent', 'junk', 'trash', 'drafts'].includes(type) && options.specialUseHints[type] && typeof options.specialUseHints[type] === 'string') {
+                    specialUseHints[normalizePath(connection, options.specialUseHints[type])] = `\\${type.replace(/^./, c => c.toUpperCase())}`;
+                }
+            }
+        }
+
         let runList = async (reference, mailbox) => {
             const cmdArgs = [encodePath(connection, reference), encodePath(connection, mailbox)];
 
@@ -71,17 +90,21 @@ module.exports = async (connection, reference, mailbox, options) => {
                             listed: true
                         };
 
+                        if (specialUseHints[entry.path]) {
+                            addSpecialUseMatch(entry, specialUseHints[entry.path], 'user');
+                        }
+
                         if (listCommand === 'XLIST' && entry.flags.has('\\Inbox')) {
                             // XLIST specific flag, ignore
                             entry.flags.delete('\\Inbox');
                             if (entry.path !== 'INBOX') {
                                 // XLIST may use localised inbox name
-                                entry.specialUse = '\\Inbox';
+                                addSpecialUseMatch(entry, '\\Inbox', 'extension');
                             }
                         }
 
                         if (entry.path.toUpperCase() === 'INBOX') {
-                            entry.specialUse = '\\Inbox';
+                            addSpecialUseMatch(entry, '\\Inbox', 'name');
                         }
 
                         if (entry.delimiter && entry.path.charAt(0) === entry.delimiter) {
@@ -92,9 +115,13 @@ module.exports = async (connection, reference, mailbox, options) => {
                         entry.parent = entry.delimiter ? entry.path.split(entry.delimiter) : [entry.path];
                         entry.name = entry.parent.pop();
 
-                        let specialUseFlag = specialUse(connection.capabilities.has('XLIST') || connection.capabilities.has('SPECIAL-USE'), entry);
-                        if (specialUseFlag && !flagsSeen.has(specialUseFlag)) {
-                            entry.specialUse = specialUseFlag;
+                        let { flag: specialUseFlag, source: flagSource } = specialUse(
+                            connection.capabilities.has('XLIST') || connection.capabilities.has('SPECIAL-USE'),
+                            entry
+                        );
+
+                        if (specialUseFlag) {
+                            addSpecialUseMatch(entry, specialUseFlag, flagSource);
                         }
 
                         entries.push(entry);
@@ -172,7 +199,7 @@ module.exports = async (connection, reference, mailbox, options) => {
             return entries;
         }
 
-        if (normalizedReference && !entries.find(entry => entry.specialUse === '\\Inbox')) {
+        if (normalizedReference && !specialUseMatches['\\Inbox']) {
             // INBOX was most probably not included in the listing if namespace was used
             await runList('', 'INBOX');
         }
@@ -213,7 +240,7 @@ module.exports = async (connection, reference, mailbox, options) => {
                         };
 
                         if (entry.path.toUpperCase() === 'INBOX') {
-                            entry.specialUse = '\\Inbox';
+                            addSpecialUseMatch(entry, '\\Inbox', 'name');
                         }
 
                         if (entry.delimiter && entry.path.charAt(0) === entry.delimiter) {
@@ -244,26 +271,52 @@ module.exports = async (connection, reference, mailbox, options) => {
         );
         response.next();
 
+        for (let type of Object.keys(specialUseMatches)) {
+            let sortedEntries = specialUseMatches[type].sort((a, b) => {
+                let aSource = SOURCE_SORT_ORDER.indexOf(a.source);
+                let bSource = SOURCE_SORT_ORDER.indexOf(b.source);
+                if (aSource === bSource) {
+                    return a.entry.path.localeCompare(b.entry.path);
+                }
+                return aSource - bSource;
+            });
+
+            if (!sortedEntries[0].entry.specialUse) {
+                sortedEntries[0].entry.specialUse = type;
+                sortedEntries[0].entry.specialUseSource = sortedEntries[0].source;
+            }
+        }
+
         let inboxEntry = entries.find(entry => entry.specialUse === '\\Inbox');
         if (inboxEntry && !inboxEntry.subscribed) {
             // override server settings and make INBOX always as subscribed
             inboxEntry.subscribed = true;
         }
 
-        ['\\Drafts', '\\Junk', '\\Sent', '\\Trash'].forEach(specialUseFlag => {
-            // try to ensure that we have most needed special use mailboxes detected
-            if (entries.find(entry => entry.specialUse === specialUseFlag)) {
-                return;
+        return entries.sort((a, b) => {
+            if (a.specialUse && !b.specialUse) {
+                return -1;
+            }
+            if (!a.specialUse && b.specialUse) {
+                return 1;
             }
+            if (a.specialUse && b.specialUse) {
+                return FLAG_SORT_ORDER.indexOf(a.specialUse) - FLAG_SORT_ORDER.indexOf(b.specialUse);
+            }
+
+            let aList = [].concat(a.parent).concat(a.name);
+            let bList = [].concat(b.parent).concat(b.name);
 
-            // special use mailbox not found? try again
-            let match = entries.find(entry => !entry.specialUse && specialUse(false, entry) === specialUseFlag);
-            if (match) {
-                match.specialUse = specialUseFlag;
+            for (let i = 0; i < aList.length; i++) {
+                let aPart = aList[i];
+                let bPart = bList[i];
+                if (aPart !== bPart) {
+                    return aPart.localeCompare(bPart || '');
+                }
             }
-        });
 
-        return entries;
+            return a.path.localeCompare(b.path);
+        });
     } catch (err) {
         connection.log.warn({ msg: 'Failed to list folders', err, cid: connection.id });
         throw err;

package/lib/imap-flow.js

@@ -1452,6 +1452,11 @@ class ImapFlow extends EventEmitter {
      * @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
+     * @param {Object} [options.specialUseHints] set specific paths as special use folders, this would override special use flags provided from the server
+     * @param {String} [options.specialUseHints.sent] Path to "Sent Mail" folder
+     * @param {String} [options.specialUseHints.trash] Path to "Trash" folder
+     * @param {String} [options.specialUseHints.junk] Path to "Junk Mail" folder
+     * @param {String} [options.specialUseHints.drafts] Path to "Drafts" folder
      * @returns {Promise<ListResponse[]>} An array of ListResponse objects
      *
      * @example

package/lib/special-use.js

@@ -269,11 +269,23 @@ module.exports = {
     },
 
     specialUse(hasSpecialUseExtension, folder) {
+        let result;
+
         if (hasSpecialUseExtension) {
-            return module.exports.flags.find(flag => folder.flags.has(flag));
+            result = {
+                flag: module.exports.flags.find(flag => folder.flags.has(flag)),
+                source: 'extension'
+            };
+        }
+
+        if (!result || !result.flag) {
+            let name = folder.name.toLowerCase().trim();
+            result = {
+                flag: Object.keys(module.exports.names).find(flag => module.exports.names[flag].includes(name)),
+                source: 'name'
+            };
         }
 
-        let name = folder.name.toLowerCase().trim();
-        return Object.keys(module.exports.names).find(flag => module.exports.names[flag].includes(name));
+        return result && result.flag ? result : { flag: null };
     }
 };

package/lib/types.d.ts

@@ -167,6 +167,11 @@ declare module "imapflow" {
          * @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
+         * @param [options.specialUseHints] - set specific paths as special use folders, this would override special use flags provided from the server
+         * @param [options.specialUseHints.sent] - Path to "Sent Mail" folder
+         * @param [options.specialUseHints.trash] - Path to "Trash" folder
+         * @param [options.specialUseHints.junk] - Path to "Junk Mail" folder
+         * @param [options.specialUseHints.drafts] - Path to "Drafts" folder
          * @returns An array of ListResponse objects
          */
         list(options?: {
@@ -178,6 +183,12 @@ declare module "imapflow" {
                 unseen?: boolean;
                 highestModseq?: boolean;
             };
+            specialUseHints?: {
+                sent?: string;
+                trash?: string;
+                junk?: string;
+                drafts?: string;
+            };
         }): Promise<ListResponse[]>;
         /**
          * Lists available mailboxes as a tree structured object

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "imapflow",
-    "version": "1.0.117",
+    "version": "1.0.119",
     "description": "IMAP Client for Node",
     "main": "./lib/imap-flow.js",
     "scripts": {
@@ -31,9 +31,9 @@
         "@babel/eslint-plugin": "7.19.1",
         "@babel/plugin-syntax-class-properties": "7.12.13",
         "@babel/preset-env": "7.20.2",
-        "@types/node": "18.11.10",
+        "@types/node": "18.11.17",
         "braintree-jsdoc-template": "3.3.0",
-        "eslint": "8.29.0",
+        "eslint": "8.30.0",
         "eslint-config-nodemailer": "1.2.0",
         "eslint-config-prettier": "8.5.0",
         "grunt": "1.5.3",
@@ -48,11 +48,11 @@
         "encoding-japanese": "2.0.0",
         "iconv-lite": "0.6.3",
         "libbase64": "1.2.1",
-        "libmime": "5.1.0",
+        "libmime": "5.2.0",
         "libqp": "2.0.1",
-        "mailsplit": "5.3.2",
+        "mailsplit": "5.4.0",
         "nodemailer": "6.8.0",
-        "pino": "8.7.0",
+        "pino": "8.8.0",
         "socks": "2.7.1"
     }
 }