iobroker.javascript 10.2.5 → 10.4.0

package/build/lib/scriptHistory.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * Storage layout and bookkeeping for the script history.
+ *
+ * Every saved source lands in the adapter's file database as one file per version, next to a small
+ * index that carries nothing but the metadata. Listing a history therefore reads one small file,
+ * and writing a version does not rewrite the sources already there - which matters for Blockly and
+ * FBD scripts, whose source is the generated code *plus* the model in one string.
+ *
+ * The functions here are pure so they can be tested without an adapter; `main.ts` does the file IO.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_HISTORY_VERSIONS = exports.DEFAULT_HISTORY_VERSIONS = exports.INDEX_FILE = exports.HISTORY_ROOT = void 0;
+exports.versionFileName = versionFileName;
+exports.historyFolder = historyFolder;
+exports.indexPath = indexPath;
+exports.versionPath = versionPath;
+exports.resolveHistoryVersions = resolveHistoryVersions;
+exports.parseIndex = parseIndex;
+exports.addVersion = addVersion;
+exports.isWorthStoring = isWorthStoring;
+exports.describeSource = describeSource;
+exports.fileToString = fileToString;
+exports.decodeFolderName = decodeFolderName;
+exports.sumIndex = sumIndex;
+exports.formatBytes = formatBytes;
+exports.trimIndex = trimIndex;
+/** Folder inside the instance's file area that holds every script's history */
+exports.HISTORY_ROOT = 'history';
+/** Name of the metadata file inside a script's history folder */
+exports.INDEX_FILE = 'index.json';
+/** Versions kept per script when the setting says nothing */
+exports.DEFAULT_HISTORY_VERSIONS = 30;
+/** Nobody is served by more than this, whatever the setting says */
+exports.MAX_HISTORY_VERSIONS = 200;
+/**
+ * The file name of one version. The timestamp is the identity of a version, so it is also its name.
+ *
+ * @param ts timestamp of the version
+ */
+function versionFileName(ts) {
+    return `${ts}.txt`;
+}
+/**
+ * Where a script's history lives.
+ *
+ * The script id is encoded: it is a user-chosen name and may contain characters that have a meaning
+ * in a path.
+ *
+ * @param scriptId full id of the script, e.g. `script.js.Folder.Name`
+ */
+function historyFolder(scriptId) {
+    return `${exports.HISTORY_ROOT}/${encodeURIComponent(scriptId)}`;
+}
+/**
+ * Path of a script's index file.
+ *
+ * @param scriptId full id of the script
+ */
+function indexPath(scriptId) {
+    return `${historyFolder(scriptId)}/${exports.INDEX_FILE}`;
+}
+/**
+ * Path of one stored version.
+ *
+ * @param scriptId full id of the script
+ * @param ts timestamp of the version
+ */
+function versionPath(scriptId, ts) {
+    return `${historyFolder(scriptId)}/${versionFileName(ts)}`;
+}
+/**
+ * How many versions to keep, from the adapter setting.
+ *
+ * Zero switches the history off, which is why it is not simply clamped into the valid range.
+ *
+ * @param configured the value from the adapter settings
+ */
+function resolveHistoryVersions(configured) {
+    const requested = parseInt(configured, 10);
+    if (isNaN(requested)) {
+        return exports.DEFAULT_HISTORY_VERSIONS;
+    }
+    if (requested <= 0) {
+        return 0;
+    }
+    return Math.min(requested, exports.MAX_HISTORY_VERSIONS);
+}
+/**
+ * Reads an index file. Anything unreadable counts as "no history yet" rather than as an error:
+ * a broken index must not stop a script from being saved.
+ *
+ * @param raw contents of the index file
+ */
+function parseIndex(raw) {
+    if (!raw) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed
+            .filter(entry => entry && typeof entry.ts === 'number')
+            .sort((a, b) => b.ts - a.ts);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Add a version to an index and work out which stored files are now surplus.
+ *
+ * The newest entry stays newest even if two saves land in the same millisecond, and the very first
+ * version is never dropped - it is the one worth having when everything else has scrolled away.
+ *
+ * @param index the index as it is on disk, newest first
+ * @param entry the version that was just written
+ * @param keep how many versions to keep
+ */
+function addVersion(index, entry, keep) {
+    const next = [entry, ...index.filter(v => v.ts !== entry.ts)].sort((a, b) => b.ts - a.ts);
+    if (next.length <= keep) {
+        return { index: next, obsolete: [] };
+    }
+    // The oldest entry is the original state of the script and is kept on top of the quota
+    const oldest = next[next.length - 1];
+    const kept = next.slice(0, keep - 1);
+    const obsolete = next.slice(keep - 1, next.length - 1).map(v => v.ts);
+    return { index: [...kept, oldest], obsolete };
+}
+/**
+ * Whether this change is worth a new version.
+ *
+ * A script object is written for all sorts of reasons - enabling it, renaming it, the adapter
+ * storing its compiled form - and none of those changed the source. Without this the history would
+ * be full of entries that differ in nothing.
+ *
+ * @param previous the source before the change, if any
+ * @param next the source after the change
+ */
+function isWorthStoring(previous, next) {
+    if (typeof next !== 'string' || !next) {
+        return false;
+    }
+    return previous !== next;
+}
+/**
+ * Describe a source for the index.
+ *
+ * @param source the source to describe
+ * @param isProtected whether it is stored encrypted
+ */
+function describeSource(source, isProtected) {
+    return {
+        size: source.length,
+        lines: source.split('\n').length,
+        ...(isProtected ? { protected: true } : {}),
+    };
+}
+/**
+ * The content of a file read through the adapter, as a string.
+ *
+ * `readFile` answers with the content for some back ends and with `{ file, mimeType }` for others,
+ * and the content itself is a string or a buffer. Everything else counts as "nothing there".
+ *
+ * @param raw whatever `readFileAsync` resolved with
+ */
+function fileToString(raw) {
+    if (raw === null || raw === undefined) {
+        return '';
+    }
+    const file = typeof raw === 'object' && 'file' in raw ? raw.file : raw;
+    if (typeof file === 'string') {
+        return file;
+    }
+    if (file instanceof Uint8Array) {
+        return Buffer.from(file).toString('utf8');
+    }
+    return '';
+}
+/**
+ * The script a history folder belongs to.
+ *
+ * @param folder the folder name as `readDir` reports it
+ */
+function decodeFolderName(folder) {
+    try {
+        return decodeURIComponent(folder);
+    }
+    catch {
+        // A folder nobody of ours wrote - report it under its own name rather than throwing
+        return folder;
+    }
+}
+/**
+ * How much one history occupies, from its index alone - the stored sources are never read for this.
+ *
+ * @param index the index of a script
+ */
+function sumIndex(index) {
+    return {
+        versions: index.length,
+        bytes: index.reduce((sum, entry) => sum + (entry.size || 0), 0),
+    };
+}
+/**
+ * A size a human can read at a glance.
+ *
+ * @param bytes the number of bytes
+ */
+function formatBytes(bytes) {
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    }
+    return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}
+/**
+ * Cut an index down to the current limit, for instance after the setting was made smaller.
+ *
+ * Follows the same rule as `addVersion`: the newest ones are kept and the very first version
+ * survives on top of the quota.
+ *
+ * @param index the index as it is on disk, newest first
+ * @param keep how many versions to keep; `0` drops everything
+ */
+function trimIndex(index, keep) {
+    const sorted = [...index].sort((a, b) => b.ts - a.ts);
+    if (!keep) {
+        return { index: [], obsolete: sorted.map(v => v.ts) };
+    }
+    if (sorted.length <= keep) {
+        return { index: sorted, obsolete: [] };
+    }
+    const oldest = sorted[sorted.length - 1];
+    return {
+        index: [...sorted.slice(0, keep - 1), oldest],
+        obsolete: sorted.slice(keep - 1, sorted.length - 1).map(v => v.ts),
+    };
+}
+//# sourceMappingURL=scriptHistory.js.map

package/build/lib/scriptHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptHistory.js","sourceRoot":"","sources":["../../src/lib/scriptHistory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Storage layout and bookkeeping for the script history.\n *\n * Every saved source lands in the adapter's file database as one file per version, next to a small\n * index that carries nothing but the metadata. Listing a history therefore reads one small file,\n * and writing a version does not rewrite the sources already there - which matters for Blockly and\n * FBD scripts, whose source is the generated code *plus* the model in one string.\n *\n * The functions here are pure so they can be tested without an adapter; `main.ts` does the file IO.\n */\n\n/** Folder inside the instance's file area that holds every script's history */\nexport const HISTORY_ROOT = 'history';\n/** Name of the metadata file inside a script's history folder */\nexport const INDEX_FILE = 'index.json';\n/** Versions kept per script when the setting says nothing */\nexport const DEFAULT_HISTORY_VERSIONS = 30;\n/** Nobody is served by more than this, whatever the setting says */\nexport const MAX_HISTORY_VERSIONS = 200;\n\n/** What is known about one stored version, without its source */\nexport interface ScriptVersion {\n    /** When it was saved, ms since the epoch - also the name of its file */\n    ts: number;\n    /** Which adapter wrote it, e.g. `system.adapter.admin.0` */\n    from?: string;\n    /** Which user wrote it, e.g. `system.user.admin` */\n    user?: string;\n    /** Length of the source in characters */\n    size: number;\n    /** Number of lines of the source */\n    lines: number;\n    /** The source was stored encrypted, as it is in the object (`native.protected`) */\n    protected?: boolean;\n}\n\n/**\n * The file name of one version. The timestamp is the identity of a version, so it is also its name.\n *\n * @param ts timestamp of the version\n */\nexport function versionFileName(ts: number): string {\n    return `${ts}.txt`;\n}\n\n/**\n * Where a script's history lives.\n *\n * The script id is encoded: it is a user-chosen name and may contain characters that have a meaning\n * in a path.\n *\n * @param scriptId full id of the script, e.g. `script.js.Folder.Name`\n */\nexport function historyFolder(scriptId: string): string {\n    return `${HISTORY_ROOT}/${encodeURIComponent(scriptId)}`;\n}\n\n/**\n * Path of a script's index file.\n *\n * @param scriptId full id of the script\n */\nexport function indexPath(scriptId: string): string {\n    return `${historyFolder(scriptId)}/${INDEX_FILE}`;\n}\n\n/**\n * Path of one stored version.\n *\n * @param scriptId full id of the script\n * @param ts timestamp of the version\n */\nexport function versionPath(scriptId: string, ts: number): string {\n    return `${historyFolder(scriptId)}/${versionFileName(ts)}`;\n}\n\n/**\n * How many versions to keep, from the adapter setting.\n *\n * Zero switches the history off, which is why it is not simply clamped into the valid range.\n *\n * @param configured the value from the adapter settings\n */\nexport function resolveHistoryVersions(configured?: unknown): number {\n    const requested = parseInt(configured as string, 10);\n    if (isNaN(requested)) {\n        return DEFAULT_HISTORY_VERSIONS;\n    }\n    if (requested <= 0) {\n        return 0;\n    }\n    return Math.min(requested, MAX_HISTORY_VERSIONS);\n}\n\n/**\n * Reads an index file. Anything unreadable counts as \"no history yet\" rather than as an error:\n * a broken index must not stop a script from being saved.\n *\n * @param raw contents of the index file\n */\nexport function parseIndex(raw: string | undefined | null): ScriptVersion[] {\n    if (!raw) {\n        return [];\n    }\n    try {\n        const parsed: unknown = JSON.parse(raw);\n        if (!Array.isArray(parsed)) {\n            return [];\n        }\n        return (parsed as ScriptVersion[])\n            .filter(entry => entry && typeof entry.ts === 'number')\n            .sort((a, b) => b.ts - a.ts);\n    } catch {\n        return [];\n    }\n}\n\n/**\n * Add a version to an index and work out which stored files are now surplus.\n *\n * The newest entry stays newest even if two saves land in the same millisecond, and the very first\n * version is never dropped - it is the one worth having when everything else has scrolled away.\n *\n * @param index the index as it is on disk, newest first\n * @param entry the version that was just written\n * @param keep how many versions to keep\n */\nexport function addVersion(\n    index: ScriptVersion[],\n    entry: ScriptVersion,\n    keep: number,\n): { index: ScriptVersion[]; obsolete: number[] } {\n    const next = [entry, ...index.filter(v => v.ts !== entry.ts)].sort((a, b) => b.ts - a.ts);\n    if (next.length <= keep) {\n        return { index: next, obsolete: [] };\n    }\n    // The oldest entry is the original state of the script and is kept on top of the quota\n    const oldest = next[next.length - 1];\n    const kept = next.slice(0, keep - 1);\n    const obsolete = next.slice(keep - 1, next.length - 1).map(v => v.ts);\n    return { index: [...kept, oldest], obsolete };\n}\n\n/**\n * Whether this change is worth a new version.\n *\n * A script object is written for all sorts of reasons - enabling it, renaming it, the adapter\n * storing its compiled form - and none of those changed the source. Without this the history would\n * be full of entries that differ in nothing.\n *\n * @param previous the source before the change, if any\n * @param next the source after the change\n */\nexport function isWorthStoring(previous: string | undefined | null, next: string | undefined | null): boolean {\n    if (typeof next !== 'string' || !next) {\n        return false;\n    }\n    return previous !== next;\n}\n\n/**\n * Describe a source for the index.\n *\n * @param source the source to describe\n * @param isProtected whether it is stored encrypted\n */\nexport function describeSource(\n    source: string,\n    isProtected: boolean,\n): Pick<ScriptVersion, 'size' | 'lines'> & {\n    protected?: boolean;\n} {\n    return {\n        size: source.length,\n        lines: source.split('\\n').length,\n        ...(isProtected ? { protected: true } : {}),\n    };\n}\n\n/**\n * The content of a file read through the adapter, as a string.\n *\n * `readFile` answers with the content for some back ends and with `{ file, mimeType }` for others,\n * and the content itself is a string or a buffer. Everything else counts as \"nothing there\".\n *\n * @param raw whatever `readFileAsync` resolved with\n */\nexport function fileToString(raw: unknown): string {\n    if (raw === null || raw === undefined) {\n        return '';\n    }\n    const file: unknown = typeof raw === 'object' && 'file' in raw ? raw.file : raw;\n    if (typeof file === 'string') {\n        return file;\n    }\n    if (file instanceof Uint8Array) {\n        return Buffer.from(file).toString('utf8');\n    }\n    return '';\n}\n\n/**\n * The script a history folder belongs to.\n *\n * @param folder the folder name as `readDir` reports it\n */\nexport function decodeFolderName(folder: string): string {\n    try {\n        return decodeURIComponent(folder);\n    } catch {\n        // A folder nobody of ours wrote - report it under its own name rather than throwing\n        return folder;\n    }\n}\n\n/**\n * How much one history occupies, from its index alone - the stored sources are never read for this.\n *\n * @param index the index of a script\n */\nexport function sumIndex(index: ScriptVersion[]): { versions: number; bytes: number } {\n    return {\n        versions: index.length,\n        bytes: index.reduce((sum, entry) => sum + (entry.size || 0), 0),\n    };\n}\n\n/**\n * A size a human can read at a glance.\n *\n * @param bytes the number of bytes\n */\nexport function formatBytes(bytes: number): string {\n    if (bytes < 1024) {\n        return `${bytes} B`;\n    }\n    if (bytes < 1024 * 1024) {\n        return `${(bytes / 1024).toFixed(1)} KB`;\n    }\n    return `${(bytes / 1024 / 1024).toFixed(2)} MB`;\n}\n\n/**\n * Cut an index down to the current limit, for instance after the setting was made smaller.\n *\n * Follows the same rule as `addVersion`: the newest ones are kept and the very first version\n * survives on top of the quota.\n *\n * @param index the index as it is on disk, newest first\n * @param keep how many versions to keep; `0` drops everything\n */\nexport function trimIndex(index: ScriptVersion[], keep: number): { index: ScriptVersion[]; obsolete: number[] } {\n    const sorted = [...index].sort((a, b) => b.ts - a.ts);\n    if (!keep) {\n        return { index: [], obsolete: sorted.map(v => v.ts) };\n    }\n    if (sorted.length <= keep) {\n        return { index: sorted, obsolete: [] };\n    }\n    const oldest = sorted[sorted.length - 1];\n    return {\n        index: [...sorted.slice(0, keep - 1), oldest],\n        obsolete: sorted.slice(keep - 1, sorted.length - 1).map(v => v.ts),\n    };\n}\n"]}