Node-RED Match Node

Common errors

• Node 'match' not found in palette.

  cause The package `node-red-contrib-match` was not correctly installed or Node-RED was not restarted after installation.
  fix Run `npm install node-red-contrib-match` in your Node-RED user directory (usually ~/.node-red), then restart your Node-RED instance. Verify installation in the 'Manage palette' menu.

• Unexpected 'no match' (second output triggered) despite seemingly correct input.

  cause Often due to a subtle mismatch in data type (e.g., string vs. number), an incorrect property path, or a context variable not being set as expected.
  fix Use a `debug` node set to 'Complete msg object' immediately before the `match` node to thoroughly inspect the incoming message payload and structure. Check context values in the sidebar. Adjust rule configuration to match actual data types and paths.

• Error: Invalid property expression: '...' in 'Match' node.

  cause The property path specified (e.g., `msg.payload.data[0].value`) is malformed or attempts to access a non-existent part of the message structure.
  fix Correct the property expression syntax. Use the '...' button next to the property field in the editor to visually browse available message properties and construct the path correctly. Ensure arrays are accessed with numeric indices and objects with keys.

• Regex match failing or behaving unexpectedly.

  cause Incorrect regular expression syntax, missing flags, or the input property value is not a string.
  fix Test your regular expression with a dedicated regex tester. Ensure the input property being matched is indeed a string. Add appropriate flags (e.g., `i` for case-insensitivity) if needed in the regex configuration.

Warnings

• gotcha Carefully define property paths and comparison types. Mismatched types (e.g., comparing a string '10' to a number 10) can lead to unexpected 'no match' results if strict equality is implied or configured. Always test rules thoroughly.
  Fix: Use the Node-RED debug panel to inspect incoming message structures (`msg`), and ensure your rule configurations accurately reflect the expected data types and paths. Use type-specific comparisons where available.
• gotcha When matching against 'context' (flow or global), ensure the context variable exists and is populated before the message reaches the Match node. An undefined context variable will likely result in a 'no match'.
  Fix: Initialize context variables upstream in your flow using `change` nodes or function nodes. Use the context sidebar in the Node-RED editor to verify context values during debugging.
• gotcha Performance can be impacted by a large number of complex rules or extremely large messages, especially if rules involve regular expressions or deep object probing. This is generally true for any extensive processing node.
  Fix: Optimize your flow by pre-filtering messages if possible, or breaking down complex matching into multiple simpler Match nodes. Profile your Node-RED instance if performance bottlenecks are suspected.
• gotcha The node checks if *all* rules are met for the first output. If you intend to match based on *any* single rule, you will need to cascade multiple Match nodes or use a different logic pattern.
  Fix: For 'OR' logic, use multiple Match nodes in parallel, each with a single rule, and then merge their outputs with a `join` node. For 'AND' logic, use a single Match node with multiple rules, or cascade them sequentially.

Install

• npm install node-red-contrib-match npm
• yarn add node-red-contrib-match yarn
• pnpm add node-red-contrib-match pnpm

Imports

• NodeRedMatchNode
  wrong:

  import { NodeRedMatchNode } from 'node-red-contrib-match';

  correct:

  // No direct JavaScript import; install via npm for Node-RED.

  This package provides a Node-RED node for use within the Node-RED editor. It does not export JavaScript symbols for direct programmatic import into user applications.
• MatchConfig
  wrong:

  const config = new MatchConfig({ rules: [...] });

  correct:

  // Configure the 'Match' node directly in the Node-RED editor's properties panel.

  Node-RED nodes are configured visually in the editor; there's no programmatic configuration API exported by this package for end-users.
• MatchFunction
  wrong:

  import { matchMessage } from 'node-red-contrib-match'; matchMessage(msg, rules);

  correct:

  // The matching logic is encapsulated within the Node-RED 'Match' node.

  The core matching functionality is internal to the Node-RED node and not exposed as a callable JavaScript function for external use.

Quickstart

Demonstrates how to install the Node-RED 'Match' node and provides conceptual guidance on its graphical use within the Node-RED editor.

// To use node-red-contrib-match, first install it into your Node-RED instance:
// npm install node-red-contrib-match

// After installation, restart Node-RED and locate the "Match" node in the palette.
// Drag it onto your flow, connect an input, and configure its rules via the
// editor's properties panel. For example, configure it to match `msg.payload === "hello"`.
// Connect the first output (match) to a debug node and the second output (no match) to another debug node.
// Inject a message with `msg.payload` set to "hello" to test the match.

// There is no direct programmatic JavaScript usage for this Node-RED node in application code.
console.log("Node-RED node 'node-red-contrib-match' is used graphically in the Node-RED editor.");