@schukai/monster 3.34.0 → 3.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schukai/monster",
-  "version": "3.34.0",
+  "version": "3.35.0",
   "description": "Monster is a simple library for creating fast, robust and lightweight websites.",
   "keywords": [
     "framework",

package/source/data/buildmap.mjs

@@ -19,27 +19,26 @@ export { buildMap, PARENT, assembleParts };
 const PARENT = "^";
 
 /**
- * With the help of the function `buildMap()`, maps can be easily created from data objects.
+ * Maps can be easily created from data objects with the help of the function `buildMap()`.
  *
- * Either a simple definition `a.b.c` or a template `${a.b.c}` can be specified as the path.
+ * The path can be specified as either a simple definition a.b.c or a template ${a.b.c}.
  * Key and value can be either a definition or a template. The key does not have to be defined.
- *
  * The templates determine the appearance of the keys and the value of the map. Either a single value
- * `id` can be taken or a composite key `${id} ${name}` can be used.
+ * id can be taken or a composite key ${id} ${name} can be used.
  *
- * If you want to access values of the parent data set, you have to use the `^` character `${id} ${^.name}`.
+ * If you want to access values of the parent data set, you have to use the ^ character, for example ${id} ${^.name}.
  *
  * @externalExample ../../example/data/buildmap.mjs
- * @param {*} subject
- * @param {string|Monster.Data~exampleSelectorCallback} selector
- * @param {string} [valueTemplate]
- * @param {string} [keyTemplate]
- * @param {Monster.Data~exampleFilterCallback} [filter]
- * @return {*}
+ * @param {*} subject - The data object from which the map will be created
+ * @param {string|Monster.Data~exampleSelectorCallback} selector - The path to the data object, or a callback that returns a map.
+ * @param {string} [valueTemplate] - A template for the value of the map.
+ * @param {string} [keyTemplate] - A template for the key of the map.
+ * @param {Monster.Data~exampleFilterCallback} [filter] - A callback function to filter out values.
+ * @return {*} - The created map.
  * @memberOf Monster.Data
- * @throws {TypeError} value is neither a string nor a function
- * @throws {TypeError} the selector callback must return a map
- */
+ * @throws {TypeError} - If the value is neither a string nor a function.
+ * @throws {TypeError} - If the selector callback does not return a map.
+ **/
 function buildMap(subject, selector, valueTemplate, keyTemplate, filter) {
     return assembleParts(subject, selector, filter, function (v, k, m) {
         k = build(v, keyTemplate, k);
@@ -49,13 +48,66 @@ function buildMap(subject, selector, valueTemplate, keyTemplate, filter) {
 }
 
 /**
+ * The assembleParts function is a private function that helps in building a map from a subject object based on a provided
+ * selector. The selector can either be a string or a callback function. This function is meant to be used as a
+ * helper function by other functions in the module.
+ *
+ * The function takes four parameters:
+ *
+ * subject: The subject object from which the map is to be built
+ * selector: The selector to determine the structure of the map. It can be a string or a callback function.
+ * filter (optional): A callback function that can be used to filter values based on some criteria.
+ * callback: A function to be called for each element in the map.
+ * If the selector parameter is a callback function, it is executed passing the subject as its argument,
+ * and the resulting value must be an instance of Map. Otherwise, if the selector parameter is a string,
+ * buildFlatMap is called to build a flat map with keys and values extracted from the subject object based on the selector.
+ *
+ * If the filter parameter is provided, it will be used to filter out certain elements from the map, based on some
+ * criteria. The callback will be passed the value, key, and map object, and if it returns false, the element will be skipped.
+ *
+ * For each element in the map, the callback function is called with the following parameters:
+ *
+ * v: The value of the element
+ * k: The key of the element
+ * m: The map object
+ * The function returns a new map with the processed values. If map is not an instance of Map, an empty map will be returned.
+ *
+ * Example Usage:
+ *
+ * ```javascript
+ * const obj = {
+ *   name: "John",
+ *   age: 30,
+ *   address: {
+ *     city: "New York",
+ *     state: "NY",
+ *     country: "USA",
+ *   },
+ * };
+ *
+ * const selector = "address";
+ *
+ * const map = assembleParts(obj, selector, null, function (v, k, m) {
+ *   this.set(k, v);
+ * });
+ *
+ * console.log(map);
+ * // Output: Map(3) {
+ * //   "address.city" => "New York",
+ * //   "address.state" => "NY",
+ * //   "address.country" => "USA"
+ * // }
+ * ```
+ *
+ *
  * @private
- * @param {*} subject
- * @param {string|Monster.Data~exampleSelectorCallback} selector
- * @param {Monster.Data~exampleFilterCallback} [filter]
- * @param {function} callback
- * @return {Map}
- * @throws {TypeError} selector is neither a string nor a function
+ * @param {*} subject - The subject object from which the map is to be built.
+ * @param {string|Monster.Data~exampleSelectorCallback} selector - The selector to determine the structure of the map. It can be a string or a callback function.
+ * @param {Monster.Data~exampleFilterCallback} [filter] - A callback function that can be used to filter values based on some criteria.
+ * @param {function} callback - A function to be called for each element in the map.
+ * @return {Map} - A new map with the processed values.
+ * @throws {TypeError} - When selector is neither a string nor a function.
+ * @memberOf Monster.Data
  */
 function assembleParts(subject, selector, filter, callback) {
     const result = new Map();

package/source/data/buildtree.mjs

@@ -33,19 +33,102 @@ const rootSymbol = Symbol("root");
  */
 
 /**
- * With the help of the function `buildTree()`, nodes can be easily created from data objects.
- *
- * @param {*} subject
- * @param {string|Monster.Data~exampleSelectorCallback} selector
- * @param {string} idKey
- * @param {string} parentIDKey
- * @param {buildTreeOptions} [options]
- * @return {*}
- * @memberOf Monster.Data
- * @throws {TypeError} value is neither a string nor a function
- * @throws {TypeError} the selector callback must return a map
- * @throws {Error} the object has no value for the specified id
+ * Creates a tree structure from a given subject using a selector and specified ID and parent ID keys.
+ *
+ * The buildTree function is a powerful tool for creating tree-like data structures from plain JavaScript
+ * objects. It takes in four required parameters: the subject object that you want to turn into a tree, a
+ * selector that identifies which parts of the subject to use when building the tree, and two keys
+ * (idKey and parentIDKey) that specify which properties in the subject represent the unique identifiers
+ * and parent-child relationships between nodes in the tree.
+ *
+ * Optionally, you can also pass in an options object to further configure the behavior of the function,
+ * such as specifying which values should be treated as roots of the tree, or providing a custom filter
+ * function to only include certain nodes in the final output.
+ *
+ * The buildTree function works by first using the assembleParts helper function to extract the relevant
+ * parts of the subject based on the selector, and then iterates over the resulting map to create Node
+ * objects and organize them into parent-child relationships based on the values of the idKey and parentIDKey properties.
+ *
+ * The resulting NodeList represents the tree structure, with each Node object containing the original
+ * object data as well as additional metadata about its position in the tree. You can then use the childNodes
+ * property of each Node to access its children, or the parent property to access its parent.
+ *
+ * Overall, the buildTree function is a flexible and powerful way to transform flat data into hierarchical
+ * structures, and can be especially useful in scenarios such as displaying folder structures or
+ * visualizing complex data relationships.
+ *
+ * Let's say you have an array of data objects representing a file system directory structure, and you want
+ * to turn it into a tree-like structure where each node represents a folder or file, and child nodes
+ * represent the contents of the folder:
+ *
+ * ```javascript
+ * const fileSystem = [
+ *   { id: 'folder1', name: 'Folder 1', type: 'folder', parent: null },
+ *   { id: 'file1', name: 'File 1', type: 'file', parent: 'folder1' },
+ *   { id: 'file2', name: 'File 2', type: 'file', parent: 'folder1' },
+ *   { id: 'subfolder1', name: 'Subfolder 1', type: 'folder', parent: 'folder1' },
+ *   { id: 'file3', name: 'File 3', type: 'file', parent: 'subfolder1' },
+ *   { id: 'file4', name: 'File 4', type: 'file', parent: 'subfolder1' },
+ *   { id: 'subfolder2', name: 'Subfolder 2', type: 'folder', parent: 'folder1' },
+ *   { id: 'file5', name: 'File 5', type: 'file', parent: 'subfolder2' },
+ *   { id: 'file6', name: 'File 6', type: 'file', parent: 'subfolder2' },
+ *   { id: 'folder2', name: 'Folder 2', type: 'folder', parent: null },
+ *   { id: 'file7', name: 'File 7', type: 'file', parent: 'folder2' },
+ *   { id: 'file8', name: 'File 8', type: 'file', parent: 'folder2' },
+ *   { id: 'subfolder3', name: 'Subfolder 3', type: 'folder', parent: 'folder2' },
+ *   { id: 'file9', name: 'File 9', type: 'file', parent: 'subfolder3' },
+ *   { id: 'file10', name: 'File 10', type: 'file', parent: 'subfolder3' },
+ * ];
+ *
+ * const tree = buildTree(fileSystem, 'id', 'id', 'parent', { rootReferences: [null] });
+ *
+ * console.log(tree.toString());
+ * ```
+ *
+ * The buildTree function takes in the array of data objects, as well as some configuration options specifying
+ * the keys to use for identifying nodes and their parent-child relationships. In this example, we use the id
+ * key to identify nodes, and the parent key to specify the parent of each node.
+ *
+ * The resulting tree object is a nested tree structure, where each node is an object representing a file or
+ * folder, and has child nodes representing its contents. The toString method of the tree object
+ * can be used to print out the tree in a readable format:
+ *
+ * ```markdown
+ * - Folder 1
+ *   - File 1
+ *   - File 2
+ *   - Subfolder 1
+ *     - File 3
+ *     - File 4
+ *   - Subfolder 2
+ *     - File 5
+ *     - File 6
+ * - Folder 2
+ *   - File 7
+ *   - File 8
+ *   - Subfolder 3
+ *     - File 9
+ *     - File 10
+ * ```
+ *
+ * @memberof Monster.Data
+ *
+ * @param {*} subject - The object or array to build the tree from.
+ * @param {string|Monster.Data~exampleSelectorCallback} selector - Either a string to specify a property of each object to use as a selector, or a selector function to generate a map of objects.
+ * @param {string} idKey - The property key to use as the unique ID of each node.
+ * @param {string} parentIDKey - The property key to use as the parent ID of each node.
+ * @param {object} [options] - Additional options to modify the function behavior.
+ * @param {Array<*>} [options.rootReferences=[null, undefined]] - An array of values to treat as root references when creating the tree.
+ * @param {function} [options.filter] - A filter function to apply to each node.
+ *
+ * @return {*} The resulting tree structure as a NodeList.
+ *
+ * @throws {TypeError} selector is neither a string nor a function.
+ * @throws {TypeError} the selector callback must return a map.
+ * @throws {Error} the object has no value for the specified id.
+ *
  * @license AGPLv3
+ *
  * @since 1.26.0
  */
 function buildTree(subject, selector, idKey, parentIDKey, options) {

package/source/data/datasource/dom.mjs

@@ -5,12 +5,11 @@
  * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html
  */
 
-import {  instanceSymbol } from "../../constants.mjs";
-import {  isObject } from "../../types/is.mjs";
+import { instanceSymbol } from "../../constants.mjs";
+import { isObject } from "../../types/is.mjs";
 import { Datasource } from "../datasource.mjs";
 
-export {DomStorage};
-
+export { DomStorage };
 
 /**
  * The DomStorage is a class that stores data in memory.
@@ -53,7 +52,7 @@ class DomStorage extends Datasource {
             },
             write: {
                 selector: undefined,
-            }
+            },
         });
     }
 
@@ -78,13 +77,12 @@ class DomStorage extends Datasource {
         return new Promise((resolve, reject) => {
             try {
                 let data = JSON.parse(storage.innerHTML);
-                self.set(data)
+                self.set(data);
                 resolve(data);
             } catch (e) {
                 reject(e);
             }
-            ;
-        })
+        });
     }
 
     /**
@@ -93,7 +91,6 @@ class DomStorage extends Datasource {
      * @throws {Error} There are no storage element
      */
     write() {
-
         const self = this;
 
         let selector = self.getOption("write.selector");
@@ -113,10 +110,6 @@ class DomStorage extends Datasource {
             } catch (e) {
                 reject(e);
             }
-        })
-
-
+        });
     }
-
 }
-

package/source/data/datasource/server/restapi.mjs

@@ -6,7 +6,7 @@
  */
 
 import { internalSymbol, instanceSymbol } from "../../../constants.mjs";
-import { isObject,isFunction } from "../../../types/is.mjs";
+import { isObject, isFunction } from "../../../types/is.mjs";
 import { Server } from "../server.mjs";
 import { WriteError } from "./restapi/writeerror.mjs";
 
@@ -127,11 +127,12 @@ class RestAPI extends Server {
         if (!init["method"]) init["method"] = "GET";
 
         let callback = self.getOption("read.responseCallback");
-        if(!callback) callback = (obj) => {
-            self.set(self.transformServerPayload.call(self, obj));
-        };
-        
-        return fetchData.call(this, init,"read", callback);
+        if (!callback)
+            callback = (obj) => {
+                self.set(self.transformServerPayload.call(self, obj));
+            };
+
+        return fetchData.call(this, init, "read", callback);
     }
 
     /**
@@ -199,7 +200,6 @@ function fetchData(init, key, callback) {
                 obj = JSON.parse(body);
 
                 response[rawDataSymbol] = obj;
-                
             } catch (e) {
                 if (body.length > 100) {
                     body = `${body.substring(0, 97)}...`;
@@ -211,7 +211,7 @@ function fetchData(init, key, callback) {
             if (callback && isFunction(callback)) {
                 callback(obj);
             }
-            
+
             return response;
         });
 }

package/source/data/transformer.mjs

@@ -5,12 +5,12 @@
  * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html
  */
 
-import {getLocaleOfDocument} from "../dom/locale.mjs";
-import {Base} from "../types/base.mjs";
-import {getGlobal, getGlobalObject} from "../types/global.mjs";
-import {ID} from "../types/id.mjs";
-import {isArray, isObject, isString, isPrimitive} from "../types/is.mjs";
-import {getDocumentTranslations, Translations} from "../i18n/translations.mjs";
+import { getLocaleOfDocument } from "../dom/locale.mjs";
+import { Base } from "../types/base.mjs";
+import { getGlobal, getGlobalObject } from "../types/global.mjs";
+import { ID } from "../types/id.mjs";
+import { isArray, isObject, isString, isPrimitive } from "../types/is.mjs";
+import { getDocumentTranslations, Translations } from "../i18n/translations.mjs";
 import {
     validateFunction,
     validateInteger,
@@ -19,10 +19,10 @@ import {
     validateString,
     validateBoolean,
 } from "../types/validate.mjs";
-import {clone} from "../util/clone.mjs";
-import {Pathfinder} from "./pathfinder.mjs";
+import { clone } from "../util/clone.mjs";
+import { Pathfinder } from "./pathfinder.mjs";
 
-export {Transformer};
+export { Transformer };
 
 /**
  * The transformer class is a swiss army knife for manipulating values. especially in combination with the pipe, processing chains can be built up.
@@ -576,7 +576,6 @@ function transform(value) {
 
             throw new Error("type not supported");
 
-
         case "map":
             map = new Map();
             while (args.length > 0) {
@@ -592,7 +591,6 @@ function transform(value) {
             return map.get(value);
 
         case "equals":
-
             if (args.length === 0) {
                 throw new Error("missing value parameter");
             }
@@ -631,11 +629,10 @@ function transform(value) {
 
         case "money":
         case "currency":
-
             try {
                 locale = getLocaleOfDocument();
             } catch (e) {
-                throw new Error("unsupported locale or missing format (" + e.message + ")");
+                throw new Error(`unsupported locale or missing format (${e.message})`);
             }
 
             const currency = value.substring(0, 3);
@@ -672,9 +669,8 @@ function transform(value) {
             try {
                 locale = getLocaleOfDocument();
                 return date.toLocaleTimeString(locale);
-
             } catch (e) {
-                throw new Error("unsupported locale or missing format (" + e.message + ")");
+                throw new Error(`unsupported locale or missing format (${e.message})`);
             }
 
         case "datetime":
@@ -686,9 +682,8 @@ function transform(value) {
             try {
                 locale = getLocaleOfDocument();
                 return date.toLocaleString(locale);
-
             } catch (e) {
-                throw new Error("unsupported locale or missing format (" + e.message + ")");
+                throw new Error(`unsupported locale or missing format (${e.message})`);
             }
 
         case "date":
@@ -700,12 +695,10 @@ function transform(value) {
             try {
                 locale = getLocaleOfDocument();
                 return date.toLocaleDateString(locale);
-
             } catch (e) {
-                throw new Error("unsupported locale or missing format (" + e.message + ")");
+                throw new Error(`unsupported locale or missing format (${e.message})`);
             }
 
-
         case "year":
             date = new Date(value);
             if (isNaN(date.getTime())) {

package/source/dom/customelement.mjs

@@ -5,19 +5,19 @@
  * License text available at https://www.gnu.org/licenses/agpl-3.0.en.html
  */
 
-import {internalSymbol} from "../constants.mjs";
-import {extend} from "../data/extend.mjs";
-import {Pathfinder} from "../data/pathfinder.mjs";
-import {Formatter} from "../text/formatter.mjs";
-
-import {parseDataURL} from "../types/dataurl.mjs";
-import {getGlobalObject} from "../types/global.mjs";
-import {isArray, isFunction, isIterable, isObject, isString} from "../types/is.mjs";
-import {Observer} from "../types/observer.mjs";
-import {ProxyObserver} from "../types/proxyobserver.mjs";
-import {validateFunction, validateInstance, validateObject, validateString} from "../types/validate.mjs";
-import {clone} from "../util/clone.mjs";
-import {addAttributeToken, getLinkedObjects, hasObjectLink} from "./attributes.mjs";
+import { internalSymbol } from "../constants.mjs";
+import { extend } from "../data/extend.mjs";
+import { Pathfinder } from "../data/pathfinder.mjs";
+import { Formatter } from "../text/formatter.mjs";
+
+import { parseDataURL } from "../types/dataurl.mjs";
+import { getGlobalObject } from "../types/global.mjs";
+import { isArray, isFunction, isIterable, isObject, isString } from "../types/is.mjs";
+import { Observer } from "../types/observer.mjs";
+import { ProxyObserver } from "../types/proxyobserver.mjs";
+import { validateFunction, validateInstance, validateObject, validateString } from "../types/validate.mjs";
+import { clone } from "../util/clone.mjs";
+import { addAttributeToken, getLinkedObjects, hasObjectLink } from "./attributes.mjs";
 import {
     ATTRIBUTE_DISABLED,
     ATTRIBUTE_ERRORMESSAGE,
@@ -25,11 +25,11 @@ import {
     ATTRIBUTE_OPTIONS_SELECTOR,
     customElementUpdaterLinkSymbol,
 } from "./constants.mjs";
-import {findDocumentTemplate, Template} from "./template.mjs";
-import {addObjectWithUpdaterToElement} from "./updater.mjs";
-import {instanceSymbol} from "../constants.mjs";
-import {getDocumentTranslations, Translations} from "../i18n/translations.mjs";
-import {getSlottedElements} from "./slotted.mjs";
+import { findDocumentTemplate, Template } from "./template.mjs";
+import { addObjectWithUpdaterToElement } from "./updater.mjs";
+import { instanceSymbol } from "../constants.mjs";
+import { getDocumentTranslations, Translations } from "../i18n/translations.mjs";
+import { getSlottedElements } from "./slotted.mjs";
 
 export {
     CustomElement,
@@ -286,7 +286,6 @@ class CustomElement extends HTMLElement {
         };
     }
 
-
     /**
      * This method updates the labels of the element.
      * The labels are defined in the options object.
@@ -315,26 +314,25 @@ class CustomElement extends HTMLElement {
             if (isString(def)) {
                 const text = translations.getText(key, def);
                 if (text !== def) {
-                    this.setOption("labels." + key, text);
+                    this.setOption(`labels.${key}`, text);
                 }
                 continue;
             } else if (isObject(def)) {
                 for (const k in def) {
                     const d = def[k];
-                    
+
                     const text = translations.getPluralRuleText(key, k, d);
                     if (!isString(text)) {
                         throw new Error("Invalid labels definition");
                     }
                     if (text !== d) {
-                        this.setOption("labels." + key + "." + k, text);
+                        this.setOption(`labels.${key}.${k}`, text);
                     }
                 }
                 continue;
             }
 
             throw new Error("Invalid labels definition");
-
         }
         return this;
     }
@@ -352,7 +350,6 @@ class CustomElement extends HTMLElement {
         throw new Error("the method getTag must be overwritten by the derived class.");
     }
 
-
     /**
      * At this point a `CSSStyleSheet` object can be returned. If the environment does not
      * support a constructor, then an object can also be built using the following detour.
@@ -422,8 +419,7 @@ class CustomElement extends HTMLElement {
 
         try {
             value = new Pathfinder(this[internalSymbol].getRealSubject()["options"]).getVia(path);
-        } catch (e) {
-        }
+        } catch (e) {}
 
         if (value === undefined) return defaultValue;
         return value;
@@ -493,8 +489,7 @@ class CustomElement extends HTMLElement {
             try {
                 initShadowRoot.call(self);
                 elements = self.shadowRoot.childNodes;
-            } catch (e) {
-            }
+            } catch (e) {}
 
             try {
                 initCSSStylesheet.call(this);
@@ -545,8 +540,7 @@ class CustomElement extends HTMLElement {
      * @return {void}
      * @since 1.7.0
      */
-    disconnectedCallback() {
-    }
+    disconnectedCallback() {}
 
     /**
      * The custom element has been moved into a new document (e.g. someone called document.adoptNode(el)).
@@ -554,8 +548,7 @@ class CustomElement extends HTMLElement {
      * @return {void}
      * @since 1.7.0
      */
-    adoptedCallback() {
-    }
+    adoptedCallback() {}
 
     /**
      * Called when an observed attribute has been added, removed, updated, or replaced. Also called for initial
@@ -792,8 +785,7 @@ function parseOptionsJSON(data) {
     try {
         let dataUrl = parseDataURL(data);
         data = dataUrl.content;
-    } catch (e) {
-    }
+    } catch (e) {}
 
     try {
         obj = JSON.parse(data);
@@ -815,7 +807,6 @@ function initHtmlContent() {
     } catch (e) {
         let html = this.getOption("templates.main", "");
         if (isString(html) && html.length > 0) {
-
             const mapping = this.getOption("templateMapping", {});
             if (isObject(mapping)) {
                 html = new Formatter(mapping).format(html);
@@ -938,7 +929,7 @@ function initShadowRoot() {
  */
 function registerCustomElement(element) {
     validateFunction(element);
-    const customElements = getGlobalObject("customElements")
+    const customElements = getGlobalObject("customElements");
     if (customElements === undefined) {
         throw new Error("customElements is not supported.");
     }