@iobroker/js-controller-adapter 7.0.2 → 7.0.3

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

@@ -18,6 +18,10 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
@@ -28,6 +32,7 @@ __export(adapter_exports, {
   AdapterClass: () => AdapterClass
 });
 module.exports = __toCommonJS(adapter_exports);
+var __import_meta_url = typeof document === "undefined" ? new (require("url".replace("", ""))).URL("file:" + __filename).href : document.currentScript && document.currentScript.src || new URL("main.js", document.baseURI).href;
 var import_node_net = __toESM(require("node:net"), 1);
 var import_fs_extra = __toESM(require("fs-extra"), 1);
 var import_node_os = __toESM(require("node:os"), 1);
@@ -49,20 +54,26 @@ var import_constants = require("../../lib/adapter/constants.js");
 var import_userInterfaceMessagingController = require("../../lib/adapter/userInterfaceMessagingController.js");
 var import_constants2 = require("@iobroker/js-controller-common-db/constants");
 var url = __toESM(require("node:url"), 1);
-const import_meta = {};
 const controllerVersion = import_package.default.version;
 const { FORBIDDEN_CHARS } = import_js_controller_common.tools;
-const thisDir = url.fileURLToPath(new URL(".", import_meta.url || `file://${__filename}`));
+const thisDir = url.fileURLToPath(new URL(".", __import_meta_url || `file://${__filename}`));
 import_js_controller_common.tools.ensureDNSOrder();
 class AdapterClass extends import_node_events.EventEmitter {
+  /** Cache of all deprecations which have already been transmitted */
   reportedDeprecations = /* @__PURE__ */ new Set();
+  /** Instance to access states DB */
   #states;
+  /** Instance to access objects DB */
   #objects;
+  /** States DB constructor */
   States;
+  /** Objects DB constructor */
   Objects;
+  /** Contents of iobroker.json */
   _config;
   _options;
   startedInCompactMode;
+  /** List of instances which want our logs */
   logList = /* @__PURE__ */ new Set();
   aliases = /* @__PURE__ */ new Map();
   aliasPatterns = /* @__PURE__ */ new Set();
@@ -70,8 +81,17 @@ class AdapterClass extends import_node_events.EventEmitter {
   eventLoopLags = [];
   overwriteLogLevel = false;
   adapterReady = false;
+  /** Callbacks from sendTo */
   messageCallbacks = /* @__PURE__ */ new Map();
+  /**
+   * Contains a live cache of the adapter's states.
+   * NOTE: This is only defined if the adapter was initialized with the option states: true.
+   */
   oStates;
+  /**
+   * Contains a live cache of the adapter's objects.
+   * NOTE: This is only defined if the adapter was initialized with the option objects: true.
+   */
   oObjects;
   _stopInProgress = false;
   _callbackId = 1;
@@ -79,6 +99,7 @@ class AdapterClass extends import_node_events.EventEmitter {
   _timers = /* @__PURE__ */ new Set();
   _intervals = /* @__PURE__ */ new Set();
   _delays = /* @__PURE__ */ new Set();
+  /** For ease of use the log property is always defined, however it is only available after `ready` has been called. */
   log;
   performStrictObjectChecks;
   _logger;
@@ -88,13 +109,20 @@ class AdapterClass extends import_node_events.EventEmitter {
   namespace;
   name;
   _systemSecret;
+  /** Whether the adapter has already terminated */
   terminated = false;
+  /** The cache of usernames */
   usernames = {};
+  /** A RegExp to test for forbidden chars in object IDs */
   FORBIDDEN_CHARS = FORBIDDEN_CHARS;
   inputCount = 0;
   outputCount = 0;
+  /** The cache of users */
   users = {};
+  // todo
+  /** The cache of user groups */
   groups = {};
+  /** An array of instances, that support auto subscribe */
   autoSubscribe = [];
   defaultHistory = null;
   pluginHandler;
@@ -102,19 +130,29 @@ class AdapterClass extends import_node_events.EventEmitter {
   getPortRunning = null;
   _namespaceRegExp;
   instance;
+  // @ts-expect-error decide how to handle it
   _utils;
+  /** contents of io-package.json */
   adapterConfig;
   connected;
   adapterDir;
+  /** contents of package.json */
   pack;
+  /** contents of io-package.json */
   ioPack;
   _initializeTimeout;
   inited;
+  /** contents of iobroker.json if required via AdapterOptions */
   systemConfig;
+  /** the configured date format of system.config, only available if requested via AdapterOptions `useFormatDate` */
   dateFormat;
+  /** if float comma instead of dot is used, only available if requested via AdapterOptions `useFormatDate` */
   isFloatComma;
+  /** configured language of system.config, only available if requested via AdapterOptions `useFormatDate` */
   language;
+  /** longitude configured in system.config, only available if requested via AdapterOptions `useFormatDate`*/
   longitude;
+  /** latitude configured in system.config, only available if requested via AdapterOptions `useFormatDate`*/
   latitude;
   _defaultObjs;
   _aliasObjectsSubscribed;
@@ -122,19 +160,32 @@ class AdapterClass extends import_node_events.EventEmitter {
   host;
   common;
   mboxSubscribed;
+  /** Stop the adapter */
   stop;
   version;
+  /** Stop the adapter only defined in compact, not for external usage */
   kill;
   processLog;
+  /**
+   * Start or stop subscribing to log messages
+   * The method is only available if logTransporter is active via io-pack or adapter options
+   * Note, that stopping will stop after 10 seconds, not immediately
+   *
+   * @param isActive - if log subscription should be activated or deactivated
+   * @param options - options passed to setState e.g. user permissions
+   */
   requireLog;
   logOffTimer;
   logRequired;
   patterns;
   statesConnectedTime;
+  /** Constants for frequent use in adapters */
   constants = {
     STATE_QUALITY: import_constants.STATE_QUALITY
   };
+  /** Features supported by the running instance */
   SUPPORTED_FEATURES = (0, import_utils.getSupportedFeatures)();
+  /** Controller for messaging related functionality */
   uiMessagingController;
   constructor(options) {
     super();
@@ -327,9 +378,20 @@ class AdapterClass extends import_node_events.EventEmitter {
     this.setExecutableCapabilities = import_js_controller_common.tools.setExecutableCapabilities;
     this._init();
   }
+  /**
+   * Get the adapter scoped package identifier of a node module
+   *
+   * @param moduleName name of the node module
+   */
   getAdapterScopedPackageIdentifier(moduleName) {
     return (0, import_utils.getAdapterScopedPackageIdentifier)({ moduleName, namespace: this.namespace });
   }
+  /**
+   * Install specified npm module
+   *
+   * @param moduleNameOrUrl name of the node module or GitHub url which can be passed to `npm install`
+   * @param options version information
+   */
   installNodeModule(moduleNameOrUrl, options) {
     import_validator.Validator.assertString(moduleNameOrUrl, "moduleNameOrUrl");
     import_validator.Validator.assertObject(options, "options");
@@ -346,19 +408,39 @@ class AdapterClass extends import_node_events.EventEmitter {
     const packageIdentifier = isUrl ? moduleNameOrUrl : `npm:${moduleName}@${version}`;
     return import_js_controller_common.tools.installNodeModule(`${internalModuleName}@${packageIdentifier}`);
   }
+  /**
+   * List all additional installed node modules from this adapter
+   */
   listInstalledNodeModules() {
     return (0, import_utils.listInstalledNodeModules)(this.namespace);
   }
+  /**
+   * Uninstall specified npm module
+   *
+   * @param moduleName name of the node module
+   */
   uninstallNodeModule(moduleName) {
     import_validator.Validator.assertString(moduleName, "moduleName");
     const internalModuleName = (0, import_utils.getAdapterScopedPackageIdentifier)({ moduleName, namespace: this.namespace });
     return import_js_controller_common.tools.uninstallNodeModule(internalModuleName);
   }
+  /**
+   * Import a node module which has been installed via `installNodeModule`
+   *
+   * @param moduleName name of the node module
+   * @returns the required node module
+   */
   importNodeModule(moduleName) {
     import_validator.Validator.assertString(moduleName, "moduleName");
     const internalModuleName = (0, import_utils.getAdapterScopedPackageIdentifier)({ moduleName, namespace: this.namespace });
     return import(internalModuleName);
   }
+  /**
+   * Decrypt the password/value with given key
+   *
+   * @param secretVal to use for decrypt (or value if only one parameter is given)
+   * @param value value to decrypt (if secret is provided)
+   */
   decrypt(secretVal, value) {
     if (value === void 0) {
       value = secretVal;
@@ -368,6 +450,12 @@ class AdapterClass extends import_node_events.EventEmitter {
     import_validator.Validator.assertString(value, "value");
     return import_js_controller_common.tools.decrypt(secretVal, value);
   }
+  /**
+   * Encrypt the password/value with given key
+   *
+   * @param secretVal to use for encrypting (or value if only one parameter is given)
+   * @param [value] value to encrypt (if secret is provided)
+   */
   encrypt(secretVal, value) {
     if (value === void 0) {
       value = secretVal;
@@ -377,11 +465,13 @@ class AdapterClass extends import_node_events.EventEmitter {
     import_validator.Validator.assertString(value, "value");
     return import_js_controller_common.tools.encrypt(secretVal, value);
   }
+  // unknown guard implementation
   getSession(id, callback) {
     import_validator.Validator.assertString(id, "id");
     import_validator.Validator.assertCallback(callback, "callback");
     return this._getSession({ id, callback });
   }
+  // actual implementation
   _getSession(options) {
     if (!this.#states) {
       this._logger.info(`${this.namespaceLog} getSession not processed because States database not connected`);
@@ -389,6 +479,7 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#states.getSession(options.id, options.callback);
   }
+  // unknown implementation guards
   setSession(id, ttl, data, callback) {
     import_validator.Validator.assertString(id, "id");
     import_validator.Validator.assertOptionalCallback(callback, "callback");
@@ -396,6 +487,7 @@ class AdapterClass extends import_node_events.EventEmitter {
     import_validator.Validator.assertObject(data, "data");
     return this._setSession({ id, ttl, data, callback });
   }
+  // actual implementation
   _setSession(options) {
     if (!this.#states) {
       this._logger.info(`${this.namespaceLog} setSession not processed because States database not connected`);
@@ -424,6 +516,14 @@ class AdapterClass extends import_node_events.EventEmitter {
       return [];
     }
   }
+  /**
+   * stops the execution of adapter, but not disables it.
+   *
+   * Sometimes, the adapter must be stopped if some libraries are missing.
+   *
+   * @param reason optional termination description
+   * @param exitCode optional exit code
+   */
   terminate(reason, exitCode) {
     if (this.terminated) {
       return;
@@ -480,6 +580,23 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }, 500);
   }
+  /**
+   * Helper function to find next free port
+   *
+   * Looks for first free TCP port starting with given one:
+   * ```js
+   *     adapter.getPort(8081, function (port) {
+   *         adapter.log.debug('Following port is free: ' + port);
+   *     });
+   * ```
+   *
+   * @param port port number to start the search for free port
+   * @param [host] optional hostname for the port search
+   * @param callback return result
+   *        ```js
+   *        function (port) {}
+   *        ```
+   */
   getPort(port, host, callback) {
     if (!port) {
       throw new Error("adapterGetPort: no port");
@@ -519,12 +636,38 @@ class AdapterClass extends import_node_events.EventEmitter {
       setImmediate(() => this.getPort(options.port + 1, options.host, options.callback));
     }
   }
+  /**
+       * Method to check for available Features for adapter development
+       *
+       * Use it like ...
+       * ```js
+       *     if (adapter.supportsFeature && adapter.supportsFeature('ALIAS')) {
+       *         ...
+       *     }
+       * ```
+  
+       * @param featureName the name of the feature to check
+       * @returns true/false if the feature is in the list of supported features
+       */
   supportsFeature(featureName) {
     if (typeof featureName === "string") {
       return this.SUPPORTED_FEATURES.includes(featureName);
     }
     return false;
   }
+  /**
+   * validates user and password
+   *
+   * @param user user name as text
+   * @param pw password as text
+   * @param [options] optional user context
+   * @param callback return result
+   *        ```js
+   *            function (result) {
+   *              if (result) adapter.log.debug('User is valid');
+   *            }
+   *        ```
+   */
   checkPassword(user, pw, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -569,6 +712,9 @@ class AdapterClass extends import_node_events.EventEmitter {
       });
     });
   }
+  /**
+   * This method update the cached values in `this.usernames`
+   */
   async _updateUsernameCache() {
     try {
       const obj = await this.getObjectListAsync({ startkey: "system.user.", endkey: "system.user.\u9999" });
@@ -584,6 +730,11 @@ class AdapterClass extends import_node_events.EventEmitter {
       throw new Error(`Could not update user cache: ${e.message}`);
     }
   }
+  /**
+   * Return ID of given username
+   *
+   * @param username - name of the user
+   */
   getUserID(username) {
     import_validator.Validator.assertString(username, "username");
     return this._getUserID({ username });
@@ -602,6 +753,19 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return this.usernames[options.username].id;
   }
+  /**
+   * sets the user's password
+   *
+   * @param user user name as text
+   * @param pw password as text
+   * @param [options] optional user context
+   * @param [callback] return result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot set password: ' + err);
+   *            }
+   *        ```
+   */
   setPassword(user, pw, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -660,6 +824,21 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     });
   }
+  /**
+   * returns if user exists and is in the group
+   *
+   * This function used mostly internally and the adapter developer do not require it.
+   *
+   * @param user user name as text
+   * @param group group name
+   * @param [options] optional user context
+   * @param callback return result
+   *        ```js
+   *            function (result) {
+   *              if (result) adapter.log.debug('User exists and in the group');
+   *            }
+   *        ```
+   */
   checkGroup(user, group, options, callback) {
     user = user || "";
     if (typeof options === "function") {
@@ -709,6 +888,99 @@ class AdapterClass extends import_node_events.EventEmitter {
       });
     });
   }
+  /**
+   * get the user permissions
+   *
+   * This function used mostly internally and the adapter developer do not require it.
+   * The function reads permissions of user's groups (it can be more than one) and merge permissions together
+   *
+   * @param  user user name as text
+   * @param  commandsPermissions object that describes the access rights like
+   *     ```js
+   *         // static information
+   *         var commandsPermissions = {
+   *            getObject:          {type: 'object',    operation: 'read'},
+   *            getObjects:         {type: 'object',    operation: 'list'},
+   *            getObjectView:      {type: 'object',    operation: 'list'},
+   *            setObject:          {type: 'object',    operation: 'write'},
+   *            subscribeObjects:   {type: 'object',    operation: 'read'},
+   *            unsubscribeObjects: {type: 'object',    operation: 'read'},
+   *            subscribeFiles:     {type: 'object',    operation: 'read'},
+   *            unsubscribeFiles:   {type: 'object',    operation: 'read'},
+   *
+   *            getStates:          {type: 'state',     operation: 'list'},
+   *            getState:           {type: 'state',     operation: 'read'},
+   *            setState:           {type: 'state',     operation: 'write'},
+   *            getStateHistory:    {type: 'state',     operation: 'read'},
+   *            subscribe:          {type: 'state',     operation: 'read'},
+   *            unsubscribe:        {type: 'state',     operation: 'read'},
+   *            getVersion:         {type: '',          operation: ''},
+   *
+   *            httpGet:            {type: 'other',     operation: 'http'},
+   *            sendTo:             {type: 'other',     operation: 'sendto'},
+   *            sendToHost:         {type: 'other',     operation: 'sendto'},
+   *
+   *            readFile:           {type: 'file',      operation: 'read'},
+   *            readFile64:         {type: 'file',      operation: 'read'},
+   *            writeFile:          {type: 'file',      operation: 'write'},
+   *            writeFile64:        {type: 'file',      operation: 'write'},
+   *            unlink:             {type: 'file',      operation: 'delete'},
+   *            rename:             {type: 'file',      operation: 'write'},
+   *            mkdir:              {type: 'file',      operation: 'write'},
+   *            readDir:            {type: 'file',      operation: 'list'},
+   *            chmodFile:          {type: 'file',      operation: 'write'},
+   *            chownFile:          {type: 'file',      operation: 'write'},
+   *
+   *            authEnabled:        {type: '',          operation: ''},
+   *            disconnect:         {type: '',          operation: ''},
+   *            listPermissions:    {type: '',          operation: ''},
+   *            getUserPermissions: {type: 'object',    operation: 'read'}
+   *         };
+   *        ```
+   * @param [options] optional user context
+   * @param [callback] return result
+   *        ```js
+   *            function (acl) {
+   *              // Access control object for admin looks like:
+   *              // {
+   *              //    file: {
+   *              //         read:       true,
+   *              //         write:      true,
+   *              //         'delete':   true,
+   *              //         create:     true,
+   *              //         list:       true
+   *              //     },
+   *              //     object: {
+   *              //         read:       true,
+   *              //         write:      true,
+   *              //         'delete':   true,
+   *              //         list:       true
+   *              //     },
+   *              //     state: {
+   *              //         read:       true,
+   *              //         write:      true,
+   *              //         'delete':   true,
+   *              //         create:     true,
+   *              //         list:       true
+   *              //     },
+   *              //     user: 'admin',
+   *              //     users:  {
+   *              //         read:       true,
+   *              //         write:      true,
+   *              //         create:     true,
+   *              //         'delete':   true,
+   *              //         list:       true
+   *              //     },
+   *              //     other: {
+   *              //         execute:    true,
+   *              //         http:       true,
+   *              //         sendto:     true
+   *              //     },
+   *              //     groups: ['administrator'] // can be more than one
+   *              // }
+   *            }
+   *        ```
+   */
   calculatePermissions(user, commandsPermissions, options, callback) {
     user = user || "";
     if (typeof options === "function") {
@@ -773,6 +1045,7 @@ class AdapterClass extends import_node_events.EventEmitter {
                   create: true,
                   list: true
                 },
+                // @ts-expect-error create is missing
                 object: {
                   read: true,
                   write: true,
@@ -830,6 +1103,11 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallback(options.callback, acl);
     });
   }
+  /**
+   * Stop an instance gracefully
+   *
+   * @param options information about the stoppage
+   */
   async _stop(options = {}) {
     const { isPause, isScheduled, reason } = options;
     let { exitCode, updateAliveState } = options;
@@ -911,6 +1189,12 @@ class AdapterClass extends import_node_events.EventEmitter {
       }, this.common?.stopTimeout || 500);
     }
   }
+  /**
+   * Reads the file certificate from a given path and adds a file watcher to restart adapter on cert changes
+   * if a cert is passed it is returned as it is
+   *
+   * @param cert cert or path to cert
+   */
   _readFileCertificate(cert) {
     if (typeof cert === "string") {
       try {
@@ -928,6 +1212,25 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return cert;
   }
+  /**
+   * returns SSL certificates by name
+   *
+   * This function returns SSL certificates (private key, public cert and chained certificate).
+   * Names are defined in the system's configuration in admin, e.g. "defaultPrivate", "defaultPublic".
+   * The result can be directly used for creation of https server.
+   *
+   * @param [publicName] public certificate name
+   * @param [privateName] private certificate name
+   * @param [chainedName] optional chained certificate name
+   * @param callback return result
+   *        ```js
+   *            function (err, certs, letsEncrypt) {
+   *              adapter.log.debug('private key: ' + certs.key);
+   *              adapter.log.debug('public cert: ' + certs.cert);
+   *              adapter.log.debug('chained cert: ' + certs.ca);
+   *            }
+   *        ```
+   */
   getCertificates(publicName, privateName, chainedName, callback) {
     if (typeof publicName === "function") {
       callback = publicName;
@@ -995,6 +1298,10 @@ class AdapterClass extends import_node_events.EventEmitter {
       ca
     }, obj.native.letsEncrypt);
   }
+  /**
+   * Restarts an instance of the adapter.
+   *
+   */
   restart() {
     if (this.stop) {
       this._logger.warn(`${this.namespaceLog} Restart initiated`);
@@ -1003,6 +1310,16 @@ class AdapterClass extends import_node_events.EventEmitter {
       this._logger.warn(`${this.namespaceLog} Cannot initiate restart, because this.stop is not defined`);
     }
   }
+  /**
+   * Updates the adapter config with new values. Only a subset of the configuration has to be provided,
+   * since merging with the existing config is done automatically, e.g., like this:
+   *
+   * `adapter.updateConfig({prop1: "newValue1"})`
+   *
+   * After updating the configuration, the adapter is automatically restarted.
+   *
+   * @param newConfig The new config values to be stored
+   */
   updateConfig(newConfig) {
     import_validator.Validator.assertObject(newConfig, "newConfig");
     return this._updateConfig({ newConfig });
@@ -1032,6 +1349,10 @@ class AdapterClass extends import_node_events.EventEmitter {
     obj.native = mergedConfig;
     return this.setForeignObjectAsync(configObjId, obj);
   }
+  /**
+   * Disables and stops the adapter instance.
+   *
+   */
   async disable() {
     const configObjId = `system.adapter.${this.namespace}`;
     let obj;
@@ -1046,6 +1367,14 @@ class AdapterClass extends import_node_events.EventEmitter {
     obj.common.enabled = false;
     return this.setForeignObjectAsync(configObjId, obj);
   }
+  /**
+   * Reads the encrypted parameter from config.
+   *
+   * It returns promise if no callback is provided.
+   *
+   * @param attribute - attribute name in native configuration part
+   * @param [callback] - optional callback
+   */
   getEncryptedConfig(attribute, callback) {
     import_validator.Validator.assertString(attribute, "attribute");
     import_validator.Validator.assertOptionalCallback(callback, "callback");
@@ -1060,6 +1389,9 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return import_js_controller_common.tools.maybeCallbackWithError(callback, `Attribute "${attribute}" not found`);
   }
+  /**
+   * Get the system secret, after retrieved once it will be read from the cache
+   */
   async getSystemSecret() {
     if (this._systemSecret !== void 0) {
       return this._systemSecret;
@@ -1074,6 +1406,16 @@ class AdapterClass extends import_node_events.EventEmitter {
     this._systemSecret = this._systemSecret || import_constants.DEFAULT_SECRET;
     return this._systemSecret;
   }
+  /**
+   * Same as setTimeout,
+   * but it clears the running timers during the unloading process
+   * does not work after unload has been called
+   *
+   * @param cb - timer callback
+   * @param timeout - timeout in milliseconds
+   * @param args - as many arguments as needed, which will be passed to setTimeout
+   * @returns timer id
+   */
   setTimeout(cb, timeout, ...args) {
     if (typeof cb !== "function") {
       this._logger.warn(`${this.namespaceLog} setTimeout expected callback to be of type "function", but got "${typeof cb}"`);
@@ -1092,6 +1434,12 @@ class AdapterClass extends import_node_events.EventEmitter {
     this._timers.add(timer);
     return timer;
   }
+  /**
+   * Same as clearTimeout
+   * but it checks the running timers on unload
+   *
+   * @param timer - the timer object
+   */
   clearTimeout(timer) {
     if (timer === void 0) {
       return;
@@ -1099,6 +1447,13 @@ class AdapterClass extends import_node_events.EventEmitter {
     clearTimeout(timer);
     this._timers.delete(timer);
   }
+  /**
+   * delays the fulfillment of the promise the amount of time.
+   * it will not fulfill during and after adapter shutdown
+   *
+   * @param timeout - timeout in milliseconds
+   * @returns promise when timeout is over
+   */
   delay(timeout) {
     if (this._stopInProgress) {
       this._logger.warn(`${this.namespaceLog} delay called, but adapter is shutting down`);
@@ -1114,6 +1469,16 @@ class AdapterClass extends import_node_events.EventEmitter {
       this._delays.add(timer);
     });
   }
+  /**
+   * Same as setInterval
+   * but it clears the running intervals during the unload process
+   * does not work after unload has been called
+   *
+   * @param cb - interval callback
+   * @param timeout - interval in milliseconds
+   * @param args - as many arguments as needed, which will be passed to setTimeout
+   * @returns interval interval object
+   */
   setInterval(cb, timeout, ...args) {
     if (typeof cb !== "function") {
       this._logger.error(`${this.namespaceLog} setInterval expected callback to be of type "function", but got "${typeof cb}"`);
@@ -1129,6 +1494,12 @@ class AdapterClass extends import_node_events.EventEmitter {
     this._intervals.add(id);
     return id;
   }
+  /**
+   * Same as clearInterval
+   * but it checks the running intervals on unload
+   *
+   * @param interval - interval object
+   */
   clearInterval(interval) {
     if (interval === void 0) {
       return;
@@ -1136,6 +1507,36 @@ class AdapterClass extends import_node_events.EventEmitter {
     clearInterval(interval);
     this._intervals.delete(interval);
   }
+  /**
+   * Creates or overwrites an object in objectDB.
+   *
+   * This function can create or overwrite objects in objectDB for this adapter.
+   * Only Ids that belong to this adapter can be modified. So the function automatically adds "adapter.X." to ID.
+   * <b>common</b>, <b>native</b> and <b>type</b> attributes are mandatory, and it will be checked.
+   * Additionally, type "state" requires <b>role</b>, <b>type</b> and <b>name</b>, e.g.:
+   * ```js
+   * {
+   *     common: {
+   *          name: 'object name',
+   *          type: 'number', // string, boolean, object, mixed, array
+   *          role: 'value'   // see https://github.com/ioBroker/ioBroker/blob/master/doc/SCHEMA.md#state-commonrole
+   *     },
+   *     native: {},
+   *     type: 'state' // channel, device
+   * }
+   * ```
+   *
+   * @param id object ID, that must be overwritten or created.
+   * @param obj new object
+   * @param [options] optional user context
+   * @param [callback] return result
+   *        ```js
+   *            function (err, obj) {
+   *              // obj is {id: id}
+   *              if (err) adapter.log.error('Cannot write object: ' + err);
+   *            }
+   *        ```
+   */
   setObject(id, obj, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1213,6 +1614,14 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallbackWithError(options.callback, "mandatory property type missing!");
     }
   }
+  /**
+   * Helper method for `set[Foreign]Object[NotExists]` that also sets the default value if one is configured
+   *
+   * @param id of the object
+   * @param obj The object to set
+   * @param options optional user context
+   * @param callback optional callback
+   */
   async _setObjectWithDefaultValue(id, obj, options, callback) {
     if (!this.#objects) {
       this._logger.info(`${this.namespaceLog} setObject not processed because Objects database not connected`);
@@ -1248,6 +1657,18 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallbackWithError(callback, e);
     }
   }
+  /**
+   * Get all states, channels and devices of this adapter.
+   *
+   * @param callback return result
+   *        ```js
+   *            function (objects) {
+   *                for (var id in objects) {
+   *                    adapter.log.debug(id);
+   *                }
+   *            }
+   *        ```
+   */
   getAdapterObjects(callback) {
     import_validator.Validator.assertOptionalCallback(callback, "callback");
     return this._getAdapterObjects({ callback });
@@ -1299,6 +1720,62 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return import_js_controller_common.tools.maybeCallback(options.callback, ret);
   }
+  /**
+   * Extend some object and create it if it does not exist
+   *
+   * You can change or extend some object. E.g. existing object is:
+   * ```js
+   * {
+   *   common: {
+   *     name: 'Adapter name',
+   *     desc: 'Description'
+   *   },
+   *   type: 'state',
+   *   native: {
+   *     unused: 'text'
+   *  }
+   * }
+   * ```
+   *
+   * If following object will be passed as argument
+   *
+   * ```js
+   * {
+   *   common: {
+   *     desc: 'New description',
+   *     min: 0,
+   *     max: 100
+   *   },
+   *   native: {
+   *     unused: null
+   *   }
+   * }
+   * ```
+   *
+   * We will get as output:
+   * ```js
+   * {
+   *   common: {
+   *     desc: 'New description',
+   *     min: 0,
+   *     max: 100
+   *   },
+   *   type: 'state',
+   *   native: {}
+   * }
+   * ```
+   *
+   * @param id object ID, that must be extended
+   * @param obj part that must be extended
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, obj) {
+   *                if (err) adapter.log.error(err);
+   *                // obj is {"id": id}
+   *            }
+   *        ```
+   */
   extendObject(id, obj, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1319,6 +1796,7 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return this._extendObject({ id, obj, options, callback });
   }
+  // TODO: the public return type needs to be defined correctly, probably needs to be discussed
   async _extendObject(options) {
     if (!this.#objects) {
       this._logger.info(`${this.namespaceLog} extendObject not processed because Objects database not connected`);
@@ -1428,6 +1906,22 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallbackWithError(options.callback, e);
     }
   }
+  /**
+   * Same as {@link AdapterClass.setObject}, but for any object.
+   *
+   * ID must be specified as a full name with adapter namespace. E.g "hm-rpc.0.ABC98989.1.STATE"
+   *
+   * @param id object ID, that must be overwritten or created.
+   * @param obj new object
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, obj) {
+   *              // obj is {id: id}
+   *              if (err) adapter.log.error('Cannot write object: ' + err);
+   *            }
+   *        ```
+   */
   setForeignObject(id, obj, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1479,6 +1973,22 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this._setObjectWithDefaultValue(id, obj, options, callback);
   }
+  /**
+   * Same as {@link AdapterClass.extendObject}, but for any object.
+   *
+   * ID must be specified as a full name with adapter namespace. E.g "hm-rpc.0.ABC98989.1.STATE"
+   *
+   * @param id object ID, that must be extended
+   * @param obj part that must be extended
+   * @param options optional user context, or use attribute preserve e.g. `{preserve: {common: ['name']}}` to preserve common.name
+   * @param callback return result
+   *        ```js
+   *            function (err, obj) {
+   *                // obj is {"id": id}
+   *                if (err) adapter.log.error(err);
+   *            }
+   *        ```
+   */
   extendForeignObject(id, obj, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1596,6 +2106,12 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallbackWithError(callback, e);
     }
   }
+  /**
+   * Checks if an object exists to the given id, id will be fixed first
+   *
+   * @param id id of the object
+   * @param options optional user context
+   */
   objectExists(id, options) {
     if (!this.#objects) {
       this._logger.info(`${this.namespaceLog} objectExists not processed because Objects database not connected`);
@@ -1609,6 +2125,12 @@ class AdapterClass extends import_node_events.EventEmitter {
     this._utils.validateId(id, false, null);
     return this.#objects.objectExists(id, options);
   }
+  /**
+   * Checks if an object exists to the given id
+   *
+   * @param id id of the object
+   * @param options optional user context
+   */
   foreignObjectExists(id, options) {
     if (!this.#objects) {
       this._logger.info(`${this.namespaceLog} foreignObjectExists not processed because Objects database not connected`);
@@ -1621,6 +2143,20 @@ class AdapterClass extends import_node_events.EventEmitter {
     this._utils.validateId(id, true, null);
     return this.#objects.objectExists(id, options);
   }
+  /**
+   * Get object of this instance.
+   *
+   * It is not required, that ID consists namespace. E.g. to get object of "adapterName.X.myObject", only "myObject" is required as ID.
+   *
+   * @param id exactly object ID (without namespace)
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, obj) {
+   *              if (err) adapter.log.error('Cannot get object: ' + err);
+   *            }
+   *        ```
+   */
   getObject(id, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1642,6 +2178,32 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.getObject(this._utils.fixId(id), options, callback);
   }
+  /**
+   * Read object view from DB.
+   *
+   * It is required, that ID consists namespace in startkey and endkey. E.g. `{startkey: 'hm-rpc.' + adapter.instance + '.', endkey: 'hm-rpc.' + adapter.instance + '.\u9999'}`
+   * to get all objects of the instance.
+   *
+   * @param design name of the design
+   * @param search name of the view
+   * @param params object containing startkey: first id to include in result; endkey: last id to include in result
+   * @param options additional objects, e.g. for permissions
+   * @param callback return result
+   *      ```js
+   *          function (err, doc) {
+   *              if (doc && doc.rows) {
+   *                   for (var i = 0; i < doc.rows.length; i++) {
+   *                       var id  = doc.rows[i].id;
+   *                        var obj = doc.rows[i].value;
+   *                        adapter.log.info('Found ' + id + ': ' + JSON.stringify(obj));
+   *                   }
+   *                           if (!doc.rows.length) adapter.log.info('No objects found.');
+   *               } else {
+   *                   adapter.log.info('No objects found: ' + err);
+   *               }
+   *           }
+   *           ```
+   */
   getObjectView(design, search, params, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1699,6 +2261,30 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return this.#objects.getObjectView(design, search, params, options, callback);
   }
+  /**
+   * Read object list from DB.
+   *
+   * It is required, that ID consists namespace in startkey and endkey. E.g. `{startkey: 'hm-rpc.' + adapter.instance + '.', endkey: 'hm-rpc.' + adapter.instance + '.\u9999'}`
+   * to get all objects of the instance.
+   *
+   * @param params startkey and endkey information
+   * @param options additional options, e.g. for permissions
+   * @param callback optional callback
+   *      ```js
+   *          function (err, res) {
+   *              if (res && res.rows) {
+   *                   for (var i = 0; i < res.rows.length; i++) {
+   *                       var id  = res.rows[i].id;
+   *                       var obj = res.rows[i].value;
+   *                       adapter.log.info('Found ' + id + ': ' + JSON.stringify(obj));
+   *                   }
+   *                   if (!res.rows.length) adapter.log.info('No objects found.');
+   *              } else {
+   *                  adapter.log.info('No objects found: ' + err);
+   *              }
+   *          }
+   *       ```
+   */
   getObjectList(params, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1715,6 +2301,34 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.getObjectList(params, options, callback);
   }
+  /**
+   * Get the enum tree.
+   *
+   * Get enums of specified tree or all enums if nothing specified as object with values.
+   * If getEnum called with no enum specified, all enums will be returned:
+   * ```js
+   *      adapter.getEnums(function (err, enums, requestEnum) {
+   *        // All enums
+   *        if (err) adapter.log.error('Cannot get object: ' + err);
+   *        for (var e in enums) {
+   *           adapter.log.debug('Enum "' + e + '" has following members: ' + enums[e].common.members.join(', '));
+   *        }
+   *      });
+   * ```
+   *
+   * @param _enum enum name, e.g. 'rooms', 'function' or '' (all enums)
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, enums, requestEnum) {
+   *              // requestEnum is _enum
+   *              if (err) adapter.log.error('Cannot get object: ' + err);
+   *              for (var e in enums) {
+   *                 adapter.log.debug('Enum "' + e + '" has following members: ' + enums[e].common.members.join(', '));
+   *              }
+   *            }
+   *        ```
+   */
   getEnum(_enum, options, callback) {
     if (typeof _enum === "function") {
       callback = _enum;
@@ -1758,6 +2372,48 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallbackWithError(callback, err, result, _enum);
     });
   }
+  /**
+   * Read the members of given enums.
+   *
+   * Get enums of specified tree or all enums if nothing specified as object with values.
+   *
+   * @param _enumList enum name or names, e.g. ['rooms', 'function']
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, enums) {
+   *              // requestEnum is _enum
+   *              if (err) adapter.log.error('Cannot get object: ' + err);
+   *              // Result is like
+   *              // {
+   *              //    "enum.rooms": {
+   *              //       "enum.rooms.livingroom": {
+   *              //           common: {
+   *              //              members: ['ID1', 'ID2']
+   *              //           }
+   *              //       },
+   *              //       "enum.rooms.sleepingroom": {
+   *              //           common: {
+   *              //              members: ['ID3', 'ID4']
+   *              //           }
+   *              //       }
+   *              //    },
+   *              //    "enum.functions": {
+   *              //       "enum.rooms.light": {
+   *              //           common: {
+   *              //              members: ['ID1', 'ID6']
+   *              //           }
+   *              //       },
+   *              //       "enum.rooms.weather": {
+   *              //           common: {
+   *              //              members: ['ID4', 'ID7']
+   *              //           }
+   *              //       }
+   *              //    }
+   *              // }
+   *            }
+   *        ```
+   */
   getEnums(_enumList, options, callback) {
     if (typeof _enumList === "function") {
       callback = _enumList;
@@ -1827,6 +2483,48 @@ class AdapterClass extends import_node_events.EventEmitter {
       });
     }
   }
+  /**
+   * Get objects by pattern, by specific type and resolve their enums.
+   *
+   * Get all objects in the system of specified type. E.g.:
+   *
+   * ```js
+   * adapter.getForeignObjects('hm-rega.0.*', 'state', ['rooms', 'functions'], function (err, objs) {
+   *   if (err) adapter.log.error('Cannot get object: ' + err);
+   *   // objs look like:
+   *   // {
+   *   //    "hm-rega.0.ABC0000.1.STATE": {
+   *   //        common: {...},
+   *   //        native: {},
+   *   //        type: 'state',
+   *   //        enums: {
+   *   //           'enums.rooms.livingroom': 'Living room',
+   *   //           'enums.functions.light': 'Light'
+   *   //       }
+   *   //    },
+   *   //    "hm-rega.0.ABC0000.2.STATE": {
+   *   //        common: {...},
+   *   //        native: {},
+   *   //        type: 'state',
+   *   //        enums: {
+   *   //           'enums.rooms.sleepingroom': 'Sleeping room',
+   *   //           'enums.functions.window': 'Windows'
+   *   //       }
+   *   //    }
+   * }
+   * ```
+   *
+   * @param pattern object ID/wildcards
+   * @param type type of object: 'state', 'channel' or 'device'. Default - 'state'
+   * @param enums object ID, that must be overwritten or created.
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, obj) {
+   *              if (err) adapter.log.error('Cannot get object: ' + err);
+   *            }
+   *        ```
+   */
   getForeignObjects(pattern, type, enums, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1933,6 +2631,22 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return import_js_controller_common.tools.maybeCallbackWithError(callback, null, list);
   }
+  /**
+   * Find any object by name or ID.
+   *
+   * Find object by the exact name or ID.
+   *
+   * @param id exactly object ID (without namespace)
+   * @param type optional common.type of state: 'number', 'string', 'boolean', 'file', ...
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            adapter.findForeignObject('Some name', function (err, id, name) {
+   *              if (err) adapter.log.error('Cannot get object: ' + err);
+   *              adapter.log.debug('ID of object with name "' + name + '" is "' + id + '"');
+   *            }
+   *        ```
+   */
   findForeignObject(id, type, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1960,6 +2674,20 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.findObject(id, type, options || {}, callback);
   }
+  /**
+   * Get any object.
+   *
+   * ID must be specified with namespace.
+   *
+   * @param id exactly object ID (with namespace)
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, obj) {
+   *              if (err) adapter.log.error('Cannot get object: ' + err);
+   *            }
+   *        ```
+   */
   getForeignObject(id, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -1993,6 +2721,23 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallbackWithError(options.callback, e);
     }
   }
+  /**
+   * Delete an object of this instance.
+   *
+   * It is not required to provide the adapter namespace, because it will automatically be added.
+   * E.g. to delete "adapterName.X.myObject", only "myObject" is required as ID.
+   *
+   * The corresponding state will be deleted too if the object has type "state".
+   *
+   * @param id exactly object ID (without namespace)
+   * @param options optional user context. E.g. recursive option could be true
+   * @param callback return result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot delete object: ' + err);
+   *            }
+   *        ```
+   */
   delObject(id, options, callback) {
     import_validator.Validator.assertString(id, "id");
     id = this._utils.fixId(id);
@@ -2022,6 +2767,20 @@ class AdapterClass extends import_node_events.EventEmitter {
       setImmediate(() => this._deleteObjects(tasks, options, cb));
     });
   }
+  /**
+   * Delete any object.
+   *
+   * The full ID with namespace must be specified. The corresponding state will be deleted too if the object has type "state".
+   *
+   * @param id exactly object ID (with namespace)
+   * @param options optional user context or `{ recursive: true }` to delete all underlying objects
+   * @param callback return result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot delete object: ' + err);
+   *            }
+   *        ```
+   */
   delForeignObject(id, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -2054,7 +2813,8 @@ class AdapterClass extends import_node_events.EventEmitter {
         const tasks = obj && (!obj.common || !obj.common.dontDelete) ? [{ id, state: obj.type === "state" }] : [];
         const selector = { startkey: `${id}.`, endkey: `${id}.\u9999` };
         this.#objects.getObjectList(selector, options, (err2, res) => {
-          res && res.rows.forEach((item) => !tasks.find((task) => task.id === item.id) && (!item.value || !item.value.common || !item.value.common.dontDelete) && tasks.push({ id: item.id, state: item.value && item.value.type === "state" }));
+          res && res.rows.forEach((item) => !tasks.find((task) => task.id === item.id) && (!item.value || !item.value.common || !item.value.common.dontDelete) && // exclude objects with dontDelete flag
+          tasks.push({ id: item.id, state: item.value && item.value.type === "state" }));
           this._deleteObjects(tasks, options, callback);
         });
       });
@@ -2087,6 +2847,18 @@ class AdapterClass extends import_node_events.EventEmitter {
       });
     }
   }
+  /**
+   * Subscribe for the changes of objects in this instance.
+   *
+   * @param pattern pattern like 'channel.*' or '*' (all objects of this adapter) - without namespaces
+   * @param options optional user context
+   * @param callback optional returns result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot subscribe object: ' + err);
+   *            }
+   *        ```
+   */
   subscribeObjects(pattern, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -2108,6 +2880,18 @@ class AdapterClass extends import_node_events.EventEmitter {
       this.#objects.subscribeUser(fixedPattern, options, callback);
     }
   }
+  /**
+   * Unsubscribe on the changes of objects in this instance.
+   *
+   * @param pattern pattern like 'channel.*' or '*' (all objects) - without namespaces
+   * @param options optional user context
+   * @param callback optional returns result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot unsubscribe object: ' + err);
+   *            }
+   *        ```
+   */
   unsubscribeObjects(pattern, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -2129,6 +2913,18 @@ class AdapterClass extends import_node_events.EventEmitter {
       this.#objects.unsubscribeUser(fixedPattern, options, callback);
     }
   }
+  /**
+   * Subscribe for the changes of objects in any instance.
+   *
+   * @param pattern pattern like 'channel.*' or '*' (all objects) - without namespaces. You can use array of patterns
+   * @param options optional user context
+   * @param callback optional returns result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot subscribe object: ' + err);
+   *            }
+   *        ```
+   */
   subscribeForeignObjects(pattern, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -2145,6 +2941,18 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.subscribeUser(pattern, options, callback);
   }
+  /**
+   * Unsubscribe for the patterns on all objects.
+   *
+   * @param pattern pattern like 'channel.*' or '*' (all objects) - without namespaces
+   * @param options optional user context
+   * @param callback optional returns result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot unsubscribe object: ' + err);
+   *            }
+   *        ```
+   */
   unsubscribeForeignObjects(pattern, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -2164,6 +2972,13 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.unsubscribeUser(pattern, options, callback);
   }
+  /**
+   * Subscribe for the changes of files in specific instance.
+   *
+   * @param id adapter ID like 'vis-2.0' or 'vis-2.admin'
+   * @param pattern pattern like 'channel.*' or '*' (all files) - without namespaces. You can use array of patterns
+   * @param options optional user context
+   */
   subscribeForeignFiles(id, pattern, options) {
     if (!this.#objects) {
       this._logger.info(`${this.namespaceLog} subscribeForeignFiles not processed because Objects database not connected`);
@@ -2176,6 +2991,13 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return this.#objects.subscribeUserFile(id, pattern, options);
   }
+  /**
+   * Unsubscribe for the changes of files on specific instance.
+   *
+   * @param id adapter ID like 'vis-2.0' or 'vis-2.admin'
+   * @param pattern pattern like 'channel.*' or '*' (all objects) - without namespaces
+   * @param options optional user context
+   */
   unsubscribeForeignFiles(id, pattern, options) {
     if (!pattern) {
       pattern = "*";
@@ -2191,6 +3013,23 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return this.#objects.unsubscribeUserFile(id, pattern, options);
   }
+  /**
+   * Same as {@link AdapterClass.setObject}, but with check if the object exists.
+   *
+   * Only Ids that belong to this adapter can be modified. So the function automatically adds "adapter.X." to ID.
+   * New object will be created only if no object exists with such ID.
+   *
+   * @param id object ID, that must be overwritten or created.
+   * @param obj new object
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, obj) {
+   *              // obj is {id: id}
+   *              if (err) adapter.log.error('Cannot write object: ' + err);
+   *            }
+   *        ```
+   */
   setObjectNotExists(id, obj, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -2241,6 +3080,23 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return import_js_controller_common.tools.maybeCallbackWithError(options.callback, null);
   }
+  /**
+   * Same as {@link AdapterClass.setForeignObject}, but with check if the object exists.
+   *
+   * ID must be specified as a full name with adapter namespace. E.g "hm-rpc.0.ABC98989.1.STATE".
+   * New object will be created only if no object exists with such ID.
+   *
+   * @param id object ID, that must be overwritten or created.
+   * @param obj new object
+   * @param options user context
+   * @param callback return result
+   *        ```js
+   *            function (err, obj) {
+   *              // obj is {id: id}
+   *              if (err) adapter.log.error('Cannot write object: ' + err);
+   *            }
+   *        ```
+   */
   setForeignObjectNotExists(id, obj, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -2302,6 +3158,14 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return id;
   }
+  /**
+   * @param deviceName
+   * @param common
+   * @param _native
+   * @param options
+   * @param callback
+   * @deprecated use `this.extendObject` instead
+   */
   createDevice(deviceName, common, _native, options, callback) {
     this._logger.info(`${this.namespaceLog} Method "createDevice" is deprecated and will be removed in js-controller 7.1, use "extendObject/setObjectNotExists" instead`);
     if (typeof options === "function") {
@@ -2346,6 +3210,17 @@ class AdapterClass extends import_node_events.EventEmitter {
       native: _native
     }, options, callback);
   }
+  /**
+   * Name of channel must be in format "channel"
+   *
+   * @param parentDevice
+   * @param channelName
+   * @param roleOrCommon
+   * @param _native
+   * @param options
+   * @param callback
+   * @deprecated use `this.extendObject` instead
+   */
   createChannel(parentDevice, channelName, roleOrCommon, _native, options, callback) {
     this._logger.info(`${this.namespaceLog} Method "createChannel" is deprecated and will be removed in js-controller 7.1, use "extendObject/setObjectNotExists" instead`);
     if (typeof options === "function") {
@@ -2390,6 +3265,16 @@ class AdapterClass extends import_node_events.EventEmitter {
     };
     this.setObjectNotExists(channelName, obj, options, callback);
   }
+  /**
+   * @param parentDevice
+   * @param parentChannel
+   * @param stateName
+   * @param roleOrCommon
+   * @param _native
+   * @param options
+   * @param callback
+   * @deprecated use `this.extendObject` instead
+   */
   createState(parentDevice, parentChannel, stateName, roleOrCommon, _native, options, callback) {
     this._logger.info(`${this.namespaceLog} Method "createState" is deprecated and will be removed in js-controller 7.1, use "extendObject/setObjectNotExists" instead`);
     if (typeof options === "function") {
@@ -2534,6 +3419,19 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     });
   }
+  /**
+   * Delete device with all its channels and states.
+   *
+   * @deprecated use `this.delObject` instead
+   * @param deviceName is the part of ID like: adapter.instance.<deviceName>
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot delete device: ' + err);
+   *            }
+   *        ```
+   */
   deleteDevice(deviceName, options, callback) {
     this._logger.info(`${this.namespaceLog} Method "deleteDevice" is deprecated and will be removed in js-controller 7.1, use "delObject" instead`);
     if (typeof options === "function") {
@@ -2726,6 +3624,21 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallback(callback);
     });
   }
+  /**
+   * Deletes channel and underlying structure
+   *
+   * @deprecated use `this.delObject` instead
+   * @alias deleteChannel
+   * @param parentDevice is the part of ID like: adapter.instance.<deviceName>
+   * @param channelName is the part of ID like: adapter.instance.<deviceName>.<channelName>
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot delete device: ' + err);
+   *            }
+   *        ```
+   */
   deleteChannel(parentDevice, channelName, options, callback) {
     this._logger.info(`${this.namespaceLog} Method "deleteChannel" is deprecated and will be removed in js-controller 7.1, use "delObject" instead`);
     if (typeof options === "function") {
@@ -2792,6 +3705,14 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return import_js_controller_common.tools.maybeCallback(callback);
   }
+  /**
+   * @param parentDevice
+   * @param parentChannel
+   * @param stateName
+   * @param options
+   * @param callback
+   * @deprecated use `this.delObject` instead
+   */
   deleteState(parentDevice, parentChannel, stateName, options, callback) {
     this._logger.info(`${this.namespaceLog} Method "deleteState" is deprecated and will be removed in js-controller 7.1, use "delObject" instead`);
     if (typeof parentChannel === "function" && stateName === void 0) {
@@ -3176,11 +4097,15 @@ class AdapterClass extends import_node_events.EventEmitter {
       stateName = stateName.substring(parentChannel.length + 1);
     }
     stateName = stateName.replace(FORBIDDEN_CHARS, "_").replace(/\./g, "_");
-    const objId = this._utils.fixId({
-      device: parentDevice,
-      channel: parentChannel,
-      state: stateName
-    }, false);
+    const objId = this._utils.fixId(
+      {
+        device: parentDevice,
+        channel: parentChannel,
+        state: stateName
+      },
+      false
+      /*, 'state'*/
+    );
     if (enumName) {
       enumName = `enum.${enumName}.`;
     } else {
@@ -3213,6 +4138,27 @@ class AdapterClass extends import_node_events.EventEmitter {
       return import_js_controller_common.tools.maybeCallback(callback);
     });
   }
+  /**
+   * Change file access rights
+   *
+   * This function updates the file access rights
+   * ```js
+   *      adapter.chmodFile('vis-2.0', '/main/vis-views.json', {mode: 0x644}, function (err, processed) {
+   *        if (err) adapter.log.error('Cannot read file: ' + err);
+   *        adapter.log.info('New files: ' + JSON.stringify(processed));
+   *      });
+   * ```
+   *
+   * @param _adapter adapter name. If the adapter name is null, so the name (not instance) of the current adapter will be taken.
+   * @param path path to file without adapter name. E.g., If you want to update "/vis-2.0/main/*", here must be "/main/*" and _adapter must be equal to "vis-2.0".
+   * @param options data with mode
+   * @param callback return result
+   *        ```js
+   *            function (err, processedFiles) {
+   *                list of processed files with new groups
+   *            }
+   *        ```
+   */
   chmodFile(_adapter, path2, options, callback) {
     if (_adapter === null) {
       _adapter = this.name;
@@ -3227,6 +4173,27 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.chmodFile(_adapter, path2, options, callback);
   }
+  /**
+   * Change a file owner
+   *
+   * This function updates the file owner and ownerGroup
+   * ```js
+   *      adapter.chownFile('vis-2.0', '/main/vis-views.json', {owner: 'newOwner', ownerGroup: 'newgroup'}, function (err, processed) {
+   *        if (err) adapter.log.error('Cannot read file: ' + err);
+   *        adapter.log.info('New files: ' + JSON.stringify(processed));
+   *      });
+   * ```
+   *
+   * @param _adapter adapter name. If the adapter name is null, so the name (not instance) of the current adapter will be taken.
+   * @param path path to file without adapter name. E.g., If you want to update "/vis-2.0/main/*", here must be "/main/*" and _adapter must be equal to "vis-2.0".
+   * @param options data with owner and ownerGroup
+   * @param callback return result
+   *        ```js
+   *            function (err, processedFiles) {
+   *                list of processed files with new groups
+   *            }
+   *        ```
+   */
   chownFile(_adapter, path2, options, callback) {
     if (_adapter === null) {
       _adapter = this.name;
@@ -3241,6 +4208,41 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.chownFile(_adapter, path2, options, callback);
   }
+  /**
+   * Read directory from DB.
+   *
+   * This function reads the content of directory from DB for given adapter and path.
+   * If getEnum called with no enum specified, all enums will be returned:
+   * ```js
+   *      adapter.readDir('vis-2.0', '/main/', function (err, filesOrDirs) {
+   *        // All enums
+   *        if (err) adapter.log.error('Cannot read directory: ' + err);
+   *        if (filesOrDirs) {
+   *           for (var f = 0; f < filesOrDirs.length; f++) {
+   *              adapter.log.debug('Directory main has the following files and dirs: ' + filesOrDirs[f].file + '[dir - ' + filesOrDirs[f].isDir + ']');
+   *           }
+   *       }
+   *      });
+   * ```
+   *
+   * @param _adapter adapter name. If the adapter name is null, so the name (not instance) of the current adapter will be taken.
+   * @param path path to directory without adapter name. E.g., If you want to read "/vis-2.0/main/views.json", here must be "/main/views.json" and _adapter must be equal to "vis-2.0".
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, filesOrDirs) {
+   *                // filesOrDirs is array with elements like
+   *                // {
+   *                //      file:       'views.json,
+   *                //      stats:      node.js stats object like https://nodejs.org/api/fs.html#fs_class_fs_stats ,
+   *                //      isDir:      true/false,
+   *                //      acl:        access control list object,
+   *                //      modifiedAt: time when modified,
+   *                //      createdAt:  time when created
+   *                // }
+   *            }
+   *        ```
+   */
   readDir(_adapter, path2, options, callback) {
     if (_adapter === null) {
       _adapter = this.name;
@@ -3322,6 +4324,28 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.mkdir(_adapter, dirname, options, callback);
   }
+  /**
+   * Read file from DB.
+   *
+   * This function reads the content of one file from DB for given adapter and file name.
+   * ```js
+   *      adapter.readFile('vis-2.0', '/main/vis-views.json', function (err, data) {
+   *        // All enums
+   *        if (err) adapter.log.error('Cannot read file: ' + err);
+   *        adapter.log.info('Content of file is: ' + data);
+   *      });
+   * ```
+   *
+   * @param _adapter adapter name. If the adapter name is null, so the name (not instance) of the current adapter will be taken.
+   * @param filename path to file without adapter name. E.g., If you want to read "/vis-2.0/main/views.json", here must be "/main/views.json" and _adapter must be equal to "vis-2.0".
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, data) {
+   *                // data is utf8 or binary Buffer depends on the file extension.
+   *            }
+   *        ```
+   */
   readFile(_adapter, filename, options, callback) {
     if (_adapter === null) {
       _adapter = this.name;
@@ -3342,6 +4366,27 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#objects.readFile(_adapter, filename, options, callback);
   }
+  /**
+   * Write file to DB.
+   *
+   * This function writes the content of one file into DB for given adapter and file name.
+   * ```js
+   *      adapter.writeFile('vis-2.0', '/main/vis-views.json', data, function (err) {
+   *        err && adapter.log.error('Cannot write file: ' + err);
+   *      });
+   * ```
+   *
+   * @param _adapter adapter name. If the adapter name is null, so the name (not instance) of the current adapter will be taken.
+   * @param filename path to file without adapter name. E.g., If you want to read "/vis-2.0/main/views.json", here must be "/main/views.json" and _adapter must be equal to "vis-2.0".
+   * @param data data as UTF8 string or buffer depends on the file extension.
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err) {
+   *
+   *            }
+   *        ```
+   */
   writeFile(_adapter, filename, data, options, callback) {
     if (_adapter === null) {
       _adapter = this.name;
@@ -3365,6 +4410,14 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return this.#objects.writeFile(_adapter, filename, data, options, callback);
   }
+  /**
+   * Checks if file exists in DB.
+   *
+   * @param _adapter adapter name
+   * @param filename path to file without adapter name. E.g., If you want to check "/vis-2.0/main/views.json", here must be "/main/views.json" and _adapter must be equal to "vis-2.0".
+   * @param options optional user context
+   * @param callback cb function if none provided, a promise is returned
+   */
   async fileExists(_adapter, filename, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -3392,11 +4445,17 @@ class AdapterClass extends import_node_events.EventEmitter {
       _format = decimals;
       decimals = 2;
     }
-    const format = !_format || _format.length !== 2 ? this.isFloatComma === void 0 ? ".," : this.isFloatComma ? ".," : ",." : _format;
+    const format = (
+      // @ts-expect-error fix later
+      !_format || _format.length !== 2 ? this.isFloatComma === void 0 ? ".," : this.isFloatComma ? ".," : ",." : _format
+    );
     if (typeof value !== "number") {
       value = parseFloat(value);
     }
-    return isNaN(value) ? "" : value.toFixed(decimals).replace(format[0], format[1]).replace(/\B(?=(\d{3})+(?!\d))/g, format[0]);
+    return isNaN(value) ? "" : (
+      // @ts-expect-error fix later
+      value.toFixed(decimals).replace(format[0], format[1]).replace(/\B(?=(\d{3})+(?!\d))/g, format[0])
+    );
   }
   formatDate(dateObj, isDuration, _format) {
     if (typeof isDuration === "string" && isDuration.toLowerCase() === "duration" || isDuration === true) {
@@ -3535,6 +4594,24 @@ class AdapterClass extends import_node_events.EventEmitter {
     put(s);
     return result;
   }
+  /**
+   * Send message to other adapter instance or all instances of adapter.
+   *
+   * This function sends a message to specific instance or all instances of some specific adapter.
+   * If no instance given (e.g. "pushover"), the callback argument will be ignored. Because normally many responses will come.
+   *
+   * @param instanceName name of the instance where the message must be sent to. E.g. "pushover.0" or "system.adapter.pushover.0".
+   * @param command command name, like "send", "browse", "list". Command is depend on target adapter implementation.
+   * @param message object that will be given as argument for request
+   * @param callback optional return result
+   *        ```js
+   *            function (result) {
+   *              // result is target adapter specific and can vary from adapter to adapter
+   *              if (!result) adapter.log.error('No response received');
+   *            }
+   *        ```
+   * @param options optional options to define a timeout. This allows to get an error callback if no answer received in time (only if target is specific instance)
+   */
   sendTo(instanceName, command, message, callback, options) {
     if (typeof message === "function" && typeof callback === "undefined") {
       callback = message;
@@ -3560,6 +4637,15 @@ class AdapterClass extends import_node_events.EventEmitter {
       callback
     });
   }
+  /**
+   * Async version of sendTo
+   * As we have a special case (first arg can be error or result, we need to promisify manually)
+   *
+   * @param instanceName name of the instance where the message must be sent to. E.g. "pushover.0" or "system.adapter.pushover.0".
+   * @param command command name, like "send", "browse", "list". Command is depend on target adapter implementation.
+   * @param message object that will be given as argument for request
+   * @param options optional options to define a timeout. This allows to get an error callback if no answer received in time (only if target is specific instance)
+   */
   sendToAsync(instanceName, command, message, options) {
     return new Promise((resolve, reject) => {
       const callback = (resOrError) => {
@@ -3661,6 +4747,23 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  /**
+   * Send message to specific host or to all hosts.
+   *
+   * This function sends a message to specific host or all hosts.
+   * If no host name given (e.g. null), the callback argument will be ignored. Because normally many responses will come.
+   *
+   * @param hostName name of the host where the message must be sent to. E.g. "myPC" or "system.host.myPC". If argument is null, the message will be sent to all hosts.
+   * @param command command name. One of: "cmdExec", "getRepository", "getInstalled", "getVersion", "getDiagData", "getLocationOnDisk", "getDevList", "getLogs", "delLogs", "readDirAsZip", "writeDirAsZip", "readObjectsAsZip", "writeObjectsAsZip", "checkLogging". Commands can be checked in controller.js (function processMessage)
+   * @param message object that will be given as argument for request
+   * @param callback optional return result
+   *        ```js
+   *            function (result) {
+   *              // result is target adapter specific and can vary from command to command
+   *              if (!result) adapter.log.error('No response received');
+   *            }
+   *        ```
+   */
   sendToHost(hostName, command, message, callback) {
     if (typeof message === "undefined") {
       message = command;
@@ -3745,6 +4848,11 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  /**
+   * Send a message to an active UI Client
+   *
+   * @param options clientId and data options
+   */
   sendToUI(options) {
     if (!this.#states) {
       throw new Error(import_js_controller_common.tools.ERRORS.ERROR_DB_CLOSED);
@@ -3763,6 +4871,14 @@ class AdapterClass extends import_node_events.EventEmitter {
       states: this.#states
     });
   }
+  /**
+   * Send notification with given scope and category to host of this adapter
+   *
+   * @param scope - scope to be addressed
+   * @param category - to be addressed, if a null message will be checked by regex of given scope
+   * @param message - message to be stored/checked
+   * @param options - Additional options for the notification, currently `contextData` is supported
+   */
   async registerNotification(scope, category, message, options) {
     if (!this.#states) {
       this._logger.info(`${this.namespaceLog} registerNotification not processed because States database not connected`);
@@ -3789,6 +4905,37 @@ class AdapterClass extends import_node_events.EventEmitter {
     };
     await this.#states.pushMessage(`system.host.${this.host}`, obj);
   }
+  /**
+   * Writes value into states DB.
+   *
+   * This function can write values into states DB for this adapter.
+   * Only Ids that belong to this adapter can be modified. So the function automatically adds "adapter.X." to ID.
+   * ack, options and callback are optional
+   *
+   * @param id object ID of the state.
+   * @param state simple value or object with attributes.
+   *  If state is object and ack exists too as function argument, function argument has priority.
+   *  ```js
+   *      {
+   *          val:    value,
+   *          ack:    true|false,       // default - false; is command(false) or status(true)
+   *          ts:     timestampMS,      // default - now
+   *          q:      qualityAsNumber,  // default - 0 (ok)
+   *          from:   origin,           // default - this adapter
+   *          c:      comment,          // default - empty
+   *          expire: expireInSeconds   // default - 0
+   *          lc:     timestampMS       // default - automatic calculation
+   *      }
+   *  ```
+   * @param ack optional is command(false) or status(true)
+   * @param options optional user context
+   * @param callback optional return error and id
+   *        ```js
+   *            function (err, id) {
+   *              if (err) adapter.log.error('Cannot set value for "' + id + '": ' + err);
+   *            }
+   *        ```
+   */
   setState(id, state, ack, options, callback) {
     if (typeof state === "object" && typeof ack !== "boolean") {
       callback = options;
@@ -3928,6 +5075,7 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  // Cache will be cleared if user or group changes. Important! only if subscribed.
   async _getUserGroups(options) {
     if (this.users[options.user]) {
       options.groups = this.users[options.user].groups;
@@ -3958,6 +5106,7 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.users[options.user] = {
       groups: options.groups,
+      // @ts-expect-error TODO: UserCommon has no acl
       acl: userAcl.common?.acl || {}
     };
     await this._getGroups(options.groups);
@@ -4226,6 +5375,25 @@ class AdapterClass extends import_node_events.EventEmitter {
       return { id, notChanged: true };
     }
   }
+  /**
+   * Writes value into states DB only if the value really changed.
+   *
+   * This function can write values into states DB for this adapter.
+   * Only Ids that belong to this adapter can be modified. So the function automatically adds "adapter.X." to ID.
+   * ack, options and callback are optional
+   *
+   * @param id object ID of the state.
+   * @param state simple value or object with attribues.
+   * @param ack optional is command(false) or status(true)
+   * @param options optional user context
+   * @param callback optional return error, id and notChanged
+   *        ```js
+   *            function (err, id, notChanged) {
+   *              if (err) adapter.log.error('Cannot set value for "' + id + '": ' + err);
+   *              if (!notChanged) adapter.log.debug('Value was changed');
+   *            }
+   *        ```
+   */
   setStateChanged(id, state, ack, options, callback) {
     if (typeof state === "object" && typeof ack !== "boolean") {
       callback = options;
@@ -4294,6 +5462,36 @@ class AdapterClass extends import_node_events.EventEmitter {
     const res = await this._setStateChangedHelper(fixedId, stateObj);
     return import_js_controller_common.tools.maybeCallbackWithError(callback, null, res.id, res.notChanged);
   }
+  /**
+   * Writes value into states DB for any instance.
+   *
+   * This function can write values into states DB for all instances and system states too.
+   * ack, options and callback are optional
+   *
+   * @param id object ID of the state.
+   * @param state simple value or object with attribues.
+   *  If state is object, so the ack will be ignored and must be included into object.
+   *  ```js
+   *      {
+   *          val:    value,
+   *          ack:    true|false,       // default - false; is command(false) or status(true)
+   *          ts:     timestampMS,      // default - now
+   *          q:      qualityAsNumber,  // default - 0 (ok)
+   *          from:   origin,           // default - this adapter
+   *          c:      comment,          // default - empty
+   *          expire: expireInSeconds   // default - 0
+   *          lc:     timestampMS       // default - automatic calculation
+   *      }
+   *  ```
+   * @param ack optional is command(false) or status(true)
+   * @param options optional user context
+   * @param callback optional return error and id
+   *        ```js
+   *            function (err, id) {
+   *              if (err) adapter.log.error('Cannot set value for "' + id + '": ' + err);
+   *            }
+   *        ```
+   */
   async setForeignState(id, state, ack, options, callback) {
     if (typeof state === "object" && typeof ack !== "boolean") {
       callback = options;
@@ -4460,6 +5658,36 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  /**
+   * Writes value into states DB for any instance, but only if state changed.
+   *
+   * This function can write values into states DB for all instances and system states too.
+   * ack, options and callback are optional
+   *
+   * @param id object ID of the state.
+   * @param state simple value or object with attribues.
+   *  If state is object and ack exists too as function argument, function argument has priority.
+   *  ```js
+   *      {
+   *          val:    value,
+   *          ack:    true|false,       // default - false; is command(false) or status(true)
+   *          ts:     timestampMS,      // default - now
+   *          q:      qualityAsNumber,  // default - 0 (ok)
+   *          from:   origin,           // default - this adapter
+   *          c:      comment,          // default - empty
+   *          expire: expireInSeconds   // default - 0
+   *          lc:     timestampMS       // default - automatic calculation
+   *      }
+   *  ```
+   * @param ack optional is command(false) or status(true)
+   * @param options optional user context
+   * @param callback optional return error and id
+   *        ```js
+   *            function (err, id) {
+   *              if (err) adapter.log.error('Cannot set value for "' + id + '": ' + err);
+   *            }
+   *        ```
+   */
   async setForeignStateChanged(id, state, ack, options, callback) {
     if (typeof state === "object" && typeof ack !== "boolean") {
       callback = options;
@@ -4513,6 +5741,23 @@ class AdapterClass extends import_node_events.EventEmitter {
     const res = await this._setStateChangedHelper(id, state);
     return import_js_controller_common.tools.maybeCallbackWithError(callback, null, res.id, res.notChanged);
   }
+  /**
+   * Read value from states DB.
+   *
+   * This function can read values from states DB for this adapter.
+   * Only Ids that belong to this adapter can be read. So the function automatically adds "adapter.X." to ID.
+   *
+   * @param id object ID of the state.
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, state) {
+   *              if (err) adapter.log.error('Cannot read value: ' + err);
+   *            }
+   *        ```
+   *
+   *        See possible attributes of the state in @setState explanation
+   */
   getState(id, options, callback) {
     if (!import_js_controller_common.tools.isObject(id)) {
       import_validator.Validator.assertString(id, "id");
@@ -4520,6 +5765,22 @@ class AdapterClass extends import_node_events.EventEmitter {
     const fixedId = this._utils.fixId(id, false);
     return this.getForeignState(fixedId, options, callback);
   }
+  /**
+   * Read value from states DB for any instance and system state.
+   *
+   * This function can read values from states DB for all instances and adapters. It expects the full path of object ID.
+   *
+   * @param id object ID of the state.
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err, state) {
+   *              if (err) adapter.log.error('Cannot read value: ' + err);
+   *            }
+   *        ```
+   *
+   *        See possible attributes of the state in @setState explanation
+   */
   getForeignState(id, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -4611,6 +5872,7 @@ class AdapterClass extends import_node_events.EventEmitter {
       return this.#states.getState(id, callback);
     }
   }
+  // find out default history instance
   async _getDefaultHistory() {
     if (!this.defaultHistory) {
       let data;
@@ -4647,6 +5909,46 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  /**
+   * Read historian data for states of any instance or system state.
+   *
+   * This function can read values from history adapters like: history, sql, influxdb. It expects the full path of object ID.
+   * Normally only foreign history has interest, so there is no getHistory and getForeignHistory
+   *
+   * Possible options:
+   *
+   *  - instance - (optional) name of instance, where to read the historian data, e.g. 'history.0', 'sql.1'. By default, will be taken from system settings.
+   *  - start - (optional) time in ms - Date.now()', by default is (now - 1 week)
+   *  - end - (optional) time in ms - Date.now()', by default is (now + 5000 seconds)
+   *  - step - (optional) used in aggregate (m4, max, min, average, total) step in ms of intervals
+   *  - count - number of values if aggregate is 'onchange' or number of intervals if other aggregate method. Count will be ignored if step is set.
+   *  - from - if from field should be included in answer
+   *  - ack - if ack field should be included in answer
+   *  - q - if q field should be included in answer
+   *  - addId - if id field should be included in answer
+   *  - limit - do not return more entries than limit
+   *  - ignoreNull - if null values should be included (false), replaced by last not null value (true) or replaced with 0 (0)
+   *  - sessionId - (optional) identifier of request, will be returned back in the answer
+   *  - aggregate - aggregate method:
+   *      - minmax - used special algorithm. Splice the whole time range in small intervals and find for every interval max, min, start and end values.
+   *      - max - Splice the whole time range in small intervals and find for every interval max value and use it for this interval (nulls will be ignored).
+   *      - min - Same as max, but take minimal value.
+   *      - average - Same as max, but take average value.
+   *      - total - Same as max, but calculate total value.
+   *      - count - Same as max, but calculate number of values (nulls will be calculated).
+   *      - none - No aggregation at all. Only raw values in the given period.
+   *
+   * @param id object ID of the state.
+   * @param options see function description
+   * @param callback return result
+   *        ```js
+   *            function (error, result, step, sessionId) {
+   *              if (error) adapter.log.error('Cannot read value: ' + err);
+   *            }
+   *        ```
+   *
+   *        See possible attributes of the state in @setState explanation
+   */
   getHistory(id, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -4659,6 +5961,7 @@ class AdapterClass extends import_node_events.EventEmitter {
     import_validator.Validator.assertCallback(callback, "callback");
     return this._getHistory({ id, options, callback });
   }
+  // Checked implementation
   async _getHistory(_options) {
     const { id, callback } = _options;
     let { options } = _options;
@@ -4683,6 +5986,15 @@ class AdapterClass extends import_node_events.EventEmitter {
       import_js_controller_common.tools.maybeCallbackWithError(callback, res.error, res.result, res.step, res.sessionId);
     });
   }
+  /**
+   * Convert ID into object with device's, channel's and state's name.
+   *
+   * Convert "adapter.instance.D.C.S" in object `{device: D, channel: C, state: S}`
+   * Convert ID to `{device: D, channel: C, state: S}`
+   *
+   * @param id short or long string of ID like "stateID" or "adapterName.0.stateID".
+   * @returns parsed ID as an object
+   */
   idToDCS(id) {
     if (!id) {
       return null;
@@ -4695,6 +6007,24 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return { device: parts[2], channel: parts[3], state: parts[4] };
   }
+  /**
+   * Deletes a state of this instance.
+   * The object will NOT be deleted. If you want to delete it too, use @delObject instead.
+   *
+   * It is not required to provice the adapter namespace, because it will automatically be added.
+   * E.g. to delete "adapterName.X.myObject", only "myObject" is required as ID.
+   *
+   * No error is returned if state does not exist.
+   *
+   * @param id exactly object ID (without namespace)
+   * @param options optional user context
+   * @param callback return result
+   *        ```js
+   *            function (err) {
+   *              if (err) adapter.log.error('Cannot delete object: ' + err);
+   *            }
+   *        ```
+   */
   delState(id, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -4718,6 +6048,19 @@ class AdapterClass extends import_node_events.EventEmitter {
     id = this._utils.fixId(id);
     return this.delForeignState(id, options, callback);
   }
+  /**
+   * Deletes a state of any adapter.
+   * The object is NOT deleted. If you want to delete it too, use @delForeignObject instead.
+   *
+   * No error is returned if state does not exist.
+   *
+   * @param id long string for ID like "adapterName.0.stateID".
+   * @param options optional argument to describe the user context
+   * @param callback return result
+   * ```js
+   * function (err) {}
+   * ```
+   */
   delForeignState(id, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -4750,6 +6093,25 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     this.#states.delState(id, callback);
   }
+  /**
+   * Read all states of this adapter, that pass the pattern
+   *
+   * Allows to read all states of current adapter according to pattern. To read all states of current adapter use:
+   * ```js
+   *     adapter.getStates('*', function (err, states) {
+   *         for (var id in states) {
+   *              adapter.log.debug('"' + id + '" = "' + states[id].val);
+   *         }
+   *     });
+   * ```
+   *
+   * @param pattern string in form 'adapter.0.*' or like this. It can be an array of IDs too.
+   * @param options optional argument to describe the user context
+   * @param callback return result
+   * ```js
+   * function (err, states) {}, where states is an object like {"ID1": {"val": 1, "ack": true}, "ID2": {"val": 2, "ack": false}, ...}
+   * ```
+   */
   getStates(pattern, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -4785,6 +6147,13 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return result;
   }
+  /**
+   * Ensures, that object information is read, and the alias id is mapped to the source id if an alias is contained in the getStates call
+   * The adaption of the actual values is then performed in _processStatesSecondary, to apply alias conversion methods
+   *
+   * @param keys all ids of the getStates call
+   * @param targetObjs the target objects (e.g. alias objects or the actual objects)
+   */
   async _processStates(keys, targetObjs) {
     const aliasIndexes = [];
     const aliasIds = [];
@@ -4815,6 +6184,25 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return this._processStatesSecondary(keys, null, null);
   }
+  /**
+   * Read all states of all adapters (and system states), that pass the pattern
+   *
+   * Allows to read all states of current adapter according to pattern. To read all states of current adapter use:
+   * ```js
+   *     adapter.getStates('*', function (err, states) {
+   *         for (var id in states) {
+   *              adapter.log.debug('"' + id + '" = "' + states[id].val);
+   *         }
+   *     });
+   * ```
+   *
+   * @param pattern string in form 'adapter.0.*' or like this. It can be an array of IDs too.
+   * @param options optional argument to describe the user context
+   * @param callback return result
+   * ```js
+   * function (err, states) {}, where states is an object like {"ID1": {"val": 1, "ack": true}, "ID2": {"val": 2, "ack": false}, ...}
+   * ```
+   */
   getForeignStates(pattern, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -4910,6 +6298,12 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  /**
+   * Add subscription for given alias, if it is not a state it will be ignored
+   *
+   * @param aliasObj the alias object
+   * @param pattern pattern to subscribe for
+   */
   async _addAliasSubscribe(aliasObj, pattern) {
     if (aliasObj.type !== "state") {
       return;
@@ -4954,6 +6348,12 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     aliasDetails.targets.push(targetEntry);
   }
+  /**
+   * Remove an alias subscribe
+   *
+   * @param sourceId id of the source object
+   * @param aliasObjOrIdx the alias target or the index of the targets array
+   */
   async _removeAliasSubscribe(sourceId, aliasObjOrIdx) {
     if (!this.aliases.has(sourceId)) {
       return;
@@ -4968,6 +6368,18 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  /**
+   * Subscribe for changes on all states of all adapters (and system states), that pass the pattern
+   *
+   * Allows to Subscribe on changes all states of all instances according to pattern. E.g. to read all states of 'adapterName.X' instance use:
+   * ```js
+   *     adapter.subscribeForeignStates('adapterName.X.*');
+   * ```
+   *
+   * @param pattern string in form 'adapter.0.*' or like this. It can be an array of IDs too.
+   * @param options optional argument to describe the user context
+   * @param callback return result ```function (err) {}```
+   */
   subscribeForeignStates(pattern, options, callback) {
     pattern = pattern || "*";
     if (typeof options === "function") {
@@ -5113,6 +6525,23 @@ class AdapterClass extends import_node_events.EventEmitter {
       this.#states.subscribeUser(pattern, callback);
     }
   }
+  /**
+   * Unsubscribe for changes for given pattern
+   *
+   * This function allows to unsubscribe from changes. The pattern must be equal to requested one.
+   * ```js
+   *     adapter.subscribeForeignStates('adapterName.X.*');
+   *     adapter.unsubscribeForeignStates('adapterName.X.abc*'); // This will not work
+   *     adapter.unsubscribeForeignStates('adapterName.X.*'); // Valid unsubscribe
+   * ```
+   *
+   * @param pattern string in form 'adapter.0.*'. Must be the same as subscribe.
+   * @param options optional argument to describe the user context
+   * @param callback return result
+   * ```js
+   * function (err) {}
+   * ```
+   */
   unsubscribeForeignStates(pattern, options, callback) {
     pattern = pattern || "*";
     if (typeof options === "function") {
@@ -5207,6 +6636,18 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return import_js_controller_common.tools.maybeCallback(callback);
   }
+  /**
+   * Subscribe for changes on all states of this instance, that pass the pattern
+   *
+   * Allows to Subscribe on changes all states of current adapter according to pattern. To read all states of current adapter use:
+   * ```js
+   *     adapter.subscribeStates('*'); // subscribe for all states of this adapter
+   * ```
+   *
+   * @param pattern string in form 'adapter.0.*' or like this. Only string allowed
+   * @param options optional argument to describe the user context
+   * @param callback optional callback
+   */
   subscribeStates(pattern, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -5223,6 +6664,20 @@ class AdapterClass extends import_node_events.EventEmitter {
       callback
     });
   }
+  /**
+   * Unsubscribe for changes for given pattern for own states.
+   *
+   * This function allows to unsubscribe from changes. The pattern must be equal to requested one.
+   *
+   * ```js
+   *     adapter.unsubscribeStates('abc*'); // This will not work
+   *     adapter.unsubscribeStates('*');    // Valid unsubscribe
+   * ```
+   *
+   * @param pattern string in form 'adapter.0.*'. Must be the same as subscribe.
+   * @param options optional argument to describe the user context
+   * @param callback optional callback
+   */
   unsubscribeStates(pattern, options, callback) {
     if (typeof options === "function") {
       callback = options;
@@ -5239,6 +6694,12 @@ class AdapterClass extends import_node_events.EventEmitter {
       callback
     });
   }
+  /**
+   * Return plugin instance
+   *
+   * @param name name of the plugin to return
+   * @returns plugin instance or null if not existent or not isActive
+   */
   getPluginInstance(name) {
     if (!this.pluginHandler) {
       return null;
@@ -5246,6 +6707,12 @@ class AdapterClass extends import_node_events.EventEmitter {
     import_validator.Validator.assertString(name, "name");
     return this.pluginHandler.getPluginInstance(name);
   }
+  /**
+   * Return plugin configuration
+   *
+   * @param name name of the plugin to return
+   * @returns plugin configuration or null if not existent or not isActive
+   */
   getPluginConfig(name) {
     if (!this.pluginHandler) {
       return null;
@@ -5274,6 +6741,13 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  /**
+   * This method returns the list of license that can be used by this adapter
+   *
+   * @param all if return the licenses, that used by other instances (true) or only for this instance (false)
+   * @param adapterName Return licenses for specific adapter
+   * @returns list of suitable licenses
+   */
   async getSuitableLicenses(all, adapterName) {
     const licenses = [];
     try {
@@ -5343,6 +6817,12 @@ class AdapterClass extends import_node_events.EventEmitter {
     });
     return licenses;
   }
+  /**
+   * Add given id to log redirect list
+   *
+   * @param isActive if id should be added or removed
+   * @param id the id to add
+   */
   logRedirect(isActive, id) {
     if (id === `system.adapter.${this.namespace}`) {
       return;
@@ -5453,6 +6933,7 @@ class AdapterClass extends import_node_events.EventEmitter {
     this.inputCount = 0;
     this.outputCount = 0;
   }
+  // debug function to find error with stop logging
   _checkLogging() {
     let logs = [];
     logs.push(`Actual Loglist - ${JSON.stringify(Array.from(this.logList))}`);
@@ -5470,7 +6951,8 @@ class AdapterClass extends import_node_events.EventEmitter {
               const objPart = obj[i];
               if (objPart) {
                 const id = keys[i].substring(0, keys[i].length - ".logging".length);
-                if (typeof objPart === "string" && (objPart.includes('"val":true') || objPart.includes('"val":"true"')) || typeof objPart === "object" && (objPart.val === true || objPart.val === "true")) {
+                if (typeof objPart === "string" && // @ts-expect-error recheck code-wise this should not be possible to have a string
+                (objPart.includes('"val":true') || objPart.includes('"val":"true"')) || typeof objPart === "object" && (objPart.val === true || objPart.val === "true")) {
                   logs.push(`Subscriber - ${id} ENABLED`);
                 } else {
                   if (logs) {
@@ -5492,6 +6974,9 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     });
   }
+  /**
+   * Initialize the logging logic
+   */
   async _initLogging() {
     if (!this.#states) {
       return;
@@ -5607,6 +7092,7 @@ class AdapterClass extends import_node_events.EventEmitter {
       };
     }
   }
+  // initStates is called from initAdapter
   _initStates(cb) {
     this._logger.silly(`${this.namespaceLog} objectDB connected`);
     this._config.states.maxQueue = this._config.states.maxQueue || 1e3;
@@ -6032,7 +7518,8 @@ class AdapterClass extends import_node_events.EventEmitter {
             }
           }
           if (!this._stopInProgress) {
-            typeof this._options.objectChange === "function" && setImmediate(() => this._options.objectChange(id, obj));
+            typeof this._options.objectChange === "function" && // @ts-expect-error
+            setImmediate(() => this._options.objectChange(id, obj));
             setImmediate(() => this.emit("objectChange", id, obj));
           }
         }
@@ -6049,6 +7536,9 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     });
   }
+  /**
+   * Called if states and objects successfully initialized
+   */
   async _prepareInitAdapter() {
     if (this.terminated || !this.#objects || !this.#states) {
       return;
@@ -6085,6 +7575,11 @@ class AdapterClass extends import_node_events.EventEmitter {
       }
     }
   }
+  /**
+   * Initialize the adapter
+   *
+   * @param adapterConfig the AdapterOptions or the InstanceObject, is null/undefined if it is install process
+   */
   async _initAdapter(adapterConfig) {
     await this._initLogging();
     if (!this.pluginHandler) {
@@ -6148,6 +7643,7 @@ class AdapterClass extends import_node_events.EventEmitter {
         name = this.name;
         instance = 0;
         adapterConfig = adapterConfig || {
+          // @ts-expect-error protectedNative exists on instance objects
           common: { mode: "once", name, protectedNative: [] },
           native: {}
         };
@@ -6170,7 +7666,11 @@ class AdapterClass extends import_node_events.EventEmitter {
       this.config = adapterConfig.native;
       this.host = adapterConfig.common.host;
       this.common = adapterConfig.common;
-      if (adapterConfig.common.mode === "schedule" || adapterConfig.common.mode === "once") {
+      if (
+        // @ts-expect-error
+        adapterConfig.common.mode === "schedule" || // @ts-expect-error
+        adapterConfig.common.mode === "once"
+      ) {
         this.stop = (params) => this._stop({ ...params, isPause: true });
       } else if (this.startedInCompactMode) {
         this.stop = (params) => this._stop({ ...params, isPause: false });
@@ -6179,7 +7679,8 @@ class AdapterClass extends import_node_events.EventEmitter {
         this.stop = (params) => this._stop({ ...params, isPause: false });
       }
       this.#states.subscribe(`${import_constants2.SYSTEM_ADAPTER_PREFIX}*.logging`);
-      if (typeof this._options.message === "function" && !(0, import_utils.isMessageboxSupported)(adapterConfig.common)) {
+      if (typeof this._options.message === "function" && // @ts-expect-error, we should infer correctly that this is an InstanceObject in this case
+      !(0, import_utils.isMessageboxSupported)(adapterConfig.common)) {
         this._logger.error(`${this.namespaceLog} : message handler implemented, but messagebox not enabled. Define common.messagebox in io-package.json for adapter or delete message handler.`);
       } else if ((0, import_utils.isMessageboxSupported)(adapterConfig.common)) {
         this.mboxSubscribed = true;
@@ -6294,6 +7795,9 @@ class AdapterClass extends import_node_events.EventEmitter {
       this.adapterReady = true;
     }
   }
+  /**
+   * Calls the ready handler, if it is an install run it calls the install handler instead
+   */
   _callReadyHandler() {
     if (this._config.isInstall && (typeof this._options.install === "function" || this.listeners("install").length)) {
       if (typeof this._options.install === "function") {
@@ -6460,6 +7964,12 @@ class AdapterClass extends import_node_events.EventEmitter {
       setImmediate(() => this._extendObjects(tasks, callback));
     }
   }
+  /**
+   * Replaces forbidden chars in an id if present
+   * Additionally logs a warning
+   *
+   * @param id the id which will be replaced
+   */
   fixForbiddenCharsInId(id) {
     const mId = id.replace(FORBIDDEN_CHARS, "_");
     if (mId !== id) {
@@ -6467,6 +7977,11 @@ class AdapterClass extends import_node_events.EventEmitter {
     }
     return mId;
   }
+  /**
+   * This method reports deprecations via Sentry (controller own instance) and can only be used internally
+   *
+   * @param options information about version to remove feature and the log message
+   */
   async reportDeprecation(options) {
     if (!this.#states) {
       throw new Error(import_js_controller_common.tools.ERRORS.ERROR_DB_CLOSED);
@@ -6493,13 +8008,18 @@ class AdapterClass extends import_node_events.EventEmitter {
     };
     await this.#states.pushMessage(`system.host.${this.host}`, obj);
   }
+  /**
+   * Initialize the plugin handler for this adapter
+   */
   _initPluginHandler() {
     const pluginSettings = {
       scope: "adapter",
       namespace: `system.adapter.${this.namespace}`,
       logNamespace: this.namespaceLog,
+      // @ts-expect-error
       log: this._logger,
       iobrokerConfig: this._config,
+      // @ts-expect-error
       parentPackage: this.pack,
       controllerVersion
     };
@@ -6510,6 +8030,9 @@ class AdapterClass extends import_node_events.EventEmitter {
       this._logger.error(`Could not add plugins: ${e.message}`);
     }
   }
+  /**
+   * Initializes the adapter
+   */
   async _init() {
     const _initDBs = () => {
       this._initObjects(() => {