@iobroker/db-objects-file 7.2.2 → 7.2.3-alpha.1-20260621-61726ea22

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

@@ -3,6 +3,9 @@
  * including the available methods for use by js-controller directly
  */
 export class ObjectsInMemoryFileDB extends InMemoryFileDB {
+    /**
+     * @param settings Settings for the objects database
+     */
     constructor(settings: any);
     change: any;
     META_ID: string;
@@ -16,14 +19,50 @@ export class ObjectsInMemoryFileDB extends InMemoryFileDB {
     writeFileInterval: number;
     objectsDir: string;
     existingMetaObjects: {};
+    /**
+     * Normalize a file name by collapsing slashes and backslashes into a single forward slash
+     *
+     * @param name The file name to normalize
+     */
     _normalizeFilename(name: any): any;
+    /**
+     * Schedule writing the file settings (_data.json) to disk
+     *
+     * @param id The object ID whose file settings should be saved, or a boolean used as the force flag
+     * @param force If true, write the settings immediately instead of debounced
+     */
     _saveFileSettings(id: any, force: any): void;
+    /**
+     * Load the file settings (_data.json) for the given object ID into memory
+     *
+     * @param id The object ID whose file settings should be loaded
+     */
     _loadFileSettings(id: any): void;
+    /**
+     * Synchronize the in-memory file metadata with the files actually present on disk (server only)
+     *
+     * @param limitId Optional object ID to limit the synchronization to
+     */
     syncFileDirectory(limitId: any): {
         numberSuccess: number;
         notifications: any[];
     };
+    /**
+     * Write a file into an object's file storage (used by the server)
+     *
+     * @param id The object ID owning the file
+     * @param name The file name
+     * @param data The file content
+     * @param options Optional write options, or the mime type as a string
+     */
     _writeFile(id: any, name: any, data: any, options: any): void;
+    /**
+     * Read a file from an object's file storage (used by the server)
+     *
+     * @param id The object ID owning the file
+     * @param name The file name
+     * @param options Optional read options
+     */
     _readFile(id: any, name: any, options: any): {
         fileContent: any;
         fileMime: any;
@@ -40,7 +79,7 @@ export class ObjectsInMemoryFileDB extends InMemoryFileDB {
      *
      * @param id id of the namespace
      * @param [name] name of the file
-     * @returns
+     * @returns true if the file exists
      */
     _fileExists(id: any, name?: any): boolean;
     /**
@@ -48,10 +87,23 @@ export class ObjectsInMemoryFileDB extends InMemoryFileDB {
      *
      * @param id id of the namespace
      * @param [name] name of the directory
-     * @returns
+     * @returns true if the directory exists
      */
     dirExists(id: any, name?: any): boolean;
+    /**
+     * Delete a file or directory from an object's file storage (used by the server)
+     *
+     * @param id The object ID owning the file
+     * @param name The file or directory name to delete
+     */
     _unlink(id: any, name: any): void;
+    /**
+     * List the contents of a directory in an object's file storage (used by the server)
+     *
+     * @param id The object ID owning the files
+     * @param name The directory name to list
+     * @param options Optional read options
+     */
     _readDir(id: any, name: any, options: any): {
         file: string;
         stats: fs.Stats;
@@ -60,31 +112,99 @@ export class ObjectsInMemoryFileDB extends InMemoryFileDB {
         modifiedAt: any;
         createdAt: any;
     }[];
+    /**
+     * Rename a file or directory in an object's file storage (used by the server)
+     *
+     * @param id The object ID owning the file
+     * @param oldName The current file or directory name
+     * @param newName The new file or directory name
+     */
     _rename(id: any, oldName: any, newName: any): void;
+    /**
+     * Create a deep clone of the given object
+     *
+     * @param obj The object to clone
+     */
     _clone(obj: any): any;
+    /**
+     * Subscribe a client to meta changes
+     *
+     * @param client The client to subscribe
+     * @param pattern The pattern of meta IDs to subscribe to
+     */
     _subscribeMeta(client: any, pattern: any): void;
+    /**
+     * Subscribe a client to object changes (used by the server)
+     *
+     * @param client The client to subscribe
+     * @param pattern The pattern of object IDs to subscribe to
+     */
     _subscribeConfigForClient(client: any, pattern: any): void;
+    /**
+     * Unsubscribe a client from object changes (used by the server)
+     *
+     * @param client The client to unsubscribe
+     * @param pattern The pattern of object IDs to unsubscribe from
+     */
     _unsubscribeConfigForClient(client: any, pattern: any): void;
+    /**
+     * Subscribe a client to file changes of an object (used by the server)
+     *
+     * @param client The client to subscribe
+     * @param id The object ID owning the files
+     * @param pattern One or more file name patterns to subscribe to
+     */
     _subscribeFileForClient(client: any, id: any, pattern: any): void;
+    /**
+     * Unsubscribe a client from file changes of an object (used by the server)
+     *
+     * @param client The client to unsubscribe
+     * @param id The object ID owning the files
+     * @param pattern One or more file name patterns to unsubscribe from
+     */
     _unsubscribeFileForClient(client: any, id: any, pattern: any): void;
+    /**
+     * Get a single object by its ID (used by the server)
+     *
+     * @param id The object ID to read
+     */
     _getObject(id: any): any;
+    /**
+     * Get all object IDs matching the given pattern, sorted (used by the server)
+     *
+     * @param pattern The pattern to match object IDs against
+     */
     _getKeys(pattern: any): string[];
+    /**
+     * Get the values of the given object IDs (used by the server)
+     *
+     * @param keys The object IDs to read
+     */
     _getObjects(keys: any): any;
+    /**
+     * Get the meta dictionary, creating it if it does not exist yet
+     */
     _ensureMetaDict(): any;
     /**
      * Get value of given meta id
      *
-     * @param id
-     * @returns
+     * @param id The meta ID to read
+     * @returns the stored meta value
      */
     getMeta(id: any): any;
     /**
      * Sets given value to id in metaNamespace
      *
-     * @param id
-     * @param value
+     * @param id The meta ID to write
+     * @param value The value to store
      */
     setMeta(id: any, value: any): void;
+    /**
+     * Directly set an object value and publish the change (used by the server)
+     *
+     * @param id The object ID to set
+     * @param obj The object to store
+     */
     _setObjectDirect(id: any, obj: any): void;
     /**
      * Delete the given object from the dataset
@@ -92,9 +212,22 @@ export class ObjectsInMemoryFileDB extends InMemoryFileDB {
      * @param id unique id of the object
      */
     _delObject(id: any): void;
+    /**
+     * Apply a view's map function over all objects and collect the matching rows
+     *
+     * @param func The view definition containing the map function
+     * @param params Query parameters such as startkey and endkey
+     */
     _applyView(func: any, params: any): {
         rows: never[];
     };
+    /**
+     * Run a predefined object view (design document) and return the matching rows (used by the server)
+     *
+     * @param design The design document name
+     * @param search The view name within the design document
+     * @param params Query parameters such as startkey and endkey
+     */
     _getObjectView(design: any, search: any, params: any): {
         rows: never[];
     };

package/build/cjs/lib/objects/objectsInMemFileDB.js

@@ -38,9 +38,12 @@ var import_db_base2 = require("@iobroker/db-base");
 var import_db_objects_redis = require("@iobroker/db-objects-redis");
 var import_deep_clone = __toESM(require("deep-clone"), 1);
 class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
+  /**
+   * @param settings Settings for the objects database
+   */
   constructor(settings) {
-    settings = settings || {};
-    settings.fileDB = settings.fileDB || {
+    settings ||= {};
+    settings.fileDB ||= {
       fileName: "objects.json",
       backupDirName: "backup-objects"
     };
@@ -75,12 +78,21 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       this.defaultNewAcl = (0, import_deep_clone.default)(configObj.common.defaultNewAcl);
     }
   }
-  // internal functionality
+  /**
+   * Normalize a file name by collapsing slashes and backslashes into a single forward slash
+   *
+   * @param name The file name to normalize
+   */
   _normalizeFilename(name) {
     return name ? name.replace(/[/\\]+/g, "/") : name;
   }
   // -------------- FILE FUNCTIONS -------------------------------------------
-  // internal functionality
+  /**
+   * Schedule writing the file settings (_data.json) to disk
+   *
+   * @param id The object ID whose file settings should be saved, or a boolean used as the force flag
+   * @param force If true, write the settings immediately instead of debounced
+   */
   _saveFileSettings(id, force) {
     if (typeof id === "boolean") {
       force = id;
@@ -115,7 +127,11 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       }, 1e3);
     }
   }
-  // internal functionality
+  /**
+   * Load the file settings (_data.json) for the given object ID into memory
+   *
+   * @param id The object ID whose file settings should be loaded
+   */
   _loadFileSettings(id) {
     if (!this.fileOptions[id]) {
       const location = import_node_path.default.join(this.objectsDir, id, "_data.json");
@@ -148,7 +164,11 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       }
     }
   }
-  // server only functionality
+  /**
+   * Synchronize the in-memory file metadata with the files actually present on disk (server only)
+   *
+   * @param limitId Optional object ID to limit the synchronization to
+   */
   syncFileDirectory(limitId) {
     const resNotifies = [];
     let resSynced = 0;
@@ -229,7 +249,14 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       notifications: resNotifies
     };
   }
-  // needed by server
+  /**
+   * Write a file into an object's file storage (used by the server)
+   *
+   * @param id The object ID owning the file
+   * @param name The file name
+   * @param data The file content
+   * @param options Optional write options, or the mime type as a string
+   */
   _writeFile(id, name, data, options) {
     if (typeof options === "string") {
       options = { mimeType: options };
@@ -291,7 +318,13 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       this.publishAll("files", `${id}$%$${name2}`, size);
     }, name, data.byteLength);
   }
-  // needed by server
+  /**
+   * Read a file from an object's file storage (used by the server)
+   *
+   * @param id The object ID owning the file
+   * @param name The file name
+   * @param options Optional read options
+   */
   _readFile(id, name, options) {
     if (options && options.acl) {
       options.acl = null;
@@ -394,7 +427,7 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
    *
    * @param id id of the namespace
    * @param [name] name of the file
-   * @returns
+   * @returns true if the file exists
    */
   // needed by server
   _fileExists(id, name) {
@@ -418,7 +451,7 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
    *
    * @param id id of the namespace
    * @param [name] name of the directory
-   * @returns
+   * @returns true if the directory exists
    */
   // special functionality only for Server (used together with SyncFileDirectory)
   dirExists(id, name) {
@@ -437,7 +470,12 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       return false;
     }
   }
-  // needed by server
+  /**
+   * Delete a file or directory from an object's file storage (used by the server)
+   *
+   * @param id The object ID owning the file
+   * @param name The file or directory name to delete
+   */
   _unlink(id, name) {
     const _path = import_db_objects_redis.objectsUtils.sanitizePath(id, name);
     id = _path.id;
@@ -483,7 +521,13 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       }, id, name);
     }
   }
-  // needed by server
+  /**
+   * List the contents of a directory in an object's file storage (used by the server)
+   *
+   * @param id The object ID owning the files
+   * @param name The directory name to list
+   * @param options Optional read options
+   */
   _readDir(id, name, options) {
     if (options && options.acl) {
       options.acl = null;
@@ -592,7 +636,13 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
     }
     return res;
   }
-  // needed by server
+  /**
+   * Rename a file or directory in an object's file storage (used by the server)
+   *
+   * @param id The object ID owning the file
+   * @param oldName The current file or directory name
+   * @param newName The new file or directory name
+   */
   _rename(id, oldName, newName) {
     const _path = import_db_objects_redis.objectsUtils.sanitizePath(id, oldName);
     id = _path.id;
@@ -622,7 +672,11 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
     });
     this._saveFileSettings(id, true);
   }
-  // internal functionality
+  /**
+   * Create a deep clone of the given object
+   *
+   * @param obj The object to clone
+   */
   _clone(obj) {
     if (obj === null || obj === void 0 || !import_db_base2.tools.isObject(obj)) {
       return obj;
@@ -633,18 +687,40 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
     }
     return temp;
   }
+  /**
+   * Subscribe a client to meta changes
+   *
+   * @param client The client to subscribe
+   * @param pattern The pattern of meta IDs to subscribe to
+   */
   _subscribeMeta(client, pattern) {
     this.handleSubscribe(client, "meta", pattern);
   }
-  // needed by server
+  /**
+   * Subscribe a client to object changes (used by the server)
+   *
+   * @param client The client to subscribe
+   * @param pattern The pattern of object IDs to subscribe to
+   */
   _subscribeConfigForClient(client, pattern) {
     this.handleSubscribe(client, "objects", pattern);
   }
-  // needed by server
+  /**
+   * Unsubscribe a client from object changes (used by the server)
+   *
+   * @param client The client to unsubscribe
+   * @param pattern The pattern of object IDs to unsubscribe from
+   */
   _unsubscribeConfigForClient(client, pattern) {
     this.handleUnsubscribe(client, "objects", pattern);
   }
-  // needed by server
+  /**
+   * Subscribe a client to file changes of an object (used by the server)
+   *
+   * @param client The client to subscribe
+   * @param id The object ID owning the files
+   * @param pattern One or more file name patterns to subscribe to
+   */
   _subscribeFileForClient(client, id, pattern) {
     if (Array.isArray(pattern)) {
       pattern.forEach((pattern2) => this.handleSubscribe(client, "files", `${id}$%$${pattern2}`));
@@ -652,7 +728,13 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       this.handleSubscribe(client, "files", `${id}$%$${pattern}`);
     }
   }
-  // needed by server
+  /**
+   * Unsubscribe a client from file changes of an object (used by the server)
+   *
+   * @param client The client to unsubscribe
+   * @param id The object ID owning the files
+   * @param pattern One or more file name patterns to unsubscribe from
+   */
   _unsubscribeFileForClient(client, id, pattern) {
     if (Array.isArray(pattern)) {
       pattern.forEach((pattern2) => this.handleUnsubscribe(client, "files", `${id}$%$${pattern2}`));
@@ -660,24 +742,39 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       this.handleUnsubscribe(client, "files", `${id}$%$${pattern}`);
     }
   }
-  // needed by server
+  /**
+   * Get a single object by its ID (used by the server)
+   *
+   * @param id The object ID to read
+   */
   _getObject(id) {
     return this.dataset[id];
   }
-  // needed by server
+  /**
+   * Get all object IDs matching the given pattern, sorted (used by the server)
+   *
+   * @param pattern The pattern to match object IDs against
+   */
   _getKeys(pattern) {
     const r = new RegExp(import_db_base2.tools.pattern2RegEx(pattern));
     const result2 = Object.keys(this.dataset).filter((id) => r.test(id) && id !== this.META_ID);
     result2.sort();
     return result2;
   }
-  // needed by server
+  /**
+   * Get the values of the given object IDs (used by the server)
+   *
+   * @param keys The object IDs to read
+   */
   _getObjects(keys) {
     if (!keys) {
       throw new Error("no keys");
     }
     return keys.map((id) => this.dataset[id]);
   }
+  /**
+   * Get the meta dictionary, creating it if it does not exist yet
+   */
   _ensureMetaDict() {
     let meta = this.dataset[this.META_ID];
     if (!meta) {
@@ -689,8 +786,8 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
   /**
    * Get value of given meta id
    *
-   * @param id
-   * @returns
+   * @param id The meta ID to read
+   * @returns the stored meta value
    */
   getMeta(id) {
     const meta = this._ensureMetaDict();
@@ -699,8 +796,8 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
   /**
    * Sets given value to id in metaNamespace
    *
-   * @param id
-   * @param value
+   * @param id The meta ID to write
+   * @param value The value to store
    */
   setMeta(id, value) {
     const meta = this._ensureMetaDict();
@@ -714,7 +811,12 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       this.stateTimer = setTimeout(() => this.saveState(), this.writeFileInterval);
     }
   }
-  // needed by server
+  /**
+   * Directly set an object value and publish the change (used by the server)
+   *
+   * @param id The object ID to set
+   * @param obj The object to store
+   */
   _setObjectDirect(id, obj) {
     this.dataset[id] = obj;
     if (obj.type === "meta" && this.existingMetaObjects[id] === false) {
@@ -745,7 +847,12 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
       this.stateTimer = setTimeout(() => this.saveState(), this.writeFileInterval);
     }
   }
-  // internal functionality
+  /**
+   * Apply a view's map function over all objects and collect the matching rows
+   *
+   * @param func The view definition containing the map function
+   * @param params Query parameters such as startkey and endkey
+   */
   _applyView(func, params) {
     const result = {
       rows: []
@@ -786,7 +893,13 @@ class ObjectsInMemoryFileDB extends import_db_base.InMemoryFileDB {
     }
     return result;
   }
-  // needed by server
+  /**
+   * Run a predefined object view (design document) and return the matching rows (used by the server)
+   *
+   * @param design The design document name
+   * @param search The view name within the design document
+   * @param params Query parameters such as startkey and endkey
+   */
   _getObjectView(design, search, params2) {
     const designObj = this.dataset[`_design/${design}`];
     if (!designObj) {