tiny-essentials 1.0.0 → 1.1.0

package/docs/basics/clock.md

@@ -0,0 +1,77 @@
+# ⏰ 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!
+
+## ✨ Features
+
+- 🔢 Calculate time differences in various units
+- 🧭 Format durations into clean, readable timer strings
+- 🧱 Support for years, months, days, hours, minutes, and seconds
+- 🎛️ Customizable output with template-based formatting
+- 🛠️ Built-in presets for classic timer formats
+- 🪶 Zero dependencies, lightweight and modular (ESM-ready!)
+
+---
+
+## 🧠 API Overview
+
+### 🔹 `getTimeDuration(timeData, durationType = 'asSeconds', now = null)`
+
+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.                            |
+
+**Returns:** `number|null` — The duration in the chosen unit.
+
+---
+
+### 🔹 `formatCustomTimer(totalSeconds, level = 'seconds', format = '{time}')`
+
+Turns seconds into a custom timer string with fine-grained control.
+
+| 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}` |
+
+**Returns:** `string` — A formatted string with padded units.
+
+---
+
+### 🔹 `formatTimer(seconds)`
+
+Formats a duration into the classic `HH:MM:SS`.
+
+```js
+formatTimer(3670); // "01:01:10"
+```
+
+---
+
+### 🔹 `formatDayTimer(seconds)`
+
+Formats a duration into `Xd HH:MM:SS`, perfect for countdowns.
+
+```js
+formatDayTimer(190000); // "2d 04:46:40"
+```
+
+---
+
+## 🧪 Examples
+
+```js
+const futureTime = new Date(Date.now() + 10000);
+const secondsLeft = getTimeDuration(futureTime, 'asSeconds');
+
+console.log(formatTimer(secondsLeft)); // e.g. "00:00:09"
+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"
+```

package/docs/basics/objFilter.md

@@ -0,0 +1,120 @@
+# 🧠 objFilter.mjs
+
+Type detection, extension, and analysis made easy — simple and extensible type validation in pure JavaScript.
+
+## Overview
+
+`objFilter.mjs` is a utility module that provides a structured and extensible way to validate, infer, and count object types in JavaScript. It’s designed to work in both Node.js and browser environments and is perfect for libraries that need consistent, extensible type-checking logic.
+
+Whether you’re validating inputs, writing schema validators, or building tools that need to "understand" JavaScript data — this module has your back!
+
+---
+
+## Features
+
+- ✅ Precise type detection (`undefined`, `null`, `array`, `buffer`, `date`, etc.)
+- ➕ Custom type extensions with ordering
+- 🔄 Reorder type checking priority
+- 🔍 Safe and predictable type checks
+- 🧮 Count values in arrays and objects
+- 🚫 No dependencies
+
+---
+
+## Usage
+
+### 🔍 `objType(obj, [type])`
+
+Get the type of any value, or check it against a known type.
+
+```js
+objType([], 'array'); // true
+objType('hello');     // "string"
+objType(undefined);   // null
+```
+
+Returns:
+- `true` / `false` if a type is provided
+- The detected type name as a string if no type is provided
+- `null` if `undefined` is passed
+
+---
+
+### ➕ `extendObjType(newTypes, [index])`
+
+Add your own custom types. You can optionally define where in the check order they go.
+
+```js
+extendObjType({
+  customElement: val => val && val.tagName === 'MY-ELEMENT'
+});
+```
+
+This will insert `customElement` before the built-in `object` type unless a position is specified.
+
+---
+
+### 🔁 `reorderObjTypeOrder(newOrder)`
+
+Set a custom priority order for how types are checked (must include only known types).
+
+```js
+reorderObjTypeOrder([
+  'string',
+  'number',
+  'array',
+  'object'
+]);
+```
+
+Returns `true` if successful, or `false` if the order includes unknown types.
+
+---
+
+### 📋 `cloneObjTypeOrder()`
+
+Safely get a copy of the current type evaluation order.
+
+```js
+const currentOrder = cloneObjTypeOrder();
+```
+
+---
+
+### 🧮 `countObj(obj)`
+
+Returns the number of elements in an array or the number of keys in an object.
+
+```js
+countObj([1, 2, 3]);       // 3
+countObj({ a: 1, b: 2 });  // 2
+countObj('hi');            // 0
+```
+
+---
+
+## Supported Types
+
+Here’s a full list of supported type names (in their default order):
+
+- `undefined`
+- `null`
+- `boolean`
+- `number`
+- `bigint`
+- `string`
+- `symbol`
+- `function`
+- `array`
+- `buffer`
+- `date`
+- `regexp`
+- `map`
+- `set`
+- `weakmap`
+- `weakset`
+- `promise`
+- `htmlElement`
+- `object`
+
+You can change this order or insert your own types with `extendObjType`.

package/docs/basics/simpleMath.md

@@ -0,0 +1,65 @@
+# 🔢 simpleMath.mjs
+
+A collection of simple math utilities that make basic calculations a breeze.
+
+## Overview
+
+`simpleMath.mjs` offers a set of essential mathematical functions, from the classic Rule of Three (direct and inverse proportions) to calculating percentages and even determining age based on a birthdate. It's an easy-to-use module for anyone who needs to perform fundamental calculations in JavaScript.
+
+---
+
+## Functions
+
+### 🔢 `ruleOfThree(val1, val2, val3, inverse)`
+
+**Performs a Rule of Three calculation.**  
+This function calculates a proportional relationship between three values, which is commonly used in mathematical and real-world scenarios.
+
+- **`val1`**: First reference value (numerator in direct proportion, denominator in inverse).
+- **`val2`**: Second reference value (denominator in direct proportion, numerator in inverse).
+- **`val3`**: Third value (numerator in direct proportion, denominator in inverse).
+- **`inverse`**: Set to `true` for inverse proportion, or `false` for direct proportion.
+
+#### Example - Direct Proportion:
+
+```js
+ruleOfThree(2, 6, 3, false); // → 9
+```
+
+#### Example - Inverse Proportion:
+
+```js
+ruleOfThree(2, 6, 3, true); // → 4
+```
+
+---
+
+### 💯 `getSimplePerc(price, percentage)`
+
+**Calculates the percentage of a given base value.**
+
+- **`price`**: The base value (for example, the original price of an item).
+- **`percentage`**: The percentage to calculate from the base value.
+
+#### Example:
+
+```js
+getSimplePerc(200, 15); // → 30
+```
+
+---
+
+### 🎂 `getAge(timeData, now)`
+
+**Calculates the age based on a birthdate.**
+
+- **`timeData`**: The birthdate. It can be a timestamp, an ISO string, or a `Date` object.
+- **`now`**: The current date (`Date` object). If not provided, the current date will be used.
+
+If the `timeData` is not provided or is invalid, the function returns `null`.
+
+#### Example:
+
+```js
+getAge('1990-01-01'); // → 35 (assuming the current year is 2025)
+```

package/docs/basics/text.md

@@ -0,0 +1,38 @@
+
+# ✍️ text.mjs
+
+A simple utility for transforming text into title case formats.
+
+## Overview
+
+`text.mjs` provides two functions to help format strings into different types of title case. These functions are useful for formatting titles, headings, or any text that needs consistent capitalization. You can choose between capitalizing the first letter of each word or leaving the first letter of the string in lowercase.
+
+---
+
+## Functions
+
+### 📝 `toTitleCase(str)`
+
+**Converts a string to title case**, where the first letter of each word is capitalized, and all other letters are converted to lowercase.
+
+- **`str`**: The string to be converted to title case.
+
+#### Example:
+
+```js
+toTitleCase('hello world'); // → "Hello World"
+```
+
+---
+
+### 📝 `toTitleCaseLowerFirst(str)`
+
+**Converts a string to title case**, where the first letter of each word is capitalized, but the first letter of the entire string remains lowercase.
+
+- **`str`**: The string to be converted to title case with the first letter in lowercase.
+
+#### Example:
+
+```js
+toTitleCaseLowerFirst('hello world'); // → "hello World"
+```

package/docs/libs/TinyCrypto.md

@@ -0,0 +1,177 @@
+# 🔐 Tiny Crypto
+
+**Tiny Crypto** is a flexible and browser-compatible encryption utility class built for AES-256-GCM encryption with full support for serialization and deserialization of complex JavaScript data types.
+
+Whether you're in Node.js or a browser, Tiny Crypto helps you easily encrypt/decrypt values, save/load configurations, and keep your secrets safe — all while supporting real-world usage like RegExp, Date, Buffer, and even DOM elements (in browsers only)!
+
+---
+
+## ✨ Features
+
+- 🔒 AES-256-GCM symmetric encryption
+- 🧠 Automatic serialization of complex types (Date, RegExp, Set, Map, etc.)
+- 📤 Save and load keys/configs from files
+- 🌐 Works in both **Node.js** and **Browsers**
+- ⚠️ Type validation on decryption
+- 💾 Smart support for file APIs (e.g. `FileReader` in browser, `fs` in Node)
+
+---
+
+## 🚀 Getting Started
+
+```js
+const crypto = new TinyCrypto();
+
+// Encrypt some data
+const { encrypted, iv, authTag } = crypto.encrypt({ hello: 'world' });
+
+// Decrypt it back
+const decrypted = crypto.decrypt({ encrypted, iv, authTag });
+
+console.log(decrypted); // { hello: 'world' }
+```
+
+---
+
+## 🧠 Supported Data Types
+
+When you encrypt a value, its type is recorded and restored when decrypted.
+
+Supports:
+
+- `String`, `Number`, `Boolean`, `BigInt`, `Null`, `Undefined`
+- `Array`, `Object`, `Map`, `Set`, `Buffer`
+- `RegExp`, `Date`, `Symbol`
+- `HTMLElement` _(browser only)_
+
+Does NOT support:
+
+- `Function`, `Promise`, `WeakMap`, `WeakSet` → ❌ Will throw!
+
+---
+
+## 🔧 API
+
+### `constructor(options)`
+
+| Option           | Type   | Default         | Description                       |
+| ---------------- | ------ | --------------- | --------------------------------- |
+| `algorithm`      | string | `'aes-256-gcm'` | AES algorithm used for encryption |
+| `key`            | Buffer | auto-generated  | The secret key to use (32 bytes)  |
+| `outputEncoding` | string | `'hex'`         | Encoding used for outputs         |
+| `inputEncoding`  | string | `'utf8'`        | Encoding used for plain data      |
+| `authTagLength`  | number | `16`            | GCM auth tag length               |
+
+---
+
+### `encrypt(data, iv?)`
+
+Encrypts a value and returns an object with `{ iv, encrypted, authTag }`.
+
+```js
+const result = crypto.encrypt('Hello!');
+```
+
+---
+
+### `decrypt({ iv, encrypted, authTag }, expectedType?)`
+
+Decrypts a previously encrypted value and returns the original data. You can optionally pass an `expectedType` to validate it.
+
+```js
+const plain = crypto.decrypt(result, 'String');
+```
+
+---
+
+### `getTypeFromEncrypted({ iv, encrypted, authTag })`
+
+Returns the type name of the encrypted data without fully decrypting it.
+
+---
+
+### `generateKey(length = 32)`
+
+Generates a secure random key. Default: 32 bytes (AES-256).
+
+---
+
+### `generateIV(length = 12)`
+
+Generates a secure random IV. Default: 12 bytes (GCM standard).
+
+---
+
+### `saveKeyToFile(filename = 'secret.key')`
+
+Saves the current key to a file (browser: prompts download).
+
+---
+
+### `loadKeyFromFile(file)`
+
+Loads a key from a file (browser: File object, Node: file path).
+
+---
+
+### `saveConfigToFile(filename = 'crypto-config.json')`
+
+Saves the current configuration as JSON.
+
+---
+
+### `loadConfigFromFile(file)`
+
+Loads configuration from a JSON file.
+
+---
+
+### `exportConfig()`
+
+Returns an object with the current settings:
+
+```json
+{
+  "algorithm": "aes-256-gcm",
+  "outputEncoding": "hex",
+  "inputEncoding": "utf8",
+  "authTagLength": 16,
+  "key": "..." // hex string
+}
+```
+
+---
+
+### `importConfig(config)`
+
+Applies a configuration object. Throws if invalid types are provided.
+
+---
+
+## 🧪 Type Validation
+
+You can ensure the decrypted value matches the original type:
+
+```js
+crypto.decrypt(result, 'map'); // ✅
+crypto.decrypt(result, 'set'); // ❌ throws if type mismatch
+```
+
+---
+
+## ❗ Errors You Might See
+
+- `Unsupported data type for encryption: Function`
+- `Type mismatch: expected Map, but got Set`
+- `Invalid config JSON file`
+- `HTMLElement deserialization is only supported in browsers`
+
+---
+
+## 🛡️ Security Notice
+
+This utility is for learning and light usage. For production, ensure:
+
+- Proper key management (use secure vaults)
+- Safe IV reuse (IVs must be unique per encryption)
+- Your platform's crypto standards are followed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.0.0",
+  "version": "1.1.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",
@@ -30,7 +30,20 @@
     "type": "git",
     "url": "git+https://github.com/JasminDreasond/Tiny-Essentials.git"
   },
-  "keywords": [],
+  "keywords": [
+    "@tinypudding/firebase-lib",
+    "@tinypudding/discord-oauth2",
+    "@tinypudding/mysql-connector",
+    "@tinypudding/puddy-lib",
+    "clock",
+    "obj-type",
+    "simple-math",
+    "text",
+    "lib",
+    "time",
+    "shuffle-array",
+    "cryptography"
+  ],
   "author": "Yasmin Seidel (Jasmin Dreasond)",
   "license": "GPL-3.0-only",
   "bugs": {
@@ -62,6 +75,7 @@
     "object-hash": "^3.0.0",
     "prettier": "3.5.3",
     "rollup": "^4.40.0",
+    "rollup-plugin-polyfill-node": "^0.13.0",
     "rollup-preserve-directives": "^1.1.3",
     "tinycolor2": "^1.6.0",
     "tslib": "^2.8.1",