Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/digital-alchemy-ts/mqtt
Configured wrapper for mqtt with wildcard support
https://github.com/digital-alchemy-ts/mqtt
digital-alchemy mqtt mqtt-client nodejs typescript
Last synced: about 2 months ago
JSON representation
Configured wrapper for mqtt with wildcard support
- Host: GitHub
- URL: https://github.com/digital-alchemy-ts/mqtt
- Owner: Digital-Alchemy-TS
- License: mit
- Created: 2024-03-10T04:13:58.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-04-15T02:11:07.000Z (9 months ago)
- Last Synced: 2024-06-08T16:52:24.873Z (7 months ago)
- Topics: digital-alchemy, mqtt, mqtt-client, nodejs, typescript
- Language: TypeScript
- Homepage: https://docs.digital-alchemy.app/MQTT
- Size: 390 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
## 📚 Description
Welcome to `@digital-alchemy/mqtt-extension`!
- [Extended docs](https://docs.digital-alchemy.app)
- [Discord](https://discord.gg/JkZ35Gv97Y)
## 💾 Install
This library can be installed as a simple dependency
```bash
npm i @digital-alchemy/mqtt-extension
```
Then added to your project
```typescript
import { LIB_MQTT } from "@digital-alchemy/mqtt-extension";
// application
const MY_APP = CreateApplication({
libraries: [LIB_MQTT],
name: "home_automation",
})
// library
export const MY_LIBRARY = CreateLibrary({
depends: [LIB_MQTT],
name: "special_logic",
})
```
## ⚙️ Configuration
> `CLIENT_OPTIONS` gets passed straight to mqtt library.
>
> See [mqtt code](https://github.com/mqttjs/MQTT.js/blob/9a18610daf7b350476c1d92347dc24f56882887b/src/lib/client.ts#L111) for all available options.
Add the following to your application's configuration file.
```ini
[mqtt.CLIENT_OPTIONS]
host=localhost
username=me
password=super-strong-password
port=1883
```
or as json in your `.env`
```
CLIENT_OPTIONS={"host":"localhost","port":1883}
```
## 🛠 Usage
> Library is in an "experimental" state
>
> More useful services will be added in the future
### 🔄 Bindings
The bindings file is an "everything in one file". It handles
- Connection at `onPostConfig`
- logging standard events (error messages, reconnect events, etc)
#### ➕ subscribe
The subscribe method will automatically listen to topics for you, and pass through messages to your provided callback. You can use wildcards in your topics:
- `+` - single level (`device/+/turned_off`)
- `#` - multi level wildcard (`device/thingie/#`)
```typescript
import { TServiceParams } from "@digital-alchemy/core";
type YourMessage = {}
export function Example({ logger, mqtt, context }: TServiceParams) {
mqtt.bindings.subscribe({
context,
exec(message:YourMessage) {
logger.info("my topic was sent!")
},
topic: "my/topic",
});
}
```
#### 📤 publish
Simple wrapper for the `publish` method on the mqtt client.
```typescript
import { TServiceParams } from "@digital-alchemy/core";
type YourMessage = {}
export function Example({ logger, mqtt, lifecycle }: TServiceParams) {
lifecycle.onReady(() => {
mqtt.bindings.publish("my/topic")
mqtt.bindings.publish("my/topic",{
extra_payload_data: {},
foo: "bar"
})
})
}
```
#### 🔍 getClient
Need something more complicated? Retrieve the already configured mqtt instance
```typescript
import { TServiceParams } from "@digital-alchemy/core";
type YourMessage = {}
export function Example({ mqtt, lifecycle }: TServiceParams) {
lifecycle.onBootstrap(() => {
const client = mqtt.bindings.getClient();
})
}
```