@fluid-experimental/property-changeset 2.0.0-internal.1.2.0.93071 → 2.0.0-internal.1.2.2

package/lib/utils.js

@@ -24,16 +24,17 @@ const { PROPERTY_PATH_DELIMITER, MSG } = constants;
  * @alias property-changeset.Utils
  * @class
 */
+// eslint-disable-next-line @typescript-eslint/no-namespace
 export var Utils;
 (function (Utils) {
     /**
-        * Traverses a ChangeSet recursively and invokes the callback for each visited property.
-        *
-        * @param in_preCallback - The (pre-order) callback function that is invoked for each property
-        * @param in_postCallback - The (post-order) callback function that is invoked for each property
-        * @param in_context -  The traversal context for the currently processed property
-        * @param in_levelCallback - A callback for when a node is reached
-        */
+    * Traverses a ChangeSet recursively and invokes the callback for each visited property.
+    *
+    * @param in_preCallback - The (pre-order) callback function that is invoked for each property
+    * @param in_postCallback - The (post-order) callback function that is invoked for each property
+    * @param in_context -  The traversal context for the currently processed property
+    * @param in_levelCallback - A callback for when a node is reached
+    */
     function _traverseChangeSetRecursivelyAsync(in_preCallback, in_postCallback, in_context, in_levelCallback) {
         let pathSeparator;
         let currentPath;
@@ -106,14 +107,11 @@ export var Utils;
                                 let nextSegmentToPushInParentStack = in_context.getLastSegment();
                                 // Note: we don't quote the path string here, since the paths
                                 // in a ChangeSet are already quoted, if necessary
-                                if (currentTypeIdContext === "map" ||
+                                in_context._lastSegmentString = currentTypeIdContext === "map" ||
                                     currentTypeIdContext === "array" ||
-                                    currentTypeIdContext === "set") {
-                                    in_context._lastSegmentString = `[${escapedSegment}]`;
-                                }
-                                else {
-                                    in_context._lastSegmentString = pathSeparator + escapedSegment;
-                                }
+                                    currentTypeIdContext === "set"
+                                    ? `[${escapedSegment}]`
+                                    : pathSeparator + escapedSegment;
                                 in_context._fullPath = currentPath + in_context.getLastSegmentString();
                                 // Store the typeid and nested ChangeSet
                                 in_context._typeid = in_nestedTypeid;
@@ -463,14 +461,11 @@ export var Utils;
             const escapedSegment = in_escape && isString(in_segment) ? PathHelper.quotePathSegmentIfNeeded(in_segment) : in_segment;
             let nextSegmentToPushInParentStack = in_context._lastSegment;
             // Note: we don't quote the path string here, since the paths in a ChangeSet are already quoted, if necessary
-            if (currentTypeIdContext === "map" ||
+            in_context._lastSegmentString = currentTypeIdContext === "map" ||
                 currentTypeIdContext === "array" ||
-                currentTypeIdContext === "set") {
-                in_context._lastSegmentString = `[${escapedSegment}]`;
-            }
-            else {
-                in_context._lastSegmentString = pathSeparator + escapedSegment;
-            }
+                currentTypeIdContext === "set"
+                ? `[${escapedSegment}]`
+                : pathSeparator + escapedSegment;
             in_context._fullPath = currentPath + in_context._lastSegmentString;
             // Store the typeid and nested ChangeSet
             in_context._typeid = in_nestedTypeid;
@@ -753,12 +748,9 @@ export var Utils;
          */
         getPostLastSegment() {
             if (this._propertyContainerType === "array" && isNumber(this._lastSegment) && this._arrayIteratorOffset !== undefined) {
-                if (this._operationType === "remove") {
-                    return this._lastSegment + this._arrayIteratorOffset - this._arrayLocalIndex;
-                }
-                else {
-                    return this._lastSegment + this._arrayIteratorOffset;
-                }
+                return this._operationType === "remove"
+                    ? this._lastSegment + this._arrayIteratorOffset - this._arrayLocalIndex
+                    : this._lastSegment + this._arrayIteratorOffset;
             }
             else {
                 return this._lastSegment;
@@ -983,14 +975,7 @@ export var Utils;
         }
         else {
             // if we're given an extra rootTypeId, use that
-            if (in_params.rootTypeid) {
-                context._typeid = in_params.rootTypeid;
-            }
-            else {
-                // By default, we assume that a ChangeSet without a typeid affects a NodeProperty, since that is the default
-                // for a repository root
-                context._typeid = "NodeProperty";
-            }
+            context._typeid = in_params.rootTypeid ? in_params.rootTypeid : "NodeProperty";
         }
         context._nestedChangeSet = in_changeSet;
         context._parentNestedChangeSet = in_changeSet;
@@ -1021,14 +1006,7 @@ export var Utils;
         }
         else {
             // if we're given an extra rootTypeId, use that
-            if (in_params.rootTypeid) {
-                context._typeid = in_params.rootTypeid;
-            }
-            else {
-                // By default, we assume that a ChangeSet without a typeid affects a NodeProperty, since that is the default
-                // for a repository root
-                context._typeid = "NodeProperty";
-            }
+            context._typeid = in_params.rootTypeid ? in_params.rootTypeid : "NodeProperty";
         }
         context._nestedChangeSet = in_changeSet;
         context._parentNestedChangeSet = in_changeSet;
@@ -1069,9 +1047,8 @@ export var Utils;
      * @param in_callback - A callback that is used to emit every template
      * @param in_finalizer - A callback that is called when enumeration is completed
      *
-     * @returns All templates that appear in the ChangeSet
-     *   The returned object has members key (string), corresponding to the type and value with the
-     *   definition (object)
+     * @returns All templates that appear in the ChangeSet.
+     * The returned object has members key (string), corresponding to the type and value with the definition (object)
      */
     function enumerateSchemas(in_changeSet, in_callback, in_finalizer) {
         const result = [];
@@ -1111,14 +1088,10 @@ export var Utils;
                     }
                     return;
                 }
-                let operationScope;
-                if (in_context.getPropertyContainerType() !== "template") {
-                    operationScope = userData[in_context.getOperationType()] = userData[in_context.getOperationType()] ||
-                        (in_context.getPropertyContainerType() === "array" ? [] : {});
-                }
-                else {
-                    operationScope = userData;
-                }
+                const operationScope = in_context.getPropertyContainerType() !== "template"
+                    ? (userData[in_context.getOperationType()] = userData[in_context.getOperationType()]
+                        || (in_context.getPropertyContainerType() === "array" ? [] : {}))
+                    : userData;
                 if (TypeIdHelper.isPrimitiveType(in_context.getTypeid())) {
                     // This is a primitive type, we store it under its name in the result
                     operationScope[in_context.getLastSegment()] = in_context.getNestedChangeSet();
@@ -1194,10 +1167,13 @@ export var Utils;
      * @param in_changeSet - The ChangeSet to process
      * @param in_excludetypeids - Exclude all typeids from the returned ChangeSet
      * @throws if path is invalid.
-     * @returns The changes that are applied to the given path
+     * @returns The changes that are applied to the given path.
+     *
+     * ```
      * <pre>
      * {insert: Object|undefined, modify: Object|undefined, remove: boolean|undefined}
      * </pre>
+     * ```
      */
     function getChangesByPath(in_path, in_root, in_changeSet, in_excludetypeids) {
         // if we're asked for the root, just return the root (in a modify)
@@ -1269,65 +1245,78 @@ export var Utils;
     /**
      * Invoke a callback for all nested ChangeSets that correspond to a set of user supplied tokenized paths.
      *
-     * @param in_paths -
-     *     A map or object which contains the tokenized paths as nested elements. Common path segment are thus shared.
-     *     NOTE: It is recommended to use Map as it provides better performance.
-     *     For example, for these three paths:
-     *     'entry1'
-     *     'nested.entry2'
-     *     'nested.entry3'
+     * @param in_paths - A map or object which contains the tokenized paths as nested elements.
+     * Common path segment are thus shared.
+     *
+     * NOTE: It is recommended to use Map as it provides better performance.
+     * For example, for these three paths:
+     *
+     * - 'entry1'
+     *
+     * - 'nested.entry2'
+     *
+     * - 'nested.entry3'
      *
-     *     Using a map for paths would look like this:
-     *     new Map([
-     *       ['entry', new Map()],
-     *       ['nested', new Map([
-     *         ['entry2', new Map()],
-     *         ['entry3', new Map()]
-     *       ])]
-     *     ])
+     * Using a map for paths would look like this:
      *
-     *     While using objects for paths would look like this:
-     *     {
-     *       entry: {},
-     *       nested: {
-     *         entry2: {}
-     *         entry3: {}
-     *       }
-     *     }
+     * ```typescript
+     * new Map([
+     *   ['entry', new Map()],
+     *   ['nested', new Map([
+     *     ['entry2', new Map()],
+     *     ['entry3', new Map()]
+     *   ])]
+     * ])
+     * ```
      *
-     *     The element under the path, will be provided to the callback. If you have to pass additional data
-     *     to the callback, you can add private data by prefixing it with __ and setting
-     *     in_options.escapeLeadingDoubleUnderscore to true.
-     *     In case you do that, bear in mind that paths that refer to changeSet properties that have at least
-     *     two underscores as prefix in its id, should contain an extra underscore character as prefix:
-     *     | Path in changeSet | Path in paths |
-     *     |       path0       |      path0    | (unescaped)
-     *     |      _path1       |     _path1    | (unescaoed)
-     *     |     __path2       |   ___path2    | (escaped with one extra leading underscore)
-     *     |    ___path3       |  ____path3    | (also escaped, the same applies to N underscores where N >= 2)
-     * @param in_changeSet -
-     *     The ChangeSet to process
-     * @param in_callback -
-     *     The function to invoke at the registered paths (it is called both for the interior and the leaf nodes). The
-     *     callback will be called for each node with the following parameters:
-     *     context - The current TraversalContext as returned by Utils.traverseChangeSetRecursively. Can be used for
-     *               querying the current Property type, operation, etc.
-     *     currentSubPaths - a subset of the tokenized paths passed in as input to this
-     *                       function that still need to be processed from the current node
-     *     currentTokenizedPath - the tokenized path leading to the current node
-     *     contractedPathSegment - True if the current node is inside a contracted path segment
-    *                              (e.g. currentTokenizedPath is ['foo'], coming from the
-    *                              changeset segment 'foo.bar'), false otherwise. If true, the
-    *                              typeid from the context parameter may not be valid at the
-    *                              current node. Callbacks may ignore this if they are not
-    *                              concerned with the type.
-     * @param in_options -
-     * @param in_options.rootOperation - The operation that has been applied to the root of the ChangeSet (either 'insert' or 'modify')
+     * While using objects for paths would look like this:
+     *
+     * ```typescript
+     * {
+     *   entry: {},
+     *   nested: {
+     *     entry2: {}
+     *     entry3: {}
+     *   }
+     * }
+     * ```
+     *
+     * The element under the path, will be provided to the callback. If you have to pass additional data
+     * to the callback, you can add private data by prefixing it with __ and setting
+     * in_options.escapeLeadingDoubleUnderscore to true.
+     * In case you do that, bear in mind that paths that refer to changeSet properties that have at least
+     * two underscores as prefix in its id, should contain an extra underscore character as prefix:
+     *
+     * ```
+     * | Path in changeSet | Path in paths |
+     * |       path0       |      path0    | (unescaped)
+     * |      _path1       |     _path1    | (unescaoed)
+     * |     __path2       |   ___path2    | (escaped with one extra leading underscore)
+     * |    ___path3       |  ____path3    | (also escaped, the same applies to N underscores where N >= 2)
+     * ```
+     * @param in_changeSet - The ChangeSet to process
+     * @param in_callback - The function to invoke at the registered paths (it is called both for the interior and the
+     * leaf nodes). The callback will be called for each node with the following parameters:
+     *
+     * - `context`: The current TraversalContext as returned by Utils.traverseChangeSetRecursively.
+     * Can be used for querying the current Property type, operation, etc.
+     *
+     * - `currentSubPaths`: A subset of the tokenized paths passed in as input to this function that still need to be
+     * processed from the current node
+     *
+     * - `currentTokenizedPath`: The tokenized path leading to the current node
+     *
+     * - `contractedPathSegment`: True if the current node is inside a contracted path segment (e.g.
+     * currentTokenizedPath is ['foo'], coming from the changeset segment 'foo.bar'), false otherwise. If true, the
+     * typeid from the context parameter may not be valid at the current node. Callbacks may ignore this if they are
+     * not concerned with the type.
+     *
+     * @param in_options.rootOperation - The operation that has been applied to the root of the ChangeSet
+     * (either 'insert' or 'modify')
      * @param in_options.rootTypeid - The full type of the root Property of the ChangeSet
-     * @param in_options.escapeLeadingDoubleUnderscore -
-     *     If this is set to true, keys which start with '__' will be escaped (by adding an additional '_') before the
-     *     lookup into the paths map. This frees the keyspace with duplicated underscores for the use by the calling
-     *     application.
+     * @param in_options.escapeLeadingDoubleUnderscore - If this is set to true, keys which start with '__' will be
+     * escaped (by adding an additional '_') before the lookup into the paths map. This frees the keyspace with
+     * duplicated underscores for the use by the calling application.
      */
     function getChangesToTokenizedPaths(in_paths, in_changeSet, in_callback, in_options = { escapeLeadingDoubleUnderscore: false, rootOperation: 'modify' }) {
         const currentTokenizedPath = [];
@@ -1375,14 +1364,11 @@ export var Utils;
             return thisLevel;
         };
         const _toCallbackParam = (pathLevels) => {
-            if (legacyPaths) {
+            return legacyPaths
                 // If a user provided objects as paths, they would expect objects in their callbacks as well.
                 // So, we transform the parameter to an object, which is not very performant but is backwards compatible.
-                return _convertMapToLevel(pathLevels);
-            }
-            else {
-                return pathLevels;
-            }
+                ? _convertMapToLevel(pathLevels)
+                : pathLevels;
         };
         if (!(in_paths instanceof Map)) {
             legacyPaths = true;
@@ -1478,32 +1464,37 @@ export var Utils;
      * Given a change set, this function will filter it based on a series of paths.
      * The final ChangeSet will only include the paths in question starting from the root of
      * the ChangeSet.
-     * For Example,
-     *   Given the following change set
-     *      'insert': {
-     *        'String': {
-     *          'string1': 'hello',
-     *          'string2': 'world
-     *        }
-     *      }
-     *   And the path
-     *     ['string1']
-     *   the resulting ChangeSet will be
-     *     'insert': {
-     *       'String': {
-     *         'string1': 'hello'
-     *       }
-     *     }
+     *
+     * @example Given the following change set:
+     *
+     * ```json
+     * 'insert': {
+     *  'String': {
+     *      'string1': 'hello',
+     *      'string2': 'world
+     *  }
+     * }
+     * ```
+     *
+     * And the path `['string1']`, the resulting ChangeSet will be:
+     *
+     * ```json
+     * 'insert': {
+     *  'String': {
+     *      'string1': 'hello'
+     *  }
+     * }
+     * ```
      *
      * NOTE: Paths that traverse through sets and arrays are not supported.
      *
-     * @param in_changeSet - The changeset to parse
+     * @param in_changeSet - The changeset to parse.
      * @param in_paths - List of paths to filter by. This can either be passed
-     *     as a flat array of paths or as a Map with the tokenized, tree structured paths, see the
-     *     documentation of getChangesToTokenizedPaths for an example.
-     *     Note: duplicate paths will be ignored including ones that encompasse other paths
+     * as a flat array of paths or as a Map with the tokenized, tree structured paths, see the
+     * documentation of getChangesToTokenizedPaths for an example.
+     * Note: duplicate paths will be ignored including ones that encompasse other paths.
      *
-     * @throws if a path given resolves into an array or set
+     * @throws If a path given resolves into an array or set.
      * @returns - Filtered ChangeSet
      */
     function getFilteredChangeSetByPaths(in_changeSet, in_paths) {
@@ -1550,21 +1541,15 @@ export var Utils;
                         changeSetToPopulate = pathToChangeSet[parentPath] || changeSetToPopulate;
                     }
                     else if (index < tokenizedPath.length - 1) {
-                        if (context.getContainerStack()[index] !== "set" && context.getContainerStack()[index] !== "map") {
-                            parentPath += `.${PathHelper.quotePathSegmentIfNeeded(segment)}`;
-                        }
-                        else {
-                            parentPath += `[${PathHelper.quotePathSegmentIfNeeded(segment)}]`;
-                        }
+                        parentPath += context.getContainerStack()[index] !== "set" && context.getContainerStack()[index] !== "map"
+                            ? `.${PathHelper.quotePathSegmentIfNeeded(segment)}`
+                            : `[${PathHelper.quotePathSegmentIfNeeded(segment)}]`;
                         changeSetToPopulate = pathToChangeSet[parentPath] || changeSetToPopulate;
                     }
                     else {
-                        if (context.getContainerStack()[index] !== "set" && context.getContainerStack()[index] !== "map") {
-                            parentPath += `.${PathHelper.quotePathSegmentIfNeeded(segment)}`;
-                        }
-                        else {
-                            parentPath += `[${PathHelper.quotePathSegmentIfNeeded(segment)}]`;
-                        }
+                        parentPath += context.getContainerStack()[index] !== "set" && context.getContainerStack()[index] !== "map"
+                            ? `.${PathHelper.quotePathSegmentIfNeeded(segment)}`
+                            : `[${PathHelper.quotePathSegmentIfNeeded(segment)}]`;
                         fullPath = parentPath;
                     }
                     pathsToDelete.push(parentPath);
@@ -1697,7 +1682,7 @@ export var Utils;
      *
      * @param in_paths - An array with paths
      * @returns {Map} A tree structured representation of the tokenized paths that can be
-     *     passed to getChangesToTokenizedPaths and getFilteredChangeSetByPaths.
+     * passed to getChangesToTokenizedPaths and getFilteredChangeSetByPaths.
      */
     function convertPathArrayToTree(in_paths) {
         in_paths = Array.isArray(in_paths) ? in_paths : [in_paths];
@@ -1737,22 +1722,27 @@ export var Utils;
      * Given a change set, this function will filter it based on a series of paths.
      * The final ChangeSet will exclude the paths in question starting from the root of
      * the ChangeSet.
-     * For Example,
-     *   Given the following change set
-     *      'insert': {
-     *        'String': {
-     *          'string1': 'hello',
-     *          'string2': 'world
-     *        }
-     *      }
-     *   And the path
-     *     ['string1']
-     *   the resulting ChangeSet will be
-     *     'insert': {
-     *       'String': {
-     *         'string2': 'world'
-     *       }
-     *     }
+     *
+     * @example Given the following change set:
+     *
+     * ```json
+     * 'insert': {
+     *  'String': {
+     *      'string1': 'hello',
+     *      'string2': 'world
+     *  }
+     * }
+     * ```
+     *
+     * And the path `['string1']`, the resulting ChangeSet will be:
+     *
+     * ```json
+     * 'insert': {
+     *  'String': {
+     *      'string2': 'world'
+     *  }
+     * }
+     * ```
      *
      * NOTE: Paths that traverse through sets and arrays are not supported.
      *
@@ -1787,7 +1777,8 @@ export var Utils;
     Utils.excludePathsFromChangeSet = excludePathsFromChangeSet;
     /**
      * Extract all paths from the ChangeSet in a flattened list and include the operations and typeid information.
-     * NOTE: The paths returned also include the parent. i.e. the path 'nodeProp.subproperty' will result in
+     * @remarks NOTE: The paths returned also include the parent. i.e. the path 'nodeProp.subproperty' will result in:
+     * ```json
      * {
      *   nodeProp: {
      *    operation: 'modify',
@@ -1798,6 +1789,8 @@ export var Utils;
      *    typeid: { typeid: 'Float32', context: 'single', isEnum: false }
      *   }
      * }
+     * ```
+     *
      * @param in_changeSet - The changeset to extract paths from
      * @param in_options - Set of options
      * @param in_options.includeOperation - Flag to include the operation