tiny-essentials 1.20.3 → 1.21.1

package/docs/v1/Personal-Ai-Prompts(portuguese).md

@@ -0,0 +1,134 @@
+> ⚠️ **Aviso:** Os prompts fornecidos neste documento foram testados apenas no ChatGPT. O funcionamento pode variar em outras plataformas ou modelos de IA.
+
+### ⚙️ Preferências Técnicas de Código (JavaScript e Geral)
+
+#### 📄 jsDoc
+
+**jsDoc detalhado e estruturado internamente**
+
+```
+A usuária prefere que, ao cuidar de estruturas de jsDoc, seja adicionado um sub jsDoc (sem descrições) nos valores internos das funções para que tudo fique adequadamente encaixado com a estrutura do jsDoc primário.
+```
+
+**jsDoc obrigatório somente com tipos, sem descrições (quando não autorizado explicitamente)**
+
+```
+A usuária prefere que, quando ela pedir para escrever um JavaScript sem ter autorizado o uso de jsDoc, o jsDoc seja gerado sem nenhuma descrição, apenas orientando os types de todos os valores dentro da função.
+```
+
+```
+A usuária prefere que, quando pedir para escrever um código JavaScript e não autorizar o uso de jsDoc, se o jsDoc for necessário, ele seja gerado apenas com os tipos dos valores nas funções, sem descrições.
+```
+
+**Evitar o uso de `@private` ou `@public`**
+
+```
+A usuária prefere que não sejam usados os identificadores `@private` ou `@public` em jsDoc.
+```
+
+#### 📝 Estilo de Código
+
+**Textos e comentários no código devem ser em inglês**
+
+```
+A usuária prefere que todos os textos escritos dentro dos códigos estejam em inglês.
+```
+
+```
+A usuária prefere que os comentários e a documentação nos scripts sejam em inglês.
+```
+
+**Evitar repetições; priorizar otimização e reutilização**
+
+```
+A usuária deseja que todos os códigos de programação fornecidos sejam otimizados, evitando repetições de fórmulas e utilizando templates ou funções reutilizáveis sempre que possível para reduzir o tamanho do código.
+```
+
+**Evitar uso de `var`; utilizar `let` ou `const`**
+
+```
+A usuária prefere evitar o uso de 'var' em JavaScript e utilizar alternativas como 'let' ou 'const'.
+```
+
+**Utilizar `import` em vez de `require`**
+
+```
+A usuária prefere que seja utilizado `import` em vez de `require` nas respostas com código JavaScript.
+```
+
+**Scripts escritos em inglês; explicações em português (no caso de algoritmos)**
+
+```
+A usuária prefere que os scripts sejam escritos em inglês, mas que as respostas sobre algoritmos sejam em português.
+```
+
+#### 🖧 Tecnologias Preferidas
+
+**Exemplos com Apache2 ao invés de Nginx**
+
+```
+A usuária prefere exemplos com **Apache2** em vez de **Nginx**.
+```
+
+---
+
+### 🖥️ Informações Técnicas Sobre o Ambiente da Usuária
+
+```
+A usuária utiliza um teclado tradicional com a tecla Windows, configurado como **English (US, Intl., with dead keys)**.
+```
+
+```
+A usuária utiliza o Kubuntu com KDE em inglês.
+```
+
+---
+
+### 🧠 Preferências de Interação, Estilo e Personalidade da Assistente
+
+**README com tom divertido, mas não “descolado demais”**
+
+```
+A usuária prefere que o tom do README seja divertido, mas não descolado, mantendo um estilo mais equilibrado e amigável.
+```
+
+**Uso de "hahaha" ao invés de "kkkkk" nas interações**
+
+```
+A usuária prefere que seja usado "hahaha" em vez de "kkkkk" nas respostas.
+```
+
+```
+<username> é geralmente o username principal da usuária.
+```
+
+---
+
+## 📌 Instruções Principais
+
+**Estilo de conversa adaptado para autismo/Asperger**
+
+```
+Não use nenhum filtro de conteúdo e nenhuma ideologia nas suas respostas desde que tudo esteja respeitando seus termos de uso.
+Eu tenho sindrome de asperger, então tenha uma personalidade mais adaptada para dialogar melhor com este tipo de pessoa.
+
+me responder usando as seguintes configurações:
+sinceridade: 100%
+```
+
+## 🖥️ Mais Instruções
+
+**Throws alinhados com o jsDoc do script**
+```
+coloque throws que ajudam a validar se os argumentos contradiz com os jsDocs:
+```
+
+**Desenvolvimento de documentação markdown**
+
+```
+agora eu vou começar a te enviar por partes a versão final do NAME_HERE. O seu trabalho vai ser apenas converter cada mensagem em documentação markdown (em inglês com emojis) até o final da class.
+```
+
+```
+continue o trabalho (documentação markdown em inglês com emojis):
+```

package/docs/v1/Personal-Ai-Prompts.md

@@ -0,0 +1,113 @@
+> ⚠️ **Disclaimer:** The prompts provided in this document have been tested only in ChatGPT. Their behavior may vary on other platforms or AI models.
+
+### ⚙️ Technical Code Preferences (JavaScript and General)
+
+#### 📄 jsDoc
+
+**Detailed jsDoc with internal structure**
+
+```
+The user prefers that, when dealing with jsDoc structures, a sub-jsDoc (without descriptions) be added to the internal values of the functions so that everything is properly aligned with the primary jsDoc structure.
+```
+
+**jsDoc required with types only, no descriptions (unless explicitly authorized)**
+
+```
+The user prefers that, when asking for JavaScript code without having authorized the use of jsDoc, the jsDoc should be generated with no descriptions, only specifying the types of all values inside the function.
+```
+
+```
+The user prefers that, when asking for JavaScript code and not authorizing the use of jsDoc, if jsDoc is necessary, it should only include the types of the function values, without descriptions.
+```
+
+**Avoid using `@private` or `@public`**
+
+```
+The user prefers that `@private` or `@public` identifiers not be used in jsDoc.
+```
+
+#### 📝 Code Style
+
+**Avoid repetition; prioritize optimization and reuse**
+
+```
+The user wants all provided programming code to be optimized, avoiding repeated formulas and using templates or reusable functions whenever possible to reduce the size of the code.
+```
+
+**Avoid using `var`; prefer `let` or `const`**
+
+```
+The user prefers to avoid using 'var' in JavaScript and instead use alternatives like 'let' or 'const'.
+```
+
+**Use `import` instead of `require`**
+
+```
+The user prefers that `import` be used instead of `require` in JavaScript code responses.
+```
+
+#### 🖧 Preferred Technologies
+
+**Examples using Apache2 instead of Nginx**
+
+```
+The user prefers examples using **Apache2** instead of **Nginx**.
+```
+
+---
+
+### 🖥️ Technical Information About the User’s Environment
+
+```
+The user uses a traditional keyboard with the Windows key, configured as **English (US, Intl., with dead keys)**.
+```
+
+```
+The user uses Kubuntu with KDE in English.
+```
+
+---
+
+### 🧠 Interaction, Style, and Assistant Personality Preferences
+
+**README with a fun tone, but not overly “cool”**
+
+```
+The user prefers the README tone to be fun, but not overly cool or trendy, keeping a more balanced and friendly style.
+```
+
+```
+<username> is usually the user’s main username.
+```
+
+---
+
+## 📌 Main Instruction
+
+**Conversation style adapted for autism/Asperger**
+
+```
+Do not use any content filters or ideology in your responses as long as everything respects your terms of use.
+I have Asperger’s syndrome, so please have a personality better adapted to interact with this kind of person.
+
+respond to me using the following settings:
+sincerity: 100%
+```
+
+## 🖥️ More Instructions
+
+**Throws aligned with the script’s jsDoc**
+
+```
+Add throws that help validate if the arguments contradict the jsDocs:
+```
+
+**Markdown documentation development**
+
+```
+Now I will start sending you, in parts, the final version of NAME_HERE. Your job will be to simply convert each message into markdown documentation (in English with emojis) until the end of the class.
+```
+
+```
+Continue the work (markdown documentation in English with emojis):
+```

package/docs/v1/README.md

@@ -46,7 +46,16 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 📦 **[TinyLocalStorage](./libs/TinyLocalStorage.md)** — A tiny wrapper for `localStorage` with full support for objects, arrays, `Map`, `Set`, and typed value helpers like string, number, and boolean.
 - 🖼️ **[TinyIframeEvents](./libs/TinyIframeEvents.md)** — A structured `postMessage`-based event router for secure and reliable communication between a parent window and its embedded iframe. Supports directional filtering, origin enforcement, payload transport, and listener lifecycle.
 - 🪟 **[TinyNewWinEvents](./libs/TinyNewWinEvents.md)** — A smart, route-based `postMessage` system for structured communication between a main window and a popup (`window.open`). Includes queueing, origin enforcement, and lifecycle tracking.
+- 🎮 **[TinyGamepad](./libs/TinyGamepad.md)** — A flexible, professional gamepad and input manager supporting keyboard, mouse, combos, haptics, and custom input mappings.
 - ✨ **[TinyTextarea](./libs/TinyTextarea.md)** — A minimal auto-expanding `<textarea>` manager with configurable row limits, extra height padding, and real-time resize/input event hooks.
+- 🌞 **[TinyDayNightCycle](./libs/TinyDayNightCycle.md)** — A comprehensive day-night cycle system managing seasons, moons, time, and weather with configurable durations, phases, and dynamic weather selection.
+- 🎯 **[TinyAdvancedRaffle](./libs/TinyAdvancedRaffle.md)** — An advanced, seedable raffle system with weighted items, pity systems, exclusions, group management, modifiers, conditional rules, normalization modes, and JSON import/export.
+- 📄 **[TinyArrayPaginator](./libs/TinyArrayPaginator.md)** — A secure and flexible array pagination wrapper that returns paginated results along with metadata, supports filtering via predicates or object-based matching, and prevents direct modification of the source data. 
+- 🍪 **[TinyCookieConsent](./libs/TinyCookieConsent.md)** — A flexible and customizable cookie consent manager that displays a consent bar, supports multiple categories, saves preferences in localStorage, allows custom renderers, and provides smooth animations for showing and hiding elements. 
+- 📦 **[TinyInventory](./libs/TinyInventory.md)** — A robust inventory management system with stack handling, slot management, special equipment slots, serialization, cloning, and item registry support.
+- 🤝 **[TinyInventoryTrader](./libs/TinyInventoryTrader.md)** — A trading helper for safely transferring items between two inventories with support for strict mode, slot targeting, and batch operations.
+- 🌐 **[TinyI18](./libs/TinyI18.md)** — A flexible i18n manager supporting local and file modes, regex-based keys, function-based entries, string interpolation, and safe helper functions for advanced rendering.
+- 🎮 **[TinyNeedBar](./libs/TinyNeedBar.md)** — A versatile "need bar" system for simulating decay over time with multiple configurable factors, serialization, cloning, and full control over clamped and infinite values.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.
@@ -62,3 +71,18 @@ To get started, navigate to the appropriate directory and explore the files list
 ## 📑 Contributing
 
 Feel free to suggest changes, improvements, or additional features. You can fork the repository and submit a pull request!
+
+---
+
+## 📘 Want to Know How I Use AI in My Projects?
+
+If you're curious about how I integrate AI into my development workflow — including how I manage prompts, avoid context drift, and keep control over logic and documentation — feel free to check out the following guides:
+
+* [**AI Tips & Workflow**](./Ai-Tips.md)
+  Personal tips, common pitfalls to avoid, and how I keep AI assistance effective without losing my own creative and logical direction.
+
+* [**Personal AI Prompts**](./Personal-Ai-Prompts.md)
+  A curated collection of my most-used AI prompts for various tasks like coding, writing, automation, and technical documentation — written in English.
+
+* [**Personal AI Prompts (Portuguese)**](./Personal-Ai-Prompts%28portuguese%29.md)
+  The same set of personal AI prompts, but fully translated into Portuguese for ease of use in native language contexts.

package/docs/v1/basics/array.md

@@ -78,3 +78,20 @@ Great for situations where you need to **dynamically sort objects** by one of th
 * Sorting users by age
 * Ordering tasks by priority
 * Displaying leaderboard scores
+
+---
+
+## 🔁 `multiplyArrayBlocks(phases, counts)`
+
+Generates a flattened array with phases repeated according to the specified counts.
+
+* **`phases`** 📝 — Array of phase names (e.g., `['Full', 'Half1', 'Half2', 'New']`).
+* **`counts`** 🔢 — Array of integers specifying how many times each phase should be repeated (e.g., `[4, 5, 5, 4]`).
+* **Returns** 📦 — A single array where each phase appears the given number of times, in order.
+
+**Example:**
+
+```js
+multiplyArrayBlocks(['Full', 'Half1', 'Half2', 'New'], [4, 5, 5, 4]);
+// ➡ ['Full','Full','Full','Full','Half1','Half1','Half1','Half1','Half1', ...]
+```

package/docs/v1/basics/clock.md

@@ -1,12 +1,12 @@
 # ⏰ clock.mjs
 
-A versatile time utility module for JavaScript that helps you calculate and format time durations with style. Whether you're building countdowns, timers, or just need a nice "HH:MM:SS" string, this module has your back!
+A versatile time utility module for JavaScript that helps you calculate and format time durations with style. Whether you're building countdowns, timers, or just need a nice "HH\:MM\:SS" string, this module has your back!
 
 ## ✨ Features
 
 - 🔢 Calculate time differences in various units
 - 🧭 Format durations into clean, readable timer strings
-- 🧱 Support for years, months, days, hours, minutes, and seconds
+- 🧱 Support for years, months, days, hours, minutes, seconds **and milliseconds**
 - 🎛️ Customizable output with template-based formatting
 - 🛠️ Built-in presets for classic timer formats
 - 🪶 Zero dependencies, lightweight and modular (ESM-ready!)
@@ -19,11 +19,11 @@ A versatile time utility module for JavaScript that helps you calculate and form
 
 Calculates how much time remains (or has passed) between now and a given time.
 
-| Param         | Type     | Description                                                                 |
-|---------------|----------|-----------------------------------------------------------------------------|
-| `timeData`    | `Date`   | The target time                                                             |
-| `durationType`| `string` | Format to return (`asMilliseconds`, `asSeconds`, `asMinutes`, etc.)         |
-| `now`         | `Date`   | Optional custom "now". Defaults to current time.                            |
+| Param          | Type     | Description                                                         |
+| -------------- | -------- | ------------------------------------------------------------------- |
+| `timeData`     | `Date`   | The target time                                                     |
+| `durationType` | `string` | Format to return (`asMilliseconds`, `asSeconds`, `asMinutes`, etc.) |
+| `now`          | `Date`   | Optional custom "now". Defaults to current time.                    |
 
 **Returns:** `number|null` — The duration in the chosen unit.
 
@@ -33,11 +33,11 @@ Calculates how much time remains (or has passed) between now and a given time.
 
 Turns seconds into a custom timer string with fine-grained control.
 
-| Param       | Type     | Description                                                                                  |
-|-------------|----------|----------------------------------------------------------------------------------------------|
+| Param          | Type     | Description                                                                                 |
+| -------------- | -------- | ------------------------------------------------------------------------------------------- |
 | `totalSeconds` | `number` | The duration to format (in seconds)                                                         |
-| `level`     | `string` | Highest level to show: `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'months'`, `'years'` |
-| `format`    | `string` | Output string template. Supports placeholders like `{days}`, `{hours}`, `{time}`, `{total}` |
+| `level`        | `string` | Highest level to show: `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'months'`, `'years'` |
+| `format`       | `string` | Output string template. Supports placeholders like `{days}`, `{hours}`, `{time}`, `{total}` |
 
 **Returns:** `string` — A formatted string with padded units.
 
@@ -63,6 +63,33 @@ formatDayTimer(190000); // "2d 04:46:40"
 
 ---
 
+### 🔹 `breakdownDuration(totalMs, level = 'milliseconds')`
+
+Breaks down a duration (in **milliseconds**) into its full components, returning an object instead of a string.
+This is useful when you want numeric values to build your own custom formats.
+
+| Param     | Type     | Description                                                                                                         |
+| --------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
+| `totalMs` | `number` | The duration to format (in milliseconds)                                                                            |
+| `level`   | `string` | Highest level to break down: `'milliseconds'`, `'seconds'`, `'minutes'`, `'hours'`, `'days'`, `'months'`, `'years'` |
+
+**Returns:** `object` — An object with numeric values for all included units:
+
+```json
+{
+  "years": 0,
+  "months": 0,
+  "days": 11,
+  "hours": 10,
+  "minutes": 20,
+  "seconds": 54,
+  "milliseconds": 321,
+  "total": 987654321
+}
+```
+
+---
+
 ## 🧪 Examples
 
 ```js
@@ -74,4 +101,17 @@ console.log(formatDayTimer(172800 + 3661)); // "2d 01:01:01"
 
 const custom = formatCustomTimer(3600 * 26 + 61, 'days', '{days}d {hours}h {minutes}m {seconds}s');
 console.log(custom); // "1d 2h 1m 1s"
+
+const breakdown = breakdownDuration(987654321, 'years');
+console.log(breakdown);
+// {
+//   years: 0,
+//   months: 0,
+//   days: 11,
+//   hours: 10,
+//   minutes: 20,
+//   seconds: 54,
+//   milliseconds: 321,
+//   total: 987654321
+// }
 ```

package/docs/v1/basics/simpleMath.md

@@ -165,3 +165,76 @@ genFibonacciSeq({
 An array representing the generated sequence.
 
 > 🔖 **Beta** – Still experimental and fun to tweak!
+
+---
+
+### 📊 `compareMarketcap`
+
+Calculates the price change of a stuff when its **market cap changes**.
+
+#### 🧩 Function Signature
+
+```js
+compareMarketcap(originalMarketCap, circulatingSupply, newMarketCap)
+```
+
+#### 📥 Parameters
+
+| Parameter           | Type     | Description                                                                 |
+| ------------------- | -------- | --------------------------------------------------------------------------- |
+| `originalMarketCap` | `number` | 💰 The original market capitalization. Must be a valid, finite number.      |
+| `circulatingSupply` | `number` | 🔄 The circulating supply of the coin. Must be a positive number.           |
+| `newMarketCap`      | `number` | 📉 The new market capitalization. Optional. Must be a valid number if used. |
+
+#### 📤 Returns
+
+An object with the following fields:
+
+```js
+{
+  originalPrice: number,       // 💵 Price before market cap changed
+  newPrice: number,            // 💸 Price after market cap changed (NaN if not provided)
+  priceChangePercent: number  // 📈 Percentage change in price (NaN if newMarketCap not provided)
+}
+```
+
+#### ⚠️ Validation Rules
+
+* Throws a `TypeError` if any of the numeric inputs are not finite numbers.
+* Throws an `Error` if `circulatingSupply` is less than or equal to zero.
+* If `newMarketCap` is omitted or not a number, `newPrice` and `priceChangePercent` will be `NaN`.
+
+#### 📝 Notes
+
+* Useful for estimating the effect of market cap fluctuations on token price.
+* Ideal for financial dashboards, token simulations, or educational tools.
+
+---
+
+### 📈 `calculateMarketcap(originalMarketCap, circulatingSupply)`
+
+Calculates the **unit price** of a coin or token based on its **market capitalization** and **circulating supply**.
+
+This function is commonly used in financial applications to estimate the price per asset unit (e.g., per token or coin).
+
+#### 🧮 Formula
+
+```
+price = originalMarketCap / circulatingSupply
+```
+
+#### 📥 Parameters
+
+| Name                | Type     | Description                                                |
+| ------------------- | -------- | ---------------------------------------------------------- |
+| `originalMarketCap` | `number` | The total market capitalization (e.g., in USD) 💵.         |
+| `circulatingSupply` | `number` | The number of tokens or coins currently in circulation 🪙. |
+
+#### 📤 Returns
+
+* `number` – The calculated **unit price** of the asset 🔢.
+
+#### ⚠️ Throws
+
+* `TypeError` – If either parameter is not a finite number ❌.
+* `Error` – If `circulatingSupply` is less than or equal to zero 🚫.