Pure JavaScript
No native addons and no build step. The protocol is implemented directly, so the package installs anywhere node does and has one runtime dependency.
Client and server
Call methods on a service, export one of your own, or run a message bus in process for tests. The low-level connection is available when you want the messages themselves.
Promises or callbacks
Every callback-taking method returns a promise when you omit the callback, and the callback form is unchanged. Failures reject with a DBusError carrying the call site.
Types included
Types ship with the package and are checked in CI, so they cannot drift. dbus-native types introspects a live service and writes TypeScript declarations for it.
Values that look like values
A variant is the value it holds, a string-keyed dict is a plain object, and 64-bit integers are bigint. Each old shape is still available per connection.
Observable and cancellable
Traffic and call timing are published on diagnostics_channel. Calls take a timeout and an AbortSignal, so nothing is left pending forever.
Both ends of the bus
const dbus = require('dbus-native');
const bus = dbus.sessionBus();
const notifications = await bus
.getService('org.freedesktop.Notifications')
.getInterface(
'/org/freedesktop/Notifications',
'org.freedesktop.Notifications'
);
const id = await notifications.Notify(
'example', 0, '', 'summary', 'body text', [], [], 5000
);
notifications.on('ActionInvoked', (id, action) => console.log(id, action));
const { defineInterface } = require('dbus-native');
const greeter = defineInterface({
name: 'com.example.Greeter',
methods: {
Hello: {
in: { name: 's' },
out: { greeting: 's' },
handler: ({ name }, { sender }) => `Hello ${name}, from ${sender}`
}
},
signals: { Greeted: { args: { who: 's' } } }
});
await bus.requestName('com.example.Greeter', 0);
await bus.export('/com/example/Greeter', greeter);
greeter.emit.Greeted('world');
Upgrading?
Migrating to 0.14.0
Variants, dicts and 64-bit integers changed shape. Leads with bigint, which is the part that breaks code far from the call.
Migrating to 0.7
D-Bus errors became real Error objects. A codemod rewrites the call sites it can attribute, and reports the rest.
Deprecations
Stable codes for behaviour that changes in a future major, so you can migrate before it does. npx dbus-native lint finds the call sites.