@lakutata/dbus 2.3.1 → 3.0.0-beta.0

package/dist/cjs/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;

package/dist/cjs/lib/Declarations.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineDBusSignal = defineDBusSignal;
+exports.defineDBusProperty = defineDBusProperty;
+exports.setDBusInterfaceDeclaration = setDBusInterfaceDeclaration;
+exports.getDBusInterfaceDeclaration = getDBusInterfaceDeclaration;
+const core_1 = require("@lakutata/core");
+const Names_js_1 = require("./Names.js");
+const Signature_js_1 = require("./Signature.js");
+/**
+ * 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')
+ * ```
+ */
+function defineDBusSignal(name, data = 'a{sv}') {
+    (0, Names_js_1.checkMemberName)(name, 'signal');
+    const isDTO = typeof data === 'function';
+    return {
+        kind: 'signal',
+        name: name,
+        type: isDTO ? (0, Signature_js_1.schemaSignature)(data) : data,
+        validate: (value) => isDTO ? data.validate(value) : value
+    };
+}
+/**
+ * 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}`)
+ * })
+ * ```
+ */
+function defineDBusProperty(name, type, options = {}) {
+    (0, Names_js_1.checkMemberName)(name, 'property');
+    const schema = options.schema;
+    return {
+        kind: 'property',
+        name: name,
+        type: type,
+        writable: options.writable === true,
+        initial: options.initial,
+        validate: (value) => schema ? core_1.DTO.validate(value, schema) : value
+    };
+}
+const DBUS_INTERFACE = Symbol('DBUS.INTERFACE');
+/**
+ * Keep the declaration of the interface of a controller
+ * @param controller
+ * @param declaration
+ */
+function setDBusInterfaceDeclaration(controller, declaration) {
+    (0, Names_js_1.checkInterfaceName)(declaration.interface);
+    (0, Names_js_1.checkPathTemplate)(declaration.path);
+    Reflect.defineMetadata(DBUS_INTERFACE, declaration, controller);
+}
+/**
+ * The declaration of the interface of a controller, or of its nearest parent class declaring one
+ * @param controller
+ */
+function getDBusInterfaceDeclaration(controller) {
+    return Reflect.getMetadata(DBUS_INTERFACE, controller);
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Check the name of an interface
+ * @param name
+ */
+export declare function checkInterfaceName(name: string): string;
+/**
+ * Check the name of a member
+ * @param name
+ * @param kind
+ */
+export declare function checkMemberName(name: string, kind: string): string;
+/**
+ * Check an object path, or a template of object paths
+ * @param path
+ */
+export declare function checkPathTemplate(path: string): string;
+/**
+ * A template of object paths
+ */
+export type PathTemplate = {
+    readonly template: string;
+    readonly variables: string[];
+    readonly static: boolean;
+    match(path: string): Record<string, string> | undefined;
+};
+/**
+ * Compile a template of object paths
+ * @param template
+ */
+export declare function compilePathTemplate(template: string): PathTemplate;
+/**
+ * The name of the DBus error of an exception: its errno, or its name
+ * @param error
+ */
+export declare function errorName(error: unknown): string;

package/dist/cjs/lib/Names.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkInterfaceName = checkInterfaceName;
+exports.checkMemberName = checkMemberName;
+exports.checkPathTemplate = checkPathTemplate;
+exports.compilePathTemplate = compilePathTemplate;
+exports.errorName = errorName;
+/**
+ * The names of the interfaces and of the errors: dot-separated elements
+ */
+const INTERFACE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)+$/;
+/**
+ * The names of the members: the methods, the properties and the signals
+ */
+const MEMBER_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The object paths, their elements may be variables of a template ("/com/example/Devices/{sn}")
+ */
+const PATH_TEMPLATE = /^\/$|^(\/([A-Za-z0-9_]+|\{[A-Za-z_][A-Za-z0-9_]*}))+$/;
+/**
+ * Check the name of an interface
+ * @param name
+ */
+function checkInterfaceName(name) {
+    if (typeof name !== 'string' || name.length > 255 || !INTERFACE_NAME.test(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 name of a member
+ * @param name
+ * @param kind
+ */
+function checkMemberName(name, kind) {
+    if (typeof name !== 'string' || name.length > 255 || !MEMBER_NAME.test(name))
+        throw new TypeError(`Invalid DBus ${kind} name "${name}": letters, digits and "_", not starting with a digit`);
+    return name;
+}
+/**
+ * Check an object path, or a template of object paths
+ * @param path
+ */
+function checkPathTemplate(path) {
+    if (typeof path !== 'string' || !PATH_TEMPLATE.test(path))
+        throw new TypeError(`Invalid DBus object path "${path}": "/" separated elements of letters, digits and "_", or variables such as "{sn}"`);
+    return path;
+}
+/**
+ * Compile a template of object paths
+ * @param template
+ */
+function compilePathTemplate(template) {
+    const variables = [];
+    const expression = new RegExp(`^${checkPathTemplate(template).replace(/\{([A-Za-z_][A-Za-z0-9_]*)}/g, (matched, name) => {
+        variables.push(name);
+        return '([A-Za-z0-9_]+)';
+    })}$`);
+    return {
+        template: template,
+        variables: variables,
+        static: !variables.length,
+        match: (path) => {
+            const matched = expression.exec(path);
+            return matched ? Object.fromEntries(variables.map((name, index) => [name, matched[index + 1]])) : undefined;
+        }
+    };
+}
+/**
+ * The name of the DBus error of an exception: its errno, or its name
+ * @param error
+ */
+function errorName(error) {
+    const { errno, name } = (error && typeof error === 'object' ? error : {});
+    const candidate = String(errno ?? name ?? 'Error');
+    //A dotted name is a full DBus error name, the others are prefixed by the service name
+    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}`;
+}

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

@@ -0,0 +1,14 @@
+import { DTO, type Schema } from '@lakutata/core';
+/**
+ * The DBus signature of the values of a schema: an object is a dictionary of variants,
+ * the scalars have their own types, the other values are variants
+ * @param schema
+ */
+export declare function schemaSignature(schema: Schema | typeof DTO): string;
+/**
+ * A value ready to be encoded: the dates are ISO strings, the undefined and null values are removed (a variant has no null);
+ * the typed values of dbus-sdk (`DBusUInt32`, `DBusVariant`…) are kept as they are, a Map keeps its entries (its keys
+ * keep their types)
+ * @param value
+ */
+export declare function toEncodable(value: unknown): unknown;

package/dist/cjs/lib/Signature.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.schemaSignature = schemaSignature;
+exports.toEncodable = toEncodable;
+const dbus_sdk_1 = require("dbus-sdk");
+/**
+ * The DBus signature of the values of a schema: an object is a dictionary of variants,
+ * the scalars have their own types, the other values are variants
+ * @param schema
+ */
+function schemaSignature(schema) {
+    const target = typeof schema === 'function' ? schema.Schema() : schema;
+    switch (target?.type) {
+        case 'object':
+            return 'a{sv}';
+        case 'string':
+            return 's';
+        case 'boolean':
+            return 'b';
+        case 'number':
+            return (target._rules ?? []).some((rule) => rule.name === 'integer') ? 'x' : 'd';
+        case 'bigint':
+            return 'x';
+        case 'array':
+            return 'av';
+        default:
+            return 'v';
+    }
+}
+/**
+ * A value ready to be encoded: the dates are ISO strings, the undefined and null values are removed (a variant has no null);
+ * the typed values of dbus-sdk (`DBusUInt32`, `DBusVariant`…) are kept as they are, a Map keeps its entries (its keys
+ * keep their types)
+ * @param value
+ */
+function toEncodable(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value instanceof dbus_sdk_1.DBusSignedValue)
+        return value;
+    if (Array.isArray(value))
+        return value.filter((item) => item !== undefined && item !== null).map(toEncodable);
+    if (value instanceof Map)
+        return new Map([...value].filter(([, item]) => item !== undefined && item !== null).map(([key, item]) => [key, toEncodable(item)]));
+    if (value && typeof value === 'object' && !Buffer.isBuffer(value) && !(value instanceof Uint8Array)) {
+        const encodable = {};
+        for (const [key, item] of Object.entries(value))
+            if (item !== undefined && item !== null)
+                encodable[key] = toEncodable(item);
+        return encodable;
+    }
+    return value;
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/types/DBusContextParams.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The parameters of a {@link DBusContext}: the adapter builds them for each method call it receives. An application
+ * builds them only to create a context itself, in a test of a controller.
+ */
+export type DBusContextParams = {
+    /**
+     * The object path of the method call (`'/com/example/Devices/A1'`), the variables of its template resolved.
+     */
+    readonly path: string;
+    /**
+     * The name of the interface called (`'com.example.Device'`).
+     */
+    readonly interface: string;
+    /**
+     * The name of the method called (`'Status'`).
+     */
+    readonly member: string;
+    /**
+     * The input of the call: the entries of its `a{sv}` dictionary, an empty object for a method without input.
+     */
+    readonly data: Record<string, any>;
+};

package/dist/cjs/types/DBusContextParams.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });