# mqtt-pattern

> Fast library for matching MQTT patterns with named wildcards

Latest version **2.1.1** (published 2026-02-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install mqtt-pattern
pnpm add mqtt-pattern
yarn add mqtt-pattern
bun add mqtt-pattern
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.1.1 |
| Published | 2026-02-16 |
| First published | 2017-04-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 18.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 31 |
| Author | rangermauve |
| Maintainers | rangermauve |
| Keywords | mqtt, pattern, match, topic |

## Links

- npm: https://www.npmjs.com/package/mqtt-pattern
- Repository: https://github.com/RangerMauve/mqtt-pattern
- Homepage: https://github.com/RangerMauve/mqtt-pattern#readme
- Issues: https://github.com/RangerMauve/mqtt-pattern/issues
- npm.io page: https://npm.io/package/mqtt-pattern

## Dependencies (2)

- [mqtt-match](https://npm.io/package/mqtt-match.md) ^1.0.2
- [ts-toolbelt](https://npm.io/package/ts-toolbelt.md) ^9.6.0

## Recent versions

- 2.1.1 (latest) — 2026-02-16
- 2.1.0 — 2023-05-13
- 2.0.1 — 2023-04-16
- 2.0.0 — 2022-12-23
- 1.2.0 — 2018-04-17
- 1.1.3 — 2018-02-27
- 1.1.1 — 2018-02-26
- 1.1.0 — 2017-11-03
- 1.0.0 — 2017-04-21

## 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"]}

---
_Source: https://npm.io/package/mqtt-pattern · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._