npm package: @pastweb/tools
Description: Set of tools for web application development
Author: Domenico Pasto
Latest version: 1.18.9

# @pastweb/tools

Contains a collection of utility functions to help with various common tasks in JavaScript and TypeScript application development.
Below you will find descriptions of each function along with examples of how to use them.

* Production ready
* Treeshake optimised

## Installation
```bash
$ npm i -S @pastweb/tools
```
```bash
$ pnpm i -S @pastweb/tools
```
```bash
$ yarn add -S @pastweb/tools
```

## Summary

- [Async functions](#async-functions)
  - [createApiAgent](#createapiagent)
  - [createAsyncStore](#createasyncstore)
    - [normalizeAsyncQueue](#normalizeasyncqueue)
  - [createEventEmitter](#createeventemitter)
  - [createLangAsyncStore](#createlangasyncstore)
  - [debounce](#debounce)
  - [throttle](#throttle)
- [Browser functions](#browser-functions)
  - [createMatchDevice](#creatematchdevice)
  - [createMatchScheme](#creatematchscheme)
    - [createMatchSchemeAsyncStore](#creatematchschemeasyncstore)
  - [createStorage](#createStorage)
  - [createViewRouter](#createviewrouter)
    - [Route Object](#route-object)
    - [filterRoutes](#filterroutes)
    - [routeDive](#routedive)
- [Date and Time](#date-and-time)
  - [isDateYoungerOf](#isdateyoungerof)
  - [isHoursTimeYoungerThen](#ishourstimeyoungerthen) _(Deprecated)_
- [Element functions](#element-functions)
  - [cl](#cl)
  - [createEntry](#createentry)
  - [createPortal](#createportal)
    - [anchorsSetup](#anchorssetup)
    - [generateAnchors](#generateanchors)
  - [getFullElementSize](#getfullelementsize)
- [Object functions](#object-functions)
  - [assign](#assign)
  - [createState](#createstate)
  - [deepMerge](#deepmerge)
  - [getType](#gettype)
  - [effect](#effect)
  - [isObject](#isobject)
  - [isType](#istype)
  - [proxy](#proxy)
  - [remove](#remove)
  - [select](#select)
  - [update](#update)
  - [withDefaults](#withdefaults)
- [String functions](#string-functions)
  - [camelize](#camelize)
  - [createIdCache](#createidcache)
  - [hashID](#hashid)
  - [kebabize](#kebabize)
- [Utility functions](#utility-functions)
  - [memo](#memo)
  - [noop](#noop)
  - [isSSR](#isssr)
- [Styles](#styles)
  - [setup](#setup)
  - [colorFilter](#colorfilter)
  - [Responsiveness mixins](#responsiveness-mixins)
  - [flex-layout](#flex-layout)

---
## Async functions

### `createApiAgent`

Creates an API agent with customizable settings for HTTP requests.

> #### Syntax
```typescript
function createApiAgent(settings?: AgentSettings): Agent;
```
Parameters
* `settings`: `AgentSettings` (optional) The settings for the API agent.
  * `withCredentials`: `boolean` (optional, default: false)
    * Indicates whether cross-site Access-Control requests should be made using credentials.
  * `headers`: `Record<string, any>` (optional, default: {})
    * Custom headers to be sent with each request.
  * `exclude`: `string | RegExp | Array<string | RegExp>` _(optional)_
    * URLs or patterns to exclude from request intercepting.
  * `onGetValidToken`: `() => Promise<Record<string, any>>` _(optional)_
    * Function to get a valid token for authorization.
  * `onUnauthorizedResponse`: `() => void` _(optional)_
    * Callback for unauthorized responses.

Returns
* `Agent`
  * The configured API agent.

Methods
* `setAgentConfig(settings: AgentSettings): void`
  * Sets the agent configuration.
* `mergeAgentConfig(newSettings: AxiosRequestConfig): void`
  * Merges new settings into the existing agent configuration.
* `delete(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>`
  * Sends a DELETE request.
* `get(url: string, config?: AxiosRequestConfig): Promise<AxiosResponse>`
  * Sends a GET request.
* `patch(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse>`
  * Sends a PATCH request.
* `post(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse>`
  * Sends a POST request.
* `put(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<AxiosResponse>`
  * Sends a PUT request.
* `upload(url: string, data: FormData, onUploadProgress?: (e: AxiosProgressEvent) => void): Promise<AxiosResponse>`
  * Uploads a file using a POST request.
* `download(url: string, fileName: string, domElement?: HTMLElement): Promise<AxiosResponse>`
  * Downloads a file using a GET request and triggers a download in the browser.

**Example:**
```typescript
import { createApiAgent } from '@pastweb/tools';

const apiAgent = createApiAgent({
  withCredentials: true,
  headers: { 'Authorization': 'Bearer token' },
  onGetValidToken: async () => ({ Authorization: 'Bearer newToken' }),
  onUnauthorizedResponse: () => {
    console.log('Unauthorized! Redirecting to login...');
  },
});

// Making a GET request
apiAgent.get('/api/data').then(response => {
  console.log('Data:', response.data);
});

// Uploading a file
const formData = new FormData();
formData.append('file', fileInput.files[0]);
apiAgent.upload('/api/upload', formData, (event) => {
  console.log('Upload progress:', Math.round((event.loaded * 100) / event.total));
});

// Downloading a file
apiAgent.download('/api/download', 'file.txt');
```
---
### `createAsyncStore`

Creates an asynchronous store with the given options.
Useful to be extended for async initialisation of application state manager like [redux](https://redux.js.org/) or [pinia](https://pinia.vuejs.org/) if needs to get initialisation data from async resources as [indexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).

> #### Syntax
```typescript
function createAsyncStore<T>(options: AsyncStoreOptions): T;
```
Parameters
* `options`: `AsyncStoreOptions`
  * The options for creating the asynchronous store.
  * `storeName`: `string`
    * The name of the store. This is required for better error debugging.
  * `timeout`: `number` (optional, default: 20000)
    * The timeout limit in milliseconds for initializing the store.

Returns
* `T`
  * The created asynchronous store.

Throws
* Will throw an error if the `storeName` option is not set.

**Example:**
```typescript
import { createAsyncStore } from '@pastweb/tools';

const storeOptions = {
  storeName: 'myStore',
  timeout: 30000,
};

const myStore = createAsyncStore(storeOptions);
```
---
### `normalizeAsyncQueue`

Normalizes an array of asynchronous operations into an array of promises.

> #### Syntax
```typescript
function normalizeAsyncQueue(wait: Wait | Wait[]): Promise<any>[];
```
Parameters
* `wait`: `Wait | Wait[]`
  * A single asynchronous operation or an array of asynchronous operations. Each operation can be:
    * A promise
    * A function that returns a promise
    * An object representing an asynchronous store

Returns
* `Promise<any>[]`
  * An array of promises.

Throws
* `Error`
  * Throws an error if an invalid type is encountered in the wait array.

**Example:**
```typescript
import { normalizeAsyncQueue } from '@pastweb/tools';

// Single promise
const singlePromise = Promise.resolve('done');
normalizeAsyncQueue(singlePromise); // [singlePromise]

// Array of promises and functions
const promise1 = Promise.resolve('done');
const promise2 = () => Promise.resolve('done');
normalizeAsyncQueue([promise1, promise2]); // [promise1, promise2()]

// Async store
const asyncStore = {
  $$asyncStore: true,
  isStoreReady: false,
  isReady: new Promise(resolve => resolve(true)),
  init: () => { asyncStore.isStoreReady = true; }
};
normalizeAsyncQueue(asyncStore); // [asyncStore.isReady]
```
Remarks
The `normalizeAsyncQueue` function is designed to handle various asynchronous operations and normalize them into a uniform array of promises. This is particularly useful when dealing with mixed asynchronous workflows, ensuring that all operations can be awaited in a consistent manner.

This function supports:
* Promises
* Functions returning promises
* Asynchronous stores

If an asynchronous store is passed in, the function will check if the store is ready. If it is not, the `init` method of the store will be called to prepare it.

---
### `createEventEmitter`

Creates an event emitter that allows subscribing to events, emitting events, and removing event listeners.
It allows you to create a custom event system where you can emit events, subscribe to events with callback functions, and remove event listeners. Each listener is assigned a unique key, which is used to manage and remove listeners efficiently.

> #### Syntax
```typescript
function createEventEmitter(): EventEmitter;
```
Returns
* `EventEmitter`
  * An object containing methods to interact with the event emitter.

Methods
* `emit(eventName: string, ...args: any[]): void`
  * Emits an event, calling all subscribed event listeners with the provided arguments.
  * `eventName`: `string`
    * The name of the event to emit.
  * `...args`: `any[]`
    * Arguments to pass to the event listeners.

* `on(eventName: string, eventCallback: EventCallback): RemoveListener`
  * Subscribes an event listener to a specific event.
  * `eventName`: `string`
    * The name of the event to subscribe to.
  * `eventCallback`: `EventCallback`
    * The callback function to execute when the event is emitted.
  * Returns: `RemoveListener`
    * An object with a removeListener method to unsubscribe from the event.

* `removeListener(eventCallbackKey: symbol): void`
Removes an event listener using its unique key.
  * `eventCallbackKey`: `symbol`
    * The unique key for the event callback to remove.

**Example:**
```typescript
import { createEventEmitter } from '@pastweb/tools';

const emitter = createEventEmitter();
const listener = emitter.on('event', (data) => console.log(data));
emitter.emit('event', 'Hello, World!');
listener.removeListener();
```
---
### `createLangAsyncStore`

Creates a language asynchronous store with `i18next` integration for managing translations.
The `createLangAsyncStore` function provides a flexible way to manage multiple languages in your application using `i18next` with async initialisation, in case ,as example you need to initialise the store getting or setting data to an async resource [indexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API).
It supports:

* Initialization with an initial language.
* Dynamic support for multiple languages.
* Integration with translation resources.
* Custom plugins for `i18next`.
The store is asynchronous and ensures that the language settings and resources are ready before allowing operations like language switching. It is designed to work seamlessly with both synchronous and asynchronous workflows.

> #### Syntax
```typescript
function createLangAsyncStore(options: LangOptions): LangAsyncStore;
```
Parameters
* `options`: `LangOptions`
  * Configuration options for the language store. This includes initial language settings, supported languages, translation resources, and additional `i18next` options.

Returns
* `LangAsyncStore`
  * The created language store, which integrates i18next and provides methods for managing translations and changing the language.

Methods and Properties
* `store.i18n`: `i18n`
  * The `i18next` instance used for managing translations.
* `store.supported`: `string[] | Promise<string[]>`
  * An array of supported languages. If an asynchronous function is provided, it returns a promise that resolves with the supported languages.
* `store.current`: `Promise<string>`
  * A promise that resolves with the current language.
* `store.t`: `TFunction`
  * A translation function provided by i18next.

* `store.changeLanguage(lng: string | undefined, callback?: Callback): Promise<TFunction<'translation', undefined>>`
  * Changes the current language of the store and triggers any specified callback or the store's `onLangChange` function.

  * `lng`: `string | undefined`
    * The language code to switch to.

  * `callback`: `Callback`
    * An optional callback function that is called after the language is changed.

  * Returns: `Promise<TFunction<'translation', undefined>>`
    * A promise that resolves with the `i18next` translation function after the language is changed.

**Example:**
```bash
$ npm i -S i18next
```
```typescript
import { createLangAsyncStore } from '@pastweb/tools/createLangAsyncStore';

const langStore = createLangAsyncStore({
  initLang: 'en',
  supported: ['en', 'fr', 'es'],
  translations: { en: { translation: { key: 'value' } } },
  i18n: { fallbackLng: 'en' },
});

langStore.changeLanguage('fr').then((t) => {
  console.log(t('key')); // Outputs the translation for 'key' in French
});
```
---
### `debounce`
Creates a debounced function that delays invoking `fn` until after `timeout` milliseconds have elapsed since the last time the debounced function was invoked.
The debounced function includes methods `cancel` and `flush` to cancel delayed invocation and to immediately invoke them, respectively.

> #### Syntax
```typescript
function debounce(fn: DebouceCallback, timeout?: number): DebouceCallback;
```
Parameters
* `fn`: `DebouceCallback`
  * The function to debounce.
* `timeout`: `number` _(optional, default: 300)_
  * The number of milliseconds to delay.

Returns
* `DebouceCallback`

**Example:**
```typescript
import { debounce } from '@pastweb/tools';

const debouncedLog = debounce((msg: string) => console.log(msg), 500);

debouncedLog('Hello');  // Will log 'Hello' after 500 milliseconds if not called again within this time.
debouncedLog.cancel();  // Cancels the delayed invocation.
debouncedLog.flush();   // Immediately invokes the delayed function.
```
---
### `throttle`

Returns a throttle function defined in the `fn` parameter, which is executed for each `timeout` passed as the second parameter. The returned throttle function includes two members:

- **`cancel`**: A function to stop the throttling of the function.
- **`flush`**: A function to flush the timeout.

> #### Syntax
```typescript
function throttle(fn: ThrottleCallback, timeout?: number): ThrottleCallback;
```
Parameters
* `fn`: `ThrottleCallback`
  * The function to run.
* `timeout`: `number` _(optional, default: 300)_
  * The timeout gap in milliseconds.

Returns
* `ThrottleCallback`
  * The throttle callback function.
**Example:**
```typescript
import { throttle } from '@pastweb/tools';

const throttledLog = throttle((msg: string) => console.log(msg), 500);

throttledLog('Hello');  // Will log 'Hello' immediately.
throttledLog('World');  // Will not log 'World' if called within 500 milliseconds.
throttledLog.cancel();  // Cancels the throttling.
throttledLog.flush();   // Flushes the timeout, allowing the function to be invoked immediately.
```
---
## Browser functions

### `createMatchDevice`

Creates a utility for detecting and managing device types based on user agent strings and media queries.
The `createMatchDevice` function is designed to help detect device types based on user agent strings and media queries. This utility is particularly useful for responsive design and ensuring that your application behaves differently depending on the device being used.

* Device Detection: The utility supports both user agent string matching and media query matching to determine device types.
* Server-Side Rendering (SSR): If server-side rendering is detected (isSSR), user agent-based detection is used, and media query-based detection is skipped.
* Dynamic Updates: The utility can respond to changes in media query matches, allowing dynamic updates to the device state.
* Event Emitter: The underlying event emitter allows you to listen for specific device match changes, enabling reactive design and behavior changes.

> #### Syntax
```typescript
function createMatchDevice(config: DevicesConfig = {}): MatchDevice;
```
Parameters
* `config`: `DevicesConfig`
  * An optional configuration object that maps device names to their detection criteria. Each device's configuration can include a user agent test and/or a media query.

Returns
* `MatchDevice`
  * An object with methods for getting the current matched devices, setting change listeners, and listening for specific device match events.

Methods
* `getDevices(): MatchDevicesResult`
  * Returns an object representing the current state of device matches. Each key in the object corresponds to a device name, and the value is a boolean indicating whether the device matches the criteria.

* `onChange(fn: (devices: MatchDevicesResult) => void): void`
  * Sets a callback function to be executed whenever the device match state changes. The callback receives an updated MatchDevicesResult object.
  * `fn: (devices: MatchDevicesResult) => void`
    * The callback function to be called on device state change.

* `onMatch(isDeviceName: string, fn: (result: boolean, deviceName: string) => void): void`
  * Sets a listener for a specific device match event. The callback is triggered whenever the specified device's match state changes.
  * `deviceName`: `string`
    * The name of the device to listen for.
  * `fn`: `(result: boolean, isDeviceName: string) => void`
    * The callback function to be called when the device match event occurs.

**Example:**
```typescript
import { createMatchDevice } from '@pastweb/tools';

const deviceConfig = {
  mobile: {
    userAgent: /Mobile|Android/i,
    mediaQuery: '(max-width: 767px)',
  },
  tablet: {
    mediaQuery: '(min-width: 768px) and (max-width: 1024px)',
  },
};

const matchDevice = createMatchDevice(deviceConfig);

matchDevice.onChange((devices) => {
  console.log('Device states updated:', devices);
});

matchDevice.onMatch('mobile', (deviceName) => {
  console.log('Mobile device match changed:', deviceName);
});

const currentDevices = matchDevice.getDevices();
console.log('Current matched devices:', currentDevices);
```
---

Here is the **Markdown documentation** in the same style as the "isType" function documentation:  

---

### `createMatchScheme`

> #### Syntax 
```ts
function createMatchScheme(config?: SchemeOptions): MatchScheme;
```

## Description  

Creates a match scheme manager that allows setting and tracking the color scheme mode.  
It detects system preferences, provides methods to update the mode, and notifies listeners of changes.

## Parameters  

### `config` (optional)  
**Type:** `SchemeOptions`  
An object containing configuration options for the match scheme.

| Property       | Type      | Default  | Description |
|---------------|----------|----------|-------------|
| `defaultMode` | `string` | `"auto"` | The initial color mode: `'auto'`, `'light'`, or `'dark'`. |
| `datasetName` | `string \| false` | `false` | The dataset attribute name used to store the color scheme in the root element. If `false`, it uses CSS class names instead. |

## Returns  

**Type:** `MatchScheme`  
An object with methods to manage and listen to scheme changes.

## Methods  

#### `getInfo`  
```ts
getInfo(): { mode: string; system: string; selected: string };
```
**Description:**  
Retrieves the current color scheme information.

**Returns:**
| Property   | Type   | Description |
|------------|--------|-------------|
| `mode`     | `string` | The currently set mode (`'auto'`, `'light'`, or `'dark'`). |
| `system`   | `string` | The system's detected color scheme (`'light'` or `'dark'`). |
| `selected` | `string` | The active mode (either `mode` or the detected system scheme if `mode` is `'auto'`). |

**Example:**  
```ts
const scheme = createMatchScheme();
console.log(scheme.getInfo()); 
// { mode: 'auto', system: 'light', selected: 'light' }
```

#### `setMode`  
```ts
setMode(mode: string): void;
```
**Description:**  
Updates the color mode. If `'auto'` is selected, the mode will follow the system's preference.

**Parameters:**
| Name   | Type   | Description |
|--------|--------|-------------|
| `mode` | `string` | The new mode: `'auto'`, `'light'`, or `'dark'`. |

**Example:**  
```ts
scheme.setMode('dark'); 
console.log(scheme.getInfo()); 
// { mode: 'dark', system: 'light', selected: 'dark' }
```

#### `onModeChange`  
```ts
onModeChange(fn: (mode: string) => void): void;
```
**Description:**  
Registers a callback that is triggered when the mode changes.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| `fn` | `(mode: string) => void` | A callback function that receives the new mode. |

**Example:**  
```ts
scheme.onModeChange((mode) => {
  console.log(`Mode changed to: ${mode}`);
});
scheme.setMode('light'); 
// Logs: "Mode changed to: light"
```

#### `onSysSchemeChange`  
```ts
onSysSchemeChange(fn: (mode: string) => void): void;
```
**Description:**  
Registers a callback that triggers when the system's preferred color scheme changes.

**Parameters:**
| Name | Type | Description |
|------|------|-------------|
| `fn` | `(mode: string) => void` | A callback function that receives the new system scheme (`'light'` or `'dark'`). |

**Example:**  
```ts
scheme.onSysSchemeChange((systemMode) => {
  console.log(`System scheme changed to: ${systemMode}`);
});
```

## Example Usage  
```ts
const scheme = createMatchScheme({ defaultMode: 'auto', datasetName: 'theme' });

console.log(scheme.getInfo()); 
// { mode: 'auto', system: 'dark', selected: 'dark' }

scheme.onModeChange((mode) => {
  console.log(`Color mode changed to: ${mode}`);
});

scheme.setMode('light');
// Logs: "Color mode changed to: light"
```

---

### `createMatchSchemeAsyncStore`

> #### Syntax  
```ts
function createMatchSchemeAsyncStore(options?: SchemeOptionsAsyncStore): ColorSchemeAsyncStore;
```

## Description  

Creates an asynchronous store for managing color schemes.  
This function initializes an asynchronous store specifically for handling  
color scheme preferences and system theme detection. It integrates with  
`createMatchScheme` to track and manage color mode changes.

## Parameters  

#### `options` (optional)  
**Type:** `SchemeOptionsAsyncStore`  
Configuration options for the asynchronous store.

| Property       | Type                  | Default              | Description |
|---------------|-----------------------|----------------------|-------------|
| `storeName`   | `string`               | `"ColorSchemeStore"` | The name of the store. |
| `datasetName` | `string \| false`      | `false`              | The dataset attribute name for storing the color scheme. If `false`, it uses CSS class names instead. |
| `defaultMode` | `string`               | `"auto"`             | The default mode (`'auto'`, `'light'`, or `'dark'`). |
| `initStore`   | `(matchScheme: MatchScheme) => Promise<void>` | `noop` | An asynchronous function that runs during store initialization. |

## Returns  

**Type:** `ColorSchemeAsyncStore`  
An object that provides methods and properties for managing color schemes asynchronously.

## Properties  

### `matchScheme`  
**Type:** `MatchScheme`  
Manages color scheme detection and provides methods to get or change the scheme.

#### `init`  
**Type:** `() => void`  
A no-op function for initialization.

#### `setStoreReady`  
**Type:** `() => void`  
Marks the store as ready after initialization.

## Example Usage  

```ts
const colorSchemeStore = createMatchSchemeAsyncStore({
  defaultMode: 'auto',
  datasetName: 'theme',
  initStore: async (matchScheme) => {
    console.log('Initializing with:', matchScheme.getInfo());
  }
});
```
---

### `createStorage`

Creates a versatile storage utility that supports both IndexedDB and localStorage.
This utility allows for custom storage handling, default settings, and hooks for various operations.

> #### Syntax
```typescript
function createStorage(config: StorageConfig = {}): Storage;
```

Parameters
* `config`: `StorageConfig`
  * An object containing configuration options for the storage utility. The available options include:
  * `dbName`: `string` _(optional)_
    * The name of the database when using IndexedDB. Default is 'storage'.
  * `storeName`: `string` _(optional)_
    * The name of the object store within the database when using IndexedDB. Default is 'storage'.
  * `type`: `'indexedDB' | 'localStorage'` _(optional)_
    * The type of storage to use. Defaults to 'indexedDB' if supported; otherwise, it falls back to 'localStorage'.
  * `defaultSettings`: `Record<string, any>` _(optional)_
    * An object representing default settings to be applied when the store is first created.
  * `onSet`: `Record<string, (storage: Storage, value: any, store: boolean) => Promise<any>>` _(optional)_
    * Hooks to run custom logic when a value is set in the store.
  * `onGet`: `Record<string, (storage: Storage, value: any) => Promise<any>>` _(optional)_
    * Hooks to run custom logic when a value is retrieved from the store.
  * `onRemove`: `Record<string, (storage: Storage, path: string, justLocalStorage: boolean) => Promise<void>>` _(optional)_
    * Hooks to run custom logic when a value is removed from the store.

Returns
* `Storage`
  * An object with methods for interacting with the storage, including getting, setting, and removing data.

Methods
* `storage.get(path: string): Promise<any>`
Retrieves a value from the storage.
  * `path`: `string`
    * The path to the value in the storage.
  * Returns: `Promise<any>`
    * A promise that resolves to the stored value.

* `storage.set(path: string, value: any, store = false): Promise<void>`
Sets a value in the storage.
  * `path`: `string`
    * The path to store the value at.
  * `value`: `any`
    * The value to store.
  * `store`: `boolean` (optional)
    * Whether to store the value in the underlying storage (e.g., IndexedDB or localStorage). Default is false.
  * Returns: `Promise<void>`
    * A promise that resolves once the value is set.

* `storage.remove(path: string, justLocalStorage = false): Promise<void>`
Removes a value from the storage.
  * `path`: `string`
    * The path to remove.
  * `justLocalStorage`: `boolean` (optional)
    * Whether to only remove the value from local storage. Default is false.
  * Returns: `Promise<void>`
    * A promise that resolves once the value is removed.

* `storage.isStored(path: string): boolean`
Checks if a specific path is stored in the storage.
  * `path`: `string`
    * The path to check.
  * Returns: `boolean`
    * True if the path is stored, false otherwise.

* `storage.isStoreReady: Promise<true>`
  * A promise that resolves when the storage is fully initialized and ready to be used.

**Example:**
```typescript
import { } from '@pastweb/tools';

const storage = createStorage({
  dbName: 'myDatabase',
  storeName: 'myStore',
  type: 'indexedDB',
  defaultSettings: { theme: 'dark' },
 });
 
 // Set a value in storage
 await storage.set('theme', 'light');
 
 // Get a value from storage
 const theme = await storage.get('theme');
 
 // Remove a value from storage
 await storage.remove('theme');
```
---
### `createViewRouter`

The `createViewRouter` function is a core utility for managing routing in a single-page application (SPA).
It provides the ability to define routes, navigate between them, and react to route changes within the application.
The `ViewRouter` use [path-to-regexp](https://github.com/pillarjs/path-to-regexp) and [history](https://github.com/browserstate/history.js) libraries covering the most common
functionalities implemented in other router UI Frameworks like [react-router](https://reactrouter.com/en/main) or [vue-router](https://router.vuejs.org/).
The goal of this implementation is to obtain a consistant set of API and terminology cross framework.

> #### Syntax
```typescript
function createViewRouter(options: RouterOptions): ViewRouter;
```

Parameters
* `options`: `RouterOptions`
  * An object containing configuration options for the router. The available options include:
  * `base`: `string` _(optional)_
    * The base path for all routes.
  * `debug`: `boolean` _(optional)_
    * If true, enables debug logging for the router.
  * `history`: `History` _(optional)_
    * The history object for managing session history.
  * `routes`: `Route[]` _(mandatory)_
    * An array of route definitions.
  * `preloader`: `() => void` _(optional)_
    * A function to execute before a route is loaded.
  * `href`: `string` _(optional)_
    * The current URL as a string.
  * `RouterView`: `Component` _(mandatory)_
    * The component to render for matched routes.
  * `beforeRouteParse`: `(route: Route) => Route` _(optional)_
    * A function to execute before parsing a route, if you want to modify a `Route`.
  * `beforeRouteSelect`: `(route: SelectedRoute) => SelectedRoute` _(optional)_
    * A function to execute before selecting a route, as example for the route authentication/authirization.
  * `sensitive`: boolean _(optional)_
    * If true, route matching will be case-sensitive.

Returns
* `ViewRouter`
  * An object that represents the router. This object contains properties and methods to manage routing within the application.

**Example:**
```typescript
import { createViewRouter } from '@pastweb/tools';
import { RouterView } from '@pastweb/x';

const router = createViewRouter({
  routes: [
    { path: '/', component: HomePage },
    { path: '/about', component: AboutPage },
  ],
  preloader: MyProloaderComponent,
  RouterView,
});
```

Note : `pastweb/x` is intended to be a specific framework package (react, preact, vue, svelte ...).

Core Features
* `Route Parsing and Matching`:
  * The router parses and normalizes routes, creating a structure that allows efficient matching of paths against the defined routes.
* `Event-Driven`:
  * It uses an event emitter to notify listeners about route changes or when new routes are added.
* `Navigation`:
  * The router offers methods to programmatically navigate, push, replace, or go back and forward in the history stack.
* `Base Path Management`:
  * Allows setting and managing a base path, which is useful for applications hosted under subdirectories.
* `Route Preloading`:
  * Supports route preloading, enabling efficient loading of route components.
* `Custom Hooks`:
  * Provides hooks (`beforeRouteParse`, `beforeRouteSelect`) that allow custom logic to be executed during route parsing and selection.

Methods
* `setBase(base: string): void`
  * Sets the base path for the router. The base path is the common prefix for all routes.
* `addRoute(route: Route): void`
  * Adds a new route to the router dynamically after the router has been initialized.
* `onRouteChange(fn: (route: SelectedRoute) => void): RemoveListener`
  * Subscribes to route change events. The provided callback function will be called whenever the route changes.
* `onRouteAdded(fn: (routes: Route[]) => void): RemoveListener`
  * Subscribes to route added events. The provided callback function will be called whenever a new route is added to the router.
* `navigate(path: string, state?: any): void`
  * Navigates to a specific path programmatically.
* `push(path: string, state?: any): void`
  * Pushes a new state onto the history stack and navigates to the specified path.
* `replace(path: string, state?: any): void`
  * Replaces the current state in the history stack with a new state and navigates to the specified path.
* `go(delta: number): void`
  * Moves forward or backward in the history stack by a specified number of steps.
* `setSearchParams(searchParams: URLSearchParams): void`
  * Sets the search parameters for the current location without reloading the page.
* `setHash(hash?: string): void`
  * Sets the hash for the current location without reloading the page.
* `getRouterLink(options: RouterLinkOptions): RouterLink`
  * Creates a router link object that contains methods for navigation and checks if the link is active or exactly active.

Edge Cases
* `No Matching Route`:
  * If no route matches the current path, the router will warn in the console and return a default empty route.
* `Base Path Changes`:
  * When the base path is changed, the router adjusts all existing routes accordingly to ensure consistent matching.

Debugging
If the `debug` option is enabled, the router logs detailed information about its internal state, such as the current paths, parsed routes, and the selected route. This can be helpful for debugging route configuration issues.

---
### `Route Object`

The `Route Object` contains the information to define a route for `ViewRouter`.

> #### Syntax
```typescript
interface Route {
  path: string;
  redirect?: string;
  view?: View;
  views?: Record<string, View>;
  children?: Route[];
  [optionName: string]: any;
};
```

Props

* `path`: `string`
  * the path string description for the route match, you can check the match syntax [here](https://github.com/pillarjs/path-to-regexp?tab=readme-ov-file#match).
* `redirect`: `string` _(optional)_
  * the URL to be redirected if the route match the `path` rule.
* `view`: `View = any | (() => Promise<{ default: any, [prop: string]: any }>)` _(optional)_
  * the `View` component or a function returning the `View` component module exported as `default`.
* `views`: `Record<string, View>` _(optional)_
  * An Object of named views to be handled from a `RouterView` component.
* `children`: `Route[]` _(optional)_
  * An array of nested `Routes`.

The `Route` object can be extended with any other custom property which will be present in the `SelectedRoute` structure as described below:

**Example:**
```typescript
const routes: Route[] = [
  {
    path: '/home',
    view: HomeComponent,
    icon: 'homeIcon',
  },
  {
    path: '/category/:name',
    view: CategoryComponent,
    icon: 'categoryIcon',
    children: [
      {
        path: '/product/:id',
        view: ProductComponent,
      }
    ],
  },
  {
    path: '/',
    redirect: '/home',
  },
];
```

When the browser URL will match one of the `Routes`, the `SelectedRoute` will be available in the `router.currentRoute` property having this structure:

```typescript
interface SelectedRoute {
  parent: SelectedRoute | boolean;
  regex: RegExp;
  path: string;
  params: RouteParams;
  searchParams: URLSearchParams;
  setSearchParams: (params: URLSearchParams) => void;
  hash: string;
  setHash: (hash?: string) => void;
  views: Record<string, View>;
  options: RouteOptions;
  child: SelectedRoute | boolean;
}
```
In the example above the `icon` property will be present in the options parameters, (`router.currentRoute.options.icon`).

---

### `filterRoutes`

The `filterRoutes` function filters a list of routes based on specified criteria. It allows you to filter out routes that do not meet the conditions defined in the provided filter descriptor.

> #### Syntax
```typescript
function filterRoutes(routes: Route[] = [], filter: FilterDescriptor = {}): Route[];
```

Parameters
* `routes`: `Route[] (default: [])`
  * An array of route objects to be filtered. Each Route object represents a route in the application and may contain properties such as path, component, redirect, children, and others.
* `filter`: `FilterDescriptor`
  * An object describing the filter criteria. The keys in this object represent the properties of the Route objects to filter on, and the values are the criteria that those properties must match. The value can be a specific value to match or a function that returns a boolean indicating whether the route matches the criteria.

Returns
* `Route[]`:
  * An array of Route objects that match the filter criteria. If a route has children, the function will recursively filter them based on the same criteria. If no routes match, an empty array is returned.

**Example:**
```typescript
import { filterRoutes, type Route } from '@pastweb/tools';

const routes: Route[] = [
  { path: '/home', component: HomeComponent },
  { path: '/about', component: AboutComponent, hideInPaths: true },
  { path: '/user/:id', component: UserComponent },
];

const filter = { component: HomeComponent };

const filteredRoutes = filterRoutes(routes, filter);
console.log(filteredRoutes); 
// Outputs: [{ path: '/home', component: HomeComponent }]
```
---

### `routeDive`

The `routeDive` function is designed to traverse a nested route structure and return the route found at a specified depth.
This is useful in scenarios where routes have nested children, and you need to access a route at a certain level within that hierarchy.

> #### Syntax
```typescript
function routeDive(route: SelectedRoute, depth: number): SelectedRoute;
```

Parameters
* `route`: `SelectedRoute`
  * The initial `SelectedRoute` object representing the current route from which the traversal begins. This route may contain nested child routes.
* `depth`: `number`
  * The number of levels to traverse into the nested route structure. A depth of 0 returns the initial route, while a higher depth traverses deeper into the nested child routes.

Returns
* `SelectedRoute`:
  * The `SelectedRoute` object located at the specified depth. If the specified depth exceeds the available levels of nesting, the function returns the deepest child route available.

**Example:**
```typescript
import { routeDive, type SelectedRoute } from '@pastweb/tools';

const currentRoute: SelectedRoute = {
  path: '/parent',
  child: {
    path: '/parent/child',
    child: {
      path: '/parent/child/grandchild',
    },
  },
};

const grandchildRoute = routeDive(currentRoute, 2);
console.log(grandchildRoute.path); // Output: '/parent/child/grandchild'
```

Edge Cases
* `Zero Depth`:
  * If the `depth` parameter is `0`, the function returns the initial route without any traversal.
`Exceeding Depth`:
  * If the specified `depth` is greater than the actual number of nested levels, the function returns the last available `child` route.

Practical Use Cases
* `View Rendering`:
  * In a UI framework where different views are rendered based on the current route, `routeDive` can be used to determine which nested route corresponds to the current view depth.
* `Breadcrumb Navigation`:
  * For generating breadcrumb navigation, `routeDive` can help in identifying the route at different levels, enabling dynamic breadcrumb creation.

Example of Nested Route Traversal
Given a route structure with multiple levels of nesting, routeDive will traverse through each level until it either reaches the specified depth or the deepest available route. This allows developers to dynamically access deeply nested routes without manually iterating through each level.

---

## Date and Time

### `isDateYoungerOf`

The `isDateYoungerOf` function checks whether a given date is younger (i.e., more recent) than a specified duration.
The duration is provided as a string composed of multiple time components such as years, months, days, hours, minutes, and seconds.

> #### Syntax
```typescript
function isDateYoungerOf(date: Date, duration: string): boolean;
```

Parameters
* `date`: `Date`
  * The date object to be checked against the specified duration.
* `duration`: `string`
  * A string representing the duration composed of various time units:
    * `Y` for years
    * `M` for months
    * `D` for days
    * `h` for hours
    * `m` for minutes
    * `s` for seconds
* The string can contain multiple components, e.g., `"2Y3M1D"` for 2 years, 3 months, and 1 day.

Returns
* `boolean`:
  * Returns `true` if the given date is younger than the specified duration relative to the current date and time. Returns `false` otherwise.

**Example:**
```typescript
import { isDateYoungerOf } from '@pastweb/tools';

const date = new Date();
date.setDate(date.getDate() - 1); // 1 day ago
console.log(isDateYoungerOf(date, '1D')); // Output: true
console.log(isDateYoungerOf(date, '2D')); // Output: true
console.log(isDateYoungerOf(date, '12h')); // Output: false
```

Edge Cases
* `Past and Future Dates`: The function checks the date against the current date and time, so it works for both past and future dates relative to `now`.
* `Zero or Negative Durations`: If the duration components result in zero or negative values, the function will consider the date as not younger and will return `false`.

---

### `isHoursTimeYoungerThen`
> **⚠️ Deprecated:** This function is deprecated and will be removed in future versions. Please use the `isDateYoungerOf` function instead.

The `isHoursTimeYoungerThen` function checks if the difference between the current time and a given timestamp is less than a specified number of hours.

> #### Syntax
```typescript
function isHoursTimeYoungerThen(hoursTime: number, then: number): boolean;
```

Parameters
* `hoursTime`: `number`
  * A timestamp in milliseconds (since the Unix epoch) representing the time to compare against the current time.
* `then`: `number`
  * The threshold number of hours to compare against. If the difference between the current time and `hoursTime` is less than this value, the function returns `true`.

Returns
* `boolean`:
  * Returns `true` if the time difference is less than the specified number of hours (`then`); otherwise, returns `false`.

**Example:**
```typescript
import { isHoursTimeYoungerThen } from '@pastweb/tools';

const hoursTime = new Date().getTime() - (2 * 60 * 60 * 1000); // 2 hours ago
console.log(isHoursTimeYoungerThen(hoursTime, 3)); // Output: true
```

Notes
* `Deprecation Notice`: This function is deprecated and will be removed in future versions. It is recommended to use the `isDateYoungerOf` function instead for more flexibility and comprehensive date comparison.
* `Precision`: The function calculates the difference down to the hour level. If more precision is required (e.g., minutes or seconds), consider using a different approach or function.

Limitations
* `Limited Granularity`: The function only compares the difference at the hour level. It does not take minutes or seconds into account beyond converting them to hours.
* `Handling of Edge Cases`: The function assumes that the `hoursTime` is a valid timestamp and that then is a non-negative number. Unexpected behavior may occur if invalid inputs are provided.

---

## Element functions

### `cl`

Combines class names using the `clsx` library.

> #### Syntax
```typescript
function cl(...args: ClassValue[]): string;
```
Parameters
* `...args`: `ClassValue[]`
  * A list of class values to combine. Each ClassValue can be a string, an object, or an array.

Returns
* `string`
  * The combined class names as a single string.

**Example:**
```typescript
import { cl } from '@pastweb/tools';

const classNames = cl('btn', { 'btn-primary': true }, 'extra-class');
// Output: 'btn btn-primary extra-class'
```
Methods
* `cl.setClasses`
  * Sets custom CSS module classes and returns a function to combine class names with these classes.
  
> #### Syntax
```typescript
cl.setClasses(classes: CSSModuleClasses | CSSModuleClasses[], mode: 'merge' | 'replace' = 'merge'): (...args: ClassValue[]) => string;
```

Parameters
* `classes`: `CSSModuleClasses | CSSModuleClasses[]`
  * An object or array of objects representing CSS module classes to use for mapping class names.

* `mode`: `'merge' | 'replace'` _(optional)_
The mode for combining classes:
  * `'merge'`: Combines the custom classes with the existing classes.
  * `'replace'`: Replaces existing class names with the custom classes.

Returns
* `(...args: ClassValue[]) => string`
A function that takes class values as arguments and returns the combined class names as a string.

Throws
* `Error`
Throws an error if a provided class object is not a valid object.

The `setClasses` method returns a function which it works as the `cl` function, but returns the scoped classes presents in the CSS Module if present or the `class string` itself if not.

**Example:**
```typescript
import { cl } from '@pastweb/tools';

const cssModules = {
  'btn': 'btn_hash',
  'btn-primary': 'btn-primary_hash',
};

const cls = cl.setClasses(cssModules);
const classNames = cls('btn', 'btn-primary', 'some-other-class');
// Output: 'btn_hash btn-primary_hash some-other-class'
```

It is possible combine the classes of multiple CSS Modules:

**Example:**
```typescript
import { cl } from '@pastweb/tools';

const cssModules1 = {
  'btn': 'btn_hash1',
  'btn-primary': 'btn-primary_hash1',
};

const cssModules2 = {
  'btn-primary': 'btn-primary_hash2',
};

const clsMerge = cl.setClasses([ cssModules1, cssModules2 ], 'merge' /** you can omit the second parameter as it is 'merge' by default */);
const classNames = clsMerge('btn', 'btn-primary');
// Output: 'btn_hash1 btn-primary_hash1 btn-primary_hash2'

const clsReplace = cl.setClasses([ cssModules1, cssModules2 ], 'replace');
const replacedClassNames = clsReplace('btn', 'btn-primary');
// Output: 'btn_hash1 btn-primary_hash2'
```

Or is it possible make a composition with different `ClassProcessor`.
Key Features:

1. Type Definition: Added `ClassProcessor` interface to define the shape of our function with both the call signature and `setClasses` method.
2. Composable setClasses: Each setClasses call:
  * Creates a new processor function
  * Maintains its own classes and mode
  * Returns a new function with its own setClasses method
  * Concatenates classes when composing

**Example:**
```typescript
import { cl } from '@pastweb/tools';
// Basic usage
cl('btn', 'active'); // 'btn active'

// Single module
const module1 = { btn: 'btn_123', active: 'active_456' };
const cl1 = cl.setClasses(module1);
cl1('btn', 'active'); // 'btn_123 active_456'

// Multiple modules composition
const module2 = { btn: 'btn_789', hover: 'hover_abc' };
const cl2 = cl1.setClasses(module2);
cl2('btn', 'hover'); // 'btn_123 btn_789 hover_abc'

// Different modes
const cl3 = cl2.setClasses({ btn: 'btn_xyz' }, 'replace');
cl3('btn', 'active'); // 'btn_xyz active_456'

// Each instance remains independent
cl('btn');     // 'btn'
cl1('btn');    // 'btn_123'
cl2('btn');    // 'btn_123 btn_789'
cl3('btn');    // 'btn_xyz'

// Example CSS modules
const module1 = { foo: 'foo_1', bar: 'bar_1' };
const module2 = { foo: 'foo_2', baz: 'baz_2' };
const module3 = { bar: 'bar_3' };

// Chained setClasses calls
const cx = cl
  .setClasses(module1, 'merge')        // First set of classes
  .setClasses(module2, 'replace')      // Override with second set
  .setClasses(module3, 'merge');       // Add third set

// Usage
console.log(cx('foo', 'bar', 'baz')); 
// Output depends on final composition, likely "foo_2 bar_3 baz_2"
```

Benefits:

1. Chainable: You can keep adding modules with .setClasses().
2. Immutable: Each call creates a new processor without modifying previous ones.
3. Flexible: Maintains mode control at each composition level.
4. Type-safe: TypeScript will properly infer types throughout the chain.

Performance Benefits:

1. Frequent calls with the same arguments will return cached results.
2. Each processor instance maintains its own cache.
3. Reduces computation for repeated class combinations.

---
### `createEntry`
Creates an entry object with event emitter capabilities and various utility methods to be extended for a specific frontend framework.

An Entry is the shorthend for Entrypoint, to be intended (in this case) as Javascript entrypoint and the DOM mount element where the Javascript Framework should apply its effect.
The `createEntry` function gives an high level interface to other frameworks for implement the `mount`, `unmount` and `update` methods with some additional support for the `SSR`.
For the `SSR` process, because the `Entries` could be nested, as example for a framework migration process, and considering different frameworks could have a `sync` or `async` function
for the Server Side Rendering, the `Entry` object has other 2 methos to solve this problem.

* `memoSSR(htmlPromiseFunction: () => Promise<string>): void;`
  * This method must be used inside the `mount` method and memorise the `HTML` string produced from the `SSR` framework function, returning a unique `ssrId`.
* `getComposedSSR(): Promise<string>`
  * Is an `async` function wich compose the final `HTML` string replacing the `sseId` with the previous memorised `HTML` for each `Entry` Object.


> #### Syntax
```typescript
function createEntry<E extends Entry<O>, O extends EntryOptions>(options?: O): E;
```

Parameters
* `options`: O
Options configuration for the entry. The options are of type `EntryOptions` and may include the following properties:
  * `EntryComponent`: `any` _(optional)_
    * The component to be set as the entry component.
  * `entryElement`: `HTMLElement` _(optional)_
    * The HTML element that represents the entry point in the DOM.
  * `querySelector`: `string` _(optional)_
    * A CSS selector string that can be used to find the entry element within the DOM.
  * `initData`: `Record<string, any>` _(optional)_
    * An object containing initial data to be passed into the entry during its creation.

Returns
* `E`
  * The created entry object, which includes event emitter functionalities and various utility methods.

Methods
The entry object returned by createEntry includes the following methods:

* `entry.memoSSR(htmlPromiseFunction: () => Promise<string>): void;`: Stores the SSR HTML promise function.
  - `htmlPromiseFunction`: `() => Promise<string>`: The function that returns an HTML promise.
* `entry.getComposedSSR(): Promise<string>`: Composes the SSR HTML from the stored promises.
  - Returns: `Promise<string>`: The composed SSR HTML.
* `entry.setEntryElement(entryElement: HTMLElement): void;`: Sets the entry element.
* `entry.setQuerySelector(querySelector: string): void;`: Sets the query selector.
* `entry.setOptions(options: O): void;`: Sets the options for the entry.
* `entry.mergeOptions(options: O): void;`: Merges the options for the entry.
* `entry.setEntryComponent(Component: any): void;`: Sets the entry component.

Events
The entry object also has event emitter capabilities with the following methods:

* `on`: Registers an event listener.
* `emit`: Emits an event.
* `removeListener`: Removes an event listener.

the events used to handle the entry are:
* `mount`: called when the entry must be mounted to the DOM.
* `update`: called when the some data in the entry nust be updated.
* `unmount`: called when the entry must be unmounted from the DOM.

**Example>**
```typescript
import { createEntry } from '@pastweb/tools';

const entry = createEntry({
  EntryComponent: MyComponent,
  entryElement: document.getElementById('app'),
  querySelector: '#app',
  initData: { key: 'value' },
});

// Usage of the entry object
entry.on('someEvent', () => console.log('Event triggered'));
entry.emit('someEvent');
```
---
### `createPortal`
Creates a Portal object that manages the lifecycle of portal entries, including opening, updating, and closing portal instances.
Portal is a common term used to identify a mechanism usually implemented in a Front End framework for render and handle components in a not nested
DOM element a good example is a rendering of a modal window you can see an example implementation for [react](https://react.dev/reference/react-dom/createPortal), [vue](https://vuejs.org/guide/built-ins/teleport) or [angualr](https://material.angular.io/cdk/portal/overview).
This function abstract the mechanism in order to have a consistant api cross Frameworks useing the [Entry](#createentry) object.

> #### Syntax
```typescript
function createPortal(
  entry: (props: Record<string, any>, component: any) => Entry<any>,
  defaults?: Record<string, any>
): Portal;
```

Parameters
* `entry`: `((props: Record<string, any>, component: any) => Entry<any>)`
  * A function that takes props and a component, returning an Entry object that represents the portal entry. This function defines how the portal entry is created.
* `defaults`: `Record<string, any>` _(optional)_
  * An optional object containing default properties that will be merged with the props when creating a portal entry. This allows for setting default behavior or configuration for the portal.

Returns
* `Portal`
An object that provides methods for managing portal entries, such as opening, updating, closing, and removing them.

**Example:**
```typescript
import { createPortal } from '@pastweb/tools';
import { MyComponent } from './MyComponent';

const myPortal = createPortal((props, component) => new MyComponent(props), { defaultProp: 'defaultValue' });

const portalId = myPortal.open(MyComponent, { prop1: 'value1' });
myPortal.update(portalId, { prop1: 'newValue' });
myPortal.close(portalId);
myPortal.remove(portalId);
```
Methods of Portal
The returned Portal object contains several methods for managing portal instances:

* `open(component: any, props?: Record<string, any>, defaults?: Record<string, any>): string | false`
  * Opens a new portal entry with the specified component and props. Returns the entry ID if successful, or false if the portal could not be opened.
* `update(entryId: string, entryData?: any): boolean`
  * Updates an existing portal entry with the given entry ID and new data. Returns true if the update was successful, or false otherwise.
* `close(entryId: string): void`
  * Closes the portal entry associated with the given entry ID.
* `remove(entryId: string): boolean`
  * Removes the portal entry associated with the given entry ID from the portals cache. Returns true if the removal was successful, or false otherwise.
* `setIdCache(newCache: any): void`
  * Sets a new cache for managing entry IDs within the portal.
* `setPortalElement(newElement: HTMLElement | (() => HTMLElement)): void`
  * Sets a new portal element or a function that returns the portal element, which is used for rendering the portal's content.
* `setPortalsCache(newPortals: any): void`
  * Replaces the current portals cache with a new one.
* `setOnRemove(fn: (entryId: string) => void): void`
  * Sets a callback function that will be called whenever a portal entry is removed.

**Example with Custom Configuration:**
```typescript
import { createPortal } from '@pastweb/tools';
import { CustomComponent } from './CustomComponent';

const customPortal = createPortal((props, component) => new CustomComponent(props), { color: 'blue' });

const entryId = customPortal.open(CustomComponent, { size: 'large' });
customPortal.setOnRemove(id => console.log(`Removed portal entry with ID: ${id}`));
customPortal.close(entryId);
```
In this example, a custom portal is created, opened with specific props, and then closed. The `setOnRemove` method is used to log a message whenever a portal entry is removed.

---
### `anchorsSetup`
Sets up a structure of portals based on provided anchor IDs, descriptors, and configurations. This function is designed to initialize a tree of portal functions that can manage portal entries across different elements identified by their IDs.

> #### Syntax
```typescript
function anchorsSetup(
  anchors: PortalAnchorsIds,
  descriptor: EntryDescriptor,
  getEntry: (...args: any[]) => any,
  idCache: IdCache,
  portalsCache: Portals
): PortalsDescriptor;
```

Parameters
* `anchors`: `PortalAnchorsIds`
  * An object mapping anchor IDs to their corresponding portal functions. This structure can be nested to represent hierarchical relationships between different portal anchors.
* `descriptor`: `EntryDescriptor`
  * An object that describes the portals to be set up. It mirrors the structure of anchors and provides configuration details for each portal.
* `getEntry`: `(...args: any[]) => any`
  * A function that returns the entry object for each portal. This function is used to generate or retrieve the entry logic needed to initialize each portal.
* `idCache`: `IdCache`
  * A cache object used for managing and tracking the IDs of portal entries. This helps in efficiently managing portal instances and their identifiers.
* `portalsCache`: `Portals`
  * A cache object used to store and manage the portal instances. This cache keeps track of the active portals and their associated data.

Returns
* `PortalsDescriptor`
  * An object that represents the set up portals, with methods for managing each portal entry (e.g., opening, updating, closing, and removing entries).

**Example:**
```typescript
import { anchorsSetup, createIdCache } from '@pastweb/tools';

const anchors = {
  header: 'header-portal',
  footer: 'footer-portal',
  content: {
    main: 'main-content-portal',
    sidebar: 'sidebar-portal',
  },
};

const descriptor = {
  header: { /* header-specific settings */ },
  footer: { /* footer-specific settings */ },
  content: {
    main: { /* main-content-specific settings */ },
    sidebar: { /* sidebar-specific settings */ },
  },
};

const idCache = createIdCache();
const portalsCache = {}; // Assuming portalsCache is initialized accordingly

const portals = anchorsSetup(anchors, descriptor, () => MyEntryFunction, idCache, portalsCache);

portals.header.open(MyComponent, { prop: 'value' });
portals.content.sidebar.update('someId', { newProp: 'newValue' });
```

`Helper Function`: `setPortals`
The `setPortals` function is a recursive helper that sets up portals within the provided structure.
It ensures that each portal is correctly initialized based on its associated ID and configuration.

**Syntax:**
```typescript
function setPortals(
  ids: Record<string, any>,
  descriptor: Record<string, any>,
  portals: Record<string, any>,
  getEntry: () => any,
  idCache: IdCache,
  portalsCache: Portals
): void;
```

Parameters
* `ids`: `Record<string, any>`
  * A mapping of portal anchor IDs to their corresponding DOM element IDs or nested structures.
* `descriptor`: `Record<string, any>`
  * A mapping of portal descriptors, which mirror the structure of ids. This describes the configurations for each portal.
* `portals`: `Record<string, any>`
  * An object that will be populated with portal functions. This object will contain methods for interacting with each portal.
* `getEntry`: `() => any`
  * A function that returns the entry logic for initializing the portal.
* `idCache`: `IdCache`
  * A cache for managing portal entry IDs.
* `portalsCache`: `Portals`
  * A cache for storing and managing the portals.

Returns
* `void`
  * The function does not return a value. Instead, it mutates the portals object to populate it with the necessary portal functions.

Error Handling
* `Throws`
  * An error is thrown if the structure of descriptor does not match the structure of ids, or if a portal setup encounters a type inconsistency.

---
### `generateAnchors`
Generates a set of unique anchor IDs based on an array of anchor paths.
This function is used to create a structured object where each path is associated with a unique ID, which can be used to identify elements in a portal system.

> #### Syntax
```typescript
function generateAnchors(anchors: string[], idCache?: IdCache): PortalAnchorsIds;
```
Parameters
* `anchors`: `string[]`:
  * An array of strings representing the anchor paths. Each path can be a simple string or a dot-separated string representing a nested structure (e.g., "header.menu.item").
* `idCache`: `IdCache`: _(optional)_
  * An instance of IdCache used to generate unique IDs. If not provided, it defaults to DEFAULT_ID_CACHE, which is a default cache instance. The IdCache helps ensure that IDs are unique within a specified scope.

Returns
* `PortalAnchorsIds`:
  * An object that maps each anchor path to a unique ID.
  The structure of the returned object mirrors the nested structure of the anchor paths, with each leaf node being a unique ID.

**Example:**
```typescript
import { generateAnchors, createIdCache } from '@pastweb/tools';

const anchors = [
  'header.menu.item1',
  'header.menu.item2',
  'footer.link1',
  'footer.link2'
];

const idCache = createIdCache();
const anchorIds = generateAnchors(anchors, idCache);

console.log(anchorIds);
/* Example output:
{
  header: {
    menu: {
      item1: "item1-unique-id",
      item2: "item2-unique-id"
    }
  },
  footer: {
    link1: "link1-unique-id",
    link2: "link2-unique-id"
  }
}
*/
```

Use Case
The generateAnchors function is typically used in situations where you need to dynamically generate and manage a set of element IDs for a portal system, especially when working with nested structures. By using this function, you can ensure that each element within your portal system has a unique identifier, making it easier to manage and reference these elements in your application.

---
### `getFullElementSize`
Calculates the full size of an HTML element, including padding, border, and margin, with the option to exclude certain attributes.

> #### Syntax
```typescript
function getFullElementSize(element: HTMLElement | null | undefined, exclude?: ATTRIB[]): FullElementSize;
```

Parameters
* `element`: `HTMLElement | null | undefined`:
  * The HTML element whose size is to be calculated. If the element is null or undefined, an empty size object is returned.
* `exclude`: `ATTRIB[]`: _(optional)_
  * An optional array of attribute names to exclude from the size calculation. The ATTRIB type represents CSS properties like padding, border, and margin. Defaults to an empty array.

Returns
* `FullElementSize`
The full size of the element, including padding, border, and margin, as an object with width and height properties.

**Example:**
```typescript
import { getFullElementSize } from '@pastweb/tools';

const element = document.getElementById('myElement');
const size = getFullElementSize(element);
console.log(size.width, size.height); // Output: { width: ..., height: ... }
```

Details
The `getFullElementSize` function is useful for calculating the total size of an HTML element, considering not only its content but also the additional space taken up by padding, border, and margin. This is particularly helpful in layout calculations where precise element dimensions are necessary.

Special Considerations
* `Server-Side Rendering (SSR)`:
  * If the function is executed in a server-side rendering (SSR) context, it will return an empty size object since the DOM is not available in SSR.

* `Empty Elements`:
  * If the element parameter is null or undefined, the function will return an empty size object with both width and height set to 0.

**Example with Exclusion**
You can exclude specific attributes from the size calculation, such as excluding padding:
```typescript
import { getFullElementSize, ATTRIB } from '@pastweb/tools';

const element = document.getElementById('myElement');
const size = getFullElementSize(element, [ATTRIB.paddingTop, ATTRIB.paddingBottom]);
console.log(size.width, size.height);
```
In this example, the size calculation excludes the top and bottom padding of the element.

Related Types
* `FullElementSize`:
  * An object type with width and height properties representing the full dimensions of an element.
* `ATTRIB`:
  * An enumeration type representing various CSS attributes like padding, border, and margin that can be included or excluded in the size calculation.

Constants Used
* `EMPTY`:
  * A constant representing an empty size object { width: 0, height: 0 }.
* `ATTRIBS`:
  * An object mapping dimension keys (width, height) to arrays of related CSS attributes that contribute to the size of an element.

---

## Object functions

### `assign`

Assigns a value to a target object at a specified path.
The function supports both mutable and immutable updates, allowing you to either directly modify the target object or return a new object with the updated value.

> #### Syntax
```typescript
function assign(target: Record<string, any>, path: string, value: any, immutable?: boolean): void | Record<string, any>;
```
Parameters
* `target`: `Record<string, any>`:
  * The target object to assign the value to.
* `path`: `string`:
  * The path at which to assign the value, specified as a dot-separated string.
* `value`: `any`:
  * The value to assign.
* `immutable`: `boolean`: _(optional, default: false)_
  * If true, performs an immutable update, returning a new object.

Returns
* `void` | `Record<string, any>`:
  * If immutable is true, returns the new object with the assigned value.
  Otherwise, returns void.

**Example:**
```typescript
import { assign } from '@pastweb/tools';

const obj = { a: { b: 2 } };

// Mutable update
assign(obj, 'a.b', 3);
console.log(obj); // Output: { a: { b: 3 } }

// Immutable update
const newObj = assign(obj, 'a.c', 4, true);
console.log(newObj); // Output: { a: { b: 3, c: 4 } }
console.log(obj);    // Output: { a: { b: 3 } } (remains unchanged)
```
---
### `createState`

Creates a simple state management utility that allows you to manage and update state in a controlled manner.
This function is generic and can be used to manage any kind of state object.

> #### Syntax
```typescript
function createState<State>(
  initialState: State | InitiaStateFunction<State> = {} as State,
  onStateChange?: (state: State) => void
): {
  state: State;
  setState: (state: Partial<State>) => void;
}
```

Parameters
* `initialState`: `State | InitiaStateFunction<State>` _(optional)_
  * The initial state of the utility. This can either be a state object or a function that returns the initial state. If not provided, an empty object of type State is used as the default.
* `onStateChange`: `(state: State) => void` _(optional)_
  * A callback function that is triggered whenever the state changes. This function receives the updated state as its argument. By default, this parameter is a no-op function (does nothing).

Returns
* `Object`: An object containing two properties:
  * `state`: `State`
    * The current state object. This state is initialized with the initialState and updated when setState is called.
  * `setState`: `(state: Partial<State>) => void`
    * A function to update the state. This function accepts a partial state object and merges it with the existing state. After the state is updated, the onStateChange callback is invoked.

**Example