@iobroker/js-controller-adapter 7.2.3 → 8.0.0-alpha.2-20260923-99da17fcc

package/build/cjs/lib/adapter/managers/MessagingManager.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/lib/adapter/managers/MessagingManager.ts"],
+  "sourcesContent": ["import type { Client as StatesInRedisClient } from '@iobroker/db-states-redis';\nimport type {\n    InternalSendToHostOptions,\n    InternalSendToOptions,\n    NotificationOptions,\n    SendToOptions,\n    SendToUserInterfaceClientOptions,\n} from '../../_Types.js';\nimport type { AdapterContext } from '@/lib/adapter/context.js';\nimport { AdapterContextBase } from '@/lib/adapter/managers/AdapterContextBase.js';\nimport { isMessageboxSupported } from '@/lib/adapter/utils.js';\n\n/** Entry in the pending-reply registry for sendTo calls with expectReply=true */\ninterface PendingReply {\n    resolve: (msg: any) => void;\n    reject: (e: Error) => void;\n    timer?: NodeJS.Timeout;\n    time: number;\n}\n\n/** Owns the adapter's outbound messaging and the pending-reply registry. */\nexport class MessagingManager extends AdapterContextBase {\n    readonly #pending = new Map<number, PendingReply>();\n    #callbackId = 1;\n    #mboxSubscribed = false;\n\n    /**\n     * @param ctx Shared adapter context providing live runtime state\n     */\n    constructor(ctx: AdapterContext) {\n        super(ctx);\n    }\n\n    /**\n     * Sends a message to another adapter instance.\n     *\n     * When `opts.expectReply` is true and the target is a specific instance (not broadcast),\n     * the returned promise resolves with the reply message when it arrives, or rejects with\n     * `Error('Timeout exceeded')` if `opts.options.timeout` elapses.\n     *\n     * @param opts Normalized send options\n     */\n    async sendTo(opts: InternalSendToOptions): Promise<any> {\n        const { command, message, callback, options, expectReply } = opts;\n        let { instanceName } = opts;\n\n        if (!instanceName) {\n            throw new Error('No instanceName provided or not a string');\n        }\n\n        if (!instanceName.startsWith('system.adapter.')) {\n            instanceName = `system.adapter.${instanceName}`;\n        }\n\n        const obj: ioBroker.SendableMessage = {\n            command,\n            message,\n            from: `system.adapter.${this.namespace}`,\n        };\n\n        const states = this.states;\n\n        if (typeof message !== 'object') {\n            this.logger.silly(\n                `${this.namespaceLog} sendTo \"${command}\" to ${instanceName} from system.adapter.${this.namespace}: ${message}`,\n            );\n        } else {\n            this.logger.silly(\n                `${this.namespaceLog} sendTo \"${command}\" to ${instanceName} from system.adapter.${this.namespace}`,\n            );\n        }\n\n        if (!instanceName.match(/\\.[0-9]+$/)) {\n            const objects = this.objects;\n\n            // Only the instance lookup is best-effort; per-instance push errors must surface.\n            const res = await objects\n                .getObjectView('system', 'instance', {\n                    startkey: `${instanceName}.`,\n                    endkey: `${instanceName}.\\u9999`,\n                })\n                .catch(() => undefined);\n\n            if (res) {\n                for (const row of res.rows) {\n                    await states.pushMessage(row.id, obj);\n                }\n            }\n            return;\n        }\n\n        if (expectReply) {\n            return this.#registerReply(states, instanceName, obj, options);\n        }\n\n        if (callback) {\n            obj.callback = { ...callback, ack: true };\n        }\n\n        await states.pushMessage(instanceName, obj);\n    }\n\n    /**\n     * Subscribes to this instance's messagebox on demand when the adapter does not advertise\n     * messagebox support, so replies to outbound messages are received. Idempotent.\n     *\n     * @param states the connected states DB client\n     */\n    #maybeSubscribe(states: StatesInRedisClient): void {\n        const common = this.common;\n        if (common && !isMessageboxSupported(common) && !this.#mboxSubscribed) {\n            this.#mboxSubscribed = true;\n            states\n                .subscribeMessage(`system.adapter.${this.namespace}`)\n                .catch(e => this.logger.error(`${this.namespaceLog} Cannot subscribe to messages: ${e.message}`));\n        }\n    }\n\n    /**\n     * Sets a reply callback header on `obj`, registers a pending-reply resolver keyed by its id,\n     * subscribes the messagebox on demand, pushes the message and returns a promise that resolves\n     * with the reply once `resolveCallback` is invoked for the matching id, or rejects with\n     * `Error('Timeout exceeded')` when `options.timeout` elapses.\n     *\n     * @param states the connected states DB client\n     * @param target the recipient id (instance or host) for `pushMessage`\n     * @param obj the message to send; its `callback` header is set here\n     * @param options additional send options (e.g. timeout)\n     */\n    async #registerReply(\n        states: StatesInRedisClient,\n        target: string,\n        obj: ioBroker.SendableMessage,\n        options?: SendToOptions,\n    ): Promise<any> {\n        this.#maybeSubscribe(states);\n\n        const id = this.#callbackId++;\n        if (this.#callbackId >= 0xffffffff) {\n            this.#callbackId = 1;\n        }\n\n        obj.callback = {\n            message: obj.message,\n            id,\n            ack: false,\n            time: Date.now(),\n        };\n\n        let pendingEntry!: PendingReply;\n        const replyPromise = new Promise<any>((resolve, reject) => {\n            let timer: NodeJS.Timeout | undefined;\n            if (options?.timeout) {\n                timer = setTimeout(() => {\n                    if (this.#pending.has(id)) {\n                        this.#pending.delete(id);\n                        reject(new Error('Timeout exceeded'));\n                    }\n                }, options.timeout);\n            }\n\n            pendingEntry = { resolve, reject, timer, time: Date.now() };\n            this.#pending.set(id, pendingEntry);\n        });\n\n        const now = Date.now();\n        for (const [_id, entry] of this.#pending) {\n            if (now - entry.time > 3_600_000) {\n                this.#pending.delete(_id);\n            }\n        }\n\n        try {\n            await states.pushMessage(target, obj);\n        } catch (e) {\n            if (pendingEntry.timer) {\n                clearTimeout(pendingEntry.timer);\n            }\n            this.#pending.delete(id);\n            throw e;\n        }\n        return replyPromise;\n    }\n\n    /**\n     * Sends a message to a host, or broadcasts to all hosts when `hostName` is `null`.\n     *\n     * When `opts.expectReply` is true and a specific host is targeted, the returned promise\n     * resolves with the reply message when it arrives, or rejects with `Error('Timeout exceeded')`\n     * if `opts.options.timeout` elapses. Broadcasts (hostName === null) resolve void.\n     *\n     * @param opts Normalized send options\n     */\n    async sendToHost(opts: InternalSendToHostOptions): Promise<any> {\n        const { command, message, expectReply, options, callback } = opts;\n        let { hostName } = opts;\n        const obj: ioBroker.SendableMessage = {\n            command,\n            message,\n            from: `system.adapter.${this.namespace}`,\n        };\n\n        const states = this.states;\n\n        if (hostName && !hostName.startsWith('system.host.')) {\n            hostName = `system.host.${hostName}`;\n        }\n\n        if (!hostName) {\n            const objects = this.objects;\n\n            const res = await objects.getObjectList({ startkey: 'system.host.', endkey: 'system.host.\\u9999' });\n\n            if (res?.rows.length) {\n                for (const row of res.rows) {\n                    const parts: string[] = row.id.split('.');\n                    // ignore system.host.name.alive and so on\n                    if (parts.length === 3) {\n                        await states.pushMessage(row.id, obj);\n                    }\n                }\n            }\n            return;\n        }\n\n        if (expectReply) {\n            return this.#registerReply(states, hostName, obj, options);\n        }\n\n        if (callback) {\n            obj.callback = { ...callback, ack: true };\n        }\n\n        await states.pushMessage(hostName, obj);\n    }\n\n    /**\n     * Resolves a pending reply promise for an acked messagebox message.\n     * Returns true if a pending entry was found and consumed.\n     *\n     * @param obj incoming message object from the messagebox\n     */\n    resolveCallback(obj: ioBroker.Message): boolean {\n        if (!obj.callback?.ack || !obj.callback.id) {\n            return false;\n        }\n\n        const entry = this.#pending.get(obj.callback.id);\n        if (!entry) {\n            return false;\n        }\n\n        if (entry.timer) {\n            clearTimeout(entry.timer);\n        }\n        this.#pending.delete(obj.callback.id);\n        entry.resolve(obj.message);\n\n        const now = Date.now();\n        for (const [id, pending] of this.#pending) {\n            if (now - pending.time > 3_600_000) {\n                this.#pending.delete(id);\n            }\n        }\n\n        return true;\n    }\n\n    /**\n     * Rejects all pending reply promises and clears their timers (used on stop).\n     */\n    clearPendingCallbacks(): void {\n        if (this.#pending.size) {\n            const err = new Error('Adapter stopped');\n            for (const entry of this.#pending.values()) {\n                if (entry.timer) {\n                    clearTimeout(entry.timer);\n                }\n                entry.reject(err);\n            }\n            this.#pending.clear();\n        }\n    }\n\n    /**\n     * Sends a message to a single UI client, or broadcasts to all connected UI clients when `clientId` is omitted.\n     *\n     * @param options clientId and data options\n     */\n    sendToUI(options: SendToUserInterfaceClientOptions): Promise<void> {\n        const states = this.states;\n\n        const { clientId, data } = options;\n\n        if (clientId === undefined) {\n            return this.uiMessagingController.sendToAllClients({\n                data,\n                states,\n            });\n        }\n\n        return this.uiMessagingController.sendToClient({\n            clientId,\n            data,\n            states,\n        });\n    }\n\n    /**\n     * Sends an addNotification command to the host of this adapter instance.\n     *\n     * @param scope notification scope\n     * @param category notification category, or `null` to match by scope regex\n     * @param message notification message\n     * @param options additional notification options\n     */\n    async registerNotification(\n        scope: string,\n        category: string | null,\n        message: string,\n        options?: NotificationOptions,\n    ): Promise<void> {\n        const states = this.states;\n\n        const obj = {\n            command: 'addNotification',\n            message: {\n                scope,\n                category,\n                message,\n                instance: this.namespace,\n                contextData: options?.contextData,\n            },\n            from: `system.adapter.${this.namespace}`,\n        };\n\n        await states.pushMessage(`system.host.${this.host}`, obj);\n    }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/build/cjs/lib/adapter/managers/ResourceManager.d.ts

@@ -0,0 +1,69 @@
+import type { AdapterContext } from '../../../lib/adapter/context.js';
+import { AdapterContextBase } from '../../../lib/adapter/managers/AdapterContextBase.js';
+import type { MessagingManager } from '../../../lib/adapter/managers/MessagingManager.js';
+/**
+ * Owns the adapter's exclusive-resource registry. Register/free requests are forwarded to the host
+ * this instance runs on, which keeps `system.host.<hostname>.usedResources.<type>` up to date; reads
+ * go straight to those states.
+ */
+export declare class ResourceManager extends AdapterContextBase {
+    #private;
+    /**
+     * @param ctx Shared adapter context providing live runtime state
+     * @param getMessaging Returns the adapter's messaging manager. Passed as a getter rather than an
+     *        instance because it is created lazily - and it has to be *the* one, since it owns the map
+     *        the host's reply is matched against.
+     */
+    constructor(ctx: AdapterContext, getMessaging: () => MessagingManager);
+    /**
+     * Registers an exclusive resource as used by this instance by forwarding it to the host.
+     *
+     * Registering is additive - one call per occupied resource, in any order. The host drops what this
+     * instance registered before when it starts, so there is nothing to reset by hand.
+     *
+     * @param type the kind of resource, e.g. "serialPort" or "tcpPort"
+     * @param data payload describing the resource
+     * @throws {Error} when the host refuses the registration or does not answer
+     */
+    registerUsedResource<T extends ioBroker.UsedResourceType>(type: T, data: ioBroker.UsedResourceData<T>): Promise<void>;
+    /**
+     * Asks the host whether another instance currently holds a resource, without registering anything.
+     *
+     * Meant to be called *before* the port or the device is opened: afterwards the operating system
+     * has already decided the conflict, and all this can add is a better error message.
+     *
+     * The answer is a hint, not a permission. The registry only knows what adapters declare, so an
+     * empty list does not promise the resource is free - something outside ioBroker may hold it.
+     *
+     * @param type the kind of resource, e.g. "serialPort" or "tcpPort"
+     * @param data description of the resource that is about to be used
+     * @returns the entries of other instances that currently hold it, newest first
+     * @throws {Error} when the host refuses the request or does not answer
+     */
+    checkUsedResource<T extends ioBroker.UsedResourceType>(type: T, data?: Partial<ioBroker.UsedResourceData<T>>): Promise<ioBroker.RegisteredResource[]>;
+    /**
+     * Frees all exclusive resources this instance registered, across all types, by forwarding it to the host.
+     *
+     * @throws {Error} when the host refuses the command or does not answer
+     */
+    clearUsedResources(): Promise<void>;
+    /**
+     * Frees previously registered exclusive resources of this instance by forwarding it to the host.
+     *
+     * @param type the kind of resource, e.g. "serialPort" or "tcpPort"
+     * @param data fields identifying the resources to free; if omitted, all resources of `type` are freed
+     * @throws {Error} when the host refuses the command or does not answer
+     */
+    freeUsedResource<T extends ioBroker.UsedResourceType>(type: T, data?: Partial<ioBroker.UsedResourceData<T>>): Promise<void>;
+    /**
+     * Reads the exclusive resources of the given type currently registered on this instance's host, across
+     * all its instances.
+     *
+     * @param type resource type to read, e.g. "serialPort"
+     * @throws {Error} when the host of this instance is unknown
+     */
+    getHostUsedResources<T extends ioBroker.UsedResourceType>(type: T): Promise<ioBroker.RegisteredResource<T>[]>;
+    /** Reads the exclusive resources of every type currently registered on this instance's host. */
+    getHostUsedResources(): Promise<ioBroker.RegisteredResource[]>;
+}
+//# sourceMappingURL=ResourceManager.d.ts.map

package/build/cjs/lib/adapter/managers/ResourceManager.js

@@ -0,0 +1,170 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ResourceManager_exports = {};
+__export(ResourceManager_exports, {
+  ResourceManager: () => ResourceManager
+});
+module.exports = __toCommonJS(ResourceManager_exports);
+var import_tools = require("@iobroker/js-controller-common-db/tools");
+var import_AdapterContextBase = require("../../../lib/adapter/managers/AdapterContextBase.js");
+const USED_RESOURCES_ID = "usedResources";
+const HOST_REPLY_TIMEOUT = 5e3;
+class ResourceManager extends import_AdapterContextBase.AdapterContextBase {
+  static {
+    __name(this, "ResourceManager");
+  }
+  #getMessaging;
+  /**
+   * @param ctx Shared adapter context providing live runtime state
+   * @param getMessaging Returns the adapter's messaging manager. Passed as a getter rather than an
+   *        instance because it is created lazily - and it has to be *the* one, since it owns the map
+   *        the host's reply is matched against.
+   */
+  constructor(ctx, getMessaging) {
+    super(ctx);
+    this.#getMessaging = getMessaging;
+  }
+  /**
+   * Send a mutating command to the host this instance runs on and wait for its verdict.
+   *
+   * The host validates every one of these - resource type, payload shape, the sending instance and
+   * whether it declares its resources at all - and answers with `{ error }` when it refuses. Without
+   * waiting for that answer the adapter would get a resolved promise for a call that did nothing,
+   * and the only trace would be a warning in a log the adapter developer does not read.
+   *
+   * @param command the host command, e.g. "registerUsedResource"
+   * @param message the command payload
+   * @returns the host's answer
+   * @throws {Error} when the host is unknown, does not answer in time, or refuses the command
+   */
+  async #sendToHost(command, message) {
+    if (!this.host) {
+      throw new Error(`${command}: host of this instance is unknown`);
+    }
+    const answer = await this.#getMessaging().sendToHost({
+      hostName: this.host,
+      command,
+      message,
+      expectReply: true,
+      // without one there is no timer at all, so an older controller which does not know the
+      // command would leave this promise pending forever
+      options: { timeout: HOST_REPLY_TIMEOUT }
+    });
+    if (answer?.error) {
+      throw new Error(`${command} was refused by the host: ${answer.error}`);
+    }
+    return answer;
+  }
+  /**
+   * Registers an exclusive resource as used by this instance by forwarding it to the host.
+   *
+   * Registering is additive - one call per occupied resource, in any order. The host drops what this
+   * instance registered before when it starts, so there is nothing to reset by hand.
+   *
+   * @param type the kind of resource, e.g. "serialPort" or "tcpPort"
+   * @param data payload describing the resource
+   * @throws {Error} when the host refuses the registration or does not answer
+   */
+  async registerUsedResource(type, data) {
+    await this.#sendToHost("registerUsedResource", { type, data, instance: this.namespace });
+  }
+  /**
+   * Asks the host whether another instance currently holds a resource, without registering anything.
+   *
+   * Meant to be called *before* the port or the device is opened: afterwards the operating system
+   * has already decided the conflict, and all this can add is a better error message.
+   *
+   * The answer is a hint, not a permission. The registry only knows what adapters declare, so an
+   * empty list does not promise the resource is free - something outside ioBroker may hold it.
+   *
+   * @param type the kind of resource, e.g. "serialPort" or "tcpPort"
+   * @param data description of the resource that is about to be used
+   * @returns the entries of other instances that currently hold it, newest first
+   * @throws {Error} when the host refuses the request or does not answer
+   */
+  async checkUsedResource(type, data) {
+    const answer = await this.#sendToHost("checkUsedResource", { type, data, instance: this.namespace });
+    return Array.isArray(answer?.conflicts) ? answer.conflicts : [];
+  }
+  /**
+   * Frees all exclusive resources this instance registered, across all types, by forwarding it to the host.
+   *
+   * @throws {Error} when the host refuses the command or does not answer
+   */
+  async clearUsedResources() {
+    await this.#sendToHost("clearUsedResources", { instance: this.namespace });
+  }
+  /**
+   * Frees previously registered exclusive resources of this instance by forwarding it to the host.
+   *
+   * @param type the kind of resource, e.g. "serialPort" or "tcpPort"
+   * @param data fields identifying the resources to free; if omitted, all resources of `type` are freed
+   * @throws {Error} when the host refuses the command or does not answer
+   */
+  async freeUsedResource(type, data) {
+    await this.#sendToHost("freeUsedResource", { type, data, instance: this.namespace });
+  }
+  /**
+   * @param type resource type to read; if omitted, the resources of every type are read
+   */
+  async getHostUsedResources(type) {
+    if (!this.host) {
+      throw new Error("getHostUsedResources: host of this instance is unknown");
+    }
+    const states = this.states;
+    const prefix = `system.host.${this.host}.${USED_RESOURCES_ID}`;
+    if (type !== void 0) {
+      const state = await states.getState(`${prefix}.${type}`);
+      return ResourceManager.#parseResources(state);
+    }
+    const keys = await states.getKeys(`${prefix}.*`);
+    const resources = [];
+    if (keys?.length) {
+      const values = await states.getStates(keys);
+      for (const state of values) {
+        resources.push(...ResourceManager.#parseResources(state));
+      }
+    }
+    return resources;
+  }
+  /**
+   * Parses a `usedResources` state value (a JSON-encoded array) into a typed list, ignoring
+   * malformed or empty content.
+   *
+   * @param state the state holding the JSON-encoded resource array, if any
+   */
+  static #parseResources(state) {
+    if (state && typeof state.val === "string" && state.val) {
+      try {
+        const parsed = JSON.parse(state.val);
+        if (Array.isArray(parsed)) {
+          return parsed.filter((entry) => (0, import_tools.hasRegisteredResourceShape)(entry));
+        }
+      } catch {
+      }
+    }
+    return [];
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ResourceManager
+});
+//# sourceMappingURL=ResourceManager.js.map

package/build/cjs/lib/adapter/managers/ResourceManager.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/lib/adapter/managers/ResourceManager.ts"],
+  "sourcesContent": ["import { hasRegisteredResourceShape } from '@iobroker/js-controller-common-db/tools';\nimport type { AdapterContext } from '@/lib/adapter/context.js';\nimport { AdapterContextBase } from '@/lib/adapter/managers/AdapterContextBase.js';\nimport type { MessagingManager } from '@/lib/adapter/managers/MessagingManager.js';\n\n/** Sub-id under a host holding the exclusive resources registered as used by its instances. */\nconst USED_RESOURCES_ID = 'usedResources';\n/** How long a mutating command waits for the host to answer, in ms */\nconst HOST_REPLY_TIMEOUT = 5_000;\n\n/**\n * Owns the adapter's exclusive-resource registry. Register/free requests are forwarded to the host\n * this instance runs on, which keeps `system.host.<hostname>.usedResources.<type>` up to date; reads\n * go straight to those states.\n */\nexport class ResourceManager extends AdapterContextBase {\n    readonly #getMessaging: () => MessagingManager;\n\n    /**\n     * @param ctx Shared adapter context providing live runtime state\n     * @param getMessaging Returns the adapter's messaging manager. Passed as a getter rather than an\n     *        instance because it is created lazily - and it has to be *the* one, since it owns the map\n     *        the host's reply is matched against.\n     */\n    constructor(ctx: AdapterContext, getMessaging: () => MessagingManager) {\n        super(ctx);\n        this.#getMessaging = getMessaging;\n    }\n\n    /**\n     * Send a mutating command to the host this instance runs on and wait for its verdict.\n     *\n     * The host validates every one of these - resource type, payload shape, the sending instance and\n     * whether it declares its resources at all - and answers with `{ error }` when it refuses. Without\n     * waiting for that answer the adapter would get a resolved promise for a call that did nothing,\n     * and the only trace would be a warning in a log the adapter developer does not read.\n     *\n     * @param command the host command, e.g. \"registerUsedResource\"\n     * @param message the command payload\n     * @returns the host's answer\n     * @throws {Error} when the host is unknown, does not answer in time, or refuses the command\n     */\n    async #sendToHost(command: string, message: Record<string, unknown>): Promise<any> {\n        if (!this.host) {\n            throw new Error(`${command}: host of this instance is unknown`);\n        }\n\n        const answer = await this.#getMessaging().sendToHost({\n            hostName: this.host,\n            command,\n            message,\n            expectReply: true,\n            // without one there is no timer at all, so an older controller which does not know the\n            // command would leave this promise pending forever\n            options: { timeout: HOST_REPLY_TIMEOUT },\n        });\n\n        if (answer?.error) {\n            throw new Error(`${command} was refused by the host: ${answer.error}`);\n        }\n\n        return answer;\n    }\n\n    /**\n     * Registers an exclusive resource as used by this instance by forwarding it to the host.\n     *\n     * Registering is additive - one call per occupied resource, in any order. The host drops what this\n     * instance registered before when it starts, so there is nothing to reset by hand.\n     *\n     * @param type the kind of resource, e.g. \"serialPort\" or \"tcpPort\"\n     * @param data payload describing the resource\n     * @throws {Error} when the host refuses the registration or does not answer\n     */\n    async registerUsedResource<T extends ioBroker.UsedResourceType>(\n        type: T,\n        data: ioBroker.UsedResourceData<T>,\n    ): Promise<void> {\n        await this.#sendToHost('registerUsedResource', { type, data, instance: this.namespace });\n    }\n\n    /**\n     * Asks the host whether another instance currently holds a resource, without registering anything.\n     *\n     * Meant to be called *before* the port or the device is opened: afterwards the operating system\n     * has already decided the conflict, and all this can add is a better error message.\n     *\n     * The answer is a hint, not a permission. The registry only knows what adapters declare, so an\n     * empty list does not promise the resource is free - something outside ioBroker may hold it.\n     *\n     * @param type the kind of resource, e.g. \"serialPort\" or \"tcpPort\"\n     * @param data description of the resource that is about to be used\n     * @returns the entries of other instances that currently hold it, newest first\n     * @throws {Error} when the host refuses the request or does not answer\n     */\n    async checkUsedResource<T extends ioBroker.UsedResourceType>(\n        type: T,\n        data?: Partial<ioBroker.UsedResourceData<T>>,\n    ): Promise<ioBroker.RegisteredResource[]> {\n        const answer = await this.#sendToHost('checkUsedResource', { type, data, instance: this.namespace });\n        return Array.isArray(answer?.conflicts) ? answer.conflicts : [];\n    }\n\n    /**\n     * Frees all exclusive resources this instance registered, across all types, by forwarding it to the host.\n     *\n     * @throws {Error} when the host refuses the command or does not answer\n     */\n    async clearUsedResources(): Promise<void> {\n        await this.#sendToHost('clearUsedResources', { instance: this.namespace });\n    }\n\n    /**\n     * Frees previously registered exclusive resources of this instance by forwarding it to the host.\n     *\n     * @param type the kind of resource, e.g. \"serialPort\" or \"tcpPort\"\n     * @param data fields identifying the resources to free; if omitted, all resources of `type` are freed\n     * @throws {Error} when the host refuses the command or does not answer\n     */\n    async freeUsedResource<T extends ioBroker.UsedResourceType>(\n        type: T,\n        data?: Partial<ioBroker.UsedResourceData<T>>,\n    ): Promise<void> {\n        await this.#sendToHost('freeUsedResource', { type, data, instance: this.namespace });\n    }\n\n    /**\n     * Reads the exclusive resources of the given type currently registered on this instance's host, across\n     * all its instances.\n     *\n     * @param type resource type to read, e.g. \"serialPort\"\n     * @throws {Error} when the host of this instance is unknown\n     */\n    async getHostUsedResources<T extends ioBroker.UsedResourceType>(type: T): Promise<ioBroker.RegisteredResource<T>[]>;\n    /** Reads the exclusive resources of every type currently registered on this instance's host. */\n    async getHostUsedResources(): Promise<ioBroker.RegisteredResource[]>;\n\n    /**\n     * @param type resource type to read; if omitted, the resources of every type are read\n     */\n    async getHostUsedResources(type?: ioBroker.UsedResourceType): Promise<ioBroker.RegisteredResource[]> {\n        if (!this.host) {\n            throw new Error('getHostUsedResources: host of this instance is unknown');\n        }\n\n        const states = this.states;\n        const prefix = `system.host.${this.host}.${USED_RESOURCES_ID}`;\n\n        if (type !== undefined) {\n            const state = await states.getState(`${prefix}.${type}`);\n            return ResourceManager.#parseResources<ioBroker.RegisteredResource>(state);\n        }\n\n        const keys = await states.getKeys(`${prefix}.*`);\n\n        const resources: ioBroker.RegisteredResource[] = [];\n        if (keys?.length) {\n            const values = await states.getStates(keys);\n            for (const state of values) {\n                resources.push(...ResourceManager.#parseResources<ioBroker.RegisteredResource>(state));\n            }\n        }\n\n        return resources;\n    }\n\n    /**\n     * Parses a `usedResources` state value (a JSON-encoded array) into a typed list, ignoring\n     * malformed or empty content.\n     *\n     * @param state the state holding the JSON-encoded resource array, if any\n     */\n    static #parseResources<R extends ioBroker.RegisteredResource>(state: ioBroker.State | null | undefined): R[] {\n        if (state && typeof state.val === 'string' && state.val) {\n            try {\n                const parsed: unknown = JSON.parse(state.val);\n                if (Array.isArray(parsed)) {\n                    // The same check the host applies when it reads these states back. They are declared\n                    // read-only, but nothing enforces that, so an entry that is not a resource at all must not\n                    // reach the caller as if it were one.\n                    return parsed.filter(entry => hasRegisteredResourceShape(entry)) as R[];\n                }\n            } catch {\n                // ignore malformed content\n            }\n        }\n        return [];\n    }\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;;;;;AAAA,mBAA2C;AAE3C,gCAAmC;AAInC,MAAM,oBAAoB;AAE1B,MAAM,qBAAqB;AAOrB,MAAO,wBAAwB,6CAAkB;EAfvD,OAeuD;;;EAC1C;;;;;;;EAQT,YAAY,KAAqB,cAAoC;AACjE,UAAM,GAAG;AACT,SAAK,gBAAgB;EACzB;;;;;;;;;;;;;;EAeA,MAAM,YAAY,SAAiB,SAAgC;AAC/D,QAAI,CAAC,KAAK,MAAM;AACZ,YAAM,IAAI,MAAM,GAAG,OAAO,oCAAoC;IAClE;AAEA,UAAM,SAAS,MAAM,KAAK,cAAa,EAAG,WAAW;MACjD,UAAU,KAAK;MACf;MACA;MACA,aAAa;;;MAGb,SAAS,EAAE,SAAS,mBAAkB;KACzC;AAED,QAAI,QAAQ,OAAO;AACf,YAAM,IAAI,MAAM,GAAG,OAAO,6BAA6B,OAAO,KAAK,EAAE;IACzE;AAEA,WAAO;EACX;;;;;;;;;;;EAYA,MAAM,qBACF,MACA,MAAkC;AAElC,UAAM,KAAK,YAAY,wBAAwB,EAAE,MAAM,MAAM,UAAU,KAAK,UAAS,CAAE;EAC3F;;;;;;;;;;;;;;;EAgBA,MAAM,kBACF,MACA,MAA4C;AAE5C,UAAM,SAAS,MAAM,KAAK,YAAY,qBAAqB,EAAE,MAAM,MAAM,UAAU,KAAK,UAAS,CAAE;AACnG,WAAO,MAAM,QAAQ,QAAQ,SAAS,IAAI,OAAO,YAAY,CAAA;EACjE;;;;;;EAOA,MAAM,qBAAkB;AACpB,UAAM,KAAK,YAAY,sBAAsB,EAAE,UAAU,KAAK,UAAS,CAAE;EAC7E;;;;;;;;EASA,MAAM,iBACF,MACA,MAA4C;AAE5C,UAAM,KAAK,YAAY,oBAAoB,EAAE,MAAM,MAAM,UAAU,KAAK,UAAS,CAAE;EACvF;;;;EAgBA,MAAM,qBAAqB,MAAgC;AACvD,QAAI,CAAC,KAAK,MAAM;AACZ,YAAM,IAAI,MAAM,wDAAwD;IAC5E;AAEA,UAAM,SAAS,KAAK;AACpB,UAAM,SAAS,eAAe,KAAK,IAAI,IAAI,iBAAiB;AAE5D,QAAI,SAAS,QAAW;AACpB,YAAM,QAAQ,MAAM,OAAO,SAAS,GAAG,MAAM,IAAI,IAAI,EAAE;AACvD,aAAO,gBAAgB,gBAA6C,KAAK;IAC7E;AAEA,UAAM,OAAO,MAAM,OAAO,QAAQ,GAAG,MAAM,IAAI;AAE/C,UAAM,YAA2C,CAAA;AACjD,QAAI,MAAM,QAAQ;AACd,YAAM,SAAS,MAAM,OAAO,UAAU,IAAI;AAC1C,iBAAW,SAAS,QAAQ;AACxB,kBAAU,KAAK,GAAG,gBAAgB,gBAA6C,KAAK,CAAC;MACzF;IACJ;AAEA,WAAO;EACX;;;;;;;EAQA,OAAO,gBAAuD,OAAwC;AAClG,QAAI,SAAS,OAAO,MAAM,QAAQ,YAAY,MAAM,KAAK;AACrD,UAAI;AACA,cAAM,SAAkB,KAAK,MAAM,MAAM,GAAG;AAC5C,YAAI,MAAM,QAAQ,MAAM,GAAG;AAIvB,iBAAO,OAAO,OAAO,eAAS,yCAA2B,KAAK,CAAC;QACnE;MACJ,QAAQ;MAER;IACJ;AACA,WAAO,CAAA;EACX;;",
+  "names": []
+}

package/build/cjs/lib/adapter/managers/SubscriptionManager.d.ts

@@ -0,0 +1,107 @@
+import type { Pattern } from '../../_Types.js';
+import type { AdapterContext } from '../../../lib/adapter/context.js';
+import { AdapterContextBase } from '../../../lib/adapter/managers/AdapterContextBase.js';
+import type { AliasManager } from '../../../lib/adapter/managers/AliasManager.js';
+/** Prefixes an id or pattern with this adapter's namespace unless already namespaced. Bound to the adapter's Validator. */
+export type FixId = (id: string, isPattern?: boolean) => string;
+type SubOptions = {
+    user?: ioBroker.ObjectIDs.User;
+} | null | undefined;
+/** Reads the objects matching a pattern, used to discover alias objects during state subscription. */
+export interface ObjectAccess {
+    /**
+     * Objects matching `pattern`, keyed by id. Bound to the legacy `getForeignObjects(pattern, null, null, options)`
+     * call, whose `null` type/enums args clobber `options` — so no type filter and no user-ACL are applied;
+     * only `alias.*` ids in the result are consumed. Kept as-is for behavior parity.
+     */
+    getForeignStateObjects(pattern: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<Record<string, ioBroker.AnyObject>>;
+}
+/** Owns object-, file- and state-change subscriptions plus the auto-subscribe bookkeeping. */
+export declare class SubscriptionManager extends AdapterContextBase {
+    #private;
+    /**
+     * @param ctx Shared adapter context providing live runtime state
+     * @param fixId Namespace-prefixer bound to the adapter's Validator
+     * @param aliasManager Alias subscription cache and bookkeeping
+     * @param objectAccess Reader for state-typed objects matching a pattern
+     */
+    constructor(ctx: AdapterContext, fixId: FixId, aliasManager: AliasManager, objectAccess: ObjectAccess);
+    /**
+     * Subscribe to object changes within this instance's namespace.
+     *
+     * @param pattern pattern without namespace, `*` for all own objects, or an array of patterns
+     *        passed through as-is (not namespaced)
+     * @param options optional user context
+     */
+    subscribeObjects(pattern: Pattern, options?: SubOptions): Promise<void>;
+    /**
+     * Unsubscribe from object changes within this instance's namespace.
+     *
+     * @param pattern pattern without namespace, `*` for all own objects, or an array of patterns
+     *        passed through as-is (not namespaced)
+     * @param options optional user context
+     */
+    unsubscribeObjects(pattern: Pattern, options?: SubOptions): Promise<void>;
+    /**
+     * Subscribe to object changes in any instance.
+     *
+     * @param pattern pattern or array of patterns
+     * @param options optional user context
+     */
+    subscribeForeignObjects(pattern: Pattern, options?: SubOptions): Promise<void>;
+    /**
+     * Unsubscribe from object changes in any instance.
+     *
+     * @param pattern pattern or array of patterns (defaults to `*`)
+     * @param options optional user context
+     */
+    unsubscribeForeignObjects(pattern: Pattern, options?: SubOptions): Promise<void>;
+    /**
+     * Subscribe to file changes in a specific instance.
+     *
+     * @param id adapter id, e.g. `vis-2.0`
+     * @param pattern pattern or array of patterns
+     * @param options optional user context
+     */
+    subscribeForeignFiles(id: string, pattern: Pattern, options?: SubOptions): Promise<void>;
+    /**
+     * Unsubscribe from file changes in a specific instance.
+     *
+     * @param id adapter id, e.g. `vis-2.0`
+     * @param pattern pattern or array of patterns (defaults to `*`)
+     * @param options optional user context
+     */
+    unsubscribeForeignFiles(id: string, pattern: Pattern, options?: SubOptions): Promise<void>;
+    /**
+     * Register an instance as auto-subscribable (its `subscribes` counter is maintained on subscribe/unsubscribe).
+     *
+     * @param id instance id, e.g. `pushover.0`
+     */
+    addSubscribableInstance(id: string): void;
+    /**
+     * Stop treating an instance as auto-subscribable.
+     *
+     * @param id instance id, e.g. `pushover.0`
+     */
+    removeSubscribableInstance(id: string): void;
+    /** Populate the auto-subscribe instance list from the objects DB. */
+    autoSubscribeOn(): Promise<void>;
+    /**
+     * Subscribe to state changes in any instance, resolving aliases and maintaining auto-subscribe counters.
+     *
+     * @param pattern pattern, `*`, an `alias.*` id, or an array of ids/patterns
+     * @param options optional user context
+     */
+    subscribeForeignStates(pattern: Pattern, options?: SubOptions): Promise<void>;
+    /**
+     * Unsubscribe from state changes in any instance, mirroring {@link subscribeForeignStates}.
+     *
+     * @param pattern pattern, `*`, an `alias.*` id, or an array of ids/patterns
+     * @param options optional user context
+     */
+    unsubscribeForeignStates(pattern: Pattern, options?: SubOptions): Promise<void>;
+}
+export {};
+//# sourceMappingURL=SubscriptionManager.d.ts.map