tiny-essentials 1.25.4 → 1.25.6

package/dist/v1/libs/TinyMamdaniInferenceSystem.mjs

@@ -0,0 +1,248 @@
+/**
+ * Internal helper to validate an array of FuzzySets.
+ * @param {FuzzySet[]} sets
+ */
+const validateFuzzySets = (sets) => {
+    if (!Array.isArray(sets)) {
+        throw new TypeError("Parameter 'sets' must be an array.");
+    }
+    if (!sets.every((set) => set instanceof FuzzySet)) {
+        throw new TypeError('All elements in the array must be instances of FuzzySet.');
+    }
+};
+/**
+ * Performs defuzzification using the Centroid (Center of Gravity) method.
+ * @param {Object.<string, number>} fuzzyOutput - Results from rule evaluation.
+ * @param {FuzzySet[]} outputSets - The sets defining the output range.
+ * @param {number} [step=0.5] - Resolution of the integral approximation.
+ * @returns {number} The crisp output value.
+ */
+export const defuzzifyCentroid = (fuzzyOutput, outputSets, step = 0.5) => {
+    validateType(fuzzyOutput, 'object', 'defuzzifyCentroid.fuzzyOutput');
+    for (const outputName in fuzzyOutput) {
+        validateType(fuzzyOutput[outputName], 'number', `fuzzyOutput['${outputName}']`);
+    }
+    validateFuzzySets(outputSets);
+    validateType(step, 'number', 'defuzzifyCentroid.step');
+    /** @type {number} - Accumulated weighted area for centroid */
+    let totalAreaWeighted = 0;
+    /** @type {number} - Accumulated total area */
+    let totalArea = 0;
+    // Numerical integration (Centroid approximation)
+    for (let i = 0; i <= 100; i += step) {
+        /** @type {number} - Maximum membership found at point x(i) */
+        let maxMembershipAtX = 0;
+        outputSets.forEach((set) => {
+            /** @type {number} - Rule strength applied to the output set */
+            const strength = fuzzyOutput[set.name] || 0;
+            /** @type {number} - Cut or scale the output set membership */
+            const membership = Math.min(strength, set.calculate(i));
+            maxMembershipAtX = Math.max(maxMembershipAtX, membership);
+        });
+        totalAreaWeighted += i * maxMembershipAtX;
+        totalArea += maxMembershipAtX;
+    }
+    return totalArea === 0 ? 0 : totalAreaWeighted / totalArea;
+};
+/**
+ * Utility to calculate fuzzy membership using a trapezoidal shape safely.
+ * @param {number} value - The input value to check.
+ * @param {number} a - Start of the rise.
+ * @param {number} b - End of the rise (start of plateau).
+ * @param {number} c - Start of the fall (end of plateau).
+ * @param {number} d - End of the fall.
+ * @param {boolean} [optimize=false] - Optimizes performance by skipping math for absolute bounds.
+ * @returns {number} Degree of membership [0, 1].
+ */
+export const trapezoid = (value, a, b, c, d, optimize = false) => {
+    if (optimize) {
+        // If the value is completely outside the outer bounds, return 0 immediately
+        if (value <= a || value >= d)
+            return 0;
+        // If the value is entirely within the plateau, return 1 immediately
+        if (value >= b && value <= c)
+            return 1;
+    }
+    /** @type {number} - Safely calculate rising slope */
+    const rise = a === b ? 1 : (value - a) / (b - a);
+    /** @type {number} - Safely calculate falling slope */
+    const fall = c === d ? 1 : (d - value) / (d - c);
+    /** @type {number} - Internal value clamping between 0 and 1 */
+    const membership = Math.max(0, Math.min(rise, 1, fall));
+    return isNaN(membership) ? 0 : membership;
+};
+/**
+ * Utility to validate types and throw formatted errors, preventing code repetition.
+ * @param {any} value - The value to evaluate.
+ * @param {string} expectedType - The expected data type.
+ * @param {string} paramName - The name of the parameter for the error message.
+ */
+const validateType = (value, expectedType, paramName) => {
+    if (typeof value !== expectedType) {
+        throw new TypeError(`Parameter '${paramName}' must be a ${expectedType}.`);
+    }
+};
+/**
+ * Represents a single Membership Function (Trapezoidal).
+ */
+class FuzzySet {
+    /**
+     * Utility to calculate fuzzy membership using a trapezoidal shape.
+     * @param {number} value - The input value to check.
+     * @param {number} a - Start of the rise.
+     * @param {number} b - End of the rise (start of plateau).
+     * @param {number} c - Start of the fall (end of plateau).
+     * @param {number} d - End of the fall.
+     * @param {boolean} [optimize=false] - Performance optimization flag.
+     * @returns {number} Degree of membership [0, 1].
+     */
+    static trapezoid(value, a, b, c, d, optimize = false) {
+        return trapezoid(value, a, b, c, d, optimize);
+    }
+    /** @type {string} - Internal name of the fuzzy set */
+    #name = '';
+    /** @type {number} - Internal left foot coordinate */
+    #a = 0;
+    /** @type {number} - Internal left shoulder coordinate */
+    #b = 0;
+    /** @type {number} - Internal right shoulder coordinate */
+    #c = 0;
+    /** @type {number} - Internal right foot coordinate */
+    #d = 0;
+    /** @type {boolean} - Internal flag to enable calculation optimization */
+    #optimize = false;
+    get name() {
+        return this.#name;
+    }
+    set name(value) {
+        validateType(value, 'string', 'FuzzySet.name');
+        this.#name = value;
+    }
+    get a() {
+        return this.#a;
+    }
+    set a(value) {
+        validateType(value, 'number', 'FuzzySet.a');
+        this.#a = value;
+    }
+    get b() {
+        return this.#b;
+    }
+    set b(value) {
+        validateType(value, 'number', 'FuzzySet.b');
+        this.#b = value;
+    }
+    get c() {
+        return this.#c;
+    }
+    set c(value) {
+        validateType(value, 'number', 'FuzzySet.c');
+        this.#c = value;
+    }
+    get d() {
+        return this.#d;
+    }
+    set d(value) {
+        validateType(value, 'number', 'FuzzySet.d');
+        this.#d = value;
+    }
+    get optimize() {
+        return this.#optimize;
+    }
+    set optimize(value) {
+        validateType(value, 'boolean', 'FuzzySet.optimize');
+        this.#optimize = value;
+    }
+    /**
+     * @param {string} name - Name of the set (e.g., "Hot").
+     * @param {number} a - Left foot.
+     * @param {number} b - Left shoulder.
+     * @param {number} c - Right shoulder.
+     * @param {number} d - Right feet.
+     * @param {boolean} [optimize=false] - Enables performance optimization.
+     */
+    constructor(name, a, b, c, d, optimize = false) {
+        this.name = name;
+        this.a = a;
+        this.b = b;
+        this.c = c;
+        this.d = d;
+        this.optimize = optimize;
+    }
+    /**
+     * Calculates the membership degree.
+     * @param {number} x - Crisp input.
+     * @returns {number}
+     */
+    calculate(x) {
+        validateType(x, 'number', 'calculate.x');
+        return FuzzySet.trapezoid(x, this.#a, this.#b, this.#c, this.#d, this.#optimize);
+    }
+}
+/**
+ * The Inference Engine handles linguistic variables and defuzzification.
+ */
+class MamdaniInferenceSystem {
+    /** @type {Map<string, FuzzySet[]>} - Storage for linguistic variables */
+    #variables = new Map();
+    /**
+     * Registers a linguistic variable and its sets.
+     * @param {string} name - Variable name (e.g., "temperature").
+     * @param {FuzzySet[]} sets - Array of fuzzy sets.
+     */
+    addVariable(name, sets) {
+        validateType(name, 'string', 'addVariable.name');
+        validateFuzzySets(sets);
+        this.#variables.set(name, sets);
+    }
+    /**
+     * Removes a linguistic variable.
+     * @param {string} name - Variable name (e.g., "temperature").
+     * @returns {boolean} True if the element was successfully removed.
+     */
+    removeVariable(name) {
+        validateType(name, 'string', 'removeVariable.name');
+        return this.#variables.delete(name);
+    }
+    /**
+     * Gets a linguistic variable and its sets.
+     * @param {string} name - Variable name (e.g., "temperature").
+     * @returns {FuzzySet[]}
+     */
+    getVariable(name) {
+        validateType(name, 'string', 'getVariable.name');
+        /** @type {FuzzySet[] | undefined} - Attempted fetch from map */
+        const result = this.#variables.get(name);
+        if (!result)
+            throw new Error(`Linguistic variable '${name}' not found in the inference system.`);
+        return [...result];
+    }
+    /**
+     * Checks if a linguistic variable exists.
+     * @param {string} name - Variable name (e.g., "temperature").
+     * @returns {boolean}
+     */
+    hasVariable(name) {
+        validateType(name, 'string', 'hasVariable.name');
+        return this.#variables.has(name);
+    }
+    /**
+     * Fuzzifies a crisp input into a map of memberships.
+     * @param {string} varName
+     * @param {number} value
+     * @returns {Object.<string, number>}
+     */
+    fuzzify(varName, value) {
+        validateType(varName, 'string', 'fuzzify.varName');
+        validateType(value, 'number', 'fuzzify.value');
+        /** @type {FuzzySet[]} - The sets associated with the variable */
+        const sets = this.#variables.get(varName) || [];
+        /** @type {Object.<string, number>} - The fuzzified results dictionary */
+        const results = {};
+        sets.forEach((set) => {
+            results[set.name] = set.calculate(value);
+        });
+        return results;
+    }
+}
+export { FuzzySet, MamdaniInferenceSystem };

package/docs/v1/README.md

@@ -63,6 +63,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 * 📝 **[TinyTextDiffer](./libs/TinyTextDiffer.md)** — A granular text comparison utility using the LCS algorithm to detect additions, deletions, and unchanged segments between multiple history versions, returning a clean, parseable diff structure.
 * 🕒 **[TinyAnalogClock](./libs/TinyAnalogClock.md)** — A lightweight analog clock engine for managing time-based rotations, supporting custom offsets, smooth transitions, and easy binding to CSS variables rendering.
 * 🔍 **[TinyArrayComparator](./libs/TinyArrayComparator.md)** — A lightweight, highly optimized JavaScript utility class designed to compare two arrays and efficiently detect which items were **added** or **deleted**.
+* 🧠 **[TinyMamdaniInferenceSystem](./libs/TinyMamdaniInferenceSystem.md)** — A implementation of a Mamdani Inference System, allowing you to model logic using trapezoidal membership functions.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.

package/docs/v1/libs/TinyMamdaniInferenceSystem.md

@@ -0,0 +1,105 @@
+# 🧠 Fuzzy Logic Engine Documentation
+
+Welcome to the official documentation for the **Fuzzy Logic Engine**! 🚀 This robust, type-safe JavaScript module provides a implementation of a Mamdani Inference System, allowing you to model logic using trapezoidal membership functions.
+
+---
+
+## 🛠️ Core Utilities
+
+### 📐 `trapezoid(value, a, b, c, d, optimize = false)`
+A high-performance utility to safely calculate the fuzzy membership degree using a trapezoidal shape. It includes built-in protections against division by zero and short-circuit optimizations.
+
+**Parameters:**
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `value` | `number` | The crisp input value to check. |
+| `a` | `number` | Start of the rise (membership = 0). |
+| `b` | `number` | End of the rise / start of plateau (membership = 1). |
+| `c` | `number` | Start of the fall / end of plateau (membership = 1). |
+| `d` | `number` | End of the fall (membership = 0). |
+| `optimize` | `boolean`, optional | Enables performance optimization by skipping math for absolute bounds. Default is `false`. |
+
+**Returns:** * `number` - The degree of membership, safely clamped between `[0, 1]`.
+
+---
+
+### 🎯 `defuzzifyCentroid(fuzzyOutput, outputSets, step = 0.5)`
+Performs defuzzification using the highly accurate Centroid (Center of Gravity) numerical integration method.
+
+* **Parameters:**
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `fuzzyOutput` | `Object.<string, number>` | The evaluated rule strengths (e.g., `{"High": 0.8, "Medium": 0.2}`). |
+| `outputSets` | `FuzzySet[]` | The array of sets defining the output spectrum. |
+| `step` | `number`, optional | Resolution of the integral approximation. Default is `0.5`. |
+
+* **Returns:** `number` - The final, precise crisp output value.
+
+---
+
+## 🏗️ Classes
+
+### 🟦 `FuzzySet`
+Represents a single linguistic term (e.g., "Cold", "High", "Severe") defined by a trapezoidal membership function. It includes strict type validations for all its properties.
+
+#### ⚙️ Constructor
+```javascript
+new FuzzySet(name, a, b, c, d, optimize = false)
+```
+
+#### 📦 Properties
+* **`name`** (`string`): The name of the fuzzy set.
+* **`a`, `b`, `c`, `d`** (`number`): The coordinates defining the trapezoidal shape.
+* **`optimize`** (`boolean`): Internal flag to enable calculation optimization for absolute bounds.
+
+#### 🧮 Methods
+* **`calculate(x)`**
+  Calculates the membership degree for a specific input using the set's coordinates and optimization flag.
+  * **Parameters:** `x` (`number`) - The crisp input value.
+  * **Returns:** `number` - Degree of membership `[0, 1]`.
+
+* **`static trapezoid(value, a, b, c, d, optimize = false)`**
+  Static wrapper for the global `trapezoid` utility.
+
+---
+
+### 🧠 `MamdaniInferenceSystem`
+The core engine that handles the storage of linguistic variables, performs fuzzification, evaluates rules, and calculates the final crisp output via defuzzification.
+
+#### ⚙️ Constructor
+```javascript
+const engine = new MamdaniInferenceSystem();
+```
+
+#### 🧮 Variable Management Methods
+
+* **`addVariable(name, sets)`** ➕
+  Registers a new linguistic variable and its associated fuzzy sets.
+  * **Parameters:** * `name` (`string`) - The variable's name (e.g., "temperature").
+    * `sets` (`FuzzySet[]`) - An array of `FuzzySet` instances.
+
+* **`removeVariable(name)`** 🗑️
+  Deletes a linguistic variable from the engine.
+  * **Parameters:** `name` (`string`) - The variable's name.
+  * **Returns:** `boolean` - `true` if successfully removed.
+
+* **`getVariable(name)`** 🔍
+  Retrieves a cloned array of the fuzzy sets for a specific variable.
+  * **Parameters:** `name` (`string`) - The variable's name.
+  * **Returns:** `FuzzySet[]`
+  * **Throws:** `Error` if the variable is not found.
+
+* **`hasVariable(name)`** ❓
+  Checks if a variable is registered in the engine.
+  * **Parameters:** `name` (`string`) - The variable's name.
+  * **Returns:** `boolean`
+
+#### 🔬 Logic Processing Methods
+
+* **`fuzzify(varName, value)`** 🌫️
+  Converts a crisp numeric input into a dictionary of fuzzy membership degrees based on the variable's sets.
+  * **Parameters:**
+    * `varName` (`string`) - The variable to evaluate.
+    * `value` (`number`) - The crisp input value.
+  * **Returns:** `Object.<string, number>` - A map of set names to their membership degrees.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.25.4",
+  "version": "1.25.6",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",
@@ -264,6 +264,10 @@
       "require": "./dist/v1/libs/TinyAdvancedRaffle.cjs",
       "import": "./dist/v1/libs/TinyAdvancedRaffle.mjs"
     },
+    "./libs/TinyMamdaniInferenceSystem": {
+      "require": "./dist/v1/libs/TinyMamdaniInferenceSystem.cjs",
+      "import": "./dist/v1/libs/TinyMamdaniInferenceSystem.mjs"
+    },
     "./libs/TinyHtmlElems": {
       "require": "./dist/v1/libs/TinyHtml/index.cjs",
       "import": "./dist/v1/libs/TinyHtml/index.mjs"