{"id":14743,"library":"node-red-contrib-match","title":"Node-RED Match Node","description":"node-red-contrib-match is a Node-RED package providing a dedicated node for advanced message filtering within a flow. It enables users to define multiple rules to check specific properties within an incoming message, or global/flow contexts, against static values, other properties, previous values, ranges, regex, types, and null/boolean states. Messages satisfying all defined rules are routed to the first output, while those failing any rule are sent to the second output. The current stable version is 1.0.2. Release cadence appears to be infrequent, primarily for bug fixes based on recent releases. Its key differentiator is the comprehensive set of comparison operators and the ability to probe deeply into objects and arrays, offering more granular control than standard switch nodes.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/DeanCording/node-red-contrib-match","tags":["javascript","node-red","match","filter"],"install":[{"cmd":"npm install node-red-contrib-match","lang":"bash","label":"npm"},{"cmd":"yarn add node-red-contrib-match","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-red-contrib-match","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as it is a Node-RED contribution package, required for runtime environment and editor integration.","package":"node-red","optional":false}],"imports":[{"note":"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.","wrong":"import { NodeRedMatchNode } from 'node-red-contrib-match';","symbol":"NodeRedMatchNode","correct":"// No direct JavaScript import; install via npm for Node-RED."},{"note":"Node-RED nodes are configured visually in the editor; there's no programmatic configuration API exported by this package for end-users.","wrong":"const config = new MatchConfig({ rules: [...] });","symbol":"MatchConfig","correct":"// Configure the 'Match' node directly in the Node-RED editor's properties panel."},{"note":"The core matching functionality is internal to the Node-RED node and not exposed as a callable JavaScript function for external use.","wrong":"import { matchMessage } from 'node-red-contrib-match'; matchMessage(msg, rules);","symbol":"MatchFunction","correct":"// The matching logic is encapsulated within the Node-RED 'Match' node."}],"quickstart":{"code":"// To use node-red-contrib-match, first install it into your Node-RED instance:\n// npm install node-red-contrib-match\n\n// After installation, restart Node-RED and locate the \"Match\" node in the palette.\n// Drag it onto your flow, connect an input, and configure its rules via the\n// editor's properties panel. For example, configure it to match `msg.payload === \"hello\"`.\n// Connect the first output (match) to a debug node and the second output (no match) to another debug node.\n// Inject a message with `msg.payload` set to \"hello\" to test the match.\n\n// There is no direct programmatic JavaScript usage for this Node-RED node in application code.\nconsole.log(\"Node-RED node 'node-red-contrib-match' is used graphically in the Node-RED editor.\");","lang":"javascript","description":"Demonstrates how to install the Node-RED 'Match' node and provides conceptual guidance on its graphical use within the Node-RED editor."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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'.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The package `node-red-contrib-match` was not correctly installed or Node-RED was not restarted after installation.","error":"Node 'match' not found in palette."},{"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.","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.","error":"Unexpected 'no match' (second output triggered) despite seemingly correct input."},{"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.","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.","error":"Error: Invalid property expression: '...' in 'Match' node."},{"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.","cause":"Incorrect regular expression syntax, missing flags, or the input property value is not a string.","error":"Regex match failing or behaving unexpectedly."}],"ecosystem":"npm"}