https://github.com/rangermauve/mqtt-pattern
Fast library for matching MQTT patterns with named wildcards
https://github.com/rangermauve/mqtt-pattern
Last synced: about 1 month ago
JSON representation
Fast library for matching MQTT patterns with named wildcards
- Host: GitHub
- URL: https://github.com/rangermauve/mqtt-pattern
- Owner: RangerMauve
- License: mit
- Created: 2017-04-21T15:59:33.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-05-02T21:08:29.000Z (about 2 years ago)
- Last Synced: 2025-04-15T06:04:31.727Z (about 1 month ago)
- Language: JavaScript
- Size: 23.4 KB
- Stars: 30
- Watchers: 6
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mqtt-pattern
Fast library for matching MQTT patterns with named wildcards to extract data from topics
Successor to [mqtt-regex](./mqtt-regex)
## Example:
``` javascript
var MQTTPattern = require("mqtt-pattern");
// Wildcards in patterns don't need names
var pattern = "device/+id/+/#data";
var topic = "device/fitbit/heartrate/rate/bpm";
var params = MQTTPattern.exec(pattern, topic);
// params will be
{
id: "fitbit",
data: ["rate", "bmp"]
}
var filled = MQTTPattern.fill(pattern, params);
// filled will be
"device/fitbit/undefined/rate/bmp"
MQTTPattern.clean("hello/+param1/world/#param2");
// hello/+/world/#
```
## Installing
With NPM:
```bash
npm install --save mqtt-pattern
```
## API
### `exec(pattern : String, topic : String) : Object | null`
Validates that `topic` fits the `pattern` and parses out any parameters.
If the topic doesn't match, it returns `null`
### `matches(pattern : String, topic : String) : Boolean`
Validates whether `topic` fits the `pattern`. Ignores parameters.
### `extract(pattern : String, topic : String) : Object`
Traverses the `pattern` and attempts to fetch parameters from the `topic`.
Useful if you know in advance that your `topic` will be valid and want to extract data.
If the `topic` doesn't match, or the `pattern` doesn't contain named wildcards, returns an empty object.
Do not use this for validation.
### `fill(pattern : String, params: Object) : String`
Reverse of `extract`, traverse the `pattern` and fill in params with keys in an object. Missing keys for `+` params are set to `undefined`. Missing keys for `#` params yeid empty strings.
### `clean(pattern : String) : String`
Removes the parameter names from a pattern.
## How params work
MQTT defines two types of "wildcards", one for matching a single section of the path (`+`), and one for zero or more sections of the path (`#`).
Note that the `#` wildcard must only be used if it's at the end of the topic.
This library was inspired by the syntax in the routers for web frameworks.
### Examples of topic patterns:
#### user/+id/#path
This would match paths that start with `user/`, and then extract the next section as the user `id`.
Then it would get the following paths and turn them into an array for the `path` param.
Here is some input/output that you can expect:
user/bob/status/mood: {id: "bob", path:["status","mood"]
user/bob: {id:"bob", path: []}
user/bob/ishungry: {id: "bob", path: ["ishungry"]
#### device/+/+/component/+type/#path
Not all wildcards need to be associated with a parameter, and it could be useful to use plain MQTT topics.
In this example you might only care about the status of some part of a device, and are willing to ignore a part of the path.
Here are some examples of what this might be used with:
device/deviceversion/deviceidhere/component/infrared/status/active: {type:"infrared",path: ["status","active"]}