hadron-document 8.6.1 → 8.6.3

package/dist/element.js

@@ -15,11 +15,21 @@ exports.Events = element_events_1.default;
 const utils_1 = require("./utils");
 const _1 = require(".");
 exports.DATE_FORMAT = 'YYYY-MM-DD HH:mm:ss.SSS';
+/**
+ * Id field constant.
+ */
 const ID = '_id';
+/**
+ * Is this the path to a field that is used internally by the
+ * MongoDB driver or server and not for user consumption?
+ */
 function isInternalFieldPath(path) {
     return typeof path === 'string' && /^__safeContent__($|\.)/.test(path);
 }
 exports.isInternalFieldPath = isInternalFieldPath;
+/**
+ * Types that are not editable.
+ */
 const UNEDITABLE_TYPES = [
     'Binary',
     'Code',
@@ -36,9 +46,17 @@ function isValueExpandable(value) {
     return (0, lodash_1.isPlainObject)(value) || (0, lodash_1.isArray)(value);
 }
 exports.isValueExpandable = isValueExpandable;
+/**
+ * Represents an element in a document.
+ */
 class Element extends eventemitter3_1.default {
+    /**
+     * Cancel any modifications to the element.
+     */
     cancel() {
         if (this.elements) {
+            // Cancel will remove elements from iterator, clone it before iterating
+            // otherwise we will skip items
             for (const element of Array.from(this.elements)) {
                 element.cancel();
             }
@@ -47,6 +65,14 @@ class Element extends eventemitter3_1.default {
             this.revert();
         }
     }
+    /**
+     * Create the element.
+     *
+     * @param key - The key.
+     * @param value - The value.
+     * @param parent - The parent element.
+     * @param added - Is the element a new 'addition'?
+     */
     constructor(key, value, parent = null, added = false) {
         super();
         this.expanded = false;
@@ -61,10 +87,14 @@ class Element extends eventemitter3_1.default {
         this.currentType = this.type;
         this.level = this._getLevel();
         this.setValid();
+        // Make sure that all values that element will hold onto will be explicit
+        // bson types: convert JavaScript numbers to either Int32 or Double
         if (typeof value === 'number') {
             value = hadron_type_checker_1.default.cast(value, hadron_type_checker_1.default.type(value));
         }
         if (isValueExpandable(value)) {
+            // NB: Important to set `originalExpandableValue` first as element
+            // generation will depend on it
             this.originalExpandableValue = value;
             this.elements = this._generateElements(value);
         }
@@ -72,6 +102,9 @@ class Element extends eventemitter3_1.default {
             this.value = value;
             this.currentValue = value;
         }
+        // The AutoEncrypter marks decrypted entries in a document
+        // for us with a special symbol. We opt into this behavior
+        // in the devtools-connect package.
         let parentValue;
         if (this.parent) {
             parentValue = this.parent.isRoot()
@@ -98,6 +131,11 @@ class Element extends eventemitter3_1.default {
         }
         return level;
     }
+    /**
+     * Edit the element.
+     *
+     * @param value - The new value.
+     */
     edit(value) {
         this.currentType = hadron_type_checker_1.default.type(value);
         if (isValueExpandable(value) && !isValueExpandable(this.currentValue)) {
@@ -144,16 +182,40 @@ class Element extends eventemitter3_1.default {
         }
         return parent;
     }
+    /**
+     * Get an element by its key.
+     *
+     * @param key - The key name.
+     *
+     * @returns The element.
+     */
     get(key) {
         return this.elements?.get(key);
     }
+    /**
+     * Get an element by its index.
+     *
+     * @param i - The index.
+     *
+     * @returns The element.
+     */
     at(i) {
         return this.elements?.at(i);
     }
+    /**
+     * Rename the element. Update the parent's mapping if available.
+     *
+     * @param key - The new key.
+     */
     rename(key) {
         this.currentKey = key;
         this._bubbleUp(element_events_1.default.Edited, this);
     }
+    /**
+     * Generate the javascript object for this element.
+     *
+     * @returns The javascript object.
+     */
     generateObject(options) {
         if (this.currentType === 'Array') {
             return object_generator_1.default.generateArray(this.elements, options);
@@ -163,6 +225,12 @@ class Element extends eventemitter3_1.default {
         }
         return this.currentValue;
     }
+    /**
+     * Generate the javascript object representing the original values
+     * for this element (pre-element removal, renaming, editing).
+     *
+     * @returns The javascript object.
+     */
     generateOriginalObject(options) {
         if (this.type === 'Array') {
             const originalElements = this._generateElements(this.originalExpandableValue);
@@ -174,6 +242,17 @@ class Element extends eventemitter3_1.default {
         }
         return this.value;
     }
+    /**
+     * Insert an element after the provided element. If this element is an array,
+     * then ignore the key specified by the caller and use the correct index.
+     * Update the keys of the rest of the elements in the LinkedList.
+     *
+     * @param element - The element to insert after.
+     * @param key - The key.
+     * @param value - The value.
+     *
+     * @returns The new element.
+     */
     insertAfter(element, key, value) {
         if (!this.elements) {
             throw new Error('Cannot insert values on non-array/non-object elements');
@@ -183,6 +262,14 @@ class Element extends eventemitter3_1.default {
         this.emitVisibleElementsChanged();
         return newElement;
     }
+    /**
+     * Add a new element to this element.
+     *
+     * @param| Number} key - The element key.
+     * @param value - The value.
+     *
+     * @returns The new element.
+     */
     insertEnd(key, value) {
         if (!this.elements) {
             throw new Error('Cannot insert values on non-array/non-object elements');
@@ -192,32 +279,67 @@ class Element extends eventemitter3_1.default {
         this.emitVisibleElementsChanged();
         return newElement;
     }
+    /**
+     * Insert a placeholder element at the end of the element.
+     *
+     * @returns The placeholder element.
+     */
     insertPlaceholder() {
+        // When adding a placeholder value to an array we default to the type
+        // of the last value currently in the array. Otherwise empty string.
         const placeholderValue = this.currentType === 'Array' && this.elements?.lastElement
             ? (0, utils_1.getDefaultValueForType)(this.elements?.lastElement.currentType)
             : '';
         return this.insertEnd('', placeholderValue);
     }
     insertSiblingPlaceholder() {
+        // When adding a sibling placeholder value to an array we default the
+        // new values' type to the preceding element's type to hopefully make
+        // it so folks don't have to change the type later. Otherwise empty string.
         const placeholderValue = this.parent?.currentType === 'Array'
             ? (0, utils_1.getDefaultValueForType)(this.currentType)
             : '';
         return this.parent.insertAfter(this, '', placeholderValue);
     }
+    /**
+     * Is the element a newly added element
+     *
+     * @returns If the element is newly added.
+     */
     isAdded() {
         return this.added || !!this.parent?.isAdded();
     }
+    /**
+     * Is the element blank?
+     *
+     * @returns If the element is blank.
+     */
     isBlank() {
         return this.currentKey === '' && this.currentValue === '';
     }
+    /**
+     * Does the element have a valid value for the current type?
+     *
+     * @returns If the value is valid.
+     */
     isCurrentTypeValid() {
         return !!this.currentTypeValid;
     }
+    /**
+     * Set the element as valid.
+     */
     setValid() {
         this.currentTypeValid = true;
         this.invalidTypeMessage = undefined;
         this._bubbleUp(element_events_1.default.Valid, this);
     }
+    /**
+     * Set the element as invalid.
+     *
+     * @param value - The value.
+     * @param newType - The new type.
+     * @param message - The error message.
+     */
     setInvalid(value, newType, message) {
         this.currentValue = value;
         this.currentType = newType;
@@ -225,6 +347,13 @@ class Element extends eventemitter3_1.default {
         this.invalidTypeMessage = message;
         this._bubbleUp(element_events_1.default.Invalid, this);
     }
+    /**
+     * Determine if the key is a duplicate.
+     *
+     * @param value - The value to check.
+     *
+     * @returns If the key is a duplicate.
+     */
     isDuplicateKey(value) {
         if (value === '') {
             return false;
@@ -236,12 +365,24 @@ class Element extends eventemitter3_1.default {
         }
         return false;
     }
+    /**
+     * Determine if the element is edited - returns true if
+     * the key or value changed. Does not count array values whose keys have
+     * changed as edited.
+     *
+     * @returns If the element is edited.
+     */
     isEdited() {
         return ((this.isRenamed() ||
             !this._valuesEqual() ||
             this.type !== this.currentType) &&
             !this.isAdded());
     }
+    /**
+     * Check for value equality.
+  
+     * @returns If the value is equal.
+     */
     _valuesEqual() {
         if (this.currentType === 'Date' && (0, lodash_1.isString)(this.currentValue)) {
             return (0, lodash_1.isEqual)(this.value, new Date(this.currentValue));
@@ -262,9 +403,19 @@ class Element extends eventemitter3_1.default {
     _isExpandable() {
         return this.currentType === 'Array' || this.currentType === 'Object';
     }
+    /**
+     * Is the element the last in the elements.
+     *
+     * @returns If the element is last.
+     */
     isLast() {
         return this.parent?.elements?.lastElement === this;
     }
+    /**
+     * Determine if the element was explicitly renamed by the user.
+     *
+     * @returns If the element was explicitly renamed by the user.
+     */
     isRenamed() {
         if (!this.parent ||
             this.parent.isRoot() ||
@@ -273,22 +424,77 @@ class Element extends eventemitter3_1.default {
         }
         return false;
     }
+    /**
+     * Determine if the element was renamed, potentially as part
+     * of moving array elements.
+     *
+     * @returns If the element was renamed, explicitly or implicitly.
+     */
     hasChangedKey() {
         return this.key !== this.currentKey;
     }
+    /**
+     * Can changes to the element be reverted?
+     *
+     * @returns If the element can be reverted.
+     */
     isRevertable() {
         return this.isEdited() || this.isRemoved();
     }
+    /**
+     * Can the element be removed?
+     *
+     * @returns If the element can be removed.
+     */
     isRemovable() {
         return !this.parent.isRemoved();
     }
+    /**
+     * Can no action be taken on the element
+     *
+     * @returns If no action can be taken.
+     */
     isNotActionable() {
         return (((this.key === ID || this.isInternalField()) && !this.isAdded()) ||
             !this.isRemovable());
     }
+    /**
+     * Determine if the value has been decrypted via CSFLE.
+     *
+     * Warning: This does *not* apply to the children of decrypted elements!
+     * This only returns true for the exact field that was decrypted.
+     *
+     * a: Object
+     *  \-- b: Object <- decrypted
+     *      \-- c: number
+     *
+     * a.isValueDecrypted() === false
+     * a.get('b')?.isValueDecrypted() === true
+     * a.get('b')?.get('c')?.isValueDecrypted() === true
+     *
+     * @returns If the value was encrypted on the server and is now decrypted.
+     */
     isValueDecrypted() {
         return this.decrypted;
     }
+    /**
+     * Detemine if this value or any of its children were marked
+     * as having been decrypted with CSFLE.
+     *
+     * Warning: This does *not* apply to the children of decrypted elements!
+     * This only returns true for the exact field that was decrypted
+     * and its parents.
+     *
+     * a: Object
+     *  \-- b: Object <- decrypted
+     *      \-- c: number
+     *
+     * a.containsDecryptedChildren() === true
+     * a.get('b')?.containsDecryptedChildren() === true
+     * a.get('b')?.get('c')?.containsDecryptedChildren() === false
+     *
+     * @returns If any child of this element has been decrypted directly.
+     */
     containsDecryptedChildren() {
         if (this.isValueDecrypted()) {
             return true;
@@ -300,10 +506,20 @@ class Element extends eventemitter3_1.default {
         }
         return false;
     }
+    /**
+     * Determine if the value is editable.
+     *
+     * @returns If the value is editable.
+     */
     isValueEditable() {
         return (this._isKeyLegallyEditable() &&
             !UNEDITABLE_TYPES.includes(this.currentType));
     }
+    /**
+     * Determine if the key of the parent element is editable.
+     *
+     * @returns If the parent's key is editable.
+     */
     isParentEditable() {
         if (this.parent && !this.parent.isRoot()) {
             return this.parent._isKeyLegallyEditable();
@@ -316,9 +532,20 @@ class Element extends eventemitter3_1.default {
                 ((this.currentKey !== ID || !this.parent?.isRoot()) &&
                     !this.isInternalField())));
     }
+    /**
+     * Determine if the key is editable.
+     *
+     * @returns If the key is editable.
+     */
     isKeyEditable() {
         return this._isKeyLegallyEditable() && !this.containsDecryptedChildren();
     }
+    /**
+     * Is this a field that is used internally by the MongoDB driver or server
+     * and not for user consumption?
+     *
+     * @returns
+     */
     isInternalField() {
         if (!this.parent) {
             return false;
@@ -331,6 +558,11 @@ class Element extends eventemitter3_1.default {
         }
         return false;
     }
+    /**
+     * Determine if the element is modified at all.
+     *
+     * @returns If the element is modified.
+     */
     isModified() {
         if (this.elements) {
             for (const element of this.elements) {
@@ -341,9 +573,19 @@ class Element extends eventemitter3_1.default {
         }
         return this.isAdded() || this.isEdited() || this.isRemoved();
     }
+    /**
+     * Is the element flagged for removal?
+     *
+     * @returns If the element is flagged for removal.
+     */
     isRemoved() {
         return this.removed;
     }
+    /**
+     * Are any immediate children of this element flagged for removal?
+     *
+     * @returns If any immediate children of this element are flagged for removal.
+     */
     hasAnyRemovedChild() {
         if (this.elements) {
             for (const element of this.elements) {
@@ -354,9 +596,17 @@ class Element extends eventemitter3_1.default {
         }
         return false;
     }
+    /**
+     * Elements themselves are not the root.
+     *
+     * @returns Always false.
+     */
     isRoot() {
         return false;
     }
+    /**
+     * Flag the element for removal.
+     */
     remove() {
         this.revert();
         this.removed = true;
@@ -365,6 +615,9 @@ class Element extends eventemitter3_1.default {
             this.emitVisibleElementsChanged(this.parent);
         }
     }
+    /**
+     * Revert the changes to the element.
+     */
     revert() {
         if (this.isAdded()) {
             this.parent?.elements?.remove(this);
@@ -395,6 +648,11 @@ class Element extends eventemitter3_1.default {
         this.setValid();
         this._bubbleUp(element_events_1.default.Reverted, this);
     }
+    /**
+     * Expands the target element and optionally its children as well.
+     * Document.expand is when we would want to expand the children otherwise we
+     * will most expand the element itself.
+     */
     expand(expandChildren = false) {
         if (!this._isExpandable()) {
             return;
@@ -408,6 +666,9 @@ class Element extends eventemitter3_1.default {
         this.emit(_1.ElementEvents.Expanded, this);
         this.emitVisibleElementsChanged();
     }
+    /**
+     * Collapses only the target element
+     */
     collapse() {
         if (!this._isExpandable()) {
             return;
@@ -421,6 +682,12 @@ class Element extends eventemitter3_1.default {
         this.emit(_1.ElementEvents.Collapsed, this);
         this.emitVisibleElementsChanged();
     }
+    /**
+     * Fire and bubble up the event.
+     *
+     * @param evt - The event.
+     * @paramdata - Optional.
+     */
     _bubbleUp(evt, ...data) {
         this.emit(evt, ...data);
         const element = this.parent;
@@ -433,20 +700,43 @@ class Element extends eventemitter3_1.default {
             }
         }
     }
+    /**
+     * Convert this element to an empty object.
+     */
     _convertToEmptyObject() {
         this.edit({});
         this.insertPlaceholder();
     }
+    /**
+     * Convert to an empty array.
+     */
     _convertToEmptyArray() {
         this.edit([]);
         this.insertPlaceholder();
     }
+    /**
+     * Is the element empty?
+     *
+     * @param element - The element to check.
+     *
+     * @returns If the element is empty.
+     */
     _isElementEmpty(element) {
         return !!element && element.isAdded() && element.isBlank();
     }
+    /**
+     * Generates a sequence of child elements.
+     *
+     * @param object - The object to generate from.
+     *
+     * @returns The elements.
+     */
     _generateElements(object) {
         return new ElementList(this, object);
     }
+    /**
+     * Removes the added elements from the element.
+     */
     _removeAddedElements() {
         if (this.elements) {
             for (const element of this.elements) {
@@ -485,11 +775,17 @@ class Element extends eventemitter3_1.default {
             targetElement._bubbleUp(element_events_1.default.VisibleElementsChanged, targetElement, targetElement.getRoot());
         }
     }
+    /**
+     * @deprecated Use ElementEvents import instead
+     */
     static get Events() {
         return _1.ElementEvents;
     }
 }
 exports.Element = Element;
+/**
+ * Represents a doubly linked list.
+ */
 class ElementList {
     constructor(parent, originalDoc) {
         this.parent = parent;
@@ -523,6 +819,16 @@ class ElementList {
     get lastElement() {
         return this.elements[this.elements.length - 1];
     }
+    /**
+     * Insert data after the provided element.
+     *
+     * @param afterElement - The element to insert after.
+     * @param key - The element key.
+     * @param value - The element value.
+     * @param added - If the element is new.
+     *
+     * @returns The inserted element.
+     */
     insertAfter(afterElement, key, value, added = true) {
         let newElement;
         let newElementIdx = -1;
@@ -541,6 +847,16 @@ class ElementList {
         }
         return newElement;
     }
+    /**
+     * Insert data before the provided element.
+     *
+     * @param beforeElement - The element to insert before.
+     * @param key - The element key.
+     * @param value - The element value.
+     * @param added - If the element is new.
+     *
+     * @returns The inserted element.
+     */
     insertBefore(beforeElement, key, value, added = true) {
         let newElement;
         let newElementIdx = -1;
@@ -558,6 +874,15 @@ class ElementList {
         }
         return newElement;
     }
+    /**
+     * Insert data at the beginning of the list.
+     *
+     * @param key - The element key.
+     * @param value - The element value.
+     * @param added - If the element is new.
+     *
+     * @returns The data element.
+     */
     insertBeginning(key, value, added = true) {
         const newElement = new Element(this.isArray() ? 0 : key, value, this.parent, added);
         if (this.isArray()) {
@@ -568,11 +893,27 @@ class ElementList {
         this.elements.unshift(newElement);
         return newElement;
     }
+    /**
+     * Insert data at the end of the list.
+     *
+     * @param key - The element key.
+     * @param value - The element value.
+     * @param added - If the element is new.
+     *
+     * @returns The data element.
+     */
     insertEnd(key, value, added = true) {
         const newElement = new Element(this.isArray() ? this.elements.length : key, value, this.parent, added);
         this.elements.push(newElement);
         return newElement;
     }
+    /**
+     * Remove the element from the list.
+     *
+     * @param removeElement - The element to remove.
+     *
+     * @returns The list with the element removed.
+     */
     remove(removeElement) {
         let removeIdx = -1;
         for (const [idx, el] of this.elements.entries()) {