@hkdigital/lib-sveltekit 0.0.42 → 0.0.45

package/dist/util/object/index.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Returns true
+ * - if the object has no (iterable) key value pairs
+ * - if the object is an empty array
+ *
+ * @param {object} obj
+ *
+ * @return {boolean}
+ *   true if the object has no key value pairs or the supplied object
+ *   is `falsey`
+ */
+export function isEmpty(obj: object): boolean;
+/**
+ * Get the number of (iterable) key value pairs in the specified object
+ *
+ * @param {object} obj
+ *
+ * @return {number} number of iterable key value pairs
+ */
+export function objectSize(obj: object): number;
+/**
+ * Returns a shallow copy of the object without the properties that
+ * have the value [null] or [undefined]
+ *
+ * @param {object} obj
+ *
+ * @param {string[]} [onlyKeys]
+ *   If specified, only the specified keys will be exported
+ *
+ * @returns {object} new object without the null properties
+ */
+export function exportNotNull(obj: object, onlyKeys?: string[]): object;
+/**
+ * Returns a shallow copy of the object without the properties that
+ * are `private`
+ * - Private properties are properties that start with an underscore
+ *   `_`.
+ *
+ * @param {object} obj
+ *
+ * @param {string[]} [keepKeys]
+ *   If specified, the sprecified private keys will be exported (e.g. `_id`)
+ *
+ * @returns {object} new object without the null properties
+ */
+export function exportNotPrivate(obj: object, keepKeys?: string[]): object;
+/**
+ * Keep only the specified keys in the object
+ * - deletes all other key-value pairs in the object
+ *
+ * @param {object} obj
+ * @param {string[]|Set} keys
+ * @param {boolean} [removeNullAndUndefined=true]
+ *
+ * @returns {object} object that only contains the specified keys
+ */
+export function keep(obj: object, keys: string[] | Set<any>, removeNullAndUndefined?: boolean): object;
+/**
+ * Freezes an object recursively
+ * - Allows non-objects to be passed as input parameter (non-objects are
+ *   immutable by default).
+ *
+ * @param {mixed} value
+ *
+ * @returns {mixed}
+ *   recursively frozen object or original input value if a non-object was
+ *   supplied as input parameter
+ */
+export function deepFreeze(value: mixed, _found: any): mixed;
+/**
+ * Set a value in an object using a path and value pair.
+ * - Automatically creates parent objects
+ *
+ * @param {object} obj - Object to set the value in
+ * @param {string|Array} path - Dot separated string path or array path
+ * @param {mixed} value - value to set
+ *
+ * @returns {boolean} true if the value was changed
+ */
+export function objectSet(obj: object, path: string | any[], value: mixed, ...args: any[]): boolean;
+/**
+ * Removes a value at the specified object path from the object.
+ * - All parent objects that remain empty will be removed too (recursively)
+ *
+ * @param {object} obj - Object to set the value in
+ * @param {string|Array} path - Dot separated string path or array path
+ * @param {mixed} value - value to set
+ */
+export function deletePath(obj: object, path: string | any[]): void;
+/**
+ * Get a value from an object using a path
+ * - Returns a default value if not found, with is [undefined] by default
+ *
+ * @param {object} obj - Object to get the value from
+ * @param {string|Array} path - Dot separated string path or array path
+ *
+ * @param {mixed} [defaultValue=undefined]
+ *   Value to return if the value does not exist
+ *
+ * @return {*} value found at path, defaultValue or undefined
+ */
+export function objectGet(obj: object, path: string | any[], defaultValue?: mixed): any;
+/**
+ * Get a value from an object using a path
+ * - Throws an exception if the path does not exist or the value is undefined
+ *
+ * @param {object} obj - Object to get the value from
+ * @param {string|Array} path - Dot separated string path or array path
+ *
+ * @param {function} [parseFn]
+ *   Optional parser function that checks and converts the value
+ *
+ * @throws No value found at path
+ * @throws Invalid value
+ *
+ * @return {*} value found at path
+ */
+export function objectGetWithThrow(obj: object, path: string | any[], parseFn?: Function): any;
+/**
+ * Get an iterator that returns the value of a path for each item (object)
+ * in the list of objects
+ *
+ * @param {object[]} arr - Array of objects
+ * @param {string|string[]} path - Dot separated string path or array path
+ *
+ * @param {object} [options] - options
+ *
+ * DEPRECEATED >>> NOT COMPATIBLE WITH LIGHTWEIGHT ITERATOR
+ * @param {object} [options.unique=false] - Only return unique values
+ *
+ * @param {mixed} [options.defaultValue]
+ *   Value to return if the value does not exist
+ *
+ * @returns {Iterator<mixed>} value at the specified path for each item
+ */
+/**
+ * Returns a list of differences between the object before and the object
+ * after the changes.
+ * - By default, the function returns changes for added, updated and removed
+ *   properties
+ *
+ * @param {object} objBefore
+ * @param {object} objAfter
+ *
+ * @param {object} options
+ * @param {boolean} [options.ignoreAdd=false]
+ * @param {boolean} [options.ignoreUpdate=false]
+ * @param {boolean} [options.ignoreDelete=false]
+ *
+ * @param {boolean} [options.ignorePrivate=true]
+ *   Ignore properties that start with an underscore e.g. _id or _updatedAt
+ *
+ * @param {boolean} [options.deleteValue=null]
+ *
+ * @returns {array}
+ *   List of changes between the object before and object after
+ */
+export function objectDiff(objBefore: object, objAfter: object, options: {
+    ignoreAdd?: boolean;
+    ignoreUpdate?: boolean;
+    ignoreDelete?: boolean;
+    ignorePrivate?: boolean;
+    deleteValue?: boolean;
+}, _recursion: any): any[];
+/**
+ * Applies a list of differences to the input object
+ * - A list of changes can be generated by e.g. objectDiff
+ *
+ * @param {object} obj
+ * @param {object[]} changes
+ *
+ * @param {object} options
+ * @param {boolean} [options.ignoreAdd=false]
+ * @param {boolean} [options.ignoreUpdate=false]
+ * @param {boolean} [options.ignoreDelete=false]
+ *
+ * @param {boolean} [options.ignorePrivate=true]
+ *   Ignore properties that start with an underscore e.g. _id or _updatedAt
+ */
+export function patchObject(obj: object, changes: object[], options?: {
+    ignoreAdd?: boolean;
+    ignoreUpdate?: boolean;
+    ignoreDelete?: boolean;
+    ignorePrivate?: boolean;
+}): void;
+/**
+ * Extend the target object with methods and properties from the source
+ * property object
+ * - The target object will be extended by inserting the source property
+ *   object into it's property chain
+
+ * - If the current target's prototype is not the same as the source
+ *   prototype, the source prototype will be cloned
+ *
+ * @param {object} target - Target object
+ * @param {object} source
+ *   object to append to the target's prototype chain. The object and it's
+ *   prototype objects are cloned first
+ */
+export function extend(target: object, source: object): void;
+/**
+ * Get a list of property names of the specified object
+ *
+ * @param {object} obj
+ *
+ * @returns {string[]} List of property names
+ */
+export function getPrototypeNames(obj: object): string[];
+/**
+ * Get a tree of values from an object
+ * - Can returns default values if one or multiple values were not found
+ *
+ * @param {object} obj - Object to get the value from
+ * @param {object} tree
+ *   Tree that contains the object paths to get.
+ *
+ *   e.g. { path: 1 }
+ *        { some: { path: { to: 1 }, otherPath: { to: 1 } } }
+ *        { "some.path.to": 1, "some.otherPath.to": 1 }
+ *        { someArray.0.name: 1 }
+ *
+ * @param {object} [options]
+ * @param {object} [options.shallowLeaves=false]
+ *   If set to true, the values of the leaves of the tree will be converted
+ *   to shallow objects if the leaves are nested objects.
+ *
+ * @return {object}
+ *   nested object with the values that were found or defaultValues
+ */
+export function getTree(obj: object, tree: object, options?: {
+    shallowLeaves?: object;
+}): object;
+/**
+ * Deep clone an object or any kind of other variable
+ * - Recursively clone all nested properties
+ * - Properties in the prototype chain are cloned too, but all copied into a
+ *   single prototype object
+ * - This method works on objects, but also on any other JS variable type
+ * - If a value cannot be cloned, a reference is returned. o.a. for
+ *   - Error objects
+ *   - Browser objects
+ *   - Functions
+ *
+ * @param {mixed} objectToBeCloned - Variable to clone
+ *
+ * @returns {mixed} cloned output
+ */
+export function clone(objectToBeCloned: mixed, _seenObjects: any): mixed;
+/**
+ * Set a read only property in an object
+ *
+ * @param {object} obj - Object to set the read only property in
+ * @param {string} propertyName - Name of the property to set
+ * @param {mixed} value - Value to set
+ */
+export function setReadOnlyProperty(obj: object, propertyName: string, value: mixed): void;
+/**
+ * Returns a clone of a (nested) object that has a maximum depth
+ *
+ * @param {object|array} obj
+ *
+ * @returns {object|array} shallow object or array
+ */
+export function shallowClone(objectOrArray: any): object | any[];
+/**
+ * Update an object
+ * - Sets the path-value pairs from the updateData in the object
+ * - Existing values will be overwritten
+ * - Existing intermediate values (objects, arrays) will be overwritten too
+ *   (if updateData is an object, not an iterable)
+ *
+ * @param {object} [obj] - Input object
+ *
+ * @param {object|iterable} updateData - Data to update
+ *
+ * Note that if using path-value pairs, the order of the pairs is relevant:
+ *   {
+ *     "some": {},
+ *     "some.path": {},
+ *     "some.path.to": 2,
+ *   }
+ *
+ * @returns {object} updated object
+ */
+export function updateObject(obj?: object, updateData: object | iterable, options: any): object;
+/**
+ * Copy own properties from an object to another object if they do not
+ * exist yet.
+ *
+ * @param {object} from - Object ot copy properties from
+ * @param {object} to - Object to copy properties to
+ */
+export function copyOwnProperties(from: object, to: object): void;
+/**
+ * Convert string with dot separated values to a list of values
+ * - Accepts that the supplied path is already an array path
+ *
+ * @param {string|string[]} path
+ *
+ * @returns {string[]} list of path values
+ */
+export function ensureArrayPath(path: string | string[]): string[];
+/**
+ * Create all parent objects on the object path if they do not yet exist yet
+ * - This method will throw an exception if there is a non-object node in
+ *   the path
+ *
+ * @param {object} obj
+ *   Object to create the parent objects in
+ *
+ * @param {string[]} arrPath
+ *   The path that specified which parent oobjects to create
+ *
+ * @returns {object} the input object with the created object properties
+ */
+export function _ensureParent(obj: object, arrPath: string[]): object;
+/**
+ * Get parent object at the specified path
+ *
+ * @param {object}   obj - Object to work in
+ * @param {string[]} arrPath - Path to get the parent object for
+ *
+ * @returns {object|array|null} parent object or null if not found
+ */
+export function _getParent(obj: object, arrPath: string[]): object | any[] | null;
+export const PATH_SEPARATOR: ".";