@lakutata/dbus 3.0.0 → 3.1.0

package/README.md

@@ -1,11 +1,13 @@
 # @lakutata/dbus
 
-The D-Bus channel of the [lakutata](https://github.com/lakutata/lakutata) framework: the application owns a service
-name on a bus (the system bus, the session bus or a private bus) and serves its controllers as the interfaces of D-Bus
-objects: their methods, properties and signals. It also has a D-Bus client component, to call the other services of a
-bus, read their properties and listen to their signals. The protocol is implemented by
+English | [中文](README.zh-CN.md)
+
+The D-Bus channel of the [lakutata](https://github.com/lakutata/lakutata) framework. The application owns a service
+name on a bus (the system bus, the session bus or a private bus) and serves its controllers as interfaces of D-Bus
+objects, with methods, properties and signals. The package also provides a D-Bus client component that calls other
+services on a bus, reads their properties and listens to their signals. The protocol is implemented by
 [dbus-sdk](https://github.com/myq1991/node-dbus-sdk), whose classes this package re-exports. The umbrella package
-`lakutata` does not re-export it: import it from `@lakutata/dbus`.
+`lakutata` does not re-export this package: import it from `@lakutata/dbus`.
 
 ## Installation
 
@@ -13,17 +15,18 @@ bus, read their properties and listen to their signals. The protocol is implemen
 npm install lakutata @lakutata/dbus
 ```
 
-- It needs a D-Bus daemon, as on Linux: the system bus (`/var/run/dbus/system_bus_socket`), the session bus of a
-  desktop session (`DBUS_SESSION_BUS_ADDRESS`), or a private `dbus-daemon`. Owning a name on the system bus needs a bus
-  policy allowing it (a file of `/etc/dbus-1/system.d/`).
-- Node.js 22 or later; its peer dependencies `@lakutata/core` and `@lakutata/entrypoint` come with `lakutata`.
+- It needs a D-Bus daemon, as found on Linux: the system bus (`/var/run/dbus/system_bus_socket`), the session bus of
+  a desktop session (`DBUS_SESSION_BUS_ADDRESS`), or a private `dbus-daemon`. To own a name on the system bus, a bus
+  policy must allow it (a file in `/etc/dbus-1/system.d/`).
+- It needs Node.js `^22.13.0 || >=24.11.0`. Its peer dependencies, `@lakutata/core` and `@lakutata/entrypoint`, are
+  installed with `lakutata`.
 
 ## Usage
 
 ### A D-Bus service
 
-`dbusEntrypoint` is the `dbus` adapter of the entrypoint. A controller declared with `@DBusInterface` serves an
-interface at an object path; its `@DBusMethod` actions are the interface's methods.
+`dbusEntrypoint` is the entrypoint's `dbus` adapter. A controller declared with `@DBusInterface` serves an interface at
+an object path, and its `@DBusMethod` actions are the methods of that interface.
 
 ```typescript
 import {Application, DTO} from 'lakutata'
@@ -69,19 +72,22 @@ Application.run(() => ({
 }))
 ```
 
-- **The input** of a method with a DTO is one argument, a dictionary of variants (`a{sv}`) holding the DTO's
-  properties; a method without a DTO takes no argument. The input goes through the middlewares, the validation and the
-  access control of the entrypoint, as in the other channels.
-- **The result** has the type of the `returns` option (a DTO is `a{sv}`, or a signature such as `'s'`), or else the type
-  of the `@Return` schema: an object is `a{sv}`, a string `s`, a boolean `b`, an integer `x`, another number `d`, an
-  array `av`, the other values a variant `v`. Without them, the method has no result. The dates are sent as ISO
-  strings, the `null` and `undefined` values are left out (a variant has no null).
-- **The errors** reach the callers as D-Bus errors named after their `errno`, prefixed by the service name
-  (`com.example.DeviceService.E_OFFLINE`), with their message.
-- **The context** of the methods is a `DBusContext`: `context.path`, `context.interface` and `context.member`.
-- **Several controllers** at the same path are the interfaces of the same objects. The objects implement
+- **Input**: a method with a DTO takes one argument, a dictionary of variants (`a{sv}`) holding the DTO's properties;
+  a method without a DTO takes no argument. The input goes through the entrypoint's middlewares, validation and access
+  control, as on the other channels.
+- **Result**: its type is given by the `returns` option (a DTO, sent as `a{sv}`, or a signature such as `'s'`), or
+  else by the `@Return` schema: an object becomes `a{sv}`, a string `s`, a boolean `b`, an integer or a bigint `x`, any
+  other number `d`, an array `av`, and any other value a variant `v`. Without either, the method has no result. Dates
+  are sent as ISO strings, and `null` and `undefined` values are left out of objects and arrays (a variant cannot hold
+  null). A method whose result is a single type (`'s'`, `'i'`…) must return a value: `undefined` fails the call.
+- **Errors** reach the callers as D-Bus errors named after their `errno` and prefixed with the service name
+  (`com.example.DeviceService.E_OFFLINE`), with their message. An element of the `errno` that does not start with a
+  letter gets an `E` prefix (`500` becomes `E500`, `_HIDDEN` becomes `E_HIDDEN`).
+- **Context**: the context of the methods is a `DBusContext`, with `context.path`, `context.interface` and
+  `context.member`.
+- **Several controllers** with the same path are interfaces of the same objects. Every object also implements
   `org.freedesktop.DBus.Properties`, `Introspectable` and `Peer`, and the root object `/` implements `ObjectManager`.
-- A method may also carry the decorators of the other channels (`@ServiceAction`, `@GET`…).
+- A method can also carry the decorators of other channels (`@ServiceAction`, `@GET`…).
 
 ### The adapter
 
@@ -89,29 +95,35 @@ Application.run(() => ({
 dbus: dbusEntrypoint({bus: 'system', service: 'com.example.DeviceService', replaceExisting: true})
 ```
 
-- `bus`: `'session'` (default, the address in `DBUS_SESSION_BUS_ADDRESS`), `'system'` (`DBUS_SYSTEM_BUS_ADDRESS`, else
-  `unix:path=/var/run/dbus/system_bus_socket`), the address of a bus (`unix:path=…`, `tcp:host=…,port=…`), or the path
-  of the socket of a private bus.
-- `service`: the well-known name of the service. The adapter fails to start when another connection owns it
-  (`replaceExisting` takes it when its owner allows it, `allowReplacement` lets another service take it).
-- `name` and `middlewares`: the adapter's name, and the middlewares of its calls (after the global ones).
-- It stops gracefully with the entrypoint: the name is released, the calls in progress end, then the connection
-  closes.
+- `bus`: `'session'` (the default: the address in `DBUS_SESSION_BUS_ADDRESS`), `'system'` (`DBUS_SYSTEM_BUS_ADDRESS`,
+  else `unix:path=/var/run/dbus/system_bus_socket`), a bus address (`unix:path=…`, `tcp:host=…,port=…`), or the socket
+  path of a private bus.
+- `service`: the well-known name of the service, two or more elements of letters, digits and `_` separated by dots.
+  D-Bus also allows `-` in service names, but this name prefixes the error names, which cannot contain it. The adapter
+  fails to start when another connection owns the name. `replaceExisting` takes the name over when its owner allows
+  it, and `allowReplacement` lets another service take it over: the replaced adapter then keeps running without the
+  name, and does not get it back.
+- `decode`: how the arguments of method calls and the property values written by clients are decoded (`DecodeOpts`
+  of `dbus-sdk`). By default (`{int64: 'number'}`), 64-bit integers arrive as numbers when they are safe integers, else
+  as bigints, so that `DTO.Number()` accepts them; `{int64: 'bigint'}` decodes them all as bigints, for `DTO.BigInt()`.
+- `name` and `middlewares`: the adapter's name, and the middlewares for its calls (run after the global ones).
+- It stops gracefully with the entrypoint: it releases the name, lets the calls in progress finish, then closes the
+  connection.
 
 ### Objects, properties and signals
 
-The path of an interface is either a path (`/com/example/Manager`), whose object is exported when the adapter starts
-and stays exported while it runs (`DBusObjectManager.removeObject()` does not remove it), or a template
-(`/com/example/Devices/{sn}`), whose objects are added and removed with `DBusObjectManager`. The
-variables of the path are merged into the input of the methods, as the route parameters (they take precedence over the
-client's input).
+The path of an interface is either a fixed path (`/com/example/Manager`) or a template (`/com/example/Devices/{sn}`).
+The object at a fixed path is exported when the adapter starts and stays exported while it runs
+(`DBusObjectManager.removeObject()` does not remove it). The objects of a template are added and removed with
+`DBusObjectManager`. The variables of the path are merged into the input of the methods, like route parameters, and
+take precedence over the values sent by the client.
 
-A property is a value of an object, kept by `DBusObjectManager`: the application sets it, the clients read it and are
-notified of its changes (`PropertiesChanged`); until it is set, its value is its `initial` value. A `writable`
-property is also written by the clients: the value is validated by the property's `schema` (the errors are given to the
-client), kept, and `DBusObjectManager` emits `propertyWritten`. A write which must reach a device, or may fail after
-the validation, is better a method: its errors are given to the caller. A signal's data is validated by its DTO when it
-is emitted.
+A property is a value of an object, kept by `DBusObjectManager`. The application sets it, and clients read it and are
+notified when it changes (`PropertiesChanged`); until it is set, it has its `initial` value. Clients can also write a
+`writable` property: the value is validated by the property's `schema` (validation errors are returned to the client),
+stored, and `DBusObjectManager` emits `propertyWritten`. A write that must reach a device, or that may fail after
+validation, is better made a method, whose errors are returned to the caller. A signal's data is validated by its DTO
+when the signal is emitted.
 
 ```typescript
 import {Component, DTO} from 'lakutata'
@@ -179,15 +191,14 @@ export class Devices extends Component {
 }
 ```
 
-`DBusObjectManager` is autoloaded, one per application: inject it in any object (`@Inject(DBusObjectManager)`) or get
-it (`getObject(DBusObjectManager)`). The objects added before the adapter starts are exported when it starts. The
-clients are told of the objects added and removed by the `ObjectManager` of the service (`InterfacesAdded`,
-`InterfacesRemoved`).
+`DBusObjectManager` is autoloaded, one per application: inject it into any object (`@Inject(DBusObjectManager)`) or get
+it with `getObject(DBusObjectManager)`. Objects added before the adapter starts are exported when it starts. The
+service's `ObjectManager` tells clients about added and removed objects (`InterfacesAdded`, `InterfacesRemoved`).
 
 ### The client
 
-`DBusClientComponent` connects to a bus when it is created, to call the services, read their objects and properties,
-and listen to their signals; it disconnects when the application stops.
+`DBusClientComponent` connects to a bus when it is created; use it to call services, read their objects and
+properties, and listen to their signals. It disconnects when the application stops.
 
 ```typescript
 import {Application} from 'lakutata'
@@ -229,38 +240,42 @@ Application
 
 | Export | What it is |
 |---|---|
-| `dbusEntrypoint`, `DBusEntrypointOptions` | The adapter of the entrypoint (its `dbus` option): the bus, the service name |
+| `dbusEntrypoint`, `DBusEntrypointOptions` | The entrypoint's adapter (for its `dbus` option) and its options: `bus`, `service`, `replaceExisting`, `allowReplacement`, `decode`, `name`, `middlewares` |
 | `DBusInterface`, `DBusInterfaceOptions` | Class decorator: a controller served as a D-Bus interface at an object path or path template |
-| `DBusMethod`, `DBusMethodOptions` | Method decorator: an action served as a method of the interface, the type of its result |
-| `defineDBusSignal`, `DBusSignalDefinition` | Declares a signal, its DTO or signature |
+| `DBusMethod`, `DBusMethodOptions` | Method decorator: serves an action as a method of the interface; the options include the type of its result (`returns`) |
+| `defineDBusSignal`, `DBusSignalDefinition` | Declares a signal, with its DTO or signature |
 | `defineDBusProperty`, `DBusPropertyDefinition`, `DBusPropertyOptions` | Declares a property: its signature, `writable`, `initial`, `schema` |
-| `DBusInterfaceDeclaration` | The declaration `@DBusInterface` records |
-| `DBusObjectManager` | The objects of the templates, the property values and the signals: `addObject`, `removeObject`, `hasObject`, `objects`, `setPropertyValue`, `getPropertyValue`, `emitSignal`; the `propertyWritten` event |
-| `DBusPropertyWrite` | A property written by a client, the argument of `propertyWritten` |
-| `DBusContext`, `DBusContextParams`, `DBUS_CONTEXT_TYPE` | The context of the method calls: `path`, `interface`, `member` |
-| `DBusChannel` | The definition of the `dbus` channel, for the custom adapters |
-| `DBusClientComponent` | The client: `invoke`, `interface`, `interfaceSignal`, `object`, `service`, `services`, `listNames`, `listServices`, `nameHasOwner`, `getNameOwner`, `addMatch`, the connection events |
-| `buildDBusClientOptions`, `DBusClientOptions` | The client's declaration and options: `busAddress`, `timeout`, `callTimeout`, `decode` (`DecodeOpts` of `dbus-sdk`; the 64-bit integers are numbers by default) |
+| `DBusInterfaceDeclaration` | The declaration recorded by `@DBusInterface` |
+| `DBusObjectManager` | Manages the objects of path templates, property values and signals: `addObject`, `removeObject`, `hasObject`, `objects`, `setPropertyValue`, `getPropertyValue`, `emitSignal`; the `propertyWritten` event |
+| `DBusPropertyWrite` | A property write by a client: the argument of `propertyWritten` |
+| `DBusContext`, `DBusContextParams`, `DBUS_CONTEXT_TYPE` | The context of method calls: `path`, `interface`, `member` |
+| `DBusChannel` | The definition of the `dbus` channel, for custom adapters |
+| `DBusClientComponent` | The client: `invoke`, `interface`, `interfaceSignal`, `object`, `service`, `services`, `listNames`, `listBusNames`, `listServices`, `listActivatableNames`, `nameHasOwner`, `getNameOwner`, `addMatch`, `removeMatch`, `uniqueName`; `on`, `once`, `off` and `removeListener` for the connection events (`serviceOnline`, `serviceOffline`, `serviceReplaced`, `methodCall`, `nameOwnerChanged`, `nameLost`, `nameAcquired`, `connectionClose`, `connectionError`) |
+| `buildDBusClientOptions`, `DBusClientOptions` | The client's declaration and options: `busAddress`, `timeout`, `callTimeout`, `decode` (`DecodeOpts` of `dbus-sdk`; 64-bit integers are numbers by default) |
 | `DBus`, `DBusRemoteInterface`, `DBusObject`, `DBusService`, `LocalService`, `LocalObject`, `LocalInterface`, `DBusSignedValue`, `DBusSignalEmitter`, `Signature`, `createDBusError`, `RequestNameFlags`, `RequestNameResultCode`, `BusNameBasicInfo`, `ConnectOpts`, `DecodeOpts`, `InvokeOpts` | Re-exported from dbus-sdk 2 (`DBusRemoteInterface` is its `DBusInterface`; see its MIGRATION.md for the changes from 1.x) |
 
-The typings document each declaration with examples.
+The typings document every declaration, with examples.
 
 ## Errors
 
 | Error | When |
 |---|---|
-| `TypeError` | An invalid interface, member or service name, or object path, when the class is declared or `dbusEntrypoint()` is called; `DBusObjectManager.addObject()` with a template; the start of the adapter, when a `@DBusMethod` belongs to a controller without `@DBusInterface` |
+| `TypeError` | An invalid interface, member or service name, object path, or signature (of a property, a signal or a `returns` option), when it is declared or `dbusEntrypoint()` is called; `DBusObjectManager.addObject()` with a template; the adapter's start, when a `@DBusMethod` belongs to a controller without `@DBusInterface` |
 | `Error` (`The DBus name … is owned by another service`) | The adapter's start, when another connection owns the service name; the entrypoint fails to start |
-| The errors of dbus-sdk (`UnknownBusAddressError`, a connection error…) | The adapter's start or the client's creation, when the bus cannot be reached; the client's calls, when a method answers a D-Bus error |
-| `InvalidValueException` (from `lakutata`) | `setPropertyValue()` or `emitSignal()` with a value its schema or DTO refuses; the client's options when it is created |
+| The errors of dbus-sdk (`UnknownBusAddressError`, a connection error…) | The adapter's start or the client's creation, when the bus cannot be reached; the client's calls, when a method replies with a D-Bus error |
+| `InvalidValueException` (from `lakutata`) | `setPropertyValue()` or `emitSignal()` with a value that its schema or DTO rejects; the client's creation, when `busAddress` is missing |
+| `InvalidObjectOptionsException` (from `lakutata`) | An option of the client has an invalid value (`timeout`, `decode`…); the application fails to start |
 
-The errors thrown by the actions are given to the callers as D-Bus errors named after their `errno`
-(`com.example.DeviceService.E_OFFLINE`), with their message; a client writing an invalid property value gets a D-Bus
-error too.
+Errors thrown by the actions reach the callers as D-Bus errors named after their `errno`
+(`com.example.DeviceService.E_OFFLINE`), with their message. A client that writes an invalid property value also gets
+a D-Bus error.
 
 ## See also
 
-- `@lakutata/entrypoint` (`lakutata/com/entrypoint`): the entrypoint, the controllers, the middlewares and the access
-  control (`doc/en/ActionPattern.md` of the package `lakutata`, Chinese in `doc/zh`).
+- The guide on the website: [D-Bus](https://lakutata.com/guide/DBus).
+- `doc/en/DBus.md` in the `lakutata` package (Chinese version in `doc/zh`): the guide to D-Bus.
+- `@lakutata/entrypoint` (`lakutata/com/entrypoint`): the entrypoint, controllers, middlewares and access control (see
+  `doc/en/Controllers.md`, `Entrypoint.md` and `Middlewares.md` in the `lakutata` package, and their Chinese versions
+  in `doc/zh`).
 - [dbus-sdk](https://github.com/myq1991/node-dbus-sdk): the D-Bus protocol, its client classes and its local services.
-- `@lakutata/core` (`lakutata`): the components, `Application` and the dependency injection.
+- `@lakutata/core` (`lakutata`): components, `Application` and dependency injection.

package/README.zh-CN.md

@@ -0,0 +1,236 @@
+# @lakutata/dbus
+
+[English](README.md) | 中文
+
+[lakutata](https://github.com/lakutata/lakutata) 框架的 D-Bus 传输方式。应用在一条总线（系统总线、会话总线或私有总线）上持有一个服务名称，把控制器作为 D-Bus 对象的接口提供出来，包括方法、属性和信号。这个包还提供一个 D-Bus 客户端组件，用来调用总线上的其他服务、读取它们的属性、监听它们的信号。协议由 [dbus-sdk](https://github.com/myq1991/node-dbus-sdk) 实现，这个包也重新导出了它的类。`lakutata` 包不重新导出这个包：请从 `@lakutata/dbus` 导入。
+
+## 安装
+
+```shell
+npm install lakutata @lakutata/dbus
+```
+
+- 需要一个 D-Bus 守护进程，Linux 上一般都有：系统总线（`/var/run/dbus/system_bus_socket`）、桌面会话的会话总线（`DBUS_SESSION_BUS_ADDRESS`），或者私有的 `dbus-daemon`。要在系统总线上持有名称，需要总线策略允许（`/etc/dbus-1/system.d/` 中的一个文件）。
+- 需要 Node.js `^22.13.0 || >=24.11.0`。它的 peer 依赖 `@lakutata/core` 和 `@lakutata/entrypoint` 会随 `lakutata` 一起安装。
+
+## 用法
+
+### 一个 D-Bus 服务
+
+`dbusEntrypoint` 是入口的 `dbus` 适配器。用 `@DBusInterface` 声明的控制器在一个对象路径上提供一个接口，它的 `@DBusMethod` 动作就是这个接口的方法。
+
+```typescript
+import {Application, DTO} from 'lakutata'
+import {buildEntrypoints, Controller} from 'lakutata/com/entrypoint'
+import {Expect, Return} from 'lakutata/decorator/dto'
+import {dbusEntrypoint, 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'})
+class ManagerController extends Controller {
+    //没有参数，返回一个字符串（s）
+    @DBusMethod('Ping', {returns: 's'})
+    public async ping(): Promise<string> {
+        return 'pong'
+    }
+
+    //一个 a{sv} 参数，返回一个 a{sv} 字典（@Return 的类型）
+    @DBusMethod('Configure', ConfigureDTO)
+    @Return(ConfigureDTO)
+    public async configure(input: ConfigureDTO): Promise<ConfigureDTO> {
+        return input
+    }
+}
+
+//busctl --user call com.example.DeviceService /com/example/Manager com.example.Manager Ping
+Application.run(() => ({
+    id: 'devices.app',
+    name: 'Devices',
+    components: {
+        entrypoint: buildEntrypoints({
+            controllers: [ManagerController],
+            dbus: dbusEntrypoint({bus: 'session', service: 'com.example.DeviceService'})
+        })
+    },
+    bootstrap: ['entrypoint']
+}))
+```
+
+- **输入**：带 DTO 的方法接受一个参数，即包含 DTO 各个属性的变体字典（`a{sv}`）；没有 DTO 的方法不接受参数。和其他传输方式一样，输入会经过入口的中间件、校验和访问控制。
+- **结果**：类型由 `returns` 选项给出（一个 DTO，以 `a{sv}` 发送；或者 `'s'` 这样的签名），没有这个选项时取自 `@Return` 的校验规则：对象对应 `a{sv}`，字符串对应 `s`，布尔值对应 `b`，整数和 bigint 对应 `x`，其他数字对应 `d`，数组对应 `av`，其他值对应变体 `v`。两者都没有时，方法没有结果。日期以 ISO 字符串发送，对象和数组中值为 `null` 和 `undefined` 的项会被去掉（变体不能为 null）。结果为单个类型（`'s'`、`'i'`……）的方法必须返回一个值：返回 `undefined` 会让调用失败。
+- **错误**作为 D-Bus 错误连同消息一起交给调用方，错误名称是服务名称加上错误的 `errno`（`com.example.DeviceService.E_OFFLINE`）。`errno` 中不以字母开头的段会加上前缀 `E`（`500` 变成 `E500`，`_HIDDEN` 变成 `E_HIDDEN`）。
+- **上下文**：方法的上下文是 `DBusContext`，带有 `context.path`、`context.interface` 和 `context.member`。
+- **路径相同的多个控制器**是同一个对象的多个接口。每个对象还实现了 `org.freedesktop.DBus.Properties`、`Introspectable` 和 `Peer`；根对象 `/` 实现了 `ObjectManager`。
+- 方法还可以同时带有其他传输方式的装饰器（`@ServiceAction`、`@GET`……）。
+
+### 适配器
+
+```text
+dbus: dbusEntrypoint({bus: 'system', service: 'com.example.DeviceService', replaceExisting: true})
+```
+
+- `bus`：`'session'`（默认值，使用 `DBUS_SESSION_BUS_ADDRESS` 中的地址）、`'system'`（`DBUS_SYSTEM_BUS_ADDRESS`，没有设置时为 `unix:path=/var/run/dbus/system_bus_socket`）、一个总线地址（`unix:path=…`、`tcp:host=…,port=…`），或者私有总线的套接字路径。
+- `service`：服务的公认名称，由字母、数字和 `_` 组成的两段或更多段，以点分隔。D-Bus 也允许服务名称中有 `-`，但这个名称会作为错误名称的前缀，而错误名称中不能有这个字符。名称已被其他连接持有时，适配器启动失败。设置 `replaceExisting` 时，如果名称的持有者允许，就接管名称；设置 `allowReplacement` 时，允许其他服务接管名称：被替换的适配器会继续运行，但没有名称，也拿不回来。
+- `decode`：方法调用的参数和客户端写入的属性值如何解码（`dbus-sdk` 的 `DecodeOpts`）。使用默认值（`{int64: 'number'}`）时，64 位整数如果是安全整数就解码为数字，否则解码为 bigint，这样 `DTO.Number()` 才能接受它们；`{int64: 'bigint'}` 把它们全部解码为 bigint，供 `DTO.BigInt()` 使用。
+- `name` 和 `middlewares`：适配器的名字，以及它的调用使用的中间件（在全局中间件之后执行）。
+- 它随入口一起平稳停止：先释放名称，等正在处理的调用结束，再关闭连接。
+
+### 对象、属性与信号
+
+接口的路径可以是一个具体路径（`/com/example/Manager`），也可以是一个模板（`/com/example/Devices/{sn}`）。具体路径上的对象在适配器启动时导出，在适配器运行期间一直保持导出（`DBusObjectManager.removeObject()` 不会移除它）。模板的对象通过 `DBusObjectManager` 添加和移除。和路由参数一样，路径中的变量会合并到方法的输入中，并覆盖客户端发送的值。
+
+属性是对象的一个值，由 `DBusObjectManager` 保存。应用设置它，客户端读取它，并在它变化时收到通知（`PropertiesChanged`）；在设置之前，它的值是 `initial`。客户端也可以写入 `writable` 属性：值先经过属性的 `schema` 校验（校验错误返回给客户端），然后保存，并由 `DBusObjectManager` 发出 `propertyWritten` 事件。需要传到设备上或者校验通过后仍可能失败的写入，更适合做成方法，这样错误能返回给调用方。发出信号时，信号的数据由它的 DTO 校验。
+
+```typescript
+import {Component, DTO} from 'lakutata'
+import {Controller} from 'lakutata/com/entrypoint'
+import {Expect, Return} from 'lakutata/decorator/dto'
+import {Inject} from 'lakutata/decorator/di'
+import {
+    DBusInterface,
+    DBusMethod,
+    DBusObjectManager,
+    defineDBusProperty,
+    defineDBusSignal,
+    type DBusPropertyWrite
+} 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<StatusDTO>('Changed', StatusDTO)
+export const DeviceState = defineDBusProperty<string>('State', 's', {initial: 'idle'})
+export const DeviceLevel = defineDBusProperty<number>('Level', 'i', {writable: true, initial: 1, schema: DTO.Number().integer().min(0).max(10)})
+
+@DBusInterface('com.example.Device', {path: '/com/example/Devices/{sn}', signals: [DeviceChanged], properties: [DeviceState, DeviceLevel]})
+export class DeviceController extends Controller {
+    //输入中的 sn 取自对象路径
+    @DBusMethod('Status', DeviceSnDTO)
+    @Return(StatusDTO)
+    public async status(input: DeviceSnDTO): Promise<StatusDTO> {
+        return {sn: input.sn, online: true} as StatusDTO
+    }
+}
+
+//在应用的 components 中声明
+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')
+        this.manager.emitSignal(path, DeviceChanged, {sn: sn, online: true} as StatusDTO)
+    }
+
+    public unplug(sn: string): void {
+        this.manager.removeObject(`/com/example/Devices/${sn}`)
+    }
+}
+```
+
+`DBusObjectManager` 会自动注册，每个应用一个：可以注入到任何对象中（`@Inject(DBusObjectManager)`），也可以用 `getObject(DBusObjectManager)` 获取。在适配器启动之前添加的对象，会在它启动时导出。服务的 `ObjectManager` 会在对象添加和移除时通知客户端（`InterfacesAdded`、`InterfacesRemoved`）。
+
+### 客户端
+
+`DBusClientComponent` 在创建时连接总线，用来调用服务、读取它们的对象和属性、监听它们的信号。应用停止时，它断开连接。
+
+```typescript
+import {Application} from 'lakutata'
+import {DBusClientComponent, type DBusRemoteInterface} from '@lakutata/dbus'
+
+Application
+    .run(() => ({
+        id: 'client.app',
+        name: 'Client',
+        components: {
+            dbus: {class: DBusClientComponent, busAddress: 'unix:path=/var/run/dbus/system_bus_socket', timeout: 5000}
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const dbus: DBusClientComponent = await app.getObject('dbus')
+        //显式给出签名的方法调用：得到输出参数组成的数组
+        const [status] = await dbus.invoke({
+            service: 'com.example.DeviceService',
+            objectPath: '/com/example/Devices/A1',
+            interface: 'com.example.Device',
+            method: 'Status',
+            signature: 'a{sv}',
+            args: [{sn: 'A1'}]
+        })
+        console.log(status)
+        //根据对象的内省信息构建的接口
+        const device: DBusRemoteInterface = await dbus.interface('com.example.DeviceService', '/com/example/Devices/A1', 'com.example.Device')
+        console.log(await device.property.State.get())
+        device.signal.on('Changed', (data: unknown): void => console.log(data))
+        //连接的事件
+        dbus.on('nameOwnerChanged', (name: string, oldOwner: string, newOwner: string): void => console.log(name, oldOwner, newOwner))
+    })
+```
+
+`buildDBusClientOptions(options)` 用带类型的选项生成同样的声明：`dbus: buildDBusClientOptions({busAddress: 'unix:path=/var/run/dbus/system_bus_socket'})`。
+
+## API
+
+| 导出 | 说明 |
+|---|---|
+| `dbusEntrypoint`、`DBusEntrypointOptions` | 供入口的 `dbus` 选项使用的适配器，及其选项：`bus`、`service`、`replaceExisting`、`allowReplacement`、`decode`、`name`、`middlewares` |
+| `DBusInterface`、`DBusInterfaceOptions` | 类装饰器：把控制器作为 D-Bus 接口，在一个对象路径或路径模板上提供 |
+| `DBusMethod`、`DBusMethodOptions` | 方法装饰器：把动作作为接口的方法提供；选项包括结果的类型（`returns`） |
+| `defineDBusSignal`、`DBusSignalDefinition` | 声明一个信号，以及它的 DTO 或签名 |
+| `defineDBusProperty`、`DBusPropertyDefinition`、`DBusPropertyOptions` | 声明一个属性：它的签名、`writable`、`initial`、`schema` |
+| `DBusInterfaceDeclaration` | `@DBusInterface` 记录下来的声明 |
+| `DBusObjectManager` | 管理路径模板的对象、属性值和信号：`addObject`、`removeObject`、`hasObject`、`objects`、`setPropertyValue`、`getPropertyValue`、`emitSignal`；`propertyWritten` 事件 |
+| `DBusPropertyWrite` | 客户端对属性的一次写入：`propertyWritten` 的参数 |
+| `DBusContext`、`DBusContextParams`、`DBUS_CONTEXT_TYPE` | 方法调用的上下文：`path`、`interface`、`member` |
+| `DBusChannel` | `dbus` 传输方式的定义，供自定义适配器使用 |
+| `DBusClientComponent` | 客户端：`invoke`、`interface`、`interfaceSignal`、`object`、`service`、`services`、`listNames`、`listBusNames`、`listServices`、`listActivatableNames`、`nameHasOwner`、`getNameOwner`、`addMatch`、`removeMatch`、`uniqueName`；用 `on`、`once`、`off` 和 `removeListener` 处理连接的事件（`serviceOnline`、`serviceOffline`、`serviceReplaced`、`methodCall`、`nameOwnerChanged`、`nameLost`、`nameAcquired`、`connectionClose`、`connectionError`） |
+| `buildDBusClientOptions`、`DBusClientOptions` | 客户端的声明及其选项：`busAddress`、`timeout`、`callTimeout`、`decode`（`dbus-sdk` 的 `DecodeOpts`；64 位整数默认解码为数字） |
+| `DBus`、`DBusRemoteInterface`、`DBusObject`、`DBusService`、`LocalService`、`LocalObject`、`LocalInterface`、`DBusSignedValue`、`DBusSignalEmitter`、`Signature`、`createDBusError`、`RequestNameFlags`、`RequestNameResultCode`、`BusNameBasicInfo`、`ConnectOpts`、`DecodeOpts`、`InvokeOpts` | 从 dbus-sdk 2 重新导出（`DBusRemoteInterface` 就是它的 `DBusInterface`；相对 1.x 的变化见它的 MIGRATION.md） |
+
+类型声明中的每一项都附有说明和示例。
+
+## 错误
+
+| 错误 | 什么时候 |
+|---|---|
+| `TypeError` | 声明时或调用 `dbusEntrypoint()` 时，接口名、成员名、服务名称、对象路径或签名（属性、信号或 `returns` 选项的签名）不合法；用模板调用 `DBusObjectManager.addObject()`；适配器启动时，某个 `@DBusMethod` 所在的控制器没有 `@DBusInterface` |
+| `Error`（`The DBus name … is owned by another service`） | 适配器启动时，服务名称已被其他连接持有；入口启动失败 |
+| dbus-sdk 的错误（`UnknownBusAddressError`、连接错误……） | 适配器启动或客户端创建时连不上总线；客户端调用的方法以 D-Bus 错误回复 |
+| `InvalidValueException`（来自 `lakutata`） | `setPropertyValue()` 或 `emitSignal()` 的值被校验规则或 DTO 拒绝；客户端创建时缺少 `busAddress` |
+| `InvalidObjectOptionsException`（来自 `lakutata`） | 客户端的某个选项的值不合法（`timeout`、`decode`……）；应用启动失败 |
+
+动作抛出的错误作为 D-Bus 错误连同消息一起交给调用方，错误名称取自它的 `errno`（`com.example.DeviceService.E_OFFLINE`）。客户端写入不合法的属性值时，也会收到 D-Bus 错误。
+
+## 另见
+
+- 网站上的指南：[D-Bus](https://lakutata.com/zh/guide/DBus)。
+- `lakutata` 包中的 `doc/zh/DBus.md`：D-Bus 指南。
+- `@lakutata/entrypoint`（`lakutata/com/entrypoint`）：入口、控制器、中间件和访问控制（见 `lakutata` 包中的 `doc/zh/Controllers.md`、`Entrypoint.md` 和 `Middlewares.md`）。
+- [dbus-sdk](https://github.com/myq1991/node-dbus-sdk)：D-Bus 协议、它的客户端类和本地服务。
+- `@lakutata/core`（`lakutata`）：组件、`Application` 和依赖注入。

package/dist/cjs/adapters/DBusEntrypoint.d.ts

@@ -1,4 +1,5 @@
 import type { EntrypointAdapter, MiddlewareDefinition } from '@lakutata/entrypoint';
+import { type DecodeOpts } from 'dbus-sdk';
 import { DBusContext } from '../context/DBusContext.js';
 /**
  * The options of {@link dbusEntrypoint}: the bus to connect to, and the service name to own on it.
@@ -19,9 +20,10 @@ export type DBusEntrypointOptions = {
      */
     bus?: 'session' | 'system' | string;
     /**
-     * The well-known name the service owns on the bus (`'com.example.DeviceService'`): two or more elements separated by
-     * dots. The clients address the service by it, and it prefixes the names of the D-Bus errors. On the system bus,
-     * the bus policy (`/etc/dbus-1/system.d/`) must allow the process to own it.
+     * The well-known name the service owns on the bus (`'com.example.DeviceService'`): two or more elements of letters,
+     * digits and `_`, separated by dots. The clients address the service by it, and it prefixes the names of the D-Bus
+     * errors (which may not hold the `-` that D-Bus allows in the names of the services). On the system bus, the bus
+     * policy (`/etc/dbus-1/system.d/`) must allow the process to own it.
      */
     service: string;
     /**
@@ -32,10 +34,17 @@ export type DBusEntrypointOptions = {
     replaceExisting?: boolean;
     /**
      * Let another connection take the name with `replaceExisting`. The adapter is not stopped when the name is taken:
-     * the clients reach the new owner.
+     * the clients reach the new owner, and the adapter keeps running without the name, which it does not get back when
+     * the new owner releases it.
      * @default false
      */
     allowReplacement?: boolean;
+    /**
+     * How the arguments of the method calls and the values the clients write to the properties are decoded
+     * (`DecodeOpts` of `dbus-sdk`): `types`, `dictionaries`, `int64` (`'number'` or `'bigint'`), as for the client.
+     * @default {int64: 'number'} (the 64-bit integers as numbers when they are safe integers, else bigints)
+     */
+    decode?: DecodeOpts;
     /**
      * The middlewares of this adapter's method calls, run after the entrypoint's global middlewares.
      * @default []

package/dist/cjs/adapters/DBusEntrypoint.js

@@ -81,7 +81,7 @@ function toMethodError(error) {
  * ```
  */
 function dbusEntrypoint(options) {
-    (0, Names_js_1.checkInterfaceName)(options.service);
+    (0, Names_js_1.checkServiceName)(options.service);
     let service;
     let detach;
     const exported = new Map();
@@ -113,7 +113,12 @@ function dbusEntrypoint(options) {
             const { path, interface: interfaceName, member } = action.address;
             if (path === undefined || interfaceName === undefined)
                 throw new TypeError(`The DBus method ${member} of ${action.controller} has no interface: declare its controller with @DBusInterface`);
-            interfacesAt(path, interfaceName).methods.push(action);
+            //A method declared twice in an interface is served by the declaration registered last
+            const methods = interfacesAt(path, interfaceName).methods;
+            const declared = methods.findIndex((method) => method.address.member === member);
+            if (declared >= 0)
+                methods.splice(declared, 1);
+            methods.push(action);
         }
         return templates;
     };
@@ -234,7 +239,8 @@ function dbusEntrypoint(options) {
                 flags |= dbus_sdk_1.RequestNameFlags.DBUS_NAME_FLAG_REPLACE_EXISTING;
             if (options.allowReplacement)
                 flags |= dbus_sdk_1.RequestNameFlags.DBUS_NAME_FLAG_ALLOW_REPLACEMENT;
-            const result = await localService.run({ ...connect, flags: flags });
+            //The 64-bit integers as numbers, as the client gives them: the schemas of numbers accept them
+            const result = await localService.run({ ...connect, decode: { int64: 'number', ...options.decode }, flags: flags });
             if (result !== dbus_sdk_1.RequestNameResultCode.DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER && result !== dbus_sdk_1.RequestNameResultCode.DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER) {
                 await localService.stop().catch(() => undefined);
                 throw new Error(`The DBus name ${options.service} is owned by another service`);

package/dist/cjs/channel/DBusChannel.d.ts

@@ -28,9 +28,11 @@ declare module '@lakutata/entrypoint' {
 }
 /**
  * The definition of the D-Bus channel of the entrypoint, named `dbus`: its actions are the methods of D-Bus interfaces,
- * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template from
- * `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching none
- * fails with `ControllerActionNotFoundException`. `@DBusMethod` and {@link dbusEntrypoint} use it: an application only
- * needs it to write an adapter of its own.
+ * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template
+ * from `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching
+ * none fails with `ControllerActionNotFoundException` in an adapter dispatching through the channel (with
+ * {@link dbusEntrypoint}, the bus answers such a call with `org.freedesktop.DBus.Error.UnknownObject` or
+ * `UnknownMethod`).
+ * `@DBusMethod` and {@link dbusEntrypoint} use it: an application only needs it to write an adapter of its own.
  */
 export declare const DBusChannel: ChannelDefinition;

package/dist/cjs/channel/DBusChannel.js

@@ -16,10 +16,12 @@ function addressKey(interfaceName, member, path) {
 }
 /**
  * The definition of the D-Bus channel of the entrypoint, named `dbus`: its actions are the methods of D-Bus interfaces,
- * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template from
- * `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching none
- * fails with `ControllerActionNotFoundException`. `@DBusMethod` and {@link dbusEntrypoint} use it: an application only
- * needs it to write an adapter of its own.
+ * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template
+ * from `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching
+ * none fails with `ControllerActionNotFoundException` in an adapter dispatching through the channel (with
+ * {@link dbusEntrypoint}, the bus answers such a call with `org.freedesktop.DBus.Error.UnknownObject` or
+ * `UnknownMethod`).
+ * `@DBusMethod` and {@link dbusEntrypoint} use it: an application only needs it to write an adapter of its own.
  */
 exports.DBusChannel = (0, channel_1.hasChannel)('dbus') ? (0, channel_1.getChannel)('dbus') : (0, channel_1.defineChannel)({
     name: 'dbus',

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

@@ -27,7 +27,7 @@ export type DBusMethodOptions = ActionOptions<DBusContext> & {
  * (`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.
+ * most. A name declared twice in an interface is served by the declaration registered last, as on the other channels.
  * @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`.
@@ -76,7 +76,7 @@ export declare function DBusMethod<ClassPrototype extends Controller, Method>(na
  * 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.
+ * most. A name declared twice in an interface is served by the declaration registered last, as on the other channels.
  * @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
@@ -90,7 +90,7 @@ export declare function DBusMethod<ClassPrototype extends Controller, Method, DT
  * 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.
+ * most. A name declared twice in an interface is served by the declaration registered last, as on the other channels.
  * @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
@@ -105,7 +105,7 @@ export declare function DBusMethod<ClassPrototype extends Controller, Method>(na
  * 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.
+ * most. A name declared twice in an interface is served by the declaration registered last, as on the other channels.
  * @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.

package/dist/cjs/decorators/DBusMethod.js

@@ -4,6 +4,7 @@ exports.DBusMethod = DBusMethod;
 const channel_1 = require("@lakutata/entrypoint/channel");
 const DBusChannel_js_1 = require("../channel/DBusChannel.js");
 const Signature_js_1 = require("../lib/Signature.js");
+const Names_js_1 = require("../lib/Names.js");
 function DBusMethod(name, dtoConstructorOrOptions, options) {
     return (target, propertyKey, descriptor) => {
         const isDTO = typeof dtoConstructorOrOptions === 'function';
@@ -13,7 +14,7 @@ function DBusMethod(name, dtoConstructorOrOptions, options) {
             : (0, channel_1.getActionDTOAndOptions)(actionOptions);
         const pattern = { member: name };
         if (returns !== undefined)
-            pattern.returns = typeof returns === 'string' ? returns : (0, Signature_js_1.schemaSignature)(returns);
+            pattern.returns = typeof returns === 'string' ? (0, Names_js_1.checkSingleType)(returns, `the result of the method ${name}`) : (0, Signature_js_1.schemaSignature)(returns);
         (0, channel_1.registerControllerAction)(DBusChannel_js_1.DBusChannel, target, propertyKey, pattern, dtoConstructor, validatedOptions);
         return descriptor;
     };

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

@@ -17,7 +17,7 @@ export interface DBusClientOptions {
     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
+     * @default none: a call waits for its reply
      */
     callTimeout?: number;
     /**

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

@@ -151,11 +151,12 @@ export declare function defineDBusSignal<T = Record<string, unknown>>(name: stri
  * @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 type The D-Bus signature of its values (`'s'`, `'i'`, `'b'`, `'a{sv}'`…), a single complete type; 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.
+ * @throws {TypeError} When the name or the signature is invalid.
  * @example
  * ```typescript
  * import {DTO} from 'lakutata'

package/dist/cjs/lib/Declarations.js

@@ -45,6 +45,8 @@ const Signature_js_1 = require("./Signature.js");
 function defineDBusSignal(name, data = 'a{sv}') {
     (0, Names_js_1.checkMemberName)(name, 'signal');
     const isDTO = typeof data === 'function';
+    if (!isDTO)
+        (0, Names_js_1.checkSingleType)(data, `the signal ${name}`);
     return {
         kind: 'signal',
         name: name,
@@ -59,11 +61,12 @@ function defineDBusSignal(name, data = 'a{sv}') {
  * @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 type The D-Bus signature of its values (`'s'`, `'i'`, `'b'`, `'a{sv}'`…), a single complete type; 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.
+ * @throws {TypeError} When the name or the signature is invalid.
  * @example
  * ```typescript
  * import {DTO} from 'lakutata'
@@ -83,6 +86,7 @@ function defineDBusSignal(name, data = 'a{sv}') {
  */
 function defineDBusProperty(name, type, options = {}) {
     (0, Names_js_1.checkMemberName)(name, 'property');
+    (0, Names_js_1.checkSingleType)(type, `the property ${name}`);
     const schema = options.schema;
     return {
         kind: 'property',

package/dist/cjs/lib/Names.d.ts

@@ -3,6 +3,18 @@
  * @param name
  */
 export declare function checkInterfaceName(name: string): string;
+/**
+ * Check the well-known name of a service. D-Bus allows "-" in the bus names, but the names of the errors are prefixed by
+ * the name of the service, and an error name may not hold it
+ * @param name
+ */
+export declare function checkServiceName(name: string): string;
+/**
+ * Check a D-Bus signature holding a single complete type (the type of a property, of a signal's data, of a result)
+ * @param signature
+ * @param what what the type is of, for the message
+ */
+export declare function checkSingleType(signature: string, what: string): string;
 /**
  * Check the name of a member
  * @param name

package/dist/cjs/lib/Names.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.checkInterfaceName = checkInterfaceName;
+exports.checkServiceName = checkServiceName;
+exports.checkSingleType = checkSingleType;
 exports.checkMemberName = checkMemberName;
 exports.checkPathTemplate = checkPathTemplate;
 exports.compilePathTemplate = compilePathTemplate;
 exports.errorName = errorName;
+const dbus_sdk_1 = require("dbus-sdk");
 /**
  * The names of the interfaces and of the errors: dot-separated elements
  */
@@ -26,6 +29,33 @@ function checkInterfaceName(name) {
         throw new TypeError(`Invalid DBus interface name "${name}": dot-separated elements of letters, digits and "_", such as "com.example.Device"`);
     return name;
 }
+/**
+ * Check the well-known name of a service. D-Bus allows "-" in the bus names, but the names of the errors are prefixed by
+ * the name of the service, and an error name may not hold it
+ * @param name
+ */
+function checkServiceName(name) {
+    if (typeof name !== 'string' || name.length > 255 || !INTERFACE_NAME.test(name))
+        throw new TypeError(`Invalid DBus service name "${name}": dot-separated elements of letters, digits and "_", such as "com.example.DeviceService" (it prefixes the names of the errors, which may not hold "-")`);
+    return name;
+}
+/**
+ * Check a D-Bus signature holding a single complete type (the type of a property, of a signal's data, of a result)
+ * @param signature
+ * @param what what the type is of, for the message
+ */
+function checkSingleType(signature, what) {
+    let types;
+    try {
+        types = dbus_sdk_1.Signature.parse(signature).length;
+    }
+    catch (error) {
+        throw new TypeError(`Invalid DBus signature "${signature}" of ${what}: ${error.message}`, { cause: error });
+    }
+    if (types !== 1)
+        throw new TypeError(`Invalid DBus signature "${signature}" of ${what}: a single complete type, such as "s" or "a{sv}"`);
+    return signature;
+}
 /**
  * Check the name of a member
  * @param name
@@ -76,5 +106,6 @@ function errorName(error) {
     if (INTERFACE_NAME.test(candidate))
         return candidate;
     const element = candidate.replace(/[^A-Za-z0-9_]/g, '_');
-    return /^[A-Za-z_]/.test(element) ? element : `E${element}`;
+    //An element of an error name starts with a letter
+    return /^[A-Za-z]/.test(element) ? element : `E${element}`;
 }

package/dist/esm/adapters/DBusEntrypoint.js

@@ -5,7 +5,7 @@ import { DBusChannel } from '../channel/DBusChannel.js';
 import { DBusContext } from '../context/DBusContext.js';
 import { ATTACH, DBusObjectManager, STORE } from '../components/DBusObjectManager.js';
 import { getDBusInterfaceDeclaration } from '../lib/Declarations.js';
-import { checkInterfaceName, compilePathTemplate, errorName } from '../lib/Names.js';
+import { checkServiceName, compilePathTemplate, errorName } from '../lib/Names.js';
 import { toEncodable, schemaSignature } from '../lib/Signature.js';
 /**
  * The connection options of a bus
@@ -75,7 +75,7 @@ function toMethodError(error) {
  * ```
  */
 export function dbusEntrypoint(options) {
-    checkInterfaceName(options.service);
+    checkServiceName(options.service);
     let service;
     let detach;
     const exported = new Map();
@@ -107,7 +107,12 @@ export function dbusEntrypoint(options) {
             const { path, interface: interfaceName, member } = action.address;
             if (path === undefined || interfaceName === undefined)
                 throw new TypeError(`The DBus method ${member} of ${action.controller} has no interface: declare its controller with @DBusInterface`);
-            interfacesAt(path, interfaceName).methods.push(action);
+            //A method declared twice in an interface is served by the declaration registered last
+            const methods = interfacesAt(path, interfaceName).methods;
+            const declared = methods.findIndex((method) => method.address.member === member);
+            if (declared >= 0)
+                methods.splice(declared, 1);
+            methods.push(action);
         }
         return templates;
     };
@@ -228,7 +233,8 @@ export function dbusEntrypoint(options) {
                 flags |= RequestNameFlags.DBUS_NAME_FLAG_REPLACE_EXISTING;
             if (options.allowReplacement)
                 flags |= RequestNameFlags.DBUS_NAME_FLAG_ALLOW_REPLACEMENT;
-            const result = await localService.run({ ...connect, flags: flags });
+            //The 64-bit integers as numbers, as the client gives them: the schemas of numbers accept them
+            const result = await localService.run({ ...connect, decode: { int64: 'number', ...options.decode }, flags: flags });
             if (result !== RequestNameResultCode.DBUS_REQUEST_NAME_REPLY_PRIMARY_OWNER && result !== RequestNameResultCode.DBUS_REQUEST_NAME_REPLY_ALREADY_OWNER) {
                 await localService.stop().catch(() => undefined);
                 throw new Error(`The DBus name ${options.service} is owned by another service`);

package/dist/esm/channel/DBusChannel.js

@@ -13,10 +13,12 @@ function addressKey(interfaceName, member, path) {
 }
 /**
  * The definition of the D-Bus channel of the entrypoint, named `dbus`: its actions are the methods of D-Bus interfaces,
- * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template from
- * `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching none
- * fails with `ControllerActionNotFoundException`. `@DBusMethod` and {@link dbusEntrypoint} use it: an application only
- * needs it to write an adapter of its own.
+ * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template
+ * from `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching
+ * none fails with `ControllerActionNotFoundException` in an adapter dispatching through the channel (with
+ * {@link dbusEntrypoint}, the bus answers such a call with `org.freedesktop.DBus.Error.UnknownObject` or
+ * `UnknownMethod`).
+ * `@DBusMethod` and {@link dbusEntrypoint} use it: an application only needs it to write an adapter of its own.
  */
 export const DBusChannel = hasChannel('dbus') ? getChannel('dbus') : defineChannel({
     name: 'dbus',

package/dist/esm/decorators/DBusMethod.js

@@ -1,6 +1,7 @@
 import { getActionDTOAndOptions, registerControllerAction } from '@lakutata/entrypoint/channel';
 import { DBusChannel } from '../channel/DBusChannel.js';
 import { schemaSignature } from '../lib/Signature.js';
+import { checkSingleType } from '../lib/Names.js';
 export function DBusMethod(name, dtoConstructorOrOptions, options) {
     return (target, propertyKey, descriptor) => {
         const isDTO = typeof dtoConstructorOrOptions === 'function';
@@ -10,7 +11,7 @@ export function DBusMethod(name, dtoConstructorOrOptions, options) {
             : getActionDTOAndOptions(actionOptions);
         const pattern = { member: name };
         if (returns !== undefined)
-            pattern.returns = typeof returns === 'string' ? returns : schemaSignature(returns);
+            pattern.returns = typeof returns === 'string' ? checkSingleType(returns, `the result of the method ${name}`) : schemaSignature(returns);
         registerControllerAction(DBusChannel, target, propertyKey, pattern, dtoConstructor, validatedOptions);
         return descriptor;
     };

package/dist/esm/lib/Declarations.js

@@ -1,5 +1,5 @@
 import { DTO } from '@lakutata/core';
-import { checkInterfaceName, checkMemberName, checkPathTemplate } from './Names.js';
+import { checkInterfaceName, checkMemberName, checkPathTemplate, checkSingleType } from './Names.js';
 import { schemaSignature } from './Signature.js';
 /**
  * Declare a D-Bus signal, to list in the `signals` of one or more `@DBusInterface`. The signal has one argument: a
@@ -39,6 +39,8 @@ import { schemaSignature } from './Signature.js';
 export function defineDBusSignal(name, data = 'a{sv}') {
     checkMemberName(name, 'signal');
     const isDTO = typeof data === 'function';
+    if (!isDTO)
+        checkSingleType(data, `the signal ${name}`);
     return {
         kind: 'signal',
         name: name,
@@ -53,11 +55,12 @@ export function defineDBusSignal(name, data = 'a{sv}') {
  * @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 type The D-Bus signature of its values (`'s'`, `'i'`, `'b'`, `'a{sv}'`…), a single complete type; 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.
+ * @throws {TypeError} When the name or the signature is invalid.
  * @example
  * ```typescript
  * import {DTO} from 'lakutata'
@@ -77,6 +80,7 @@ export function defineDBusSignal(name, data = 'a{sv}') {
  */
 export function defineDBusProperty(name, type, options = {}) {
     checkMemberName(name, 'property');
+    checkSingleType(type, `the property ${name}`);
     const schema = options.schema;
     return {
         kind: 'property',

package/dist/esm/lib/Names.js

@@ -1,3 +1,4 @@
+import { Signature } from 'dbus-sdk';
 /**
  * The names of the interfaces and of the errors: dot-separated elements
  */
@@ -19,6 +20,33 @@ export function checkInterfaceName(name) {
         throw new TypeError(`Invalid DBus interface name "${name}": dot-separated elements of letters, digits and "_", such as "com.example.Device"`);
     return name;
 }
+/**
+ * Check the well-known name of a service. D-Bus allows "-" in the bus names, but the names of the errors are prefixed by
+ * the name of the service, and an error name may not hold it
+ * @param name
+ */
+export function checkServiceName(name) {
+    if (typeof name !== 'string' || name.length > 255 || !INTERFACE_NAME.test(name))
+        throw new TypeError(`Invalid DBus service name "${name}": dot-separated elements of letters, digits and "_", such as "com.example.DeviceService" (it prefixes the names of the errors, which may not hold "-")`);
+    return name;
+}
+/**
+ * Check a D-Bus signature holding a single complete type (the type of a property, of a signal's data, of a result)
+ * @param signature
+ * @param what what the type is of, for the message
+ */
+export function checkSingleType(signature, what) {
+    let types;
+    try {
+        types = Signature.parse(signature).length;
+    }
+    catch (error) {
+        throw new TypeError(`Invalid DBus signature "${signature}" of ${what}: ${error.message}`, { cause: error });
+    }
+    if (types !== 1)
+        throw new TypeError(`Invalid DBus signature "${signature}" of ${what}: a single complete type, such as "s" or "a{sv}"`);
+    return signature;
+}
 /**
  * Check the name of a member
  * @param name
@@ -69,5 +97,6 @@ export function errorName(error) {
     if (INTERFACE_NAME.test(candidate))
         return candidate;
     const element = candidate.replace(/[^A-Za-z0-9_]/g, '_');
-    return /^[A-Za-z_]/.test(element) ? element : `E${element}`;
+    //An element of an error name starts with a letter
+    return /^[A-Za-z]/.test(element) ? element : `E${element}`;
 }

package/dist/types/adapters/DBusEntrypoint.d.ts

@@ -1,4 +1,5 @@
 import type { EntrypointAdapter, MiddlewareDefinition } from '@lakutata/entrypoint';
+import { type DecodeOpts } from 'dbus-sdk';
 import { DBusContext } from '../context/DBusContext.js';
 /**
  * The options of {@link dbusEntrypoint}: the bus to connect to, and the service name to own on it.
@@ -19,9 +20,10 @@ export type DBusEntrypointOptions = {
      */
     bus?: 'session' | 'system' | string;
     /**
-     * The well-known name the service owns on the bus (`'com.example.DeviceService'`): two or more elements separated by
-     * dots. The clients address the service by it, and it prefixes the names of the D-Bus errors. On the system bus,
-     * the bus policy (`/etc/dbus-1/system.d/`) must allow the process to own it.
+     * The well-known name the service owns on the bus (`'com.example.DeviceService'`): two or more elements of letters,
+     * digits and `_`, separated by dots. The clients address the service by it, and it prefixes the names of the D-Bus
+     * errors (which may not hold the `-` that D-Bus allows in the names of the services). On the system bus, the bus
+     * policy (`/etc/dbus-1/system.d/`) must allow the process to own it.
      */
     service: string;
     /**
@@ -32,10 +34,17 @@ export type DBusEntrypointOptions = {
     replaceExisting?: boolean;
     /**
      * Let another connection take the name with `replaceExisting`. The adapter is not stopped when the name is taken:
-     * the clients reach the new owner.
+     * the clients reach the new owner, and the adapter keeps running without the name, which it does not get back when
+     * the new owner releases it.
      * @default false
      */
     allowReplacement?: boolean;
+    /**
+     * How the arguments of the method calls and the values the clients write to the properties are decoded
+     * (`DecodeOpts` of `dbus-sdk`): `types`, `dictionaries`, `int64` (`'number'` or `'bigint'`), as for the client.
+     * @default {int64: 'number'} (the 64-bit integers as numbers when they are safe integers, else bigints)
+     */
+    decode?: DecodeOpts;
     /**
      * The middlewares of this adapter's method calls, run after the entrypoint's global middlewares.
      * @default []

package/dist/types/channel/DBusChannel.d.ts

@@ -28,9 +28,11 @@ declare module '@lakutata/entrypoint' {
 }
 /**
  * The definition of the D-Bus channel of the entrypoint, named `dbus`: its actions are the methods of D-Bus interfaces,
- * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template from
- * `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching none
- * fails with `ControllerActionNotFoundException`. `@DBusMethod` and {@link dbusEntrypoint} use it: an application only
- * needs it to write an adapter of its own.
+ * addressed by `{member, interface, path}` (the method name from `@DBusMethod`, the interface and the path template
+ * from `@DBusInterface`). A call matches an action by its interface, its method and its object path; a call matching
+ * none fails with `ControllerActionNotFoundException` in an adapter dispatching through the channel (with
+ * {@link dbusEntrypoint}, the bus answers such a call with `org.freedesktop.DBus.Error.UnknownObject` or
+ * `UnknownMethod`).
+ * `@DBusMethod` and {@link dbusEntrypoint} use it: an application only needs it to write an adapter of its own.
  */
 export declare const DBusChannel: ChannelDefinition;

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

@@ -27,7 +27,7 @@ export type DBusMethodOptions = ActionOptions<DBusContext> & {
  * (`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.
+ * most. A name declared twice in an interface is served by the declaration registered last, as on the other channels.
  * @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`.
@@ -76,7 +76,7 @@ export declare function DBusMethod<ClassPrototype extends Controller, Method>(na
  * 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.
+ * most. A name declared twice in an interface is served by the declaration registered last, as on the other channels.
  * @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
@@ -90,7 +90,7 @@ export declare function DBusMethod<ClassPrototype extends Controller, Method, DT
  * 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.
+ * most. A name declared twice in an interface is served by the declaration registered last, as on the other channels.
  * @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
@@ -105,7 +105,7 @@ export declare function DBusMethod<ClassPrototype extends Controller, Method>(na
  * 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.
+ * most. A name declared twice in an interface is served by the declaration registered last, as on the other channels.
  * @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.

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

@@ -17,7 +17,7 @@ export interface DBusClientOptions {
     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
+     * @default none: a call waits for its reply
      */
     callTimeout?: number;
     /**

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

@@ -151,11 +151,12 @@ export declare function defineDBusSignal<T = Record<string, unknown>>(name: stri
  * @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 type The D-Bus signature of its values (`'s'`, `'i'`, `'b'`, `'a{sv}'`…), a single complete type; 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.
+ * @throws {TypeError} When the name or the signature is invalid.
  * @example
  * ```typescript
  * import {DTO} from 'lakutata'

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

@@ -3,6 +3,18 @@
  * @param name
  */
 export declare function checkInterfaceName(name: string): string;
+/**
+ * Check the well-known name of a service. D-Bus allows "-" in the bus names, but the names of the errors are prefixed by
+ * the name of the service, and an error name may not hold it
+ * @param name
+ */
+export declare function checkServiceName(name: string): string;
+/**
+ * Check a D-Bus signature holding a single complete type (the type of a property, of a signal's data, of a result)
+ * @param signature
+ * @param what what the type is of, for the message
+ */
+export declare function checkSingleType(signature: string, what: string): string;
 /**
  * Check the name of a member
  * @param name

package/package.json

@@ -1,7 +1,26 @@
 {
   "name": "@lakutata/dbus",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "The DBus channel of the lakutata framework: controller actions served as the methods, properties and signals of DBus objects, and the DBus client component.",
+  "keywords": [
+    "lakutata",
+    "dbus",
+    "d-bus",
+    "linux",
+    "ipc",
+    "typescript"
+  ],
+  "homepage": "https://lakutata.com/packages/dbus",
+  "bugs": {
+    "url": "https://github.com/lakutata/lakutata/issues",
+    "email": "admin@lakutata.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lakutata/lakutata.git",
+    "directory": "packages/dbus"
+  },
+  "author": "alex.ma",
   "type": "module",
   "main": "./dist/cjs/exports/DBus.js",
   "types": "./dist/cjs/exports/DBus.d.ts",
@@ -32,11 +51,11 @@
     "dbus-sdk": "^2.0.1"
   },
   "peerDependencies": {
-    "@lakutata/core": "3.0.0",
-    "@lakutata/entrypoint": "3.0.0"
+    "@lakutata/core": "3.1.0",
+    "@lakutata/entrypoint": "3.1.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": "^22.13.0 || >=24.11.0"
   },
   "files": [
     "dist",