@lakutata/dbus 2.3.0 → 3.0.0-beta.0

package/dist/types/components/DBusObjectManager.d.ts

@@ -0,0 +1,164 @@
+import { Component } from '@lakutata/core';
+import type { DBusPropertyDefinition, DBusSignalDefinition } from '../lib/Declarations.js';
+/**
+ * What a DBus adapter does for the object manager while it runs
+ */
+export type DBusObjectSink = {
+    /**
+     * Export an object, false when no interface of the adapter serves its path
+     */
+    addObject(path: string): boolean;
+    /**
+     * Stop exporting an object added by the object manager, false when it does not export it or exports it as a fixed
+     * object (the path of a template without variables), which it keeps
+     */
+    removeObject(path: string): boolean;
+    /**
+     * Whether it exports the object as a fixed object
+     */
+    isFixed(path: string): boolean;
+    emitSignal(path: string, signal: DBusSignalDefinition<any>, data: unknown): boolean;
+    propertyChanged(path: string, property: DBusPropertyDefinition<any>, value: unknown): void;
+};
+/**
+ * A property value written by a D-Bus client, the argument of the `propertyWritten` event of
+ * {@link DBusObjectManager}. The value is already validated and kept when the event is emitted.
+ */
+export type DBusPropertyWrite = {
+    /**
+     * The object path of the property (`'/com/example/Devices/A1'`).
+     */
+    readonly path: string;
+    /**
+     * The name of the interface the client wrote it through (`'com.example.Device'`).
+     */
+    readonly interface: string;
+    /**
+     * The property's definition, to compare with the one built by `defineDBusProperty`.
+     */
+    readonly property: DBusPropertyDefinition<any>;
+    /**
+     * The value written, validated by the property's schema.
+     */
+    readonly value: unknown;
+};
+export declare const ATTACH: unique symbol;
+export declare const STORE: unique symbol;
+/**
+ * The application's D-Bus objects: it adds and removes the objects of the path templates of `@DBusInterface`
+ * (`/com/example/Devices/{sn}`), keeps the values of their properties, and emits their signals. Inject it
+ * (`@Inject(DBusObjectManager)`) or get it (`getObject(DBusObjectManager)`) from any object: it is autoloaded, a
+ * singleton of the application, and needs no registration.
+ *
+ * Its state lives in the application, not on the bus: the objects added before a {@link dbusEntrypoint} starts are
+ * exported when it starts, and every running D-Bus adapter whose interfaces match a path exports the object. The
+ * clients are told of the objects added and removed by the `org.freedesktop.DBus.ObjectManager` interface of the root
+ * object (`InterfacesAdded`, `InterfacesRemoved`).
+ *
+ * It emits `propertyWritten` (a {@link DBusPropertyWrite}) when a client writes a writable property.
+ * @example
+ * ```typescript
+ * import {Component} from 'lakutata'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {DBusObjectManager, defineDBusProperty, defineDBusSignal, type DBusPropertyWrite} from '@lakutata/dbus'
+ *
+ * export const DeviceState = defineDBusProperty<string>('State', 's', {initial: 'idle'})
+ * export const DeviceLevel = defineDBusProperty<number>('Level', 'i', {writable: true, initial: 1})
+ * export const DeviceRemoved = defineDBusSignal<string>('Removed', 's')
+ *
+ * //Declared in the components of the application, with the controllers of the interfaces at /com/example/Devices/{sn}
+ * export class Devices extends Component {
+ *     @Inject(DBusObjectManager)
+ *     protected readonly manager: DBusObjectManager
+ *
+ *     protected async init(): Promise<void> {
+ *         this.manager.on('propertyWritten', (write: DBusPropertyWrite): void => {
+ *             if (write.property === DeviceLevel) console.log(`${write.path}: level ${write.value}`)
+ *         })
+ *     }
+ *
+ *     public plug(sn: string): void {
+ *         const path: string = `/com/example/Devices/${sn}`
+ *         this.manager.addObject(path)
+ *         this.manager.setPropertyValue(path, DeviceState, 'running')
+ *     }
+ *
+ *     public unplug(sn: string): void {
+ *         const path: string = `/com/example/Devices/${sn}`
+ *         this.manager.emitSignal(path, DeviceRemoved, sn)
+ *         this.manager.removeObject(path)
+ *     }
+ * }
+ * ```
+ */
+export declare class DBusObjectManager extends Component {
+    #private;
+    /**
+     * Send the changes to an adapter until the returned function is called; the objects already added are exported by it
+     * @param sink
+     */
+    [ATTACH](sink: DBusObjectSink): () => void;
+    /**
+     * Keep a value written by a client
+     * @param write
+     */
+    [STORE](write: DBusPropertyWrite): void;
+    /**
+     * Add an object: every running D-Bus adapter whose interfaces have a path template matching it (or the same path)
+     * exports it, with those interfaces, and the adapters started later export it when they start. The variables of the
+     * matching templates are given to the methods called on it. An object whose path matches no template is kept, but
+     * not exported.
+     * @param path The object path (`'/com/example/Devices/A1'`), not a template.
+     * @returns `false` when the object was already added, `true` otherwise.
+     * @throws {TypeError} When the path is invalid, or is a template (it contains braces).
+     */
+    addObject(path: string): boolean;
+    /**
+     * Remove an object added with {@link addObject}: the adapters stop exporting it, and its property values are
+     * forgotten (added again, it starts from the initial values). A fixed object (the path of a template without
+     * variables, exported by the adapters themselves) stays exported, with its property values, when it was also
+     * added: only its entry in {@link objects} is removed.
+     * @param path The object path given to {@link addObject}.
+     * @returns `false` when the object was not added, `true` otherwise.
+     */
+    removeObject(path: string): boolean;
+    /**
+     * Tell whether an object was added with {@link addObject} and not removed since.
+     * @param path The object path.
+     * @returns `true` when the object is added.
+     */
+    hasObject(path: string): boolean;
+    /**
+     * List the objects added with {@link addObject}, in the order they were added; the objects of the paths without
+     * variables, exported by the adapters themselves, are not listed.
+     * @returns The object paths.
+     */
+    objects(): string[];
+    /**
+     * Set the value of a property on an object, validated by the property's schema: the clients read it from then on,
+     * and the running adapters exporting the object announce it (`PropertiesChanged`). The value is kept even when no
+     * adapter exports the object yet.
+     * @param path The object path (`'/com/example/Devices/A1'`).
+     * @param property The property's definition, listed in the `properties` of the object's interface.
+     * @param value The new value.
+     * @throws {InvalidValueException} When the value does not match the property's schema; nothing is changed.
+     */
+    setPropertyValue<T>(path: string, property: DBusPropertyDefinition<T>, value: T): void;
+    /**
+     * Get the value of a property on an object: the last value set by the application or written by a client.
+     * @param path The object path.
+     * @param property The property's definition.
+     * @returns The value, or the property's `initial` value until one is set.
+     */
+    getPropertyValue<T>(path: string, property: DBusPropertyDefinition<T>): T | undefined;
+    /**
+     * Emit a signal from an object, through every running adapter exporting the object with an interface listing the
+     * signal. The data is validated by the signal's DTO first.
+     * @param path The object path (`'/com/example/Devices/A1'`).
+     * @param signal The signal's definition, listed in the `signals` of the object's interface.
+     * @param data The data of the signal.
+     * @returns `false` when no running adapter exports the object with this signal (nothing is sent), `true` otherwise.
+     * @throws {InvalidValueException} When the data does not match the signal's DTO.
+     */
+    emitSignal<T>(path: string, signal: DBusSignalDefinition<T>, data: T): boolean;
+}

package/dist/types/context/DBusContext.d.ts

@@ -0,0 +1,52 @@
+import { BaseContext } from '@lakutata/entrypoint';
+import { type DBusContextParams } from '../types/DBusContextParams.js';
+/**
+ * The `type` of every {@link DBusContext}: `'DBUS'`. A middleware or an access rule shared by several transports tells
+ * the D-Bus calls apart with it.
+ */
+export declare const DBUS_CONTEXT_TYPE: string;
+/**
+ * The context of a D-Bus method call: `this.context` of a controller action declared with `@DBusMethod` when a client
+ * calls it through {@link dbusEntrypoint}. The adapter creates one per call; its `data` is the call's input (the entries
+ * of its `a{sv}` dictionary). The variables of the object path template are not in the context: they are merged into
+ * the action's input, as the route parameters of HTTP.
+ * @example
+ * ```typescript
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {DBusContext, DBusInterface, DBusMethod} from '@lakutata/dbus'
+ *
+ * @DBusInterface('com.example.Manager', {path: '/com/example/Manager'})
+ * class ManagerController extends Controller {
+ *     //Returns "com.example.Manager.Ping at /com/example/Manager"
+ *     @DBusMethod('Ping', {returns: 's'})
+ *     public async ping(): Promise<string> {
+ *         const context: DBusContext = this.context as DBusContext
+ *         return `${context.interface}.${context.member} at ${context.path}`
+ *     }
+ * }
+ * ```
+ */
+export declare class DBusContext<T extends Record<string, any> = {}> extends BaseContext<T> {
+    /**
+     * Always {@link DBUS_CONTEXT_TYPE} (`'DBUS'`).
+     */
+    readonly type: string;
+    /**
+     * The object path the client called (`'/com/example/Devices/A1'`).
+     */
+    readonly path: string;
+    /**
+     * The name of the interface the client called (`'com.example.Device'`).
+     */
+    readonly interface: string;
+    /**
+     * The name of the method the client called (`'Status'`).
+     */
+    readonly member: string;
+    /**
+     * Create the context of a method call, validating its properties.
+     * @param params The object path, the interface, the method and the input of the call.
+     * @throws {InvalidValueException} When a property is missing or invalid.
+     */
+    constructor(params: DBusContextParams);
+}

package/dist/types/decorators/DBusInterface.d.ts

@@ -0,0 +1,74 @@
+import type { Controller } from '@lakutata/entrypoint';
+import { type DBusPropertyDefinition, type DBusSignalDefinition } from '../lib/Declarations.js';
+/**
+ * The options of {@link DBusInterface}: where the interface is served, and its signals and properties.
+ */
+export type DBusInterfaceOptions = {
+    /**
+     * The object path of the interface. A path without variables (`'/com/example/Manager'`) is one object, exported
+     * while the adapter runs ({@link DBusObjectManager.removeObject} does not remove it). A template (`'/com/example/Devices/{sn}'`) serves the objects added with
+     * {@link DBusObjectManager.addObject} whose path matches it; its variables are merged into the input of the methods,
+     * as route parameters (they take precedence over the client's input). Its elements are letters, digits and `_`, or
+     * variables in braces; a variable matches one element.
+     */
+    path: string;
+    /**
+     * The signals of the interface, declared with {@link defineDBusSignal} and emitted with
+     * {@link DBusObjectManager.emitSignal}.
+     * @default []
+     */
+    signals?: DBusSignalDefinition<any>[];
+    /**
+     * The properties of the interface, declared with {@link defineDBusProperty} and set with
+     * {@link DBusObjectManager.setPropertyValue}.
+     * @default []
+     */
+    properties?: DBusPropertyDefinition<any>[];
+};
+/**
+ * Serve a controller as a D-Bus interface: its `@DBusMethod` actions are the interface's methods, and the signals and
+ * properties of the options are its other members, on the objects at `options.path`. The controllers declaring the same
+ * path are served by the same objects, each one interface; a subclass inherits the declaration of its parent class.
+ * The objects also implement `org.freedesktop.DBus.Properties`, `Introspectable` and `Peer`, and the root object `/`
+ * implements `ObjectManager`. Nothing is served until a {@link dbusEntrypoint} runs.
+ * @param name The name of the interface (`'com.example.Device'`): two or more elements separated by dots, made of
+ * letters, digits and `_`, not starting with a digit; 255 characters at most.
+ * @param options The object path (or template) of the interface, its signals and its properties.
+ * @returns The class decorator.
+ * @throws {TypeError} When the class is declared, if the name of the interface or the path is invalid.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {Expect, Return} from 'lakutata/decorator/dto'
+ * import {DBusInterface, DBusMethod, defineDBusProperty, defineDBusSignal} from '@lakutata/dbus'
+ *
+ * class DeviceSnDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public sn: string
+ * }
+ *
+ * class StatusDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public sn: string
+ *
+ *     @Expect(DTO.Boolean().required())
+ *     public online: boolean
+ * }
+ *
+ * export const DeviceChanged = defineDBusSignal('Changed', StatusDTO)
+ * export const DeviceState = defineDBusProperty<string>('State', 's', {initial: 'idle'})
+ *
+ * //Served by the objects /com/example/Devices/A1, /com/example/Devices/B2… added with DBusObjectManager
+ * @DBusInterface('com.example.Device', {path: '/com/example/Devices/{sn}', signals: [DeviceChanged], properties: [DeviceState]})
+ * export class DeviceController extends Controller {
+ *     //The sn of the input is the one of the object path
+ *     @DBusMethod('Status', DeviceSnDTO)
+ *     @Return(StatusDTO)
+ *     public async status(input: DeviceSnDTO): Promise<StatusDTO> {
+ *         return {sn: input.sn, online: true} as StatusDTO
+ *     }
+ * }
+ * ```
+ */
+export declare function DBusInterface<ClassConstructor extends typeof Controller>(name: string, options: DBusInterfaceOptions): (target: ClassConstructor) => void;

package/dist/types/decorators/DBusMethod.d.ts

@@ -0,0 +1,115 @@
+import type { DTO, MethodDecorator } from '@lakutata/core';
+import type { Controller } from '@lakutata/entrypoint';
+import { ActionOptions } from '@lakutata/entrypoint/channel';
+import type { DBusContext } from '../context/DBusContext.js';
+/**
+ * The options of {@link DBusMethod}: the options of a controller action (`name`, `description`, `acl`, `rule`,
+ * `groups`, `middlewares`), with the D-Bus type of the method's result.
+ */
+export type DBusMethodOptions = ActionOptions<DBusContext> & {
+    /**
+     * The type of the method's result: a DTO (a dictionary of variants, `a{sv}`) or a D-Bus signature (`'s'`, `'b'`,
+     * `'x'`, `'v'`…). Without it, the type comes from the method's `@Return` schema: an object is `a{sv}`, a string
+     * `s`, a boolean `b`, an integer or a bigint `x`, another number `d`, an array `av`, any other value a variant `v`.
+     * @default the type of the `@Return` schema; without `@Return`, the method has no result
+     */
+    returns?: typeof DTO | string;
+};
+/**
+ * Serve a controller action as a method of the D-Bus interface its controller declares with `@DBusInterface`. A method
+ * with a DTO takes one argument, a dictionary of variants (`a{sv}`) holding the DTO's properties; a method without one
+ * takes no argument. The input goes through the entrypoint's middlewares, the DTO validation and the access control,
+ * as in the other channels, and the variables of the object path template are merged into it.
+ *
+ * The result is encoded with the type of `returns` or of `@Return` (the dates as ISO strings, the `null` and
+ * `undefined` values left out, since a variant has no null); a method with neither returns nothing. An error thrown by
+ * the action is answered as a D-Bus error named after its `errno` (or its name), prefixed by the service name
+ * (`com.example.DeviceService.E_OFFLINE`), with its message; an `errno` already containing dots is used as it is.
+ * The same method may also carry the decorators of the other channels (`@ServiceAction`, `@GET`…).
+ * @param name The name of the method (`'Reboot'`): letters, digits and `_`, not starting with a digit; 255 characters at
+ * most. Unique in its interface.
+ * @returns The method decorator.
+ * @throws {TypeError} When the method is declared, if its name is invalid; when the adapter starts, if its controller
+ * has no `@DBusInterface`.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Controller} from 'lakutata/com/entrypoint'
+ * import {Expect, Return} from 'lakutata/decorator/dto'
+ * import {DBusInterface, DBusMethod} from '@lakutata/dbus'
+ *
+ * class ConfigureDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public sn: string
+ *
+ *     @Expect(DTO.Number().integer().min(0).optional())
+ *     public retries?: number
+ * }
+ *
+ * @DBusInterface('com.example.Manager', {path: '/com/example/Manager'})
+ * export class ManagerController extends Controller {
+ *     //No argument, returns a string (s)
+ *     @DBusMethod('Ping', {returns: 's'})
+ *     public async ping(): Promise<string> {
+ *         return 'pong'
+ *     }
+ *
+ *     //One argument a{sv}, returns a dictionary a{sv} (the type of @Return)
+ *     @DBusMethod('Configure', ConfigureDTO, {description: 'Configure a device'})
+ *     @Return(ConfigureDTO)
+ *     public async configure(input: ConfigureDTO): Promise<ConfigureDTO> {
+ *         return input
+ *     }
+ *
+ *     //No result
+ *     @DBusMethod('Reset')
+ *     public async reset(): Promise<void> {
+ *     }
+ * }
+ * ```
+ */
+export declare function DBusMethod<ClassPrototype extends Controller, Method>(name: string): MethodDecorator<ClassPrototype, Method, any>;
+/**
+ * Serve a controller action as a method of the D-Bus interface its controller declares with `@DBusInterface`: its input
+ * is the DTO, given by the client as one dictionary of variants (`a{sv}`); its result has the type of `@Return`.
+ * The input goes through the entrypoint's middlewares, the DTO validation and the access control, and the variables
+ * of the object path template are merged into it. An error thrown by the action is answered as a D-Bus error named
+ * after its `errno`, prefixed by the service name (`com.example.DeviceService.E_OFFLINE`).
+ * @param name The name of the method (`'Reboot'`): letters, digits and `_`, not starting with a digit; 255 characters at
+ * most. Unique in its interface.
+ * @param dtoConstructor The DTO of the method's input, given by the client as an `a{sv}` dictionary.
+ * @returns The method decorator.
+ * @throws {TypeError} When the method is declared, if its name is invalid; when the adapter starts, if its controller
+ * has no `@DBusInterface`.
+ */
+export declare function DBusMethod<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(name: string, dtoConstructor: DTOConstructor): MethodDecorator<ClassPrototype, Method, any>;
+/**
+ * Serve a controller action as a method of the D-Bus interface its controller declares with `@DBusInterface`, with
+ * action options: it takes no argument; its result has the type of `returns` or of `@Return`.
+ * The input goes through the entrypoint's middlewares, the DTO validation and the access control, and the variables
+ * of the object path template are merged into it. An error thrown by the action is answered as a D-Bus error named
+ * after its `errno`, prefixed by the service name (`com.example.DeviceService.E_OFFLINE`).
+ * @param name The name of the method (`'Reboot'`): letters, digits and `_`, not starting with a digit; 255 characters at
+ * most. Unique in its interface.
+ * @param options The options of the action, and the type of its result (`returns`).
+ * @returns The method decorator.
+ * @throws {TypeError} When the method is declared, if its name is invalid; when the adapter starts, if its controller
+ * has no `@DBusInterface`.
+ */
+export declare function DBusMethod<ClassPrototype extends Controller, Method>(name: string, options: DBusMethodOptions): MethodDecorator<ClassPrototype, Method, any>;
+/**
+ * Serve a controller action as a method of the D-Bus interface its controller declares with `@DBusInterface`, with
+ * action options: its input is the DTO, given by the client as one dictionary of variants (`a{sv}`); its result has the
+ * type of `returns` or of `@Return`.
+ * The input goes through the entrypoint's middlewares, the DTO validation and the access control, and the variables
+ * of the object path template are merged into it. An error thrown by the action is answered as a D-Bus error named
+ * after its `errno`, prefixed by the service name (`com.example.DeviceService.E_OFFLINE`).
+ * @param name The name of the method (`'Reboot'`): letters, digits and `_`, not starting with a digit; 255 characters at
+ * most. Unique in its interface.
+ * @param dtoConstructor The DTO of the method's input, given by the client as an `a{sv}` dictionary.
+ * @param options The options of the action, and the type of its result (`returns`).
+ * @returns The method decorator.
+ * @throws {TypeError} When the method is declared, if its name is invalid; when the adapter starts, if its controller
+ * has no `@DBusInterface`.
+ */
+export declare function DBusMethod<ClassPrototype extends Controller, Method, DTOConstructor extends typeof DTO = typeof DTO>(name: string, dtoConstructor: DTOConstructor, options: DBusMethodOptions): MethodDecorator<ClassPrototype, Method, any>;

package/dist/types/exports/DBus.d.ts

@@ -0,0 +1,11 @@
+export { DBusChannel } from '../channel/DBusChannel.js';
+export { DBusContext, DBUS_CONTEXT_TYPE } from '../context/DBusContext.js';
+export { type DBusContextParams } from '../types/DBusContextParams.js';
+export { DBusInterface, type DBusInterfaceOptions } from '../decorators/DBusInterface.js';
+export { DBusMethod, type DBusMethodOptions } from '../decorators/DBusMethod.js';
+export { defineDBusSignal, defineDBusProperty, type DBusSignalDefinition, type DBusPropertyDefinition, type DBusPropertyOptions, type DBusInterfaceDeclaration } from '../lib/Declarations.js';
+export { dbusEntrypoint, type DBusEntrypointOptions } from '../adapters/DBusEntrypoint.js';
+export { DBusObjectManager, type DBusPropertyWrite } from '../components/DBusObjectManager.js';
+export { DBusClientComponent, buildDBusClientOptions } from '../components/DBusClientComponent.js';
+export type { DBusClientOptions } from '../lib/DBusClientOptions.js';
+export { DBus, DBusInterface as DBusRemoteInterface, DBusObject, DBusService, LocalInterface, LocalObject, LocalService, createDBusError, DBusSignedValue, DBusSignalEmitter, Signature, RequestNameFlags, RequestNameResultCode, type BusNameBasicInfo, type ConnectOpts, type DecodeOpts, type InvokeOpts } from 'dbus-sdk';

package/dist/types/lib/DBusClientOptions.d.ts

@@ -0,0 +1,30 @@
+import type { DecodeOpts } from 'dbus-sdk';
+/**
+ * The options of {@link buildDBusClientOptions}: the bus a {@link DBusClientComponent} connects to, and how it decodes
+ * the replies.
+ */
+export interface DBusClientOptions {
+    /**
+     * The address of the bus: `'unix:path=/var/run/dbus/system_bus_socket'` (the system bus),
+     * `'unix:path=/run/user/1000/bus'`, `'tcp:host=127.0.0.1,port=5555'`; the value of `DBUS_SESSION_BUS_ADDRESS` for
+     * the session bus.
+     */
+    busAddress: string;
+    /**
+     * How long the connection to the bus may take, in milliseconds (a positive integer).
+     * @default 20000
+     */
+    timeout?: number;
+    /**
+     * How long a call may wait for its reply, in milliseconds (a positive integer); a call's own `timeout` overrides it.
+     * @default dbus-sdk's default
+     */
+    callTimeout?: number;
+    /**
+     * How the replies and the signals are decoded (`DecodeOpts` of `dbus-sdk`): `types` (`'none'`, `'variants'`,
+     * `'all'`: where the values keep their D-Bus types as typed values), `dictionaries` (`'object'` or `'map'`),
+     * `int64` (`'number'` or `'bigint'`).
+     * @default {int64: 'number'} (the 64-bit integers as numbers when they are safe integers, else bigints)
+     */
+    decode?: DecodeOpts;
+}

package/dist/types/lib/Declarations.d.ts

@@ -0,0 +1,187 @@
+import { DTO, type Schema } from '@lakutata/core';
+/**
+ * A D-Bus signal, built by {@link defineDBusSignal}: list it in the `signals` of `@DBusInterface`, and emit it with
+ * {@link DBusObjectManager.emitSignal}. The definition itself identifies the signal: two definitions with the same
+ * name are two signals.
+ * @typeParam T The data the signal carries.
+ */
+export type DBusSignalDefinition<T = unknown> = {
+    /**
+     * Always `'signal'`.
+     */
+    readonly kind: 'signal';
+    /**
+     * The member name of the signal (`'Changed'`).
+     */
+    readonly name: string;
+    /**
+     * The D-Bus signature of the signal's one argument: `a{sv}` for a DTO, or the signature given.
+     */
+    readonly type: string;
+    /**
+     * Validate the data of an emission: with the DTO when the signal has one, returning the validated data; as it is
+     * otherwise.
+     * @param data The data to emit.
+     * @returns The data validated.
+     * @throws {InvalidValueException} When the data does not match the signal's DTO.
+     */
+    readonly validate: (data: T) => T;
+};
+/**
+ * A D-Bus property, built by {@link defineDBusProperty}: list it in the `properties` of `@DBusInterface`. Its values
+ * are kept by {@link DBusObjectManager}, one per object path: the application sets them with
+ * {@link DBusObjectManager.setPropertyValue}, the clients read them, and write them when the property is writable. The
+ * definition itself identifies the property.
+ * @typeParam T The values of the property.
+ */
+export type DBusPropertyDefinition<T = unknown> = {
+    /**
+     * Always `'property'`.
+     */
+    readonly kind: 'property';
+    /**
+     * The member name of the property (`'State'`).
+     */
+    readonly name: string;
+    /**
+     * The D-Bus signature of the property's values (`'s'`, `'i'`, `'a{sv}'`…).
+     */
+    readonly type: string;
+    /**
+     * Whether the clients may write the property (`org.freedesktop.DBus.Properties.Set`); a read-only property refuses
+     * their writes with a D-Bus error.
+     */
+    readonly writable: boolean;
+    /**
+     * The value of the property on every object until it is set.
+     */
+    readonly initial?: T;
+    /**
+     * Validate a value of the property, synchronously, with its `schema` (the value as it is without a schema).
+     * @param value The value set by the application or written by a client.
+     * @returns The value validated.
+     * @throws {InvalidValueException} When the value does not match the schema; a client writing it gets a D-Bus error.
+     */
+    readonly validate: (value: T) => T;
+};
+/**
+ * The options of {@link defineDBusProperty}.
+ * @typeParam T The values of the property.
+ */
+export type DBusPropertyOptions<T> = {
+    /**
+     * Whether the clients may write the property. A value written is validated with `schema`, kept, and announced by
+     * `DBusObjectManager` with a `propertyWritten` event and to the clients with `PropertiesChanged`.
+     * @default false
+     */
+    writable?: boolean;
+    /**
+     * The value of the property on every object until it is set; it is not validated.
+     * @default undefined
+     */
+    initial?: T;
+    /**
+     * The schema validating the values of the property (`DTO.Number().integer().min(0)`), the ones set by the
+     * application and the ones written by the clients.
+     * @default none: every value is accepted
+     */
+    schema?: Schema;
+};
+/**
+ * The declaration of a D-Bus interface served by a controller, as `@DBusInterface` records it.
+ */
+export type DBusInterfaceDeclaration = {
+    /**
+     * The name of the interface (`'com.example.Device'`).
+     */
+    readonly interface: string;
+    /**
+     * The object path, or path template, of the interface (`'/com/example/Devices/{sn}'`).
+     */
+    readonly path: string;
+    /**
+     * The signals of the interface.
+     */
+    readonly signals: DBusSignalDefinition<any>[];
+    /**
+     * The properties of the interface.
+     */
+    readonly properties: DBusPropertyDefinition<any>[];
+};
+/**
+ * Declare a D-Bus signal, to list in the `signals` of one or more `@DBusInterface`. The signal has one argument: a
+ * dictionary of variants (`a{sv}`) holding a DTO, or a value of the signature given. Its data is validated by its DTO
+ * when it is emitted.
+ * @typeParam T The data the signal carries.
+ * @param name The member name of the signal (`'Changed'`): letters, digits and `_`, not starting with a digit; 255
+ * characters at most.
+ * @param data The DTO of the signal's data, or the D-Bus signature of its argument (`'s'`, `'a{sv}'`…); with a
+ * signature, the data is not validated. `'a{sv}'` by default.
+ * @returns The signal's definition.
+ * @throws {TypeError} When the name is invalid.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {Expect} from 'lakutata/decorator/dto'
+ * import {defineDBusSignal, type DBusObjectManager} from '@lakutata/dbus'
+ *
+ * class StatusDTO extends DTO {
+ *     @Expect(DTO.String().required())
+ *     public sn: string
+ *
+ *     @Expect(DTO.Boolean().required())
+ *     public online: boolean
+ * }
+ *
+ * //A dictionary of variants a{sv}, validated by StatusDTO
+ * export const DeviceChanged = defineDBusSignal<StatusDTO>('Changed', StatusDTO)
+ * //A string s
+ * export const DeviceMessage = defineDBusSignal<string>('Message', 's')
+ *
+ * declare const manager: DBusObjectManager
+ * manager.emitSignal('/com/example/Devices/A1', DeviceChanged, {sn: 'A1', online: true} as StatusDTO)
+ * manager.emitSignal('/com/example/Devices/A1', DeviceMessage, 'Rebooted')
+ * ```
+ */
+export declare function defineDBusSignal<T = Record<string, unknown>>(name: string, data?: typeof DTO | string): DBusSignalDefinition<T>;
+/**
+ * Declare a D-Bus property, to list in the `properties` of one or more `@DBusInterface`. Its values are kept by
+ * `DBusObjectManager`, one per object: the application sets them, the clients read them (`Get`, `GetAll`) and are told
+ * of their changes (`PropertiesChanged`), and write them when the property is writable.
+ * @typeParam T The values of the property.
+ * @param name The member name of the property (`'State'`): letters, digits and `_`, not starting with a digit; 255
+ * characters at most.
+ * @param type The D-Bus signature of its values (`'s'`, `'i'`, `'b'`, `'a{sv}'`…); it is not checked against `schema`.
+ * @param options Whether the clients may write it, its initial value and the schema of its values; none by default
+ * (read-only, no initial value, every value accepted).
+ * @returns The property's definition.
+ * @throws {TypeError} When the name is invalid.
+ * @example
+ * ```typescript
+ * import {DTO} from 'lakutata'
+ * import {defineDBusProperty, type DBusObjectManager, type DBusPropertyWrite} from '@lakutata/dbus'
+ *
+ * //Read-only, "idle" until it is set
+ * export const DeviceState = defineDBusProperty<string>('State', 's', {initial: 'idle'})
+ * //Written by the clients, from 0 to 10
+ * export const DeviceLevel = defineDBusProperty<number>('Level', 'i', {writable: true, initial: 1, schema: DTO.Number().integer().min(0).max(10)})
+ *
+ * declare const manager: DBusObjectManager
+ * manager.setPropertyValue('/com/example/Devices/A1', DeviceState, 'running')
+ * manager.on('propertyWritten', (write: DBusPropertyWrite): void => {
+ *     if (write.property === DeviceLevel) console.log(`${write.path}: level ${write.value}`)
+ * })
+ * ```
+ */
+export declare function defineDBusProperty<T = unknown>(name: string, type: string, options?: DBusPropertyOptions<T>): DBusPropertyDefinition<T>;
+/**
+ * Keep the declaration of the interface of a controller
+ * @param controller
+ * @param declaration
+ */
+export declare function setDBusInterfaceDeclaration(controller: Function, declaration: DBusInterfaceDeclaration): void;
+/**
+ * The declaration of the interface of a controller, or of its nearest parent class declaring one
+ * @param controller
+ */
+export declare function getDBusInterfaceDeclaration(controller: Function): DBusInterfaceDeclaration | undefined;