tiny-essentials 1.18.1 → 1.19.0

package/docs/v1/libs/TinyLocalStorage.md

@@ -0,0 +1,350 @@
+# 📦 TinyLocalStorage
+
+Tiny wrapper for `localStorage` with full support for complex structures like `Map`, `Set`, `Date`, `RegExp`, `BigInt`, and even custom types. Offers a type-safe interface and a powerful event system via `TinyEvents`.
+
+---
+
+## 🚀 Quick Start
+
+```js
+const storage = new TinyLocalStorage();
+
+storage.setString('name', 'Yasmin');
+storage.setNumber('age', 25);
+storage.setBool('likesCats', true);
+storage.setJson('myMap', new Map([['a', 1], ['b', 2]]));
+storage.setDate('today', new Date());
+
+console.log(storage.getString('name')); // "Yasmin"
+console.log(storage.getJson('myMap')); // Map { 'a' => 1, 'b' => 2 }
+console.log(storage.getDate('today') instanceof Date); // true
+```
+
+---
+
+## 🧠 Features
+
+* ✅ Store & restore `Map`, `Set`, `Date`, `RegExp`, `BigInt`, `Symbol`, `null`, `undefined`.
+* ✅ Custom type encoding and decoding system.
+* ✅ Type-safe methods for string, number and boolean.
+* ✅ Built-in event system (`TinyEvents`) with optional native `storage` listener.
+* ✅ Optional fallback when decoding fails.
+
+---
+
+## 📦 Storage Methods
+
+### `setJson(key, data)`
+
+Stores any supported JSON-like structure, including `Map`, `Set`, `Date`, `RegExp`, `BigInt`, etc.
+
+```ts
+setJson(name: string, data: LocalStorageJsonValue): void
+```
+
+### `getJson(key, fallback?)`
+
+Retrieves and decodes the previously stored structure. Optional fallback allows recovery on decode failure.
+
+```ts
+getJson(
+  name: string,
+  defaultData?: 'array' | 'obj' | 'map' | 'set' | 'null'
+): LocalStorageJsonValue | null
+```
+
+---
+
+### `setItem(key, rawString)`
+
+Stores a raw `string` value as-is.
+
+```ts
+setItem(name: string, data: string): void
+```
+
+### `getItem(key)`
+
+Retrieves a raw `string` value.
+
+```ts
+getItem(name: string): string | null
+```
+
+---
+
+### `setString(key, string)`
+
+Stores a `string` value.
+
+```ts
+setString(name: string, data: string): void
+```
+
+### `getString(key)`
+
+Retrieves a `string` value.
+
+```ts
+getString(name: string): string | null
+```
+
+---
+
+### `setNumber(key, number)`
+
+Stores a `number` value.
+
+```ts
+setNumber(name: string, data: number): void
+```
+
+### `getNumber(key)`
+
+Retrieves a `number` value.
+
+```ts
+getNumber(name: string): number | null
+```
+
+---
+
+### `setBool(key, boolean)`
+
+Stores a `boolean` value.
+
+```ts
+setBool(name: string, data: boolean): void
+```
+
+### `getBool(key)`
+
+Retrieves a `boolean` value.
+
+```ts
+getBool(name: string): boolean | null
+```
+
+---
+
+### `setDate(key, date)`
+
+Stores a `Date` object.
+
+```ts
+setDate(name: string, data: Date): void
+```
+
+### `getDate(key)`
+
+Retrieves a `Date` object.
+
+```ts
+getDate(name: string): Date | null
+```
+
+---
+
+### `setRegExp(key, pattern)`
+
+Stores a `RegExp` object.
+
+```ts
+setRegExp(name: string, data: RegExp): void
+```
+
+### `getRegExp(key)`
+
+Retrieves a `RegExp` object.
+
+```ts
+getRegExp(name: string): RegExp | null
+```
+
+---
+
+### `setBigInt(key, value)`
+
+Stores a `BigInt` value.
+
+```ts
+setBigInt(name: string, data: bigint): void
+```
+
+### `getBigInt(key)`
+
+Retrieves a `BigInt` value.
+
+```ts
+getBigInt(name: string): bigint | null
+```
+
+---
+
+### `setSymbol(key, value)`
+
+Stores a `Symbol`. Only global symbols (`Symbol.for`) will preserve identity.
+
+```ts
+setSymbol(name: string, data: symbol): void
+```
+
+### `getSymbol(key)`
+
+Retrieves a `Symbol` value.
+
+```ts
+getSymbol(name: string): symbol | null
+```
+
+---
+
+### `getValue(key)`
+
+Retrieves any previously stored value, regardless of type.
+
+```ts
+getValue(name: string): any | null
+```
+
+---
+
+## ❌ Deletion Methods
+
+### `removeItem(key)`
+
+Removes a specific key from `localStorage`.
+
+```ts
+removeItem(name: string): void
+```
+
+### `clearLocalStorage()`
+
+Clears all keys in the active storage.
+
+---
+
+## 🌐 Storage Configuration
+
+### `setLocalStorage(storage)`
+
+Switch between `localStorage` and `sessionStorage`.
+
+```ts
+setLocalStorage(storage: Storage): void
+```
+
+### `localStorageExists()`
+
+Returns `true` if the browser supports the configured storage backend.
+
+---
+
+## 🧩 Custom Type Registration
+
+### `registerJsonType(type, encodeFn, decodeFn)`
+
+Registers support for custom types with encoder/decoder logic.
+
+```ts
+registerJsonType(
+  type: any,
+  encodeFn: (value: any, encodeSpecialJson: EncodeFn) => any,
+  decodeFn: {
+    check: (value: any) => boolean,
+    decode: (value: any, decodeSpecialJson: DecodeFn) => any
+  }
+): void
+```
+
+---
+
+### `deleteJsonType(type)`
+
+Unregisters a previously registered custom type.
+
+```ts
+deleteJsonType(type: any): void
+```
+
+Removes the encoder and decoder associated with the given type. Useful for cleanup or reconfiguration.
+
+---
+
+## 🔥 Events (via TinyEvents)
+
+### Built-in Events
+
+| Event Name     | Triggered When...                           |
+| -------------- | ------------------------------------------- |
+| `'setJson'`    | `.setJson()` is called                      |
+| `'setItem'`    | `.setItem()` is called                      |
+| `'setString'`  | `.setString()` is called                    |
+| `'setNumber'`  | `.setNumber()` is called                    |
+| `'setBool'`    | `.setBool()` is called                      |
+| `'setSymbol'`  | `.setSymbol()` is called                    |
+| `'setBigInt'`  | `.setBigInt()` is called                    |
+| `'setRegExp'`  | `.setRegExp()` is called                    |
+| `'setDate'`    | `.setDate()` is called                      |
+| `'removeItem'` | `.removeItem()` is called                   |
+| `'storage'`    | Browser's native `storage` event (optional) |
+
+All events receive `{ key, value }` or `{ key }` depending on context.
+
+---
+
+## 🧹 Destroying
+
+### `destroy()`
+
+Cleans up listeners and internal event systems.
+
+```ts
+destroy(): void
+```
+
+---
+
+## 🧪 Type Definition
+
+```ts
+type LocalStorageJsonValue =
+  | Record<string | number | symbol, any>
+  | any[]
+  | Map<string | number | symbol, any>
+  | Set<any>;
+```
+
+---
+
+## 🔐 Internal Helpers
+
+### `encodeSpecialJson(value)`
+
+Recursively encodes supported complex types into serializable JSON-like structures.
+
+### `decodeSpecialJson(value)`
+
+Decodes those JSON-like structures back into `Map`, `Set`, `Date`, etc.
+
+---
+
+## 🧪 Example: Map, Set, Date, RegExp
+
+```js
+const map = new Map([['x', 123]]);
+const set = new Set(['apple', 'banana']);
+const date = new Date();
+const regex = /hello/i;
+
+storage.setJson('dataMap', map);
+storage.setJson('dataSet', set);
+storage.setDate('today', date);
+storage.setRegExp('pattern', regex);
+
+console.log(storage.getJson('dataMap') instanceof Map); // true
+console.log(storage.getJson('dataSet') instanceof Set); // true
+console.log(storage.getDate('today') instanceof Date); // true
+console.log(storage.getRegExp('pattern') instanceof RegExp); // true
+```

package/docs/v1/libs/TinyRateLimiter.md

@@ -303,6 +303,3 @@ if (limiter.isRateLimited("user42")) {
 | Group-based rate limiting  | ✅       |
 | Activity metrics per group | ✅       |
 
----
-
-Made with 💜 to protect your app from spammers and abusers — in a cute and efficient way! 😄

package/docs/v1/libs/TinyTimeout.md

@@ -0,0 +1,190 @@
+# 🕒 TinyTimeout
+
+`TinyTimeout` is a smart utility class designed to help manage dynamically scaled `setTimeout` calls based on how frequently a given ID is triggered. It also supports condition polling (`waitForTrue`) for asynchronous workflows. This is especially useful for cooldown systems, progressive delays, or throttling logic.
+
+---
+
+## ✨ Features
+
+* ⏱️ **Dynamic Timeout Scaling** based on trigger frequency
+* 🔁 **Auto-decrement cooldowns** over time
+* ⚙️ Optional **value override support** per ID
+* 🔍 **Polling Support** with `waitForTrue`
+* 🧼 Easy cleanup with `destroy()`
+
+---
+
+## 🚀 Usage
+
+```js
+const timeout = new TinyTimeout();
+
+// Schedule a timeout with ID tracking and increasing delay
+timeout.set('example-id', () => {
+  console.log('Triggered after dynamic delay!');
+}, 200); // 200ms base multiplier
+
+// Optional limit
+timeout.set('example-id', () => {
+  console.log('Max delay limited to 2000ms');
+}, 500, 2000);
+
+// Wait until some condition becomes true
+await timeout.waitForTrue(() => document.readyState === 'complete');
+```
+
+---
+
+## 🔧 Constructor
+
+```ts
+new TinyTimeout(options?: {
+  cooldownWatcherTime?: number;
+  allowAutoConfigChange?: boolean;
+});
+```
+
+| Option                  | Type      | Default | Description                                              |
+| ----------------------- | --------- | ------- | -------------------------------------------------------- |
+| `cooldownWatcherTime`   | `number`  | `5000`  | Interval (ms) to decrease cooldown counters.             |
+| `allowAutoConfigChange` | `boolean` | `false` | Whether to auto update the base value of an existing ID. |
+
+---
+
+## 📘 Methods
+
+### 🧠 `set(id, callback, value, limit?)`
+
+Schedules a timeout using a delay based on how frequently the ID has been triggered.
+
+```ts
+set(id: string, callback: Function, value: number, limit?: number | null): number;
+```
+
+| Parameter  | Type             | Required  | Description                                                                 |
+| ---------- | ---------------- | --------- | --------------------------------------------------------------------------- |
+| `id`       | `string`         | ✅        | Unique identifier for the timeout logic.                                    |
+| `callback` | `Function`       | ✅        | Function to execute after the delay.                                        |
+| `value`    | `number`         | ✅        | Base multiplier for delay in milliseconds.                                  |
+| `limit`    | `number \| null` | ❌        | Optional maximum delay in milliseconds to cap the calculated timeout.       |
+
+📌 **Returns:**  
+A numeric ID returned by `setTimeout`, which can be manually canceled later using `clearTimeout(id)` if necessary.
+
+🛠️ **Behavior:**  
+- The more often an `id` is used consecutively, the longer the timeout becomes.
+- This delay is calculated as `value * now`, where `now` increases each time the `id` is triggered.
+- The delay will never exceed `limit` if it’s provided.
+
+---
+
+### 🔁 `waitForTrue(getValue, checkInterval = 100)`
+
+Waits until a provided function returns `true`, polling periodically.
+
+```ts
+static waitForTrue(getValue: () => boolean, checkInterval?: number): Promise<void>
+```
+
+* `getValue`: Function that returns `true` when the wait should end.
+* `checkInterval`: Polling interval in milliseconds.
+
+---
+
+### 🧩 `waitForTrue(getValue, checkInterval?)` *(instance version)*
+
+Same as `waitForTrue`, but uses the instance's `cooldownWatcherTime` as the default if `checkInterval` is `null`.
+
+```ts
+waitForTrue(getValue: () => boolean, checkInterval?: number | null): Promise<void>
+```
+
+---
+
+### 🛠️ `setCooldownWatcherTime(value)`
+
+Updates the cooldown decrement interval. Automatically restarts the internal timer.
+
+```ts
+setCooldownWatcherTime(value: number): void
+```
+
+---
+
+### ⚙️ `setAllowAutoConfigChange(value)`
+
+Enables or disables automatic value reconfiguration for known IDs.
+
+```ts
+setAllowAutoConfigChange(value: boolean): void
+```
+
+---
+
+### ❓ `getCooldownWatcherTime()`
+
+Returns the current interval used for decrementing cooldowns.
+
+```ts
+getCooldownWatcherTime(): number
+```
+
+---
+
+### ❓ `getAllowAutoConfigChange()`
+
+Returns whether auto-config change is enabled.
+
+```ts
+getAllowAutoConfigChange(): boolean
+```
+
+---
+
+### 🔥 `destroy()`
+
+Cleans up all internals, clears intervals, and invalidates the instance.
+
+```ts
+destroy(): void
+```
+
+---
+
+### ✅ `isDestroyed()`
+
+Checks if the instance has already been destroyed.
+
+```ts
+isDestroyed(): boolean
+```
+
+---
+
+## 🧼 Best Practices
+
+* Use meaningful `id`s to separate timeout logic across components or users.
+* Consider enabling `allowAutoConfigChange` if base delays change dynamically in your app.
+* Always call `destroy()` when you're done to avoid memory leaks!
+
+---
+
+## 🧪 Example
+
+```js
+const t = new TinyTimeout({ cooldownWatcherTime: 3000 });
+
+t.set('search', () => console.log('Search triggered'), 100);
+t.set('search', () => console.log('Slower search due to spamming'), 100);
+t.set('search', () => console.log('Even slower!'), 100, 500);
+
+await t.waitForTrue(() => myAsyncCondition === true);
+
+t.destroy();
+```
+
+---
+
+## 🧠 Why use TinyTimeout?
+
+Sometimes `setTimeout` isn't enough when you need backoff, throttling, or async condition checks. TinyTimeout handles usage frequency and time-based cooldown logic all in one place, and its polling function is perfect for complex reactive UIs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "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",
@@ -62,18 +62,41 @@
     "@tinypudding/discord-oauth2",
     "@tinypudding/mysql-connector",
     "@tinypudding/puddy-lib",
+    "tiny-essentials",
+    "timeout",
+    "storage",
+    "text-editor",
+    "color-converter",
     "clock",
+    "time",
+    "text",
+    "text-range",
+    "input-editor",
+    "string-utils",
+    "string-manipulation",
     "obj-type",
+    "type-checker",
     "simple-math",
-    "text",
-    "lib",
-    "time",
+    "math-utils",
     "shuffle-array",
+    "array-utils",
+    "json",
+    "json-utils",
     "json-color",
+    "json-highlight",
+    "json-viewer",
     "terminal-color",
+    "cli-color",
     "cli-output",
+    "pretty-print-json",
     "colorize-json",
-    "pretty-print-json"
+    "lib",
+    "utility",
+    "utils",
+    "toolkit",
+    "frontend-utils",
+    "backend-utils",
+    "nodejs-utils"
   ],
   "author": "Yasmin Seidel (Jasmin Dreasond)",
   "license": "GPL-3.0-only",