@iobroker/db-objects-redis 7.2.3 → 8.0.0-alpha.1-20260921-e5941ca8a

package/build/cjs/lib/objects/objectsInRedisClient.d.ts

@@ -1,48 +1,48 @@
-import type { ACLObject, CheckFileRightsCallback, GetUserGroupPromiseReturn } from '../../lib/objects/objectsUtils.js';
+import { type ACLObject, type FileObject, type UserContext } from '../../lib/objects/objectsUtils.js';
+import * as CONSTS from '../../lib/objects/constants.js';
 import type { InternalLogger } from '@iobroker/js-controller-common-db/tools';
 import type { ConnectionOptions, DbStatus } from '@iobroker/db-base/inMemFileDB';
 type ChangeFunction = (id: string, object: ioBroker.Object | null) => void;
-type GetUserGroupCallbackNoError = (user: string, groups: string[], acl: ioBroker.ObjectPermissions) => void;
+type GetUserGroupCallbackNoError = (user: ioBroker.ObjectIDs.User, groups: ioBroker.ObjectIDs.Group[], acl: ioBroker.ObjectPermissions) => void;
 interface RedisConnectionOptions extends ConnectionOptions {
     redisNamespace?: string;
 }
+/** Settings for the objects database client */
 export interface ObjectsSettings {
+    /** Called once the client is connected */
     connected: () => void;
+    /** Whether this client runs inside the controller */
     controller?: boolean;
+    /** Called when the connection to the primary host is lost */
     primaryHostLost?: () => void;
+    /** Called when the client gets disconnected */
     disconnected?: () => void;
+    /** Handler for system-level object changes */
     change?: ChangeFunction;
+    /** Handler for user-level object changes */
     changeUser?: ChangeFunction;
+    /** Handler for user-level file changes */
     changeFileUser?: ioBroker.FileChangeHandler;
+    /** Whether to connect to the database immediately (default true) */
     autoConnect?: boolean;
+    /** Logger instance to use */
     logger: InternalLogger;
+    /** Name of this host */
     hostname?: string;
+    /** Namespace of this client */
     namespace?: string;
+    /** Default ACL applied to newly created objects */
     defaultNewAcl?: ACLObject;
+    /** Namespace used for meta-information */
     metaNamespace?: string;
+    /** Redis key prefix (defaults to "cfg") */
     redisNamespace?: string;
+    /** Connection options for the redis server */
     connection: RedisConnectionOptions;
 }
-interface CallOptions {
-    groups?: string[];
-    group?: string;
-    user?: ioBroker.ObjectIDs.User;
-    owner?: ioBroker.ObjectIDs.User;
-    ownerGroup?: string;
-    acl?: any;
-    [other: string]: any;
-}
-interface WriteFileOptions extends CallOptions {
-    mimeType?: string;
-}
-interface Options {
-    /** The user id for database operations */
-    user?: string;
-    [other: string]: unknown;
-}
-type CheckFileCallback = (checkFailed: boolean, options?: CallOptions, fileOptions?: {
-    notExists: boolean;
-}) => void;
+/**
+ * Client for the objects database backed by Redis (or the in-memory redis-protocol server)
+ */
 export declare class ObjectsInRedisClient {
     private client;
     private readonly fileNamespace;
@@ -69,222 +69,1058 @@ export declare class ObjectsInRedisClient {
     private noLegacyMultihost?;
     private readonly userSubscriptions;
     private readonly systemSubscriptions;
+    /**
+     * @param settings Settings for the objects client including connection and namespaces
+     */
     constructor(settings: ObjectsSettings);
     /**
      * Checks if we are allowed to start and sets the protocol version accordingly
      */
     private _determineProtocolVersion;
+    /**
+     * Connect to the objects database and set up the change and file subscriptions
+     */
     connectDb(): void;
+    /**
+     * Get the current status of the database
+     */
     getStatus(): DbStatus;
     /**
      * Checks if given ID is a meta-object, else throws error
      *
      * @param id to check
-     * @throws Error if id is invalid
+     * @throws {Error} if id is invalid
      */
     validateMetaObject(id: string): Promise<void>;
+    /**
+     * Normalize a file name by collapsing slashes and backslashes into a single forward slash
+     *
+     * @param name The file name to normalize
+     */
     normalizeFilename(name: string): string;
     /**
      * Sets a buffer to the Redis DB
      *
-     * @param id id of the file
+     * @param id ID of the file
      * @param data content, if string is passed it will be converted to a Buffer
      */
     private _setBinaryState;
     /**
-     * get buffer of given id from redis
+     * Get a buffer of a given ID from redis
      *
      * @param id - id of the data with namespace prefix
      */
     private _getBinaryState;
     /**
-     * deletes binary state of given id from redis db
+     * deletes binary state of a given ID from redis db
      *
      * @param id - id to delete, with namespace prefix
      */
     private _delBinaryState;
+    /**
+     * Build the internal redis key for a file
+     *
+     * @param id The ID of the object owning the file
+     * @param name The file name
+     * @param isMeta Whether to return the key of the meta-entry (true) or the data entry (false)
+     */
     getFileId(id: string, name: string, isMeta?: boolean): string;
-    checkFile(id: string, name: string, options: CallOptions, flag: any, callback?: CheckFileCallback): Promise<ioBroker.CallbackReturnTypeOf<CheckFileCallback> | void>;
-    checkFileRights(id: string, name: string | null, options?: CallOptions | null, flag?: any, callback?: CheckFileRightsCallback): void;
+    /**
+     * Check whether the current options have the required rights on a file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param userContext The resolved user context used for permission checks
+     * @param flag The access flag(s) to check for
+     */
+    checkFileAsync(id: string, name: string | null, userContext: UserContext, flag: CONSTS.GenericAccessFlags): Promise<FileObject | null>;
+    /**
+     * Check whether the current user is allowed to access a file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name, or null for the whole namespace
+     * @param options The current request options including the user
+     * @param flag The access flag(s) to check for
+     * @param callback Called with the effective options once the rights have been checked
+     */
+    checkFileRights(id: string, name: string | null, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, flag: CONSTS.GenericAccessFlags, callback: (err: Error | string | null | undefined, fileOptions?: FileObject, userContext?: {
+        user: ioBroker.ObjectIDs.User;
+        group: ioBroker.ObjectIDs.Group;
+        groups: ioBroker.ObjectIDs.Group[];
+        acl: ioBroker.ObjectPermissions;
+        checked?: boolean;
+    }) => void): void;
     private _setDefaultAcl;
+    /**
+     * Set the default ACL applied to new objects and apply it to all existing objects without an ACL
+     *
+     * @param defaultNewAcl The default ACL to use, or null to use the built-in default
+     */
     setDefaultAcl(defaultNewAcl: ACLObject | null): Promise<void>;
-    getUserGroup(user: ioBroker.ObjectIDs.User, callback: GetUserGroupCallbackNoError): Promise<GetUserGroupPromiseReturn> | void;
+    /**
+     * Determine the groups and effective ACL of the given user
+     *
+     * @param user The id of the user to look up
+     * @param callback Called with the user, its groups, and the effective ACL
+     */
+    getUserGroup(user: ioBroker.ObjectIDs.User, callback: GetUserGroupCallbackNoError): void;
     private _writeFile;
-    writeFile(id: string, name: string, data: any, callback?: ioBroker.ErrorCallback): Promise<void>;
-    writeFile(id: string, name: string, data: any, options?: WriteFileOptions | null, callback?: ioBroker.ErrorCallback): Promise<void>;
-    writeFileAsync(id: string, name: string, data: any, options?: WriteFileOptions | null): Promise<void>;
+    /**
+     * Write data into a file of an object
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param data The data to write
+     * @param callback Called once the file has been written
+     */
+    writeFile(id: string, name: string, data: string | Buffer | null | undefined, callback?: ioBroker.ErrorCallback): Promise<void>;
+    /**
+     * Write data into a file of an object
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param data The data to write
+     * @param options The current request options including the user
+     * @param callback Called once the file has been written
+     */
+    writeFile(id: string, name: string, data: string | Buffer | null | undefined, options?: {
+        virtualFile?: boolean;
+        user?: ioBroker.ObjectIDs.User;
+        group?: ioBroker.ObjectIDs.Group;
+        mode?: number;
+        mimeType?: string;
+    } | null, callback?: ioBroker.ErrorCallback): Promise<void>;
+    /**
+     * Promise-version of writeFile
+     *
+     * @param id The ID of the object owning the file
+     * @param name The file name
+     * @param data The data to write
+     * @param options The current request options including the user
+     */
+    writeFileAsync(id: string, name: string, data: string | Buffer | null | undefined, options?: {
+        virtualFile?: boolean;
+        user?: ioBroker.ObjectIDs.User;
+        group?: ioBroker.ObjectIDs.Group;
+        mode?: number;
+        mimeType?: string;
+    } | null): Promise<void>;
     private _readFile;
-    readFile(id: string, name: string, options?: CallOptions | null): ioBroker.ReadFilePromise;
-    readFile(id: string, name: string, options: CallOptions | null | undefined, callback: ioBroker.ReadFileCallback): void;
     /**
-     * Check if given object exists
+     * Read a file of an object
+     *
+     * @param id The ID of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the user
+     */
+    readFile(id: string, name: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): ioBroker.ReadFilePromise;
+    /**
+     * Read a file of an object
      *
-     * @param id id of the object
+     * @param id The ID of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the user
+     * @param callback Called with the file content and mime type
+     */
+    readFile(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, callback: ioBroker.ReadFileCallback): void;
+    /**
+     * Check if a given object exists
+     *
+     * @param id ID of the object
      * @param options optional user context
      */
-    objectExists(id: string, options?: CallOptions | null): Promise<boolean>;
+    objectExists(id: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<boolean>;
     /**
-     * Check if given file exists
+     * Check if a given file exists
      *
-     * @param id id of the namespace
+     * @param id ID of the namespace
      * @param name name of the file
      * @param options optional user context
      */
-    fileExists(id: string, name: string, options?: CallOptions | null): Promise<boolean>;
+    fileExists(id: string, name: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<boolean>;
     private _unlink;
-    unlink(id: string, name: string, options: CallOptions | null | undefined, callback?: ioBroker.RmCallback): void;
-    unlinkAsync(id: string, name: string, options?: CallOptions): Promise<void>;
-    delFile(id: string, name: string, options: CallOptions, callback: ioBroker.ErrorCallback): void;
-    delFileAsync(id: string, name: string, options: CallOptions): Promise<void>;
+    /**
+     * Delete a file or directory of an object
+     *
+     * @param id The id of the object owning the file
+     * @param name The file or directory name to delete
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the list of removed files
+     */
+    unlink(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, callback?: ioBroker.RmCallback): void;
+    /**
+     * Promise-version of unlink
+     *
+     * @param id The id of the object owning the file
+     * @param name The file or directory name to delete
+     * @param options The current request options including the user
+     */
+    unlinkAsync(id: string, name: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
+    /**
+     * Delete a file of an object (alias for {@link unlink})
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name to delete
+     * @param options The current request options including the user
+     * @param callback Called once the file has been deleted
+     */
+    delFile(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, callback: ioBroker.ErrorCallback): void;
+    /**
+     * Promise-version of delFile
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name to delete
+     * @param options The current request options including the user
+     */
+    delFileAsync(id: string, name: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
     private _readDir;
-    readDir(id: string, name: string, options: CallOptions | null | undefined, callback: ioBroker.ReadDirCallback): void;
-    readDirAsync(id: string, name: string, options?: CallOptions): ioBroker.ReadDirPromise;
+    /**
+     * List the contents of a directory of an object
+     *
+     * @param id The id of the object owning the files
+     * @param name The directory name to list
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the directory entries
+     */
+    readDir(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, callback: ioBroker.ReadDirCallback): void;
+    /**
+     * Promise-version of readDir
+     *
+     * @param id The id of the object owning the files
+     * @param name The directory name to list
+     * @param options The current request options including the user
+     */
+    readDirAsync(id: string, name: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): ioBroker.ReadDirPromise;
     private _renameHelper;
     private _rename;
-    rename(id: string, oldName: string, newName: string, options?: CallOptions | null, callback?: ioBroker.ErrorCallback): void | Promise<void>;
-    renameAsync(id: string, oldName: string, newName: string, options: CallOptions): Promise<void>;
+    /**
+     * Rename a file or directory of an object
+     *
+     * @param id The id of the object owning the file
+     * @param oldName The current file or directory name
+     * @param newName The new file or directory name
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the file has been renamed
+     */
+    rename(id: string, oldName: string, newName: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback?: ioBroker.ErrorCallback): void | Promise<void>;
+    /**
+     * Promise-version of rename
+     *
+     * @param id The id of the object owning the file
+     * @param oldName The current file or directory name
+     * @param newName The new file or directory name
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the operation is performed
+     */
+    renameAsync(id: string, oldName: string, newName: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    }): Promise<void>;
     private _touch;
-    touch(id: string, name: string, options: CallOptions | null, callback: ioBroker.ErrorCallback): void;
-    touchAsync(id: string, name: string, options: CallOptions): Promise<void>;
+    /**
+     * Update the modification time of a file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the file has been touched
+     */
+    touch(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback: ioBroker.ErrorCallback): void;
+    /**
+     * Promise-version of touch
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the operation is performed
+     */
+    touchAsync(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    }): Promise<void>;
     private _rmHelper;
     private _rm;
-    rm(id: string, name: string, options: CallOptions | null, callback: ioBroker.RmCallback): void;
-    rmAsync(id: string, name: string, options: CallOptions): Promise<void | ioBroker.RmResult[]>;
-    mkdir(id: string, dirName?: string, options?: CallOptions | null, callback?: ioBroker.ErrorCallback): void;
-    mkdirAsync(id: string, dirName?: string, options?: CallOptions): Promise<void>;
+    /**
+     * Delete a file or directory of an object
+     *
+     * @param id The id of the object owning the file
+     * @param name The file or directory name to delete
+     * @param options The current request options including the user, or the callback
+     * @param callback Called with the list of removed files
+     */
+    rm(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback: ioBroker.RmCallback): void;
+    /**
+     * Promise-version of rm
+     *
+     * @param id The id of the object owning the file
+     * @param name The file or directory name to delete
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the operation is performed
+     */
+    rmAsync(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    }): Promise<void | ioBroker.RmResult[]>;
+    /**
+     * Create a directory for an object's files (simulated, as redis has no real directories)
+     *
+     * @param id The id of the object owning the files
+     * @param dirName The directory name to create
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the directory has been created
+     */
+    mkdir(id: string, dirName?: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+        mode?: number;
+        group?: ioBroker.ObjectIDs.Group;
+    } | null | ioBroker.ErrorCallback, callback?: ioBroker.ErrorCallback): void;
+    /**
+     * Promise-version of mkdir
+     *
+     * @param id The id of the object owning the files
+     * @param dirName The directory name to create
+     * @param options The current request options including the user
+     */
+    mkdirAsync(id: string, dirName?: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+        mode?: number;
+        group: ioBroker.ObjectIDs.Group;
+    } | null): Promise<void>;
     private _chownFileHelper;
     private _chownFile;
-    chownFile(id: string, name: string, options: CallOptions, callback: ioBroker.ChownFileCallback): void;
-    chownFileAsync(id: string, name: string, options: CallOptions): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ChownFileCallback>>;
+    /**
+     * Change the owner and owner group of a file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the new owner and the user
+     * @param options.owner The new owner (user id) to assign to the file
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.ownerGroup The new owner group to assign to the file
+     * @param options.group The new owner group to assign (alias for ownerGroup)
+     * @param callback Called with the processed file(s)
+     */
+    chownFile(id: string, name: string, options: {
+        owner: ioBroker.ObjectIDs.User;
+        user?: ioBroker.ObjectIDs.User;
+        ownerGroup?: ioBroker.ObjectIDs.Group;
+        group?: ioBroker.ObjectIDs.Group;
+    }, callback: ioBroker.ChownFileCallback): void;
+    /**
+     * Promise-version of chownFile
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the new owner and the user
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.owner The new owner (user id) to assign to the file
+     * @param options.ownerGroup The new owner group to assign to the file
+     */
+    chownFileAsync(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+        owner: ioBroker.ObjectIDs.User;
+        ownerGroup?: ioBroker.ObjectIDs.Group;
+    }): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ChownFileCallback>>;
     /**
      *
      * @param keys Key names to handle
      * @param metas Objects for the keys to handle
      * @param options options
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.mode The new permission mode to apply
      * @param callback callback function
      */
     private _chmodFileHelper;
     private _chmodFile;
-    chmodFile(id: string, name: string, options: CallOptions | null, callback: ioBroker.ChownFileCallback): void;
-    chmodFileAsync(id: string, name: string, options: CallOptions): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ChownFileCallback>>;
+    /**
+     * Change the file mode (permissions) of a single file
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the new mode and the user, or the callback
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.mode The new permission mode to apply
+     * @param callback Called with the processed file
+     */
+    chmodFile(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+        mode: number;
+    }, callback: ioBroker.ChownFileCallback): void;
+    /**
+     * Promise-version of chmodFile
+     *
+     * @param id The id of the object owning the file
+     * @param name The file name
+     * @param options The current request options including the new mode and the user
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.mode The new permission mode to apply
+     */
+    chmodFileAsync(id: string, name: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+        mode: number;
+    }): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ChownFileCallback>>;
+    /**
+     * Enable or disable the file cache
+     *
+     * @param enabled Whether the file cache should be enabled
+     * @param callback Called with the resulting cache state
+     */
     enableFileCache(enabled: boolean, callback?: (err: Error | null | undefined, res: boolean) => void): void;
-    enableFileCache(enabled: boolean, options?: CallOptions, callback?: (err: Error | null | undefined, res: boolean) => void): void;
-    enableFileCacheAsync(enabled: boolean, options?: CallOptions): Promise<boolean>;
+    /**
+     * Enable or disable the file cache
+     *
+     * @param enabled Whether the file cache should be enabled
+     * @param options The current request options including the user
+     * @param callback Called with the resulting cache state
+     */
+    enableFileCache(enabled: boolean, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | ((err: Error | null | undefined, res: boolean) => void), callback?: (err: Error | null | undefined, res: boolean) => void): void;
+    /**
+     * Promise-version of enableFileCache
+     *
+     * @param enabled Whether the file cache should be enabled
+     * @param options The current request options including the user
+     */
+    enableFileCacheAsync(enabled: boolean, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<boolean>;
     private _subscribeFile;
     private _unsubscribeFile;
-    subscribeUserFile(id: string, pattern: string | string[], options?: CallOptions | null): Promise<void>;
-    unsubscribeUserFile(id: string, pattern: string | string[], options?: CallOptions | null): Promise<void>;
+    /**
+     * Subscribe a user to file changes of an object
+     *
+     * @param id The id of the object owning the files
+     * @param pattern One or more file name patterns to subscribe to
+     * @param options The current request options including the user
+     */
+    subscribeUserFile(id: string, pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
+    /**
+     * Unsubscribe a user from file changes of an object
+     *
+     * @param id The id of the object owning the files
+     * @param pattern One or more file name patterns to unsubscribe from
+     * @param options The current request options including the user
+     */
+    unsubscribeUserFile(id: string, pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
     private _subscribe;
     private subscribeConfig;
+    /**
+     * Subscribe to object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param callback Called once the subscription is registered
+     */
     subscribe(pattern: string | string[], callback?: ioBroker.ErrorCallback): void;
-    subscribe(pattern: string | string[], options?: CallOptions, callback?: ioBroker.ErrorCallback): void;
-    subscribeAsync(pattern: string | string[], options?: CallOptions): Promise<void>;
+    /**
+     * Subscribe to object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param options The current request options including the user
+     * @param callback Called once the subscription is registered
+     */
+    subscribe(pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback?: ioBroker.ErrorCallback): void;
+    /**
+     * Promise-version of subscribe
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param options The current request options including the user
+     */
+    subscribeAsync(pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
+    /**
+     * Subscribe a user to object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param callback Called once the subscription is registered
+     */
     subscribeUser(pattern: string | string[], callback?: ioBroker.ErrorCallback): void;
-    subscribeUser(pattern: string | string[], options?: CallOptions | null, callback?: ioBroker.ErrorCallback): void;
-    subscribeUserAsync(pattern: string | string[], options: CallOptions): Promise<void>;
+    /**
+     * Subscribe a user to object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param options The current request options including the user
+     * @param callback Called once the subscription is registered
+     */
+    subscribeUser(pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback?: ioBroker.ErrorCallback): void;
+    /**
+     * Promise-version of subscribeUser
+     *
+     * @param pattern One or more patterns to subscribe to
+     * @param options The current request options including the user
+     */
+    subscribeUserAsync(pattern: string | string[], options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
     private _unsubscribe;
     private unsubscribeConfig;
+    /**
+     * Unsubscribe from object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param callback Called once the subscription is removed
+     */
     unsubscribe(pattern: string | string[], callback?: ioBroker.ErrorCallback): void;
-    unsubscribe(pattern: string | string[], options?: CallOptions | null, callback?: ioBroker.ErrorCallback): void;
-    unsubscribeAsync(pattern: string | string[], options: CallOptions): Promise<void>;
-    unsubscribeUser(pattern: string | string[], options?: CallOptions | null, callback?: ioBroker.ErrorCallback): void;
-    unsubscribeUserAsync(pattern: string | string[], options: CallOptions): Promise<void>;
+    /**
+     * Unsubscribe from object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param options The current request options including the user
+     * @param callback Called once the subscription is removed
+     */
+    unsubscribe(pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback?: ioBroker.ErrorCallback): void;
+    /**
+     * Promise-version of unsubscribe
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param options The current request options including the user
+     */
+    unsubscribeAsync(pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
+    /**
+     * Unsubscribe a user from object changes matching the given pattern
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the subscription is removed
+     */
+    unsubscribeUser(pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback?: ioBroker.ErrorCallback): void;
+    /**
+     * Promise-version of unsubscribeUser
+     *
+     * @param pattern One or more patterns to unsubscribe from
+     * @param options The current request options including the user
+     */
+    unsubscribeUserAsync(pattern: string | string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
     private _objectHelper;
     private _chownObject;
-    chownObject(pattern: string, options: CallOptions, callback?: ioBroker.ChownObjectCallback): void | Promise<void>;
-    chownObjectAsync(pattern: string, options: CallOptions): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ChownObjectCallback>>;
+    /**
+     * Change the owner and owner group of all objects matching the given pattern
+     *
+     * @param pattern The pattern of object ids whose owner should be changed
+     * @param options The current request options including the new owner and the user, or the callback
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.owner The new owner (user id) to assign to the objects
+     * @param options.ownerGroup The new owner group to assign to the objects
+     * @param options.group The new owner group to assign (alias for ownerGroup)
+     * @param callback Called with the list of changed objects
+     */
+    chownObject(pattern: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+        owner: ioBroker.ObjectIDs.User;
+        ownerGroup?: ioBroker.ObjectIDs.Group;
+        group?: ioBroker.ObjectIDs.Group;
+    }, callback?: ioBroker.ChownObjectCallback): void | Promise<void>;
+    /**
+     * Promise-version of chownObject
+     *
+     * @param pattern The pattern of object ids whose owner should be changed
+     * @param options The current request options including the new owner and the user
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.owner The new owner (user id) to assign to the objects
+     * @param options.ownerGroup The new owner group to assign to the objects
+     * @param options.group The new owner group to assign (alias for ownerGroup)
+     */
+    chownObjectAsync(pattern: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+        owner: ioBroker.ObjectIDs.User;
+        ownerGroup?: ioBroker.ObjectIDs.Group;
+        group?: ioBroker.ObjectIDs.Group;
+    }): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ChownObjectCallback>>;
     private _chmodObject;
-    chmodObject(pattern: string, options: CallOptions | null, callback?: ioBroker.ChownObjectCallback): void | Promise<void>;
-    chmodObjectAsync(pattern: string, options: CallOptions): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ChownObjectCallback>>;
+    /**
+     * Change the file mode (permissions) of all files matching the given pattern
+     *
+     * @param pattern The pattern of object ids whose files should be changed
+     * @param options The current request options including the new mode and the user, or the callback
+     * @param options.mode The new permission mode to apply
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.object The permission bitmask for object access
+     * @param options.state The permission bitmask for state access
+     * @param callback Called with the list of changed objects
+     */
+    chmodObject(pattern: string, options: {
+        mode?: number;
+        user?: ioBroker.ObjectIDs.User;
+        object?: number;
+        state?: number;
+    }, callback?: ioBroker.ChownObjectCallback): void | Promise<void>;
+    /**
+     * Promise-version of chmodObject
+     *
+     * @param pattern The pattern of object ids whose files should be changed
+     * @param options The current request options including the new mode and the user
+     * @param options.mode The new permission mode to apply
+     * @param options.user The user on whose behalf the operation is performed
+     * @param options.object The permission bitmask for object access
+     * @param options.state The permission bitmask for state access
+     */
+    chmodObjectAsync(pattern: string, options: {
+        mode?: number;
+        user?: ioBroker.ObjectIDs.User;
+        object?: number;
+        state?: number;
+    }): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ChownObjectCallback>>;
     private _getObject;
-    getObject<T extends string>(id: T, options: Options | undefined | null, callback: ioBroker.GetObjectCallback<T>): void;
-    getObject<T extends string>(id: T, options?: Options | null): ioBroker.GetObjectPromise<T>;
+    /**
+     * Get a single object by its id
+     *
+     * @param id The id of the object to read
+     * @param options The current request options including the user
+     * @param callback Called with the read object
+     */
+    getObject<T extends string>(id: T, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | undefined | null, callback: ioBroker.GetObjectCallback<T>): void;
+    /**
+     * Get a single object by its id
+     *
+     * @param id The id of the object to read
+     * @param options The current request options including the user
+     */
+    getObject<T extends string>(id: T, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): ioBroker.GetObjectPromise<T>;
+    /**
+     * Get a single object by its id
+     *
+     * @param id The id of the object to read
+     * @param callback Called with the read object
+     */
     getObject<T extends string>(id: T, callback: ioBroker.GetObjectCallback<T>): void;
     /**
+     * Promise-version of getObject
      *
-     * @param id
-     * @param options
+     * @param id The id of the object to read
+     * @param options The current request options including the user
      * @deprecated use `getObject` without callback instead
      */
-    getObjectAsync<T extends string>(id: T, options?: Record<string, any> | null): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.GetObjectCallback<T>>>;
+    getObjectAsync<T extends string>(id: T, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.GetObjectCallback<T>>>;
     private _getKeys;
-    getKeys(pattern: string, options: CallOptions | null | undefined, callback: ioBroker.GetKeysCallback, dontModify?: boolean): void;
+    /**
+     * Get all object ids matching the given pattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user
+     * @param callback Called with the matching keys
+     * @param dontModify If true, the returned keys are not stripped of the namespace
+     */
+    getKeys(pattern: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, callback: ioBroker.GetKeysCallback, dontModify?: boolean): void;
+    /**
+     * Get all object ids matching the given pattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param callback Called with the matching keys
+     */
     getKeys(pattern: string, callback: ioBroker.GetKeysCallback): void;
-    getKeys(pattern: string, options?: CallOptions | null, callback?: undefined, dontModify?: boolean): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.GetKeysCallback>>;
-    getKeysAsync(id: string, options?: CallOptions): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.GetKeysCallback>>;
+    /**
+     * Get all object ids matching the given pattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user
+     * @param callback Must be undefined for the promise variant
+     * @param dontModify If true, the returned keys are not stripped of the namespace
+     */
+    getKeys(pattern: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback?: undefined, dontModify?: boolean): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.GetKeysCallback>>;
+    /**
+     * Promise-version of getKeys
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the keys are read
+     */
+    getKeysAsync(pattern: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    }): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.GetKeysCallback>>;
     private _getObjects;
-    getObjects(keys: string[], options?: CallOptions | null): Promise<ioBroker.AnyObject[]>;
-    getObjects(keys: string[], callback: (err?: Error | null, objs?: ioBroker.AnyObject[]) => void): void;
-    getObjects(keys: string[], options: CallOptions | null, callback: (err?: Error | null, objs?: ioBroker.AnyObject[]) => void, dontModify?: boolean): void;
-    getObjectsAsync(keys: string[], options?: CallOptions | null): Promise<ioBroker.AnyObject[]>;
+    /**
+     * Get multiple objects by their ids
+     *
+     * @param keys The ids of the objects to read
+     * @param options The current request options including the user
+     */
+    getObjects(keys: string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<ioBroker.AnyObject[]>;
+    /**
+     * Get multiple objects by their ids
+     *
+     * @param keys The ids of the objects to read
+     * @param callback Called with the read objects
+     */
+    getObjects(keys: string[], callback: (err?: Error | null, objs?: ({
+        error: string;
+    } | ioBroker.AnyObject | null)[]) => void): void;
+    /**
+     * Get multiple objects by their ids
+     *
+     * @param keys The ids of the objects to read
+     * @param options The current request options including the user
+     * @param callback Called with the read objects
+     * @param dontModify If true, the returned objects are not cloned/modified
+     */
+    getObjects(keys: string[], options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, callback: (err?: Error | null, objs?: ({
+        error: string;
+    } | ioBroker.AnyObject | null)[]) => void, dontModify?: boolean): void;
+    /**
+     * Promise-version of getObjects
+     *
+     * @param keys The ids of the objects to read
+     * @param options The current request options including the user
+     */
+    getObjectsAsync(keys: string[], options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<ioBroker.AnyObject[]>;
     private _getObjectsByPattern;
-    getObjectsByPattern(pattern: string, options: CallOptions | null): Promise<ioBroker.AnyObject[] | void>;
-    getObjectsByPattern(pattern: string, options: CallOptions | null, callback: (err?: Error | null, objs?: ioBroker.AnyObject[]) => void): void;
-    getObjectsByPatternAsync(pattern: string, options: CallOptions): Promise<ioBroker.AnyObject[] | void>;
+    /**
+     * Get all objects whose id matches the given pattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user
+     */
+    getObjectsByPattern(pattern: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<ioBroker.AnyObject[] | void>;
+    /**
+     * Get all objects whose id matches the given pattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user
+     * @param callback Called with the matching objects
+     */
+    getObjectsByPattern(pattern: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback: (err?: Error | null, objs?: ({
+        error: string;
+    } | ioBroker.AnyObject | null)[]) => void): void;
+    /**
+     * Promise-version of getObjectsByPattern
+     *
+     * @param pattern The pattern to match object ids against
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the objects are read
+     */
+    getObjectsByPatternAsync(pattern: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    }): Promise<({
+        error: string;
+    } | ioBroker.AnyObject | null)[] | void>;
     private _setObject;
-    setObject<T extends string>(id: T, obj: ioBroker.SettableObject<ioBroker.ObjectIdToObjectType<T>>): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.SetObjectCallback>>;
-    setObject<T extends string>(id: T, obj: ioBroker.SettableObject<ioBroker.ObjectIdToObjectType<T>>, callback?: ioBroker.SetObjectCallback): void | Promise<ioBroker.CallbackReturnTypeOf<ioBroker.SetObjectCallback>>;
-    setObject<T extends string>(id: T, obj: ioBroker.SettableObject<ioBroker.ObjectIdToObjectType<T>>, options?: CallOptions | null, callback?: ioBroker.SetObjectCallback): void | Promise<ioBroker.CallbackReturnTypeOf<ioBroker.SetObjectCallback>>;
     /**
+     * Set anew or update an object
+     *
+     * @param id ID of the object
+     * @param obj The object to write
+     * @param options options for access control are optional
+     */
+    setObject<T extends string>(id: T, obj: ioBroker.SettableObject<ioBroker.ObjectIdToObjectType<T>>, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.SetObjectCallback>>;
+    /**
+     * Set anew or update an object
+     *
+     * @param id ID of the object
+     * @param obj The object to write
+     * @param options options for access control are optional
+     * @param callback return function
+     */
+    setObject<T extends string>(id: T, obj: ioBroker.SettableObject<ioBroker.ObjectIdToObjectType<T>>, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | undefined | null, callback: ioBroker.SetObjectCallback): void;
+    /**
+     * Set anew or update an object
      *
-     * @param id
-     * @param obj
-     * @param options
+     * @param id ID of the object
+     * @param obj The object to write
+     * @param callback return function
+     */
+    setObject<T extends string>(id: T, obj: ioBroker.SettableObject<ioBroker.ObjectIdToObjectType<T>>, callback: ioBroker.SetObjectCallback): void;
+    /**
+     * Promise-version of setObject
+     *
+     * @param id ID of the object
+     * @param obj The object to write
+     * @param options options for access control are optional
      * @deprecated use `setObject` without callback instead
      */
-    setObjectAsync(id: string, obj: ioBroker.SettableObject, options?: CallOptions | null): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.SetObjectCallback>>;
+    setObjectAsync(id: string, obj: ioBroker.SettableObject, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.SetObjectCallback>>;
     private _delObject;
+    /**
+     * Delete an object
+     *
+     * @param id The id of the object to delete
+     * @param callback Called once the object has been deleted
+     */
     delObject(id: string, callback: ioBroker.ErrorCallback): void;
-    delObject(id: string, options: CallOptions | null, callback: ioBroker.ErrorCallback): void;
-    delObject(id: string, options?: CallOptions | null): Promise<void>;
-    delObjectAsync(id: string, options?: CallOptions): Promise<void>;
     /**
-     * Function to checks if comparisons will work according to the configured Locale
+     * Delete an object
+     *
+     * @param id The id of the object to delete
+     * @param options The current request options including the user
+     * @param callback Called once the object has been deleted
+     */
+    delObject(id: string, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, callback: ioBroker.ErrorCallback): void;
+    /**
+     * Delete an object
+     *
+     * @param id The id of the object to delete
+     * @param options The current request options including the user
+     */
+    delObject(id: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<void>;
+    /**
+     * Promise-version of delObject
+     *
+     * @param id The id of the object to delete
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the operation is performed
+     */
+    delObjectAsync(id: string, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    }): Promise<void>;
+    /**
+     * Function to check if comparisons will work according to the configured Locale
      */
     isSystemLocaleSupported(): Promise<boolean>;
     private _applyViewFunc;
     private _getObjectView;
-    getObjectView<Design extends string = string, Search extends string = string>(design: Design, search: Search, params?: ioBroker.GetObjectViewParams, options?: CallOptions | null): ioBroker.GetObjectViewPromise<ioBroker.InferGetObjectViewItemType<Design, Search>>;
-    getObjectView<Design extends string = string, Search extends string = string>(design: Design, search: Search, params: ioBroker.GetObjectViewParams | undefined, options: CallOptions | undefined | null, callback: ioBroker.GetObjectViewCallback<ioBroker.InferGetObjectViewItemType<Design, Search>>): void;
+    /**
+     * Run a predefined object view (design document) and return the matching rows
+     *
+     * @param design The design document name
+     * @param search The view name within the design document
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user
+     */
+    getObjectView<Design extends string = string, Search extends string = string>(design: Design, search: Search, params?: ioBroker.GetObjectViewParams, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null): ioBroker.GetObjectViewPromise<ioBroker.InferGetObjectViewItemType<Design, Search>>;
+    /**
+     * Run a predefined object view (design document) and return the matching rows
+     *
+     * @param design The design document name
+     * @param search The view name within the design document
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user
+     * @param callback Called with the matching rows
+     */
+    getObjectView<Design extends string = string, Search extends string = string>(design: Design, search: Search, params: ioBroker.GetObjectViewParams | undefined, options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | undefined | null, callback: ioBroker.GetObjectViewCallback<ioBroker.InferGetObjectViewItemType<Design, Search>>): void;
+    /**
+     * Run a predefined object view (design document) and return the matching rows
+     *
+     * @param design The design document name
+     * @param search The view name within the design document
+     * @param params Query parameters such as startkey and endkey
+     * @param callback Called with the matching rows
+     */
     getObjectView<Design extends string = string, Search extends string = string>(design: Design, search: Search, params: ioBroker.GetObjectViewParams, callback: ioBroker.GetObjectViewCallback<ioBroker.InferGetObjectViewItemType<Design, Search>>): void;
-    getObjectViewAsync<Design extends string = string, Search extends string = string>(design: Design, search: Search, params?: ioBroker.GetObjectViewParams, options?: CallOptions): ioBroker.GetObjectViewPromise<ioBroker.InferGetObjectViewItemType<Design, Search>>;
+    /**
+     * Promise-version of getObjectView
+     *
+     * @param design The design document name
+     * @param search The view name within the design document
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the view is queried
+     */
+    getObjectViewAsync<Design extends string = string, Search extends string = string>(design: Design, search: Search, params?: ioBroker.GetObjectViewParams, options?: {
+        user?: ioBroker.ObjectIDs.User;
+    }): ioBroker.GetObjectViewPromise<ioBroker.InferGetObjectViewItemType<Design, Search>>;
     private _getObjectList;
+    /**
+     * Get the list of objects matching the given parameters
+     *
+     * @param params Query parameters such as startkey and endkey
+     */
     getObjectList(params: ioBroker.GetObjectListParams): ioBroker.GetObjectListPromise;
-    getObjectList(params: ioBroker.GetObjectListParams, options?: CallOptions | null): ioBroker.GetObjectListPromise;
+    /**
+     * Get the list of objects matching the given parameters
+     *
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user
+     */
+    getObjectList(params: ioBroker.GetObjectListParams, options?: {
+        user?: ioBroker.ObjectIDs.User;
+        sorted?: boolean;
+    } | null): ioBroker.GetObjectListPromise;
+    /**
+     * Get the list of objects matching the given parameters
+     *
+     * @param params Query parameters such as startkey and endkey
+     * @param callback Called with the matching objects
+     */
     getObjectList(params: ioBroker.GetObjectListParams, callback: ioBroker.GetObjectListCallback<ioBroker.Object>): void;
-    getObjectList<T extends ioBroker.GetObjectListCallback<ioBroker.Object>>(params: ioBroker.GetObjectListParams, options?: CallOptions | null, callback?: T): T extends ioBroker.GetObjectListCallback<ioBroker.Object> ? void : ioBroker.GetObjectListPromise;
-    getObjectListAsync(params: ioBroker.GetObjectListParams, options?: CallOptions): ioBroker.GetObjectListPromise;
+    /**
+     * Get the list of objects matching the given parameters
+     *
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user
+     * @param callback Called with the matching objects
+     */
+    getObjectList<T extends ioBroker.GetObjectListCallback<ioBroker.Object>>(params: ioBroker.GetObjectListParams, options?: {
+        user?: ioBroker.ObjectIDs.User;
+        sorted?: boolean;
+    } | null, callback?: T): T extends ioBroker.GetObjectListCallback<ioBroker.Object> ? void : ioBroker.GetObjectListPromise;
+    /**
+     * Promise-version of getObjectList
+     *
+     * @param params Query parameters such as startkey and endkey
+     * @param options The current request options including the user
+     */
+    getObjectListAsync(params: ioBroker.GetObjectListParams, options?: {
+        user?: ioBroker.ObjectIDs.User;
+        checked?: true;
+        sorted?: boolean;
+    } | null): ioBroker.GetObjectListPromise;
     private _extendObject;
-    extendObject<T extends string>(id: T, obj: ioBroker.PartialObject<ioBroker.ObjectIdToObjectType<T, 'write'>>, options?: ioBroker.ExtendObjectOptions | null): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ExtendObjectCallback>>;
-    extendObject<T extends string>(id: T, obj: ioBroker.PartialObject<ioBroker.ObjectIdToObjectType<T, 'write'>>, options?: ioBroker.ExtendObjectOptions | null, callback?: ioBroker.ExtendObjectCallback): void | Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ExtendObjectCallback>>;
-    extendObjectAsync(id: string, obj: Partial<ioBroker.AnyObject>, options?: ioBroker.ExtendObjectOptions): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.ExtendObjectCallback>>;
+    /**
+     * Extend an existing object with the given partial object, creating it if it does not exist
+     *
+     * @param id The id of the object to extend
+     * @param obj The partial object to merge into the existing object
+     * @param options The current request options including the user, or the callback
+     */
+    extendObject<T extends string>(id: T, obj: ioBroker.PartialObject<ioBroker.ObjectIdToObjectType<T, 'write'>>, options?: ioBroker.ExtendObjectOptions | null): Promise<{
+        id: string;
+        value: ioBroker.AnyObject;
+    }>;
     /**
      * Returns the object id if found
      *
-     * @param idOrName
-     * @param type
-     * @param options
-     * @param callback
+     * @param idOrName The id or name to search for
+     * @param type The expected common type, or null for any
+     * @param options The current request options (may include a language)
+     * @param options.language The language to use when resolving names
+     * @param options.user The user on whose behalf the lookup is performed
+     * @param userContext The resolved user context to check the rights against
+     * @param callback Called with the found id and the original id/name
      */
     private _findObject;
-    findObject(idOrName: string, type: ioBroker.CommonType | null, options: (CallOptions & {
+    /**
+     * Find an object by its id or name
+     *
+     * @param idOrName The id or name to search for
+     * @param type The expected common type, or null for any
+     * @param options The current request options (may include a language)
+     * @param callback Called with the found id and the original id/name
+     */
+    findObject(idOrName: string, type: ioBroker.CommonType | null, options: {
         language?: ioBroker.Languages;
-    }) | null, callback: ioBroker.FindObjectCallback): void;
+        user?: ioBroker.ObjectIDs.User;
+    } | null, callback: ioBroker.FindObjectCallback): void;
+    /**
+     * Find an object by its id or name
+     *
+     * @param idOrName The id or name to search for
+     * @param type The expected common type, or null for any
+     * @param callback Called with the found id and the original id/name
+     */
     findObject(idOrName: string, type: ioBroker.CommonType | null, callback: ioBroker.FindObjectCallback): void;
-    findObject(idOrName: string, type?: ioBroker.CommonType | null, options?: (CallOptions & {
+    /**
+     * Find an object by its id or name
+     *
+     * @param idOrName The id or name to search for
+     * @param type The expected common type, or null for any
+     * @param options The current request options (may include a language)
+     */
+    findObject(idOrName: string, type?: ioBroker.CommonType | null, options?: {
         language?: ioBroker.Languages;
-    }) | null): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.FindObjectCallback>>;
+        user?: ioBroker.ObjectIDs.User;
+    } | null): Promise<ioBroker.CallbackReturnTypeOf<ioBroker.FindObjectCallback>>;
+    /**
+     * Add object property paths that should be preserved when an object is overwritten (controller only)
+     *
+     * @param settings One or more property paths to preserve
+     */
     addPreserveSettings(settings: string[] | string): void;
     private _destroyDBHelper;
     private _destroyDB;
-    destroyDB(options: CallOptions | null | undefined, callback: ioBroker.ErrorCallback): void;
-    destroyDBAsync(options?: CallOptions): Promise<void>;
+    /**
+     * Delete the whole objects database (requires admin rights)
+     *
+     * @param options The current request options including the user, or the callback
+     * @param callback Called once the database has been destroyed
+     */
+    destroyDB(options: {
+        user?: ioBroker.ObjectIDs.User;
+    } | null | undefined, callback: ioBroker.ErrorCallback): void;
+    /**
+     * Promise-version of destroyDB
+     *
+     * @param options The current request options including the user
+     * @param options.user The user on whose behalf the database is destroyed
+     */
+    destroyDBAsync(options?: {
+        user?: ioBroker.ObjectIDs.User;
+    }): Promise<void>;
+    /**
+     * Destructor of the class. Called when shutting down to close the redis connections.
+     */
     destroy(): Promise<void>;
+    /**
+     * Load and register the Lua scripts used for atomic operations on the redis server
+     */
     loadLuaScripts(): Promise<void>;
     /**
-     * Get all keys matching a pattern using redis SCAN command, duplicates are filtered out
+     * Get all keys matching a pattern using redis SCAN command; duplicates are filtered out
      *
-     * @param pattern - pattern to match, e. g. io.hm-rpc.0*
+     * @param pattern - pattern to match, e.g. io.hm-rpc.0*
      * @param count - count argument used by redis SCAN, default is 250
      */
     private _getKeysViaScan;
@@ -313,15 +1149,15 @@ export declare class ObjectsInRedisClient {
      */
     extendPrimaryHostLock(ms: number): Promise<number>;
     /**
-     * Sets current host as primary if no primary host active
-     * Value will expire after ms milliseconds
+     * Sets the current host as primary if no primary host active
+     * Value expires after ms milliseconds
      *
      * @param ms - ms until value expires
      * @returns 1 if lock acquired else 0
      */
     setPrimaryHost(ms: number): Promise<number>;
     /**
-     * Get name of the primary host
+     * Get the name of the primary host
      */
     getPrimaryHost(): Promise<string | null>;
     /**
@@ -335,7 +1171,7 @@ export declare class ObjectsInRedisClient {
      */
     setProtocolVersion(version: number | string): Promise<void>;
     /**
-     * Subscribe to expired events to get expiration of primary host
+     * Subscribe to expired events to get expiration of the primary host
      */
     subscribePrimaryHost(): Promise<void>;
     /**