@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

Summary

• Async functions
  • createApiAgent
  • createAsyncStore
    • normalizeAsyncQueue
  • createEventEmitter
  • createLangAsyncStore
  • debounce
  • throttle
• Browser functions
  • createMatchDevice
  • createStorage
  • createViewRouter
    • Route Object
    • filterRoutes
    • routeDive
• Date and Time
  • isDateYoungerOf
  • isHoursTimeYoungerThen (Deprecated)
• Element functions
  • cl
  • createEntry
  • createPortal
    • anchorsSetup
    • generateAnchors
  • getFullElementSize
• Object functions
  • assign
  • createState
  • deepMerge
  • getType
  • effect
  • isObject
  • isType
  • proxy
  • remove
  • select
  • update
  • withDefaults
• String functions
  • camelize
  • createIdCache
  • hashID
  • kebabize
• Utility functions
  • memo
  • noop
  • isSSR
• Styles
  • setup
  • colorFilter
  • icon mixin

Async functions

createApiAgent

Creates an API agent with customizable settings for HTTP requests.

Syntax

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:

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 or pinia if needs to get initialisation data from async resources as indexedDB.

Syntax

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:

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

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:

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

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:

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. 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

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:

$ npm i -S i18next

import { createLangAsyncStore } from '@pastweb/tools';

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

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:

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

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:

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

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:

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);

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

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:

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 and history libraries covering the most common functionalities implemented in other router UI Frameworks like react-router or vue-router. The goal of this implementation is to obtain a consistant set of API and terminology cross framework.

Syntax

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:

import { createViewRouter } from '@pastweb/tools';

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

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

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.
• 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:

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:

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

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:

import { filterRoutes } from './path/to/filterRoutes';
import { Route } from '../types';

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

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:

import { routeDive } from './path/to/routeDive';
import { SelectedRoute } from '../types';

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

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:

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

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:

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

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:

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

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:

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:

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'

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

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>

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, vue or angualr. This function abstract the mechanism in order to have a consistant api cross Frameworks useing the Entry object.

Syntax

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:

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:

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

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:

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:

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

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:

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

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:

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:

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

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:

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

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:

import { createState } from 'pastweb/tools';

type MyState = {
  count: number;
  user: { name: string; age: number };
};

const initialState: MyState = { count: 0, user: { name: 'Alice', age: 25 } };

const { state, setState } = createState(initialState, (newState) => {
  console.log('State changed:', newState);
});

console.log(state.count); // 0

setState({ count: state.count + 1 });
console.log(state.count); // 1

setState({ user: { name: 'Bob', age: 30 } });
console.log(state.user.name); // Bob

deepMerge

A utility function that deeply merges two or more objects, handling nested objects and arrays in a sophisticated manner. This function is particularly useful when you need to combine multiple configuration objects or deeply nested data structures.

Syntax

function deepMerge(...sources: { [key: string]: any }[]): { [key: string]: any }

Parameters

• ...sources: { [key: string]: any }[]
  • One or more source objects to merge. Each object in the sources array is merged into the preceding one, with later objects overwriting properties of earlier ones where conflicts arise.

Returns

• { [key: string]: any }: A new object resulting from deeply merging all provided source objects. The merge is performed in such a way that nested objects and arrays are combined rather than simply overwritten.

Example:

import { deepMerge } from '@pastweb/tools';

const obj1 = {
  name: 'Alice',
  details: { age: 25, location: 'Wonderland' },
  hobbies: ['reading', 'chess'],
};

const obj2 = {
  details: { age: 30, job: 'Explorer' },
  hobbies: ['adventure'],
};

const merged = deepMerge(obj1, obj2);

console.log(merged);
// Output:
// {
//   name: 'Alice',
//   details: { age: 30, location: 'Wonderland', job: 'Explorer' },
//   hobbies: ['adventure'],
// }

effect

The effect function creates a reactive effect on specified properties of a target object. Whenever one of these properties changes, a provided callback function is executed, receiving details about the change. This mechanism supports performance optimization by batching and debouncing changes.

Syntax

function effect<T extends object = {}>(
  target: T,
  callback: EffectCallback<T>,
  ...filter: (Extract<keyof T, string> | number | symbol)[]
): void;

Parameters

• target: T
  • The target object to observe. The function will monitor changes to specified properties of this object.
• callback: EffectCallback<T>
  • The callback function to execute when a specified property changes. It receives an object containing the newValues, oldValues, and the properties (prop) that changed.
• ...filter: (Extract<keyof T, string> | number | symbol)[]
  • An optional list of property names, symbols, or numbers to observe. If not provided, all properties of the target object will be observed.

Returns

• void:
  • This function doesn't return any value. It modifies the target object to reactively respond to changes.

Example:

import { effect } from '@pastweb/tools';

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

effect(obj, ({ newValues, oldValues }) => {
  console.log(`Changes detected:`, newValues, oldValues);
}, 'a');

obj.a = 3; // Logs: Changes detected: { a: 3 } { a: 1 }

Description The effect function monitors changes to specific properties of a target object. When a change occurs, it triggers a callback function that receives information about the updated values. The changes are debounced to improve performance, ensuring that rapid updates are grouped together before the callback is executed.

This function is useful for creating reactive systems where changes to an object's state should trigger specific actions or updates.

getType

The getType function is a utility that determines the type of a given value in a precise manner. It returns the type of the target as a string, providing a more accurate result than the native typeof operator, especially for complex data types.

Syntax

function getType(target: any): string;

Parameters

• target: any
  • The value whose type is to be determined. This can be any JavaScript value, such as a string, number, object, array, function, etc.

Returns

• string:
  • A string representing the type of the target. The returned string is one of the built-in JavaScript types (e.g., "Object", "Array", "Function", "String", "Number", "Null", "Undefined", etc.).

Example:

import { getType } from '@pastweb/tools';

console.log(getType(123)); // "Number"
console.log(getType('Hello')); // "String"
console.log(getType([1, 2, 3])); // "Array"
console.log(getType({ key: 'value' })); // "Object"
console.log(getType(null)); // "Null"
console.log(getType(undefined)); // "Undefined"
console.log(getType(() => {})); // "Function"
console.log(getType(new Date())); // "Date"

Use Cases

• Type Checking:
  • When you need to check the type of a value with more precision than typeof allows, especially in cases where you need to distinguish between objects, arrays, and null values.
• Validation:
  • Useful in scenarios where input validation is required, and you need to ensure that a value is of a specific type before proceeding with further operations.
• Debugging:
  • Helps in debugging by providing clear and accurate type information, which can be logged or used to enforce certain conditions in your code.

Notes

• Precise Type Detection:
  • getType provides a precise type string for complex types like "Array", "Date", "RegExp", etc., which typeof would otherwise categorize as "object".
• Null Handling:
  • Unlike typeof, which returns "object" for null, getType correctly identifies null values by returning "Null".
• Custom Objects:
  • For user-defined classes, the function will return "Object" unless the Object.prototype.toString method is overridden.

Edge Cases

• Null and Undefined:
  • Returns "Null" and "Undefined" for null and undefined values, respectively, providing more clarity than typeof, which returns "object" for null.
• Symbol:
  • Correctly returns "Symbol" for symbol values, which typeof also handles but might be less intuitive in some cases.

isObject

The isObject function checks whether a given value is an object. It returns true if the value is an object, and false otherwise.

Syntax

function isObject(target: any): boolean;

Parameters

• target: any
  • The value to check. This can be of any type (e.g., string, number, array, object, etc.).

Returns

• boolean:
  • Returns true if the target is of type Object; otherwise, it returns false.

Example:

import { isObject } from '@pastweb/tools';

console.log(isObject({})); // true
console.log(isObject([])); // false
console.log(isObject(null)); // false
console.log(isObject('hello')); // false

isType

The isType function is a utility that checks whether a given value matches a specified type. It uses the getType function to accurately determine the type of the target and compares it to the provided type string.

Syntax

function isType(type: string, target: any): boolean;

Parameters

• type: string
  • The type to check against. This should be a string representing the expected type of the target, such as "String", "Number", "Array", "Object", etc.
• target: any
  • The value whose type is to be checked. This can be any JavaScript value, such as a string, number, object, array, function, etc.

Returns

• boolean:
  • Returns true if the target matches the specified type, otherwise false.

Example:

import { isType } from '@pastweb/tools';

console.log(isType('String', 'Hello')); // true
console.log(isType('Number', 123)); // true
console.log(isType('Array', [1, 2, 3])); // true
console.log(isType('Object', { key: 'value' })); // true
console.log(isType('Null', null)); // true
console.log(isType('Undefined', undefined)); // fals