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

package/build/esm/lib/inMemFileDB.d.ts

@@ -1,66 +1,120 @@
 /**
  *      States DB in memory - Server
  *
- *      Copyright 2013-2024 bluefox <dogafox@gmail.com>
+ *      Copyright 2013-2026 bluefox <dogafox@gmail.com>
  *
  *      MIT License
  *
  */
 import type { InternalLogger } from '@iobroker/js-controller-common-db/tools';
+interface BackupOptions {
+    /** deactivates backup if true */
+    disabled: boolean;
+    /** minimum number of files */
+    files: number;
+    hours: number;
+    /** minutes */
+    period: number;
+    path: string;
+}
+export type MetaObject = Record<string, string>;
+export type FileSize = number;
+/** Options describing how to connect to the database server */
 export interface ConnectionOptions {
+    /** Password for authentication, if required */
     pass?: string;
+    /** Name of the sentinel master to connect to */
     sentinelName?: string;
     /** array on sentinel */
     host: string | string[];
     /** array on sentinel */
     port: number | number[];
-    options: Record<string, any>;
+    /** Additional connection options passed to the database driver */
+    options: ioBroker.ObjectsDatabaseOptions['options'];
+    /** Options forwarded to the JSONL database backend */
+    jsonlOptions?: ioBroker.ObjectsDatabaseOptions['jsonlOptions'];
+    /** Redis key prefix used by the in-memory server */
+    redisNamespace?: string;
+    /** Enable more verbose connection logging */
     enhancedLogging?: boolean;
+    /** Disable the in-memory file cache and always read files from disk */
+    noFileCache?: boolean;
+    /** Whether the connection should be secured via TLS */
+    secure?: boolean;
+    /** Backup configuration */
     backup?: BackupOptions;
     /** relative path to the data dir */
     dataDir?: string;
+    /** Interval in milliseconds in which the in-memory states are persisted to disk */
+    writeFileInterval?: number;
 }
-type ChangeFunction = (id: string, state: any) => void;
+type ChangeFunction<TObject> = (id: string, obj: TObject) => void;
+/** Status information about the database */
 export interface DbStatus {
-    type: string;
+    /** Type of the database backend (e.g. file, jsonl, redis) */
+    type: 'file' | 'redis' | 'jsonl';
+    /** Whether this process runs the database server */
     server: boolean;
 }
-interface BackupOptions {
-    /** deactivates backup if true */
-    disabled: boolean;
-    /** minimum number of files */
-    files: number;
-    hours: number;
-    /** minutes */
-    period: number;
-    path: string;
-}
+/** Options describing where the database stores its files */
 export interface DbOptions {
+    /** Name of the directory used for backups */
     backupDirName: string;
+    /** Name of the database file */
     fileName: string;
 }
-interface FileDbSettings {
-    fileDB: DbOptions;
-    jsonlDB: DbOptions;
-    backup: BackupOptions;
-    change?: ChangeFunction;
-    connected: (nameOfServer: string) => void;
-    logger: InternalLogger;
+/** Settings accepted by the in-memory database classes and their subclasses */
+export interface FileDbSettings<TObject> {
+    /** File DB storage options (filled in by the subclass constructor before `super()`) */
+    fileDB?: DbOptions;
+    /** JSONL DB storage options (only set by the JSONL backend; only the file name is used) */
+    jsonlDB?: Pick<DbOptions, 'fileName'>;
+    /** Backup options (derived from `connection.backup` by the base constructor) */
+    backup?: BackupOptions;
+    /** Callback invoked when a value in the database changes */
+    change?: ChangeFunction<TObject>;
+    /** Callback invoked once the database server is ready */
+    connected: (nameOfServer?: string) => void;
+    /** Logger instance (or logger configuration) used for all database logging */
+    logger?: InternalLogger;
+    /** Options describing how to connect to the database server */
     connection: ConnectionOptions;
     /** unused */
     auth?: null;
-    secure: boolean;
-    /** as required by createServer TODO: if createServer is typed, add type */
-    certificates: any;
-    port: number;
-    host: string;
+    /** Whether the server connection should be secured via TLS */
+    secure?: boolean;
+    /** Port the in-memory server listens on */
+    port?: number;
+    /** Host the in-memory server binds to */
+    host?: string;
     /** logging namespace */
     namespace?: string;
+    /** Host name used as a fallback for the logging namespace */
+    hostname?: string;
+    /** Default ACL applied to newly created objects */
+    defaultNewAcl?: {
+        object: number;
+        state: number;
+        file: number;
+        owner: ioBroker.ObjectIDs.User;
+        ownerGroup: ioBroker.ObjectIDs.Group;
+    };
+    /** Redis key prefix used by the in-memory server (defaults to "io") */
+    redisNamespace?: string;
+    /** Namespace used for the message box */
+    namespaceMsg?: string;
+    /** Namespace used for log messages */
+    namespaceLog?: string;
+    /** Namespace used for sessions */
+    namespaceSession?: string;
+    /** Namespace used for meta information */
+    metaNamespace?: string;
+    /** Redis key prefix used for object meta information (defaults to "meta") */
+    namespaceMeta?: string;
 }
 interface Subscription {
     pattern: string;
     regex: RegExp;
-    options: any;
 }
 interface SubscriptionClient {
     _subscribe?: Record<string, Subscription[]>;
@@ -69,19 +123,25 @@ interface SubscriptionClient {
  * The parent of the class structure, which provides basic JSON storage
  * and general subscription and publish functionality
  */
-export declare class InMemoryFileDB {
-    private settings;
-    private readonly change;
-    protected dataset: Record<string, any>;
-    private readonly namespace;
+export declare class InMemoryFileDB<TObject, THandler extends SubscriptionClient = SubscriptionClient> {
+    protected settings: FileDbSettings<TObject>;
+    protected change: ChangeFunction<TObject> | undefined;
+    protected dataset: Record<string, TObject | MetaObject>;
+    protected namespace: string;
     private lastSave;
-    private stateTimer;
+    protected stateTimer: NodeJS.Timeout | null;
     private callbackSubscriptionClient;
-    private readonly dataDir;
+    protected readonly dataDir: string;
     private readonly datasetName;
-    private log;
-    private readonly backupDir;
-    constructor(settings: FileDbSettings);
+    protected log: InternalLogger;
+    protected readonly backupDir: string;
+    /**
+     * @param settings Settings for the database, the connection and backups
+     */
+    constructor(settings: FileDbSettings<TObject>);
+    /**
+     * Open the database by loading the dataset from disk
+     */
     open(): Promise<void>;
     /**
      * Loads a dataset file
@@ -89,20 +149,55 @@ export declare class InMemoryFileDB {
      * @param datasetName Filename of the file to load
      * @returns obj read data, normally as object
      */
-    loadDatasetFile(datasetName: string): Promise<Record<string, any>>;
+    loadDatasetFile(datasetName: string): Promise<Record<string, TObject>>;
     /**
      * Loads the dataset including pot. Fallback handling
      *
      * @param datasetName Filename of the file to load
      * @returns obj dataset read as object
      */
-    loadDataset(datasetName: string): Promise<Record<string, any>>;
+    loadDataset(datasetName: string): Promise<Record<string, TObject>>;
+    /**
+     * Normalize the backup settings and create the backup directory
+     */
     initBackupDir(): void;
-    handleSubscribe(client: SubscriptionClient, type: string, pattern: string | string[], cb?: () => void): void;
-    handleSubscribe(client: SubscriptionClient, type: string, pattern: string | string[], options: any, cb?: () => void): void;
+    /**
+     * Subscribe a client to changes matching the given pattern
+     *
+     * @param client The client to register the subscription for
+     * @param type The subscription type (e.g. objects or states)
+     * @param pattern One or more patterns to subscribe to
+     */
+    handleSubscribe(client: SubscriptionClient, type: string, pattern: string | string[]): void;
+    /**
+     * Remove a client's subscription for the given pattern
+     *
+     * @param client The client whose subscription should be removed
+     * @param type The subscription type (e.g. objects or states)
+     * @param pattern One or more patterns to unsubscribe from
+     * @param cb Called once the subscription has been removed
+     */
     handleUnsubscribe(client: SubscriptionClient, type: string, pattern: string | string[], cb?: () => void): void | Promise<void>;
-    publishToClients(_client: SubscriptionClient, _type: string, _id: string, _obj: any): number;
+    /**
+     * Publish a change to a single client. Must be implemented by a subclass that handles client communication.
+     *
+     * @param _client The client to publish to
+     * @param _type The change type (e.g. objects or states)
+     * @param _id The ID of the changed object or state
+     * @param _obj The new value of the object or state
+     */
+    publishToClients(_client: SubscriptionClient, _type: string, _id: string, _obj: TObject | string | null | FileSize | MetaObject): number;
+    /**
+     * Delete outdated backup files according to the configured retention settings
+     *
+     * @param baseFilename Base file name of the backups that should be pruned
+     */
     deleteOldBackupFiles(baseFilename: string): void;
+    /**
+     * Format a timestamp into a "YYYY-MM-DD_HH-MM-SS" string used for backup file names
+     *
+     * @param date Timestamp in milliseconds
+     */
     getTimeStr(date: number): string;
     /**
      * Handle saving the dataset incl. backups
@@ -120,9 +215,25 @@ export declare class InMemoryFileDB {
      * @param jsonString JSON string of the complete dataset to also be stored into a compressed backup file
      */
     saveBackup(jsonString: string): void;
+    /**
+     * Get the current status of the database
+     */
     getStatus(): DbStatus;
-    getClients(): Record<string, any>;
-    publishAll(type: string, id: string, obj: any): number;
+    /**
+     * Get the currently connected clients. Subclasses override this to return the real clients.
+     */
+    getClients(): Record<string, THandler>;
+    /**
+     * Publish a change to all connected clients and local subscribers
+     *
+     * @param type The change type (e.g. objects or states)
+     * @param id The ID of the changed object or state
+     * @param obj The new value of the object or state
+     */
+    publishAll(type: string, id: string, obj: TObject | string | null | FileSize | MetaObject): number;
+    /**
+     * Destructor of the class. Called when shutting down to persist state and clear timers.
+     */
     destroy(): Promise<void>;
 }
 export {};

package/build/esm/lib/inMemFileDB.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inMemFileDB.d.ts","sourceRoot":"","sources":["../../../src/lib/inMemFileDB.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"inMemFileDB.d.ts","sourceRoot":"","sources":["../../../src/lib/inMemFileDB.ts"],"names":[],"mappings":"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"}

package/build/esm/lib/inMemFileDB.js

@@ -1,11 +1,12 @@
 /**
  *      States DB in memory - Server
  *
- *      Copyright 2013-2024 bluefox <dogafox@gmail.com>
+ *      Copyright 2013-2026 bluefox <dogafox@gmail.com>
  *
  *      MIT License
  *
  */
+/// <reference types="@iobroker/types-dev" />
 import fs from 'fs-extra';
 import path from 'node:path';
 import { tools } from '@iobroker/js-controller-common-db';
@@ -17,22 +18,22 @@ import { createGzip } from 'node:zlib';
 export class InMemoryFileDB {
     settings;
     change;
-    dataset;
+    dataset = {};
     namespace;
-    lastSave;
-    stateTimer;
-    callbackSubscriptionClient;
+    lastSave = null;
+    stateTimer = null;
+    callbackSubscriptionClient = {};
     dataDir;
     datasetName;
     log;
     backupDir;
+    /**
+     * @param settings Settings for the database, the connection and backups
+     */
     constructor(settings) {
-        this.settings = settings || {};
+        this.settings = settings;
         this.change = this.settings.change;
-        this.dataset = {};
         this.namespace = this.settings.namespace || '';
-        this.lastSave = null;
-        this.callbackSubscriptionClient = {};
         this.settings.backup = this.settings.connection.backup || {
             disabled: false, // deactivates
             files: 24, // minimum number of files
@@ -40,30 +41,37 @@ export class InMemoryFileDB {
             period: 120, // minutes
             path: '', // use default path
         };
+        const backup = this.settings.backup;
         this.dataDir = this.settings.connection.dataDir || tools.getDefaultDataDir();
         if (!path.isAbsolute(this.dataDir)) {
             this.dataDir = path.normalize(path.join(tools.getControllerDir(), this.dataDir));
         }
         this.dataDir = this.dataDir.replace(/\\/g, '/');
-        const fileName = this.settings.jsonlDB ? this.settings.jsonlDB.fileName : this.settings.fileDB.fileName;
+        const fileDbOptions = this.settings.fileDB;
+        if (!fileDbOptions) {
+            throw new Error(`${this.namespace} No fileDB storage options were provided`);
+        }
+        const fileName = this.settings.jsonlDB ? this.settings.jsonlDB.fileName : fileDbOptions.fileName;
         this.datasetName = path.join(this.dataDir, fileName);
         const parts = path.dirname(this.datasetName);
         fs.ensureDirSync(parts);
-        this.stateTimer = null;
-        this.backupDir = this.settings.backup.path || path.join(this.dataDir, this.settings.fileDB.backupDirName);
+        this.backupDir = backup.path || path.join(this.dataDir, fileDbOptions.backupDirName);
         this.log = tools.getLogger(this.settings.logger);
-        if (!this.settings.backup.disabled) {
+        if (!backup.disabled) {
             try {
                 this.initBackupDir();
             }
             catch (e) {
                 this.log.error(`Database backups are disabled, because backup directory could not be initialized: ${e.message}`);
                 this.log.error('This leads to an increased risk of data loss, please check that the configured backup directory is available and restart the controller');
-                this.settings.backup.disabled = true;
+                backup.disabled = true;
             }
         }
         this.log.debug(`${this.namespace} Data File: ${this.datasetName}`);
     }
+    /**
+     * Open the database by loading the dataset from disk
+     */
     async open() {
         // load values from file
         this.dataset = await this.loadDataset(this.datasetName);
@@ -137,57 +145,71 @@ export class InMemoryFileDB {
         }
         return ret;
     }
+    /**
+     * Normalize the backup settings and create the backup directory
+     */
     initBackupDir() {
+        // Create backup directory
+        fs.ensureDirSync(this.backupDir);
+        const backup = this.settings.backup;
+        if (!backup) {
+            return;
+        }
         // Interval in minutes => to milliseconds
-        this.settings.backup.period =
-            this.settings.backup.period === undefined ? 120 : parseInt(String(this.settings.backup.period));
-        if (isNaN(this.settings.backup.period)) {
-            this.settings.backup.period = 120;
+        backup.period = backup.period === undefined ? 120 : parseInt(String(backup.period));
+        if (isNaN(backup.period)) {
+            backup.period = 120;
         }
         // Node.js timeouts overflow after roughly 24 days, defaulting to 1 millisecond, which causes chaos.
         // If a user configured the backup this way, we use our default of 120 minutes instead.
         const maxTimeoutMinutes = Math.floor((2 ** 31 - 1) / 60000);
-        if (this.settings.backup.period > maxTimeoutMinutes) {
-            this.log.warn(`${this.namespace} Configured backup period ${this.settings.backup.period} is larger than the supported maximum of ${maxTimeoutMinutes} minutes. Defaulting to 120 minutes.`);
-            this.settings.backup.period = 120;
+        if (backup.period > maxTimeoutMinutes) {
+            this.log.warn(`${this.namespace} Configured backup period ${backup.period} is larger than the supported maximum of ${maxTimeoutMinutes} minutes. Defaulting to 120 minutes.`);
+            backup.period = 120;
         }
-        this.settings.backup.period *= 60_000;
-        this.settings.backup.files =
-            this.settings.backup.files === undefined ? 24 : parseInt(String(this.settings.backup.files));
-        if (isNaN(this.settings.backup.files)) {
-            this.settings.backup.files = 24;
+        backup.period *= 60_000;
+        backup.files = backup.files === undefined ? 24 : parseInt(String(backup.files));
+        if (isNaN(backup.files)) {
+            backup.files = 24;
         }
-        this.settings.backup.hours =
-            this.settings.backup.hours === undefined ? 48 : parseInt(String(this.settings.backup.hours));
-        if (isNaN(this.settings.backup.hours)) {
-            this.settings.backup.hours = 48;
+        backup.hours = backup.hours === undefined ? 48 : parseInt(String(backup.hours));
+        if (isNaN(backup.hours)) {
+            backup.hours = 48;
         }
-        // Create backup directory
-        fs.ensureDirSync(this.backupDir);
     }
-    handleSubscribe(client, type, pattern, options, cb) {
-        if (typeof options === 'function') {
-            cb = options;
-            options = undefined;
-        }
-        client._subscribe = client._subscribe || {};
-        client._subscribe[type] = client._subscribe[type] || [];
+    /**
+     * Subscribe a client to changes matching the given pattern
+     *
+     * @param client The client to register the subscription for
+     * @param type The subscription type (e.g. objects or states)
+     * @param pattern One or more patterns to subscribe to
+     */
+    handleSubscribe(client, type, pattern) {
+        client._subscribe ||= {};
+        client._subscribe[type] ||= [];
         const s = client._subscribe[type];
         if (pattern instanceof Array) {
             pattern.forEach(pattern => {
                 if (s.find(sub => sub.pattern === pattern)) {
                     return;
                 }
-                s.push({ pattern, regex: new RegExp(tools.pattern2RegEx(pattern)), options });
+                s.push({ pattern, regex: new RegExp(tools.pattern2RegEx(pattern)) });
             });
         }
         else {
             if (!s.find(sub => sub.pattern === pattern)) {
-                s.push({ pattern, regex: new RegExp(tools.pattern2RegEx(pattern)), options });
+                s.push({ pattern, regex: new RegExp(tools.pattern2RegEx(pattern)) });
             }
         }
-        typeof cb === 'function' && cb();
     }
+    /**
+     * Remove a client's subscription for the given pattern
+     *
+     * @param client The client whose subscription should be removed
+     * @param type The subscription type (e.g. objects or states)
+     * @param pattern One or more patterns to unsubscribe from
+     * @param cb Called once the subscription has been removed
+     */
     handleUnsubscribe(client, type, pattern, cb) {
         const s = client?._subscribe?.[type];
         if (s) {
@@ -208,16 +230,29 @@ export class InMemoryFileDB {
         }
         return tools.maybeCallback(cb);
     }
+    /**
+     * Publish a change to a single client. Must be implemented by a subclass that handles client communication.
+     *
+     * @param _client The client to publish to
+     * @param _type The change type (e.g. objects or states)
+     * @param _id The ID of the changed object or state
+     * @param _obj The new value of the object or state
+     */
     publishToClients(_client, _type, _id, _obj) {
         throw new Error('no communication handling implemented');
     }
+    /**
+     * Delete outdated backup files according to the configured retention settings
+     *
+     * @param baseFilename Base file name of the backups that should be pruned
+     */
     deleteOldBackupFiles(baseFilename) {
         // delete files only if settings.backupNumber is not 0
         let files = fs.readdirSync(this.backupDir);
         files.sort();
-        const limit = Date.now() - this.settings.backup.hours * 3600000;
+        const limit = Date.now() - (this.settings.backup?.hours ?? 48) * 3600000;
         files = files.filter(f => f.endsWith(`${baseFilename}.gz`));
-        while (files.length > this.settings.backup.files) {
+        while (files.length > (this.settings.backup?.files ?? 24)) {
             const file = files.shift();
             if (!file) {
                 continue;
@@ -234,6 +269,11 @@ export class InMemoryFileDB {
             }
         }
     }
+    /**
+     * Format a timestamp into a "YYYY-MM-DD_HH-MM-SS" string used for backup file names
+     *
+     * @param date Timestamp in milliseconds
+     */
     getTimeStr(date) {
         const dateObj = new Date(date);
         let text = `${dateObj.getFullYear().toString()}-`;
@@ -265,7 +305,7 @@ export class InMemoryFileDB {
     async saveState() {
         try {
             const jsonString = await this.saveDataset();
-            if (!this.settings.backup.disabled && jsonString) {
+            if (!this.settings.backup?.disabled && jsonString) {
                 this.saveBackup(jsonString);
             }
         }
@@ -342,9 +382,12 @@ export class InMemoryFileDB {
         // save files for the last x hours
         const now = Date.now();
         // makes backups only if settings.backupInterval is not 0
-        if (this.settings.backup.period && (!this.lastSave || now - this.lastSave > this.settings.backup.period)) {
+        const fileName = this.settings.fileDB?.fileName;
+        if (fileName &&
+            this.settings.backup?.period &&
+            (!this.lastSave || now - this.lastSave > this.settings.backup.period)) {
             this.lastSave = now;
-            const backFileName = path.join(this.backupDir, `${this.getTimeStr(now)}_${this.settings.fileDB.fileName}.gz`);
+            const backFileName = path.join(this.backupDir, `${this.getTimeStr(now)}_${fileName}.gz`);
             try {
                 if (!fs.existsSync(backFileName)) {
                     const output = fs.createWriteStream(backFileName);
@@ -359,7 +402,7 @@ export class InMemoryFileDB {
                     compress.write(jsonString);
                     compress.end();
                     // analyse older files
-                    this.deleteOldBackupFiles(this.settings.fileDB.fileName);
+                    this.deleteOldBackupFiles(fileName);
                 }
             }
             catch (e) {
@@ -367,12 +410,25 @@ export class InMemoryFileDB {
             }
         }
     }
+    /**
+     * Get the current status of the database
+     */
     getStatus() {
         return { type: 'file', server: true };
     }
+    /**
+     * Get the currently connected clients. Subclasses override this to return the real clients.
+     */
     getClients() {
         return {};
     }
+    /**
+     * Publish a change to all connected clients and local subscribers
+     *
+     * @param type The change type (e.g. objects or states)
+     * @param id The ID of the changed object or state
+     * @param obj The new value of the object or state
+     */
     publishAll(type, id, obj) {
         if (id === undefined) {
             this.log.error(`${this.namespace} Can not publish empty ID`);
@@ -399,7 +455,9 @@ export class InMemoryFileDB {
         }
         return publishCount;
     }
-    // Destructor of the class. Called by shutting down.
+    /**
+     * Destructor of the class. Called when shutting down to persist state and clear timers.
+     */
     async destroy() {
         if (this.stateTimer) {
             clearTimeout(this.stateTimer);