@schukai/monster 1.23.0 → 1.26.1

package/source/i18n/formatter.js

@@ -0,0 +1,140 @@
+'use strict';
+
+/**
+ * @author schukai GmbH
+ */
+
+
+import {internalSymbol} from "../constants.js";
+import {extend} from "../data/extend.js";
+import {assignToNamespace, Monster} from '../namespace.js';
+import {Formatter as TextFormatter} from "../text/formatter.js";
+import {validateInstance, validateString} from "../types/validate.js";
+import {Translations} from "./translations.js";
+
+/**
+ * @private
+ * @type {symbol}
+ */
+const internalTranslationSymbol = Symbol('internalTranslation')
+
+/**
+ * The Formatter extends the Text.Formatter with the possibility to replace the key by a translation.
+ *
+ * You can create an instance via the monster namespace `new Monster.I18n.Formatter()`.
+ *
+ * ```
+ * <script type="module">
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
+ * new Monster.I18n.Formatter()
+ * </script>
+ * ```
+ *
+ * Alternatively, you can also integrate this function individually.
+ *
+ * ```
+ * <script type="module">
+ * import {Formatter} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/formatter.js';
+ * new Formatter()
+ * </script>
+ * ```
+ *
+ * @example
+ *
+ * import {Formatter} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/formatter.js';
+ * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/translations.js';
+ *
+ * const translations = new Translations('en')
+ *     .assignTranslations({
+ *         thekey: "${animal} has eaten the ${food}!"
+ *     });
+ *
+ * new Formatter({}, translations).format("thekey:animal=dog::food=cake")
+ * // ↦ dog has eaten the cake!
+ *
+ * @since 1.26.0
+ * @copyright schukai GmbH
+ * @memberOf Monster.I18n
+ */
+class Formatter extends TextFormatter {
+
+    /**
+     * Default values for the markers are `${` and `}`
+     *
+     * @param {object} object
+     * @throws {TypeError} value is not a object
+     */
+    constructor(object, translation, options) {
+        super(object, options);
+        this[internalTranslationSymbol] = validateInstance(translation, Translations);
+    }
+
+    /**
+     * @property {object} marker
+     * @property {array} marker.open=["i18n{","${"]
+     * @property {array} marker.close=["${"]
+     * @property {object} parameter
+     * @property {string} parameter.delimiter="::"
+     * @property {string} parameter.assignment="="
+     * @property {object} callbacks
+     * @property {function} callbacks.i18n=()=>{}
+     */
+    get defaults() {
+        const self = this;
+        return extend({}, super.defaults, {
+            callbacks: {
+                i18n: (value) => {
+                    return self[internalTranslationSymbol].getText(validateString(value));
+                }
+            },
+            marker: {
+                open: ['i18n{', '${'],
+                close: ['}'],
+            },
+        })
+    }
+
+    /**
+     *
+     * @param {string} text
+     * @return {string}
+     * @throws {TypeError} value is not a string
+     * @throws {Error} too deep nesting
+     * @throws {Error} key not found
+     * @throws {Error} the closing marker is missing
+     */
+    format(text) {
+        validateString(text)
+
+        const openMarker = this[internalSymbol]['marker']['open']?.[0];
+        const closeMarker = this[internalSymbol]['marker']['close']?.[0];
+
+        if (text.indexOf(openMarker) === 0) {
+            text = text.substring(openMarker.length);
+
+            if (text.indexOf(closeMarker) === text.length - closeMarker.length) {
+                text = text.substring(0, text.length - closeMarker.length);
+            } else {
+                throw new Error("the closing marker is missing")
+            }
+        }
+
+
+        const parts = validateString(text).split('::')
+        const translationKey = parts.shift().trim(); // key value delimiter
+        const parameter = parts.join('::').trim();
+
+
+        let assembledText = openMarker + 'static:' + translationKey + ' | call:i18n';
+        if (parameter.length > 0) {
+            assembledText += '::' + parameter;
+        }
+        assembledText += closeMarker;
+        return super.format(assembledText);
+    }
+
+
+}
+
+assignToNamespace('Monster.I18n', Formatter);
+export {Monster, Formatter}

package/source/i18n/locale.js

@@ -25,8 +25,8 @@ const localeStringSymbol = Symbol('localeString');
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/locale.js';
- * console.log(new Monster.I18n.Locale())
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
+ * new Monster.I18n.Locale()
  * </script>
  * ```
  *
@@ -34,8 +34,8 @@ const localeStringSymbol = Symbol('localeString');
  *
  * ```
  * <script type="module">
- * import {Locale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/locale.js';
- * console.log(new Locale())
+ * import {Locale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/locale.js';
+ * new Locale()
  * </script>
  * ```
  *
@@ -172,6 +172,8 @@ class Locale extends Base {
     }
 
     /**
+     * The structure has the following: language, script, region, variants, extlang, privateUse
+     *
      * @return {Monster.I18n.LocaleMap}
      */
     getMap() {
@@ -201,8 +203,8 @@ class Locale extends Base {
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/locale.js';
- * console.log(new Monster.I18n.createLocale())
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
+ * new Monster.I18n.createLocale()
  * </script>
  * ```
  *
@@ -210,8 +212,8 @@ class Locale extends Base {
  *
  * ```
  * <script type="module">
- * import {createLocale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/locale.js';
- * console.log(createLocale())
+ * import {createLocale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/locale.js';
+ * createLocale()
  * </script>
  * ```
  *

package/source/i18n/provider.js

@@ -15,8 +15,8 @@ import {Translations} from "./translations.js"
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/provider.js';
- * console.log(new Monster.I18n.Provider())
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
+ * new Monster.I18n.Provider()
  * </script>
  * ```
  *
@@ -24,8 +24,8 @@ import {Translations} from "./translations.js"
  *
  * ```
  * <script type="module">
- * import {Provider} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/provider.js';
- * console.log(new Provider())
+ * import {Provider} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/provider.js';
+ * new Provider()
  * </script>
  * ```
  *

package/source/i18n/providers/fetch.js

@@ -1,10 +1,11 @@
 'use strict';
 
-import {PROPERTY_KEY_INTERNALDATA} from "../../constants.js";
-import {extend} from "../../data/extend.js";
 /**
  * @author schukai GmbH
  */
+
+import {internalSymbol} from "../../constants.js";
+import {extend} from "../../data/extend.js";
 import {assignToNamespace, Monster} from '../../namespace.js';
 import {Formatter} from "../../text/formatter.js";
 import {getGlobalFunction} from "../../types/global.js";
@@ -14,12 +15,6 @@ import {parseLocale} from "../locale.js";
 import {Provider} from "../provider.js";
 import {Translations} from "../translations.js";
 
-/**
- * @private
- * @type {symbol}
- */
-const optionsSymbol = Symbol.for(PROPERTY_KEY_INTERNALDATA);
-
 /**
  * The fetch provider retrieves a JSON file from the given URL and returns a translation object.
  *
@@ -27,8 +22,8 @@ const optionsSymbol = Symbol.for(PROPERTY_KEY_INTERNALDATA);
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/providers/fetch.js';
- * console.log(new Monster.I18n.Providers.Fetch())
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
+ * new Monster.I18n.Providers.Fetch()
  * </script>
  * ```
  *
@@ -36,21 +31,36 @@ const optionsSymbol = Symbol.for(PROPERTY_KEY_INTERNALDATA);
  *
  * ```
  * <script type="module">
- * import {Fetch} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/providers/fetch.js';
- * console.log(new Fetch())
+ * import {Fetch} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/providers/fetch.js';
+ * new Fetch()
  * </script>
  * ```
+ * 
+ * @example <caption>das ist ein test</caption>
+ * 
+ * import {Fetch} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/providers/fetch.js';
+ * 
+ * // fetch from API
+ * const translation = new Fetch('https://example.com/${language}.json').getTranslation('en-GB');
+ * // ↦ https://example.com/en.json
  *
  * @since 1.13.0
  * @copyright schukai GmbH
  * @memberOf Monster.I18n.Providers
  * @see {@link https://datatracker.ietf.org/doc/html/rfc3066}
+ * @tutorial i18n-locale-and-formatter
  */
 class Fetch extends Provider {
 
     /**
      * As options the key `fetch` can be passed. This config object is passed to the fetch method as init.
-     *
+     * 
+     * The url may contain placeholders (language, script, region, variants, extlang, privateUse), so you can specify one url for all translations.
+     * 
+     * ```
+     * new Fetch('https://www.example.com/assets/${language}.json')
+     * ```
+     * 
      * @param {string|URL} url
      * @param {Object} options see {@link Monster.I18n.Providers.Fetch#defaults}
      * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/fetch}
@@ -77,7 +87,7 @@ class Fetch extends Provider {
          * @private
          * @property {Object} options
          */
-        this[optionsSymbol] = extend({}, super.defaults, this.defaults, validateObject(options));
+        this[internalSymbol] = extend({}, super.defaults, this.defaults, validateObject(options));
 
     }
 

package/source/i18n/translations.js

@@ -17,8 +17,8 @@ import {Locale, parseLocale} from "./locale.js";
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/translations.js';
- * console.log(new Monster.I18n.Translations())
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
+ * new Monster.I18n.Translations()
  * </script>
  * ```
  *
@@ -26,22 +26,33 @@ import {Locale, parseLocale} from "./locale.js";
  *
  * ```
  * <script type="module">
- * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/i18n/translations.js';
- * console.log(new Translations())
+ * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/translations.js';
+ * new Translations()
  * </script>
  * ```
  *
  * @example
  *
+ * import {Translations} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/translations.js';
+ * import {parseLocale} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/i18n/locale.js';
+ *
  * const translation = new Translations(parseLocale('en-GB'));
  *
  * translation.assignTranslations({
- *            text1: "abc",
- *            text2: {'other': 'xyz'}
- *         });
+ *           text1: "click",
+ *           text2: {
+ *             'one': 'click once',
+ *             'other': 'click n times'
+ *           }
+ *        });
+ *
+ * console.log(translation.getText('text1'));
+ * // ↦ click
  *
- * translation.getText('text1);
- * translation.getPluralRuleText('text1',2);
+ * console.log(translation.getPluralRuleText('text2',1));
+ * // -> click once
+ * console.log(translation.getPluralRuleText('text2',2));
+ * // -> click n times
  *
  * @since 1.13.0
  * @copyright schukai GmbH
@@ -204,6 +215,5 @@ class Translations extends Base {
 
 }
 
-
 assignToNamespace('Monster.I18n', Translations);
 export {Monster, Translations}

package/source/logging/handler/console.js

@@ -15,7 +15,7 @@ import {LogEntry} from "../logentry.js";
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/logging/handler/console.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
  * console.log(new Monster.Logging.Handler.ConsoleHandler())
  * </script>
  * ```
@@ -24,7 +24,7 @@ import {LogEntry} from "../logentry.js";
  *
  * ```
  * <script type="module">
- * import {ConsoleHandler} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/logging/handler/console.js';
+ * import {ConsoleHandler} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/logging/handler/console.js';
  * console.log(new ConsoleHandler())
  * </script>
  * ```

package/source/logging/handler.js

@@ -15,7 +15,7 @@ import {ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN} from "./logger.js";
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/logging/handler.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
  * console.log(new Monster.Logging.Handler())
  * </script>
  * ```
@@ -24,7 +24,7 @@ import {ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN} from "./logger.js";
  *
  * ```
  * <script type="module">
- * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/logging/handler.js';
+ * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/logging/handler.js';
  * console.log(new Handler())
  * </script>
  * ```

package/source/logging/logentry.js

@@ -14,7 +14,7 @@ import {validateInteger} from '../types/validate.js';
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/logging/logentry.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
  * console.log(new Monster.Logging.LogEntry())
  * </script>
  * ```
@@ -23,7 +23,7 @@ import {validateInteger} from '../types/validate.js';
  *
  * ```
  * <script type="module">
- * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/logging/logentry.js';
+ * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/logging/logentry.js';
  * console.log(new LogEntry())
  * </script>
  * ```

package/source/logging/logger.js

@@ -65,8 +65,8 @@ const OFF = 0;
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/logging/logger.js';
- * console.log(new Monster.Logging.Logger())
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
+ * new Monster.Logging.Logger()
  * </script>
  * ```
  *
@@ -74,8 +74,8 @@ const OFF = 0;
  *
  * ```
  * <script type="module">
- * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/logging/logger.js';
- * console.log(new Logger())
+ * import {ID} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/logging/logger.js';
+ * new Logger()
  * </script>
  * ```
  *

package/source/math/random.js

@@ -15,8 +15,9 @@ import {getGlobal} from '../types/global.js';
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/math/random.js';
- * console.log(Monster.Math.random(1,10)) // ↦ 5
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
+ * Monster.Math.random(1,10)
+ * // ↦ 5
  * </script>
  * ```
  *
@@ -24,8 +25,9 @@ import {getGlobal} from '../types/global.js';
  *
  * ```
  * <script type="module">
- * import {random} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/math/random.js';
- * console.log(random(1,10)) // ↦ 5
+ * import {random} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/modules/math/random.js';
+ * random(1,10)
+ * // ↦ 5
  * </script>
  * ```
  *
@@ -116,7 +118,11 @@ function create(min, max) {
         return create(min, max);
     }
 
-    return min + rval;
+    if (rval < min) {
+        rval += min;
+    }
+    
+    return rval;
 
 }
 

package/source/namespace.js

@@ -65,7 +65,7 @@ export const Monster = new Namespace("Monster");
  *
  * ```
  * <script type="module">
- * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.23.0/dist/modules/namespace.js';
+ * import {Monster} from 'https://cdn.jsdelivr.net/npm/@schukai/monster@1.26.1/dist/monster.js';
  * function hello() {
  *            console.log('Hello World!');
  *        }