JavaScript-Bibliothek common-history

Diese JavaScript-Bibliothek bietet eine Funktion zum Wiederherstellen eines Objekts aus einem vorhandenen Historien-/Versionsobjekt.

Verwendung

Binden Sie die Bibliothek stets am Anfang eines Skripts ein:

let history = require('common/history');

Funktionen

restoreHistory(object, historyObject)

Diese Funktion stellt den Zustand eines agorum core Objekts anhand eines angegebenen Historienobjekts her, also einer früheren Version desselben Objekts.

Syntax

history.restoreHistory(object, historyObject)

Parameter

Parameter	Beschreibung	Pflicht	Standard
object (agorum.Object)	Das Zielobjekt, dessen aktuelle Version durch eine Version aus der Historie ersetzt werden soll.	ja	–
historyObject (agorum.Object)	Die Version des Objekts aus der Historie, die wiederhergestellt werden soll.	ja	-

Beispiel

let objects = require('common/objects');
let history = require('common/history');

/**
 * Retrieves the first (oldest) history entry of an agorum core object.
 * This function returns the original version of the document.
 *
 * @param {agorum.Object} obj - The agorum core object with history
 * @return {?agorum.Object} The first history object or null if no history exists
 *
 * @example
 * let document = objects.find('12345');
 * let firstVersion = getFirstHistory(document);
 * if (firstVersion) {
 *     console.log('Original version from: ' + firstVersion.modified);
 * }
 */
let getFirstHistory = obj => {
  return getHistory(obj, 1);
};

/**
 * Retrieves the last (most recent) history entry of an agorum core object.
 * This function returns the latest historical version before the current state.
 *
 * @param {agorum.Object} obj - The agorum core object with history
 * @return {?agorum.Object} The latest history object or null if no history exists
 *
 * @example
 * let document = objects.find('12345');
 * let lastVersion = getLastHistory(document);
 * if (lastVersion) {
 *     console.log('Most recent version from: ' + lastVersion.modified);
 * }
 */
let getLastHistory = obj => {
  return getHistory(obj, obj.historyCount);
};

/**
 * Returns the total number of history entries for an agorum core object.
 *
 * @param {agorum.Object} obj - The base agorum core object for retrieving the related history count
 * @return {number} The count of history entries (0 if no history exists)
 *
 * @example
 * let document = objects.find('12345');
 * let count = getHistoryCount(document);
 * console.log('This document has ' + count + ' historical versions');
 */
let getHistoryCount = obj => {
  return obj.historyCount;
};

/**
 * Retrieves a specific history entry by position number.
 * History objects are sorted by their ID to ensure consistent ordering.
 *
 * @param {agorum.Object} obj - The agorum core object with history
 * @param {number} num - The history position to retrieve:
 *                       - Positive values (1 to count): From first/oldest (1) to last/newest (count)
 *                       - Negative values (-1 to -count): From last/newest (-1) to first/oldest (-count)
 *                       - 0 or out of range values return null
 * @return {?agorum.Object} The history object at the specified position or null if out of range
 *
 * @example
 * let document = objects.find('12345');
 * // Get the third history entry (third oldest)
 * let thirdVersion = getHistory(document, 3);
 *
 * // Get the second to last history entry
 * let secondToLast = getHistory(document, -2);
 *
 * // Get all history entries
 * let count = getHistoryCount(document);
 * for (let i = 1; i <= count; i++) {
 *     let version = getHistory(document, i);
 *     console.log('Version ' + i + ': ' + version.modified);
 * }
 */
let getHistory = (obj, num) => {
  let count = getHistoryCount(obj);

  // Convert positive indices (1-based to 0-based)
  if (num > 0 && num <= count) num -= 1;

  // Convert negative indices to positive array indices
  if (num < 0 && num >= -count) num = count + num;

  // Check bounds
  if (num < 0 || num >= count) return null;

  // Sort by ID for consistent ordering and return the requested entry
  return obj.historyObjects.sort((a, b) => a.ID - b.ID)[num];
};

/**
 * Internal helper function that performs the actual history restoration.
 * Uses the agorum core history API to restore a specific history object.
 *
 * @private
 * @param {agorum.Object} historyObject - The history object to restore
 * @throws {Error} May throw if historyObject is null or restoration fails
 *
 * @todo Add null check and proper error handling
 */
let restoreHistory = historyObject => {
  if (!historyObject) return new Error('History cannot be restored');
  if (!historyObject.historyObject) return new Error('Object is not a history');
  history.restoreHistory(historyObject.belongingObject, historyObject);
  return true;
};

// Example

let obj = objects.find(1356734);

restoreHistory(getLastHistory(obj));

Rückgabewerte

Kein Rückgabewert (undefined). Bei Erfolg ist object nach der Ausführung auf den Stand von historyObject zurückgesetzt.

Exceptions

Die Funktion kann Exceptions auslösen, insbesondere wenn:

• object oder historyObject ungültig oder null sind.
• historyObject nicht zur Historie von object gehört.