imapkit 0.0.0-stage → 4.0.0

package/lib/dates.js

@@ -0,0 +1,123 @@
+'use strict';
+
+// Month names of the RFC 3501 section 9 date-month rule, in the case they are sent in
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/**
+ * Returns the index of a month name, ignoring case like all ABNF strings
+ *
+ * @param {String} name Three letter month name, e.g. "jan"
+ * @return {Number} 0 for January to 11 for December, or -1 for an unknown name
+ */
+function monthIndex(name) {
+    const value = String(name || '').toLowerCase();
+    return MONTHS.findIndex(month => month.toLowerCase() === value);
+}
+
+/**
+ * Checks if day, month and year make a real date
+ *
+ * @param {Number|String} day Day of the month
+ * @param {Number} month Month index, 0 for January
+ * @param {Number|String} year Full year
+ * @return {Boolean} true if the date exists
+ */
+function isRealDate(day, month, year) {
+    day = Number(day);
+    year = Number(year);
+    if (month < 0 || month > 11 || !Number.isInteger(day) || day < 1) {
+        return false;
+    }
+    return day <= new Date(Date.UTC(year, month + 1, 0)).getUTCDate();
+}
+
+/**
+ * Converts day, month and year to a comparable YYYY-MM-DD string
+ *
+ * @param {Number|String} day Day of the month
+ * @param {Number} month Month index, 0 for January
+ * @param {Number|String} year Full year
+ * @return {String|Boolean} the date, or false for an impossible date
+ */
+function dateKey(day, month, year) {
+    if (!isRealDate(day, month, year)) {
+        return false;
+    }
+    return String(year).padStart(4, '0') + '-' + String(month + 1).padStart(2, '0') + '-' + String(day).padStart(2, '0');
+}
+
+/**
+ * Parses a date-time value of the RFC 3501 section 9 form, like an INTERNALDATE ("14-Sep-2013 21:22:28 -0300").
+ * A value with only the date part is accepted as well, its time fields are left undefined
+ *
+ * @param {String} value Date-time value
+ * @return {Object|null} `{ day, month, year, hours, minutes, seconds, zone }` with the month index, or null
+ */
+function parseDateTime(value) {
+    const match = (value || '').toString().match(/^\s*(\d{1,2})-([A-Za-z]{3})-(\d{4})(?: (\d{2}):(\d{2}):(\d{2}) ([+-]\d{4}))?/);
+    if (!match || !isRealDate(match[1], monthIndex(match[2]), match[3])) {
+        return null;
+    }
+    const time = match[4] === undefined ? {} : { hours: Number(match[4]), minutes: Number(match[5]), seconds: Number(match[6]), zone: match[7] };
+    return Object.assign({ day: Number(match[1]), month: monthIndex(match[2]), year: Number(match[3]) }, time);
+}
+
+/**
+ * Parses the date-time of a Date header (RFC 5322 section 3.3, with the obsolete forms of section 4.3: comments,
+ * two and three digit years, zone names). SEARCH uses only the date as written (RFC 3501 section 6.4.4), SORT
+ * normalizes date and time to UTC with toTimestamp (RFC 5256 section 2.2), so both read the header with this
+ *
+ * @param {String} header Value of the Date header
+ * @return {Object|null} `{ day, month, year, hours, minutes, seconds, zone }` with the month index, or null if the
+ *   header has no valid date. The time fields are undefined when the header has no time
+ */
+function parseHeaderDate(header) {
+    const match = (header || '')
+        .toString()
+        .replace(/\([^()]*\)/g, ' ')
+        .match(/^\s*(?:[A-Za-z]+\s*,)?\s*(\d{1,2})\s+([A-Za-z]{3})\s+(\d{2,4})(?:\s+(\d{1,2})\s*:\s*(\d{2})(?:\s*:\s*(\d{2}))?(?:\s+([+-]\d{4}|[A-Za-z]+))?)?/);
+    if (!match) {
+        return null;
+    }
+    let year = Number(match[3]);
+    // RFC 5322 section 4.3: two digit years below 50 are 20xx, three digit years add 1900
+    if (match[3].length === 2) {
+        year += year < 50 ? 2000 : 1900;
+    } else if (match[3].length === 3) {
+        year += 1900;
+    }
+    const day = Number(match[1]);
+    const month = monthIndex(match[2]);
+    if (!isRealDate(day, month, year)) {
+        return null;
+    }
+    const time = match[4] === undefined ? {} : { hours: Number(match[4]), minutes: Number(match[5]), seconds: Number(match[6] || 0), zone: match[7] };
+    return Object.assign({ day, month, year }, time);
+}
+
+// RFC 5322 section 4.3 obsolete zones, military zones are treated as "-0000"
+const ZONES = { UT: 0, GMT: 0, EST: -5, EDT: -4, CST: -6, CDT: -5, MST: -7, MDT: -6, PST: -8, PDT: -7 };
+
+/**
+ * Converts date and time parts to milliseconds since the epoch, adjusted by the time zone. An unknown zone is UTC
+ *
+ * @param {Object} date `{ day, month, year, hours, minutes, seconds, zone }`, see parseDateTime and parseHeaderDate
+ * @return {Number} timestamp
+ */
+function toTimestamp(date) {
+    const zone = date.zone || '';
+    let offset = 0;
+    if (/^[+-]\d{4}$/.test(zone)) {
+        const sign = zone.charAt(0) === '-' ? -1 : 1;
+        const zoneHours = Number(zone.substr(1, 2));
+        const zoneMinutes = Number(zone.substr(3, 2));
+        if (zoneMinutes < 60) {
+            offset = sign * (zoneHours * 60 + zoneMinutes);
+        }
+    } else if (Object.hasOwn(ZONES, zone.toUpperCase())) {
+        offset = ZONES[zone.toUpperCase()] * 60;
+    }
+    return Date.UTC(date.year, date.month, date.day, date.hours || 0, date.minutes || 0, date.seconds || 0) - offset * 60 * 1000;
+}
+
+module.exports = { MONTHS, monthIndex, isRealDate, dateKey, parseDateTime, parseHeaderDate, toTimestamp };

package/lib/deflate-layer.js

@@ -0,0 +1,232 @@
+'use strict';
+
+const zlib = require('zlib');
+
+// Z_SYNC_FLUSH ends with an empty stored block, LEN 0 and NLEN 0xFFFF (RFC 1951 section 3.2.4)
+const SYNC_MARKER = Buffer.from([0x00, 0x00, 0xff, 0xff]);
+// Z_FINISH right after a flush is an empty final block with fixed Huffman codes
+const EMPTY_FINAL_BLOCK = Buffer.from([0x03, 0x00]);
+
+/**
+ * One end of a COMPRESS=DEFLATE layer (RFC 4978): raw DEFLATE (RFC 1951, no zlib header or
+ * checksum) in both directions. The server plugin uses it, and so do the clients of the tests and
+ * the compare tool.
+ *
+ * Either direction can be terminated, which UNAUTHENTICATE requires (RFC 8437 section 4.1). Output
+ * terminates with a final DEFLATE block, data written after that goes out uncompressed once the
+ * compressed data is out. Input terminates where the peer ended its compression: at the end of
+ * its DEFLATE stream if it sent a final block, otherwise at the end of the sync flush that
+ * carried the last compressed data. The input is split at sync flush markers to find that point.
+ */
+class DeflateLayer {
+    /**
+     * @param {Object} options
+     * @param {Function} options.writeRaw `(buffer)` sends octets to the peer
+     * @param {Function} options.onData `(buffer)` gets the input, decompressed while compression is active
+     * @param {Function} [options.onError] `(err)` called when the input is not valid DEFLATE data
+     */
+    constructor(options) {
+        this.writeRaw = options.writeRaw;
+        this.onData = options.onData;
+        this.onError = options.onError || (() => false);
+
+        // outgoing data is compressed
+        this.active = true;
+        // incoming data is compressed
+        this.inputActive = true;
+
+        this._deflate = zlib.createDeflateRaw();
+        this._deflate.on('data', chunk => this.writeRaw(chunk));
+        this._deflate.on('error', err => this.onError(err));
+        // writes that wait for the final compressed data, null when nothing is waiting
+        this._held = null;
+        this._endCallbacks = [];
+        this._flushScheduled = false;
+
+        this._inflate = zlib.createInflateRaw({ flush: zlib.constants.Z_SYNC_FLUSH });
+        this._inflate.on('data', chunk => {
+            // anything the peer compressed after it ended its compression is dropped
+            if (this.inputActive) {
+                this.onData(chunk);
+            }
+        });
+        this._inflate.on('error', err => {
+            this.inputActive = false;
+            this._pieces = [];
+            this._busy = false;
+            this.onError(err);
+            this._next();
+        });
+        // input waiting for the inflater, split at sync flush markers
+        this._pieces = [];
+        this._busy = false;
+        // octets given to the inflater
+        this._fed = 0;
+        // the peer may still send the empty final block of its DEFLATE stream
+        this._expectFinal = false;
+        // called once the received data is processed
+        this._idleCallbacks = [];
+    }
+
+    /**
+     * Sends data to the peer, compressed while compression is active
+     *
+     * @param {Buffer} data Data to send
+     */
+    write(data) {
+        if (this._held) {
+            this._held.push(data);
+            return;
+        }
+        if (!this.active) {
+            this.writeRaw(data);
+            return;
+        }
+        this._deflate.write(data);
+        if (!this._flushScheduled) {
+            // everything written in one go, like a burst of responses, is flushed together, so the peer
+            // gets it right away instead of when the compressor buffer fills up (RFC 4978 section 4)
+            this._flushScheduled = true;
+            process.nextTick(() => {
+                this._flushScheduled = false;
+                if (this.active && !this._deflate.destroyed) {
+                    this._deflate.flush(zlib.constants.Z_SYNC_FLUSH);
+                }
+            });
+        }
+    }
+
+    /**
+     * Terminates the outgoing compression with a final DEFLATE block. Later writes are sent
+     * uncompressed, after the compressed data.
+     *
+     * @param {Function} [callback] Called once the compressed data is written out
+     */
+    end(callback) {
+        if (callback) {
+            this._endCallbacks.push(callback);
+        }
+        if (!this.active) {
+            if (!this._held) {
+                this._runCallbacks('_endCallbacks');
+            }
+            return;
+        }
+        this.active = false;
+        this._held = [];
+        this._deflate.once('end', () => {
+            const held = this._held;
+            this._held = null;
+            held.forEach(data => this.writeRaw(data));
+            this._runCallbacks('_endCallbacks');
+        });
+        this._deflate.end();
+    }
+
+    // calls the callbacks of a list once, callbacks added meanwhile wait for the next run
+    _runCallbacks(key) {
+        const callbacks = this[key];
+        this[key] = [];
+        callbacks.forEach(callback => callback());
+    }
+
+    /**
+     * Handles octets received from the peer
+     *
+     * @param {Buffer} chunk Received data
+     */
+    receive(chunk) {
+        if (!this.inputActive && !this._busy && !this._pieces.length) {
+            this._receivePlain(chunk);
+            return;
+        }
+        let start = 0;
+        let pos;
+        while ((pos = chunk.indexOf(SYNC_MARKER, start)) >= 0) {
+            this._pieces.push(chunk.subarray(start, pos + SYNC_MARKER.length));
+            start = pos + SYNC_MARKER.length;
+        }
+        if (start < chunk.length) {
+            this._pieces.push(chunk.subarray(start));
+        }
+        this._next();
+    }
+
+    /**
+     * Tells the layer that the peer terminates its compression after the data decompressed so far
+     * (RFC 8437 section 4.1). Call it from onData, the rest of the input is then passed on as is.
+     */
+    endInput() {
+        this.inputActive = false;
+    }
+
+    /**
+     * Calls back once all received data is passed on
+     *
+     * @param {Function} callback Function to call
+     */
+    whenIdle(callback) {
+        this._idleCallbacks.push(callback);
+        this._next();
+    }
+
+    _next() {
+        if (this._busy) {
+            return;
+        }
+        if (!this._pieces.length) {
+            this._runCallbacks('_idleCallbacks');
+            return;
+        }
+        if (!this.inputActive) {
+            const rest = Buffer.concat(this._pieces);
+            this._pieces = [];
+            this._receivePlain(rest);
+            this._next();
+            return;
+        }
+
+        const piece = this._pieces.shift();
+        this._busy = true;
+        this._fed += piece.length;
+        this._inflate.write(piece, () => {
+            this._busy = false;
+            // octets the inflater did not use follow the end of the peer's DEFLATE stream
+            const unused = this._fed - this._inflate.bytesWritten;
+            if (unused > 0 || this._inflate.readableEnded) {
+                this.inputActive = false;
+                if (unused > 0) {
+                    this._pieces.unshift(piece.subarray(piece.length - unused));
+                }
+            } else if (!this.inputActive) {
+                // the input ended at a sync flush, the final block may still follow
+                this._expectFinal = true;
+            }
+            this._next();
+        });
+    }
+
+    _receivePlain(chunk) {
+        if (this._expectFinal) {
+            this._expectFinal = false;
+            if (chunk.subarray(0, EMPTY_FINAL_BLOCK.length).equals(EMPTY_FINAL_BLOCK)) {
+                chunk = chunk.subarray(EMPTY_FINAL_BLOCK.length);
+            }
+        }
+        if (chunk.length) {
+            this.onData(chunk);
+        }
+    }
+
+    /**
+     * Frees the compressor and the decompressor
+     */
+    destroy() {
+        this.active = this.inputActive = false;
+        this._pieces = [];
+        this._deflate.destroy();
+        this._inflate.destroy();
+    }
+}
+
+module.exports = DeflateLayer;

package/lib/envelope.js

@@ -0,0 +1,82 @@
+'use strict';
+
+// This module converts message structure into an ENVELOPE object
+
+/**
+ * Convert a message object to an ENVELOPE object
+ *
+ * @param {Object} header Parsed header of a mime tree node
+ * @return {Object} ENVELOPE compatible object
+ */
+module.exports = function (header) {
+    // RFC 3501 9: env-date and env-subject are nstring, NIL when the header is missing
+    const subject = header.subject;
+    return [
+        header.date || null,
+        typeof subject === 'string' ? subject : null,
+        processAddress(header.from),
+        processAddress(header.sender, header.from),
+        processAddress(header['reply-to'], header.from),
+        processAddress(header.to),
+        processAddress(header.cc),
+        processAddress(header.bcc),
+        // If this is an embedded MESSAGE/RFC822, then Gmail seems to
+        // have a bug here, it states '"NIL"' as the value, not 'NIL'
+        header['in-reply-to'] || null,
+        header['message-id'] || null
+    ];
+};
+
+/**
+ * Converts an address object to a list of arrays
+ * [{name: "User Name", addres:"user@example.com"}] -> [["User Name", null, "user", "example.com"]]
+ *
+ * @param {Array} arr An array of address objects
+ * @return {Array} A list of addresses
+ */
+function processAddress(arr, def) {
+    arr = [].concat(arr || []);
+    if (!arr.length) {
+        arr = [].concat(def || []);
+    }
+    if (!arr.length) {
+        return null;
+    }
+    let result = [];
+    arr.forEach(addr => {
+        if (addr.group) {
+            // Handle group syntax
+            result.push([null, null, addr.name || '', null]);
+            result = result.concat(processAddress(addr.group) || []);
+            result.push([null, null, null, null]);
+            return;
+        }
+
+        let name = addr.name || null;
+        let address = addr.address || '';
+
+        if (!address && name) {
+            // a bare word ("To: localuser") is the mailbox, not the name
+            address = name;
+            name = null;
+        }
+
+        if (!address) {
+            return;
+        }
+
+        const at = address.lastIndexOf('@');
+        const user = at >= 0 ? address.substr(0, at) : address;
+        // RFC 3501 7.4.2 reserves a NIL host for group markers, so an address without a domain gets
+        // the placeholder host that Dovecot uses for the same input
+        const domain = (at >= 0 ? address.substr(at + 1) : '') || 'MISSING_DOMAIN';
+
+        result.push([name, null, user || null, domain]);
+    });
+
+    // env-from = "(" 1*address ")", there is no SP between the addresses (RFC 3501 section 9)
+    Object.defineProperty(result, 'adjacentLists', { value: true });
+    return result.length ? result : null;
+}
+
+module.exports.processAddress = processAddress;

package/lib/esearch.js

@@ -0,0 +1,208 @@
+'use strict';
+
+const { badError } = require('./commands/handlers/search');
+const { MAX_NUMBER } = require('./numbers');
+
+/**
+ * ESEARCH response helpers (RFC 4731, RFC 4466 section 2.6.2). Used by the ESEARCH, SEARCHRES, PARTIAL,
+ * CONTEXT=SEARCH and MULTISEARCH plugins, and meant to be reused where SEARCH always answers with ESEARCH (IMAP4rev2, RFC 9051).
+ */
+
+/**
+ * Formats a list of numbers as a compact sequence-set, e.g. [1, 2, 3, 5] becomes "1:3,5"
+ *
+ * @param {Array} numbers List of nz-numbers, in any order
+ * @return {String} sequence-set, empty for an empty list
+ */
+function toSequenceSet(numbers) {
+    return toOrderedSet(Array.from(new Set(numbers)).sort((a, b) => a - b));
+}
+
+/**
+ * Formats a list of numbers as a sequence-set that keeps their order, for SORT results (RFC 5267
+ * section 3.2): only runs of ascending consecutive numbers become ranges, e.g. [5, 3, 4, 2] becomes "5,3:4,2"
+ *
+ * @param {Array} numbers List of nz-numbers in the requested order
+ * @return {String} sequence-set, empty for an empty list
+ */
+function toOrderedSet(numbers) {
+    const ranges = [];
+    numbers.forEach(nr => {
+        const last = ranges[ranges.length - 1];
+        if (last && last[1] + 1 === nr) {
+            last[1] = nr;
+        } else {
+            ranges.push([nr, nr]);
+        }
+    });
+    return ranges.map(range => (range[0] === range[1] ? String(range[0]) : range[0] + ':' + range[1])).join(',');
+}
+
+/**
+ * Parses the argument of the PARTIAL search return option (RFC 5267 section 4.4, RFC 9394 section 4):
+ * partial-range-first = nz-number ":" nz-number, partial-range-last = "-" nz-number ":" "-" nz-number.
+ * "*" is not allowed, and 500:400 is the same as 400:500
+ *
+ * @param {Object} item Parsed argument
+ * @param {Boolean} allowLast If true, the partial-range-last form of RFC 9394 is accepted
+ * @return {Object} `{ range, from, to, fromEnd }`, `range` is the argument as the client sent it
+ */
+function parsePartialRange(item, allowLast) {
+    const value = item && ['ATOM', 'SEQUENCE'].includes(item.type) ? String(item.value) : '';
+    const match = value.match(/^(-?)([1-9][0-9]*):(-?)([1-9][0-9]*)$/);
+    if (!match || match[1] !== match[3] || (match[1] && !allowLast)) {
+        throw badError('PARTIAL expects a range like 1:100' + (allowLast ? ' or -1:-100' : ''));
+    }
+    const first = Number(match[2]);
+    const last = Number(match[4]);
+    if (first > MAX_NUMBER || last > MAX_NUMBER) {
+        throw badError('PARTIAL range is out of bounds');
+    }
+    return { range: value, from: Math.min(first, last), to: Math.max(first, last), fromEnd: !!match[1] };
+}
+
+/**
+ * Picks the results that a PARTIAL range refers to. The first result is 1, and -1 is the last one
+ * (RFC 9394 section 3.1). Results outside the list are left out
+ *
+ * @param {Array} list Results in mailbox order
+ * @param {Object} partial Parsed range, see parsePartialRange
+ * @return {Array} results in the range, in mailbox order
+ */
+function selectPartial(list, partial) {
+    if (!partial.fromEnd) {
+        return list.slice(partial.from - 1, partial.to);
+    }
+    return list.slice(Math.max(list.length - partial.to, 0), Math.max(list.length - partial.from + 1, 0));
+}
+
+/**
+ * Registers the PARTIAL search return option, shared by the PARTIAL and CONTEXT=SEARCH plugins. The
+ * partial-range-last form (-1:-100) is only valid with the PARTIAL capability (RFC 9394 section 4)
+ *
+ * @param {Object} server IMAP server, with the ESEARCH plugin loaded
+ */
+function registerPartialOption(server) {
+    if (server.searchReturnOptions.has('PARTIAL')) {
+        return;
+    }
+    server.searchReturnOptions.set('PARTIAL', { data: true, once: true, parse: item => parsePartialRange(item, !!server.partialRangeLast) });
+    // RFC 5267 section 4.4 and RFC 9394 section 3.1: a command MUST NOT contain more than one PARTIAL or ALL
+    server.searchReturnOptions.set('ALL', Object.assign({}, server.searchReturnOptions.get('ALL'), { once: true }));
+    server.searchReturnChecks.push(options => options.has('PARTIAL') && options.has('ALL') && 'PARTIAL and ALL can not be used together');
+}
+
+/**
+ * Picks the messages that the requested result options return. With COUNT or ALL, or without
+ * MIN, MAX and PARTIAL, these are all matching messages, otherwise the lowest and/or the highest
+ * matching message and the ones in the PARTIAL range. This is the set that the MODSEQ result
+ * option describes (RFC 4731 section 3.2) and that SAVE stores (RFC 5182 section 2.4, RFC 9394
+ * section 3.2)
+ *
+ * @param {Array} list Matching messages, in mailbox order
+ * @param {Map} options Upper case result option names to their arguments, an empty map stands for ALL
+ * @return {Array} returned messages, in mailbox order
+ */
+function selectReturned(list, options) {
+    const partial = options.get('PARTIAL');
+    if (!list.length || options.has('ALL') || options.has('COUNT') || (!partial && !options.has('MIN') && !options.has('MAX'))) {
+        return list;
+    }
+    const returned = new Set(partial ? selectPartial(list, partial) : []);
+    if (options.has('MIN')) {
+        returned.add(list[0]);
+    }
+    if (options.has('MAX')) {
+        returned.add(list[list.length - 1]);
+    }
+    return list.filter(message => returned.has(message));
+}
+
+/**
+ * Builds the search correlator (RFC 4466 section 2.6.2), with the MAILBOX and UIDVALIDITY
+ * correlators of RFC 7377 section 4 if a mailbox is given
+ *
+ * @param {String} tag Tag of the command
+ * @param {Object} [mailbox] Mailbox the response is about
+ * @return {Array} correlator list
+ */
+function buildCorrelator(tag, mailbox) {
+    const correlator = [
+        { type: 'ATOM', value: 'TAG' },
+        { type: 'STRING', value: tag }
+    ];
+    if (mailbox) {
+        correlator.push(
+            { type: 'ATOM', value: 'MAILBOX' },
+            // send() puts in the form of the name that the session uses
+            { type: 'MAILBOX', value: mailbox.path },
+            { type: 'ATOM', value: 'UIDVALIDITY' },
+            mailbox.uidvalidity
+        );
+    }
+    return correlator;
+}
+
+/**
+ * Builds an ESEARCH response (RFC 4466 section 2.6.2) with the RFC 4731 section 3.1 return data
+ * and PARTIAL (RFC 5267 section 4.4, RFC 9394 section 3.1)
+ *
+ * @param {String} tag Tag of the command, for the search correlator
+ * @param {Boolean} isUid If true, the response lists UIDs and has the UID indicator
+ * @param {Object} result Search result, `{ list, numbers }` (see lib/commands/handlers/search.js)
+ * @param {Map} options Upper case result option names to their arguments, an empty map stands for ALL (RFC 4731 section 3.1)
+ * @param {Object} [mailbox] Adds the MAILBOX and UIDVALIDITY correlators of RFC 7377 for this mailbox
+ * @param {Array} [sorted] The matching messages in sort order, for an extended SORT (RFC 5267 section 3.1): MIN and MAX are
+ *        the first and the last sorted message, ALL and PARTIAL list the results in sort order
+ * @return {Object} response for connection.send()
+ */
+function buildEsearchResponse(tag, isUid, result, options, mailbox, sorted) {
+    const values = (sorted || result.list).map(message => (isUid ? message.uid : result.numbers[message.uid]));
+    if (!sorted) {
+        values.sort((a, b) => a - b);
+    }
+    const toSet = sorted ? toOrderedSet : toSequenceSet;
+
+    const attributes = [buildCorrelator(tag, mailbox)];
+    if (isUid) {
+        attributes.push({ type: 'ATOM', value: 'UID' });
+    }
+
+    const add = (name, value) => attributes.push({ type: 'ATOM', value: name }, value);
+    // MIN, MAX and ALL are left out when nothing matched, COUNT is always included (RFC 4731 section 3.1)
+    if (values.length && options.has('MIN')) {
+        add('MIN', values[0]);
+    }
+    if (values.length && options.has('MAX')) {
+        add('MAX', values[values.length - 1]);
+    }
+    if (values.length && (options.has('ALL') || !options.size)) {
+        add('ALL', { type: 'SEQUENCE', value: toSet(values) });
+    }
+    if (options.has('PARTIAL')) {
+        // the requested range, and NIL when no results fall in it (RFC 9394 section 3.1)
+        const partial = options.get('PARTIAL');
+        const selected = selectPartial(values, partial);
+        add('PARTIAL', [{ type: 'ATOM', value: partial.range }, selected.length ? { type: 'SEQUENCE', value: toSet(selected) } : null]);
+    }
+    if (options.has('COUNT')) {
+        add('COUNT', values.length);
+    }
+
+    return {
+        tag: '*',
+        command: 'ESEARCH',
+        attributes
+    };
+}
+
+module.exports = {
+    toSequenceSet,
+    toOrderedSet,
+    selectReturned,
+    selectPartial,
+    parsePartialRange,
+    registerPartialOption,
+    buildCorrelator,
+    buildEsearchResponse
+};