join-wait.html

<script type="text/x-red" data-template-name="join-wait">
    <div class="form-row">
        <label for="node-input-name" title="Display name for this node on the canvas."><i class="fa fa-tag"></i> Name</label>
        <input type="text" id="node-input-name" placeholder="Name">
    </div>

    <div class="form-row">
        <label for="node-input-pathTopic" title="Message property whose value identifies the incoming path."><i class="fa fa-bookmark-o"></i> Path field</label>
        <input type="text" id="node-input-pathTopic" placeholder="topic">
        <input type="hidden" id="node-input-pathTopicType">
    </div>
    <div class="form-tips" style="margin-bottom:12px">
        The message property whose value identifies an incoming path —
        e.g. <code>msg.topic</code> or <code>msg.paths</code>. May be a string
        or an object with multiple keys.
    </div>

    <div class="form-row" style="margin-bottom:4px">
        <label title="Path names to wait for; repeat an entry to require it n times."><i class="fa fa-code-fork"></i> Wait paths</label>
    </div>
    <div class="form-row node-input-paths-container-row">
        <ol id="node-input-paths-container"></ol>
    </div>
    <div class="form-tips" style="margin-bottom:6px">
        The set of paths whose arrival within the time window emits a
        merged success output. Press <kbd>Enter</kbd> in a row to add the
        next one. Repeat an entry to require n-of-the-same.
    </div>
    <div class="form-tips" id="join-wait-output-preview" style="margin-bottom:12px; font-family:var(--red-ui-monospace-font, monospace)"></div>

    <div class="form-row">
        <label for="node-input-timeout" title="How long all wait paths have to arrive before the queue is expired."><i class="fa fa-clock-o"></i> Timeout</label>
        <input type="text" id="node-input-timeout" style="text-align:end; width:90px" placeholder="15">
        <select id="node-input-timeoutUnits" style="width:160px; margin-left:5px">
            <option value="1">Milliseconds</option>
            <option value="1000">Seconds</option>
            <option value="60000">Minutes</option>
            <option value="3600000">Hours</option>
            <option value="86400000">Days</option>
        </select>
    </div>
    <div class="form-tips" id="join-wait-timeout-hint" style="margin-bottom:12px; color:#b07b00; display:none">
        <i class="fa fa-exclamation-triangle"></i> <span></span>
    </div>

    <div class="form-row">
        <label for="node-input-exactOrder" title="Any order (default) or strict sequence."><i class="fa fa-sort"></i> Match order</label>
        <select id="node-input-exactOrder" style="width:70%">
            <option value="false">Any order</option>
            <option value="true">Exact order</option>
        </select>
    </div>

    <div class="form-row">
        <label for="node-input-correlationTopic" title="Optional. Property whose value groups related messages (e.g. msg._msgid)."><i class="fa fa-bookmark-o"></i> Group by</label>
        <input type="text" id="node-input-correlationTopic" placeholder="(none)">
        <input type="hidden" id="node-input-correlationTopicType">
    </div>
    <div class="form-tips" style="margin-bottom:12px">
        Optional. Group messages so unrelated streams don't merge —
        e.g. <code>msg._msgid</code> when waiting on a single split flow.
    </div>

    <div class="form-row" style="margin-bottom:14px">
        <label></label>
        <button type="button" id="join-wait-open-examples" class="red-ui-button">
            <i class="fa fa-folder-open-o"></i> Open example flows
        </button>
    </div>

    <details class="join-wait-advanced" style="margin-top:14px">
    <summary style="cursor:pointer; font-weight:bold; padding:6px 0; color:var(--red-ui-header-text-color, inherit)">Advanced</summary>

    <div class="form-row" style="margin-top:10px; margin-bottom:4px">
        <label title="Paths that immediately drain the queue to the expired output."><i class="fa fa-times-circle-o"></i> Reset paths</label>
    </div>
    <div class="form-row node-input-pathsToExpire-container-row">
        <ol id="node-input-pathsToExpire-container"></ol>
    </div>
    <div class="form-tips" style="margin-bottom:12px">
        Optional. Any of these paths immediately drains the queue (with the
        drained items going to the second output). Each entry must be unique.
    </div>

    <div class="form-row">
        <label for="node-input-firstMsg" title="Use the first or last message in the matched window as the base of the merged output."><i class="fa fa-comments-o"></i> Output base</label>
        <select id="node-input-firstMsg" style="width:70%">
            <option value="true">First received message</option>
            <option value="false">Last received message</option>
        </select>
    </div>

    <div class="form-row">
        <label for="node-input-mapPayload" title="Keep the original Path-field values, or overwrite each with that message's payload."><i class="fa fa-arrow-right"></i> Merge values</label>
        <select id="node-input-mapPayload" style="width:70%">
            <option value="false">Original Path field values</option>
            <option value="true">Each msg.payload</option>
        </select>
    </div>

    <div class="form-row" title="Treat each entry in Wait paths and Reset paths as a regular expression.">
        <label for="node-input-useRegex"></label>
        <input type="checkbox" id="node-input-useRegex" style="display:inline-block; width:22px; vertical-align:baseline; margin-right:6px;">
        <label for="node-input-useRegex" style="width:auto">Treat path entries as regular expressions</label>
    </div>

    <div class="form-row" title="Log a warning when a message arrives with a path that isn't in either list.">
        <label for="node-input-warnUnmatched"></label>
        <input type="checkbox" id="node-input-warnUnmatched" style="display:inline-block; width:22px; vertical-align:baseline; margin-right:6px;">
        <label for="node-input-warnUnmatched" style="width:auto">Log a warning for unmatched paths</label>
    </div>

    <div class="form-row" title="Disable the msg.complete short-circuit.">
        <label for="node-input-disableComplete"></label>
        <input type="checkbox" id="node-input-disableComplete" style="display:inline-block; width:22px; vertical-align:baseline; margin-right:6px;">
        <label for="node-input-disableComplete" style="width:auto">Ignore <code>msg.complete</code></label>
    </div>

    <div class="form-row" title="Save the queue to the context store on close so it survives redeploys (and full restarts when a persistent store is configured).">
        <label for="node-input-persistOnRestart"></label>
        <input type="checkbox" id="node-input-persistOnRestart" style="display:inline-block; width:22px; vertical-align:baseline; margin-right:6px;">
        <label for="node-input-persistOnRestart" style="width:auto">Preserve queue across deploys / restarts</label>
    </div>

    <div class="form-row" id="join-wait-persist-store-row">
        <label for="node-input-persistStore" title="Override the context store used to persist the queue."><i class="fa fa-database"></i> Persist store</label>
        <select id="node-input-persistStore" style="width:70%">
            <option value="">(default context store)</option>
        </select>
    </div>
    <div class="form-tips" id="join-wait-persist-store-tip" style="margin-bottom:12px">
        Override the context store this node uses. Leave on default — set
        the default to a persistent store (e.g. <code>localfilesystem</code>)
        in <code>settings.js</code> and every join-wait node automatically
        survives full restarts.
    </div>
    </details>
</script>

<script type="text/javascript">
    (function () {
        // Every DOM hook the editor uses, in one place.
        const SEL = {
            pathField: '#node-input-pathTopic',
            pathFieldType: '#node-input-pathTopicType',
            correlator: '#node-input-correlationTopic',
            correlatorType: '#node-input-correlationTopicType',
            timeout: '#node-input-timeout',
            timeoutUnits: '#node-input-timeoutUnits',
            useRegex: '#node-input-useRegex',
            persistOnRestart: '#node-input-persistOnRestart',
            persistStore: '#node-input-persistStore',
            outputPreview: '#join-wait-output-preview',
            timeoutHint: '#join-wait-timeout-hint',
            examplesButton: '#join-wait-open-examples',
            persistStoreRow: '#join-wait-persist-store-row',
            persistStoreTip: '#join-wait-persist-store-tip',
            dialogForm: '#dialog-form',
            advancedDetails: '#dialog-form details',
        };
        // editableList wrapper IDs (no leading '#'); consumers either
        // pass them to readEditableList or interpolate `#` themselves.
        const LIST_ID = {
            paths: 'node-input-paths-container',
            expire: 'node-input-pathsToExpire-container',
        };
        const listInputs = (id) => $('#' + id + ' input[type=text]');
        // Path-field name + typedInput type, read together to avoid drift.
        const readPathField = () => ({
            name: $(SEL.pathField).val() || 'topic',
            type: $(SEL.pathFieldType).val() || 'msg',
        });

        const arrayValidator = (allowEmpty, requireUnique) => (v) => {
            // Accept legacy JSON-string format too, for back-compat with old flows.
            let arr = v;
            if (typeof v === 'string') {
                if (v === '') return allowEmpty;
                try {
                    arr = JSON.parse(v);
                } catch (err) {
                    return false;
                }
            }
            if (!Array.isArray(arr)) return false;
            if (arr.length === 0) return allowEmpty;
            if (!arr.every((s) => typeof s === 'string' && s.length > 0)) return false;
            if (requireUnique) {
                const seen = Object.create(null);
                for (let i = 0; i < arr.length; i++) {
                    if (seen[arr[i]]) return false;
                    seen[arr[i]] = true;
                }
            }
            return true;
        };

        // Note: Node-RED calls validate functions with `this` bound to the
        // node config, so this stays a function expression (arrow would
        // not bind `this`).
        function correlationValidator(v) {
            // Empty / undefined / non-jsonata: nothing to validate here.
            if (this.correlationTopicType !== 'jsonata' || !v) return true;
            // jsonata is exposed as a global by the Node-RED editor.
            if (typeof jsonata !== 'function') return true;
            try {
                jsonata(v);
                return true;
            } catch (err) {
                return false;
            }
        }

        const isValidRegex = (s) => {
            try {
                new RegExp(s);
                return true;
            } catch (err) {
                return false;
            }
        };

        const setRowValid = (input, ok, message) => {
            input.css('border-color', ok ? '' : '#d9534f');
            input.attr('title', ok ? '' : message || '');
        };

        // Single-row validation: empty / invalid regex. List-level
        // checks (uniqueness, cross-list overlap) live in validateAllRows
        // because they need both lists' current values in scope.
        const validateRow = (input, ownValues, otherValues, opts) => {
            const requireUnique = opts && opts.requireUnique;
            const otherListLabel = (opts && opts.otherListLabel) || '';
            const value = String(input.val() || '');
            if (value === '') {
                setRowValid(input, false, 'path name cannot be empty');
                return false;
            }
            if ($(SEL.useRegex).is(':checked') && !isValidRegex(value)) {
                setRowValid(input, false, 'invalid regular expression');
                return false;
            }
            if (requireUnique && ownValues && ownValues.filter((x) => x === value).length > 1) {
                setRowValid(input, false, 'duplicate entry — must be unique');
                return false;
            }
            if (otherValues && otherValues.indexOf(value) !== -1) {
                setRowValid(
                    input,
                    false,
                    '"' + value + '" is also in ' + otherListLabel + " — paths shouldn't overlap",
                );
                return false;
            }
            setRowValid(input, true);
            return true;
        };

        // Re-validate every row across both lists so duplicate and
        // cross-list overlap warnings stay in sync.
        const validateAllRows = () => {
            const $paths = listInputs(LIST_ID.paths);
            const $expire = listInputs(LIST_ID.expire);
            // jQuery .map / .each callbacks rely on `this`, so they stay
            // as function expressions.
            const pathValues = $paths
                .map(function () {
                    return String($(this).val() || '');
                })
                .get();
            const expireValues = $expire
                .map(function () {
                    return String($(this).val() || '');
                })
                .get();
            $paths.each(function () {
                validateRow($(this), pathValues, expireValues, {
                    requireUnique: false,
                    otherListLabel: 'Reset paths',
                });
            });
            $expire.each(function () {
                validateRow($(this), expireValues, pathValues, {
                    requireUnique: true,
                    otherListLabel: 'Wait paths',
                });
            });
        };

        const initEditableList = (containerId, items, opts) => {
            const $container = $('#' + containerId);
            const placeholder = (opts && opts.placeholder) || 'e.g. sensor_1';
            // Numeric height → list scrolls internally past the limit.
            // Recomputed in oneditresize to fill the tray.
            $container.editableList({
                addItem: (row, index, data) => {
                    const value = (data && data.value) || '';
                    row.css({ overflow: 'hidden', whiteSpace: 'nowrap' });
                    const input = $('<input/>', {
                        type: 'text',
                        placeholder: placeholder,
                        style: 'width:100%',
                    }).val(value);
                    input.on('input change blur', () => {
                        validateAllRows();
                        if (opts && opts.onChange) opts.onChange();
                    });
                    // Pressing Enter in a row adds the next one.
                    input.on('keydown', (e) => {
                        if (e.key === 'Enter' || e.keyCode === 13) {
                            e.preventDefault();
                            $container.editableList('addItem', { value: '' });
                            // Focus the newly-added row.
                            setTimeout(() => {
                                $container.editableList('items').last().find('input').trigger('focus');
                            }, 0);
                        }
                    });
                    // Bulk-paste newline-separated text into multiple
                    // rows. Single-line pastes fall through to default.
                    input.on('paste', (e) => {
                        const clip = (e.originalEvent || e).clipboardData;
                        if (!clip) return;
                        const text = clip.getData('text');
                        if (!text || !/[\r\n]/.test(text)) return;
                        const lines = text
                            .split(/\r?\n/)
                            .map((s) => s.trim())
                            .filter((s) => s.length > 0);
                        if (lines.length === 0) return;
                        e.preventDefault();
                        input.val(lines[0]);
                        for (let i = 1; i < lines.length; i++) {
                            $container.editableList('addItem', { value: lines[i] });
                        }
                        validateAllRows();
                        if (opts && opts.onChange) opts.onChange();
                    });
                    row.append(input);
                    validateAllRows();
                    if (opts && opts.onChange) opts.onChange();
                },
                removeItem: () => {
                    validateAllRows();
                    if (opts && opts.onChange) opts.onChange();
                },
                removable: true,
                sortable: true,
                height: (opts && opts.height) || 200,
            });
            (items || []).forEach((v) => {
                $container.editableList('addItem', { value: v });
            });
        };

        // Re-validate every editableList row when the regex toggle flips.
        const rebindRegexValidation = () => {
            $(SEL.useRegex).on('change', validateAllRows);
        };

        const readEditableList = (containerId) => {
            const values = [];
            $('#' + containerId)
                .editableList('items')
                .each(function () {
                    // jQuery `each` binds `this` to the row element, so
                    // this callback stays a function expression.
                    const v = $(this).find('input').val();
                    if (v != null && v !== '') values.push(v);
                });
            return values;
        };

        // Coerce legacy string-array values into a plain array for editing.
        const toArray = (v) => {
            if (Array.isArray(v)) return v;
            if (typeof v === 'string' && v !== '') {
                try {
                    const parsed = JSON.parse(v);
                    return Array.isArray(parsed) ? parsed : [];
                } catch (err) {
                    return [];
                }
            }
            return [];
        };

        // Preview of the merged success output. Repeated entries
        // surface as `(×n)` so the n-of-the-same semantic is visible.
        const updateOutputPreview = () => {
            const paths = readEditableList(LIST_ID.paths);
            const counts = Object.create(null);
            const order = [];
            paths.forEach((p) => {
                if (counts[p] === undefined) order.push(p);
                counts[p] = (counts[p] || 0) + 1;
            });
            const field = readPathField();
            const $tip = $(SEL.outputPreview);
            if (order.length === 0) {
                $tip.text('');
                return;
            }
            const entries = order.slice(0, 4).map((p) => (counts[p] > 1 ? p + ' (×' + counts[p] + '): …' : p + ': …'));
            if (order.length > 4) entries.push('…');
            $tip.text('→ ' + field.type + '.' + field.name + ' = { ' + entries.join(', ') + ' }');
        };

        // Warn when the resolved timeout is impractically short (the README
        // recommends padding ~5–10 ms for evaluation overhead).
        const updateTimeoutHint = () => {
            const t = Number($(SEL.timeout).val()) || 0;
            const u = Number($(SEL.timeoutUnits).val()) || 1;
            const ms = t * u;
            const $hint = $(SEL.timeoutHint);
            if (ms > 0 && ms < 50) {
                $hint.find('span').text('Very short — pad ~10 ms to leave room for evaluation overhead.');
                $hint.show();
            } else {
                $hint.hide();
            }
        };

        // Populate the Persist store <select> from /join-wait/stores.
        // apiRootUrl prefixes the call so it resolves under custom
        // httpAdminRoot / reverse proxies.
        const populatePersistStores = (currentValue) => {
            const $sel = $(SEL.persistStore);
            const base = (RED.settings && RED.settings.apiRootUrl) || '';
            $.getJSON(base + 'join-wait/stores')
                .done((stores) => {
                    (Array.isArray(stores) ? stores : []).forEach((s) => {
                        if (s.name === 'default') return; // already represented as the blank option
                        const label = s.module ? s.name + ' (' + s.module + ')' : s.name;
                        $('<option/>').val(s.name).text(label).appendTo($sel);
                    });
                    // If the saved value isn't in the list, append it so we
                    // don't silently drop a user-provided override.
                    if (currentValue && !$sel.find('option[value="' + currentValue + '"]').length) {
                        $('<option/>')
                            .val(currentValue)
                            .text(currentValue + ' (not configured)')
                            .appendTo($sel);
                    }
                    $sel.val(currentValue || '');
                })
                .fail(() => {
                    // Admin route not reachable. Preserve the saved
                    // value as an explicit option so the dropdown doesn't
                    // silently overwrite persistStore with '' on save.
                    if (currentValue) {
                        $('<option/>')
                            .val(currentValue)
                            .text(currentValue + ' (stores list unavailable)')
                            .appendTo($sel);
                        $sel.val(currentValue);
                    }
                });
        };

        // Last `size` handed to oneditresize. Cached so the <details>
        // toggle handler can re-run the resize math without waiting for
        // the next tray drag.
        let lastTraySize = null;

        // Stretch the Wait paths editableList to fill the tray —
        // pattern from core switch/change/httprequest.
        const resizePathsList = () => {
            const $form = $(SEL.dialogForm);
            if (!$form.length || !lastTraySize || !lastTraySize.height) return;
            let height = lastTraySize.height;
            // jQuery `.each` binds `this` to the row element, so this
            // callback stays a function expression.
            $form.children(':not(.node-input-paths-container-row)').each(function () {
                const $r = $(this);
                if ($r.is(':visible')) height -= $r.outerHeight(true) || 0;
            });
            height -= 12; // breathing room for margins/padding the loop misses
            if (height < 140) height = 140;
            $('#' + LIST_ID.paths).editableList('height', height);
        };

        // clipboard.js disables import actions while an edit tray is
        // open, and RED.tray.close(cb) fires cb before the editor:close
        // event — so we listen for editor:close ourselves and defer one
        // tick past the synchronous listener chain that clears the flag.
        // The pending guard suppresses a fast double-click registering
        // two listeners.
        let pendingExamplesOpen = false;
        const openExamplesDialog = () => {
            if (pendingExamplesOpen) return;
            pendingExamplesOpen = true;
            const invoke = () => {
                setTimeout(() => {
                    pendingExamplesOpen = false;
                    if (!RED.actions || typeof RED.actions.invoke !== 'function') return;
                    // core:show-examples-import-dialog was added in Node-RED 3.1.
                    const actions = RED.actions.list && RED.actions.list();
                    const hasExamples =
                        Array.isArray(actions) &&
                        actions.some((a) => (a && a.id) === 'core:show-examples-import-dialog');
                    RED.actions.invoke(hasExamples ? 'core:show-examples-import-dialog' : 'core:show-import-dialog');
                }, 0);
            };
            if (RED.events && typeof RED.events.once === 'function') {
                RED.events.once('editor:close', invoke);
            } else if (RED.events && typeof RED.events.on === 'function') {
                const handler = () => {
                    if (RED.events.off) RED.events.off('editor:close', handler);
                    invoke();
                };
                RED.events.on('editor:close', handler);
            }
            if (RED.tray && typeof RED.tray.close === 'function') {
                RED.tray.close();
            } else {
                invoke();
            }
        };

        RED.nodes.registerType('join-wait', {
            category: 'function',
            color: '#8baac7',
            defaults: {
                name: { value: '' },
                paths: { value: [], validate: arrayValidator(false, false) },
                pathsToExpire: { value: [], validate: arrayValidator(true, true) },
                useRegex: { value: false },
                warnUnmatched: { value: true },
                pathTopic: { value: 'topic', required: true },
                pathTopicType: { value: 'msg' },
                correlationTopic: { value: '', validate: correlationValidator },
                correlationTopicType: { value: 'undefined' },
                timeout: {
                    value: 15000,
                    required: true,
                    validate: function (v) {
                        return (Number(v) || 0) > 0;
                    },
                },
                timeoutUnits: { value: 1, validate: RED.validators.number() },
                exactOrder: { value: 'false', required: true },
                firstMsg: { value: 'true', required: true },
                mapPayload: { value: 'false', required: true },
                disableComplete: { value: false },
                // On by default → survives redeploys via the in-memory
                // context store. Restart-persistence still needs Persist
                // store pointing at a persistent context.
                persistOnRestart: { value: true },
                persistStore: { value: '' },
            },
            inputs: 1,
            outputs: 2,
            outputLabels: ['success', 'expired'],
            icon: 'node-red-contrib-join-wait.png',
            label: function () {
                return this.name || 'join-wait';
            },
            labelStyle: function () {
                return this.name ? 'node_label_italic' : '';
            },
            oneditprepare: function () {
                $(SEL.pathField).typedInput({
                    default: this.pathTopicType || 'msg',
                    typeField: $(SEL.pathFieldType),
                    types: ['msg', 'flow', 'global'],
                });
                $(SEL.correlator).typedInput({
                    default: this.correlationTopicType || 'undefined',
                    typeField: $(SEL.correlatorType),
                    types: [
                        { value: 'undefined', label: RED._('common.type.undefined'), hasValue: false },
                        'msg',
                        'flow',
                        'global',
                        'jsonata',
                    ],
                });
                // Decimals OK (runtime multiplies by the unit factor).
                $(SEL.timeout).spinner({ min: 0.001, step: 1, numberFormat: 'n' });

                initEditableList(LIST_ID.paths, toArray(this.paths), {
                    placeholder: 'e.g. sensor_1',
                    onChange: updateOutputPreview,
                    height: 200,
                });
                initEditableList(LIST_ID.expire, toArray(this.pathsToExpire), {
                    placeholder: 'e.g. abort',
                    height: 140,
                });
                rebindRegexValidation();

                $(SEL.pathField).on('change input', updateOutputPreview);
                updateOutputPreview();

                $(SEL.timeout + ', ' + SEL.timeoutUnits).on('change input', updateTimeoutHint);
                updateTimeoutHint();

                populatePersistStores(this.persistStore);

                // Persist store row is meaningless without Preserve queue.
                const $persistRow = $(SEL.persistStoreRow + ', ' + SEL.persistStoreTip);
                const syncPersistStoreVisibility = () => {
                    $persistRow.toggle($(SEL.persistOnRestart).is(':checked'));
                    resizePathsList();
                };
                $(SEL.persistOnRestart).on('change', syncPersistStoreVisibility);
                syncPersistStoreVisibility();

                $(SEL.examplesButton).on('click', openExamplesDialog);

                // Reflow the list when Advanced toggles (oneditresize
                // only fires on tray drag).
                $(SEL.advancedDetails).on('toggle', resizePathsList);
            },
            oneditsave: function () {
                this.paths = readEditableList(LIST_ID.paths);
                this.pathsToExpire = readEditableList(LIST_ID.expire);
            },
            oneditresize: function (size) {
                lastTraySize = size;
                resizePathsList();
            },
        });
    })();
</script>

<script type="text/x-red" data-help-name="join-wait">
    <p>Waits for a set of related messages to arrive on different paths within
    a time window, then emits a single merged message. Optionally treats some
    paths as resets that drain the queue.</p>

    <h3>Inputs</h3>
    <dl class="message-properties">
        <dt>payload<span class="property-type">any</span></dt>
        <dd>Forwarded as-is (and optionally used to merge values — see "Merge values").</dd>

        <dt class="optional">path field<span class="property-type">string | object</span></dt>
        <dd>The message property named in the <b>Path field</b> setting (default <code>msg.topic</code>).
        Either a single path name (<code>"path_1"</code>) or an object whose
        keys are path names (<code>{path_1: ..., path_2: ...}</code>) when one
        message represents multiple paths.</dd>

        <dt class="optional">complete<span class="property-type">any</span></dt>
        <dd>If present, the queue is evaluated for completion and then drained.
        Disable via "Ignore <code>msg.complete</code>".</dd>

        <dt class="optional">reset<span class="property-type">boolean</span></dt>
        <dd>If <code>true</code>, the queue for the current group is silently
        cleared (no output emitted). The other message fields are ignored.</dd>

        <dt class="optional">pathsToWait<span class="property-type">string[]</span></dt>
        <dd>Per-message override of "Wait paths" (one-shot — does not change
        the node's stored config).</dd>

        <dt class="optional">pathsToExpire<span class="property-type">string[]</span></dt>
        <dd>Per-message override of "Reset paths" (one-shot).</dd>

        <dt class="optional">useRegex<span class="property-type">boolean</span></dt>
        <dd>Per-message override of the regex setting (one-shot).</dd>
    </dl>

    <h3>Outputs</h3>
    <ol class="node-ports">
        <li>Success — emitted when all "Wait paths" arrive within the timeout.
        The merged data is attached on the <b>Path field</b> property.</li>
        <li>Expired — drained messages from queues that timed out, hit a reset
        path, or that <code>msg.complete</code> evaluated.</li>
    </ol>

    <h3>Details</h3>

    <p><b>Path field</b> — the property whose value identifies the path. Can
    be set as a string (one path) or an object (multiple paths from one
    message). Defaults to <code>msg.topic</code>.</p>

    <p><b>Wait paths</b> — list of paths to wait for. Repeating an entry means
    "this path must arrive that many times". Configurable at runtime via
    <code>msg.pathsToWait</code>.</p>

    <p><b>Reset paths</b> — paths that immediately drain the queue. Each must
    be unique. Configurable at runtime via <code>msg.pathsToExpire</code>.</p>

    <p><b>Group by</b> — optional correlation property. When set, only
    messages with the same value are joined together. Useful with
    <code>msg._msgid</code> when waiting on a single split flow. Supports
    <code>msg</code>, <code>flow</code>, <code>global</code>, and
    <code>jsonata</code> property types.</p>

    <p><b>Match order</b> — "Any order" (default) or "Exact order". In exact
    mode, unexpected paths between expected ones are tolerated. To determine
    the matching window, the timestamp of the <i>latest</i> required path is
    used. For example, with wait paths <code>[path_1, path_2, path_3]</code>
    and arrivals <code>[path_1, path_2, path_1*, path_2*, path_3*]</code>,
    the starred entries form the match.</p>

    <p><b>Output base</b> — whether to use the first or last received message
    as the base for the merged output.</p>

    <p><b>Merge values</b> — keep the original values from the path field, or
    overwrite each with that message's <code>msg.payload</code>.</p>

    <h3>Notes</h3>

    <ul>
        <li>If <b>Use regex</b> is on, each entry in Wait/Reset paths is
        compiled as a regular expression. <code>^</code>/<code>$</code>
        anchors are not implicit — <code>path\d+</code> matches
        <code>my_path1_test</code>.</li>
        <li>For repeated paths in any-order mode with regex, paths are counted
        greedily left-to-right. <code>["path_[12]", "path_2"]</code> never
        completes because <code>path_2</code> arrivals get attributed to the
        first regex.</li>
        <li>When the same path arrives multiple times, only the latest value
        is kept in the merged output.</li>
        <li>Pad <b>Timeout</b> with a small overhead (~5–10&nbsp;ms) for
        evaluation time when working with very short windows.</li>
        <li>When <b>Preserve queue</b> is on, the queue is written to the
        node's context on close (and reloaded on the next start). With
        the default in-memory store this only survives a redeploy; for
        full restart persistence, point <b>Persist store</b> at a
        store backed by <code>localfilesystem</code> (or any persistent
        module) configured under <code>contextStorage</code> in
        <code>settings.js</code>.</li>
    </ul>
</script>