tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
199 lines (133 loc) • 4.43 kB
Markdown
# 🕒 TinyDomReadyManager
A flexible, customizable JavaScript class to execute code **only when the DOM is ready**, or when additional asynchronous requirements (like Promises or asset loads) are met.
Supports **prioritized callbacks**, **filters**, and now even **DOM-only fast execution**!
## 🧠 Type Definitions
### `Fn` 🛠️
```ts
type Fn = () => void;
```
A basic function to be executed once the system is ready.
### `FnFilter` 🔍
```ts
type FnFilter = () => boolean;
```
A conditional function that decides whether a handler should be executed.
Returns `true` to allow execution, or `false` to skip.
### `Handler` 🧩
```ts
interface Handler {
fn: Fn;
once: boolean;
priority: number;
filter: FnFilter | null;
domOnly: boolean;
}
```
Describes a registered handler and how it should be treated during readiness flow.
## 🚀 Class: `TinyDomReadyManager`
### `init()` 🕓
```ts
init(): void
```
Initializes the manager and waits for the `DOMContentLoaded` event.
If the DOM is already ready, it triggers immediately.
* ⚠️ Throws an `Error` if called more than once.
### `addPromise(promise)` ⏳
```ts
addPromise(promise: Promise<any>): void
```
Adds a custom `Promise` that delays full readiness.
This allows tasks like `fetch()` or image preloading to block late-stage handlers.
* ⚠️ Throws a `TypeError` if `promise` is not a real `Promise`.
### `onReady(fn, options?)` ✅
```ts
onReady(fn: Fn, options?: {
once?: boolean;
priority?: number;
filter?: FnFilter | null;
domOnly?: boolean;
}): void
```
Registers a function to run at the right moment:
| Option | Type | Default | Description |
| ---------- | ------------------ | ------- | ------------------------------------------------------------------------ |
| `once` | `boolean` | `true` | Whether to execute only once |
| `priority` | `number` | `0` | Higher values run earlier |
| `filter` | `FnFilter \| null` | `null` | Optional condition before executing |
| `domOnly` | `boolean` | `false` | 🚀 If `true`, runs immediately after **DOM is ready**, skipping promises |
* ⚠️ Throws a `TypeError` if `fn` is not a function.
### `isReady()` 📡
```ts
isReady(): boolean
```
Returns `true` only after both the DOM is ready **and** all added promises have resolved.
### `isDomReady()` 🧱
```ts
isDomReady(): boolean
```
Returns `true` if the DOM is already ready (i.e., `DOMContentLoaded` has fired).
Returns `false` if the DOM is still loading.
> ✅ Useful when you want to know *just* when the document is interactive, regardless of async operations.
## 🧪 Readiness Phases
| Phase | Description |
| --------------- | ---------------------------------------- |
| **DOM Ready** | Triggers `domOnly: true` handlers |
| **Fully Ready** | Triggers all normal `onReady()` handlers |
## 💡 Example Usage
### Basic Usage
```js
import TinyDomReadyManager from './TinyDomReadyManager.js';
const manager = new TinyDomReadyManager();
manager.onReady(() => {
console.log('Ready after DOM + Promises!');
});
manager.addPromise(fetch('/config.json'));
manager.init();
```
### DOM-Only Handler (Faster)
```js
manager.onReady(() => {
console.log('DOM is ready, skipping Promises!');
}, { domOnly: true, priority: 100 });
```
### Conditional + Prioritized
```js
manager.onReady(() => {
console.log('Only runs if in dark mode');
}, {
priority: 5,
filter: () => document.documentElement.classList.contains('dark')
});
```
### Mixing Both Types
```js
manager.onReady(() => {
console.log('DOM-only logic A');
}, { domOnly: true, priority: 10 });
manager.onReady(() => {
console.log('DOM-only logic B');
}, { domOnly: true, priority: 5 });
manager.onReady(() => {
console.log('Waits for API call');
});
manager.addPromise(fetch('/api/user'));
manager.init();
```
## 📌 Notes
* `domOnly` handlers are ideal for UI setup or event binding.
* Regular handlers are best for things that depend on data loading or external states.
* All handlers are executed safely, and exceptions are caught with warning logs.