@leancodepl/utils 8.4.0 → 8.5.1

package/index.cjs.js

@@ -3,7 +3,21 @@
 var invariant = require('tiny-invariant');
 var react = require('react');
 
-function addPrefix(object, prefix) {
+/**
+ * Adds a prefix to all keys in an object, creating a new object with prefixed keys.
+ * 
+ * @template T - The type of the input object
+ * @template TPrefix - The type of the prefix string
+ * @param object - The object whose keys will be prefixed
+ * @param prefix - The prefix string to add to each key
+ * @returns A new object with all keys prefixed
+ * @example
+ * ```typescript
+ * const apiData = { userId: 1, userName: 'John' };
+ * const prefixed = addPrefix(apiData, 'api_');
+ * // Result: { api_userId: 1, api_userName: 'John' }
+ * ```
+ */ function addPrefix(object, prefix) {
     return Object.fromEntries(Object.entries(object).map(([key, value])=>[
             `${prefix}${key}`,
             value
@@ -16,10 +30,30 @@ function transformFirst(value, transformFn) {
     }
     return transformFn(value[0]) + value.slice(1);
 }
-function toLowerFirst(value) {
+/**
+ * Converts the first character of a string to lowercase.
+ * 
+ * @param value - The string to transform
+ * @returns The string with the first character in lowercase
+ * @example
+ * ```typescript
+ * const result = toLowerFirst('UserName');
+ * // Result: 'userName'
+ * ```
+ */ function toLowerFirst(value) {
     return transformFirst(value, (value)=>value.toLowerCase());
 }
-function toUpperFirst(value) {
+/**
+ * Converts the first character of a string to uppercase.
+ * 
+ * @param value - The string to transform
+ * @returns The string with the first character in uppercase
+ * @example
+ * ```typescript
+ * const result = toUpperFirst('userName');
+ * // Result: 'UserName'
+ * ```
+ */ function toUpperFirst(value) {
     return transformFirst(value, (value)=>value.toUpperCase());
 }
 
@@ -49,36 +83,151 @@ function transformDeep(value, mode) {
     }
     return value;
 }
-function uncapitalizeDeep(value) {
+/**
+ * Recursively transforms all object keys to use uncapitalized (camelCase) format.
+ * 
+ * @template T - The type of the input value
+ * @param value - The value to transform (can be object, array, or primitive)
+ * @returns A new object with all keys converted to camelCase
+ * @example
+ * ```typescript
+ * const serverData = { UserId: 1, UserName: 'John', Profile: { FirstName: 'John' } };
+ * const clientData = uncapitalizeDeep(serverData);
+ * // Result: { userId: 1, userName: 'John', profile: { firstName: 'John' } }
+ * ```
+ */ function uncapitalizeDeep(value) {
     return transformDeep(value, "uncapitalize");
 }
-function capitalizeDeep(value) {
+/**
+ * Recursively transforms all object keys to use capitalized (PascalCase) format.
+ * 
+ * @template T - The type of the input value
+ * @param value - The value to transform (can be object, array, or primitive)
+ * @returns A new object with all keys converted to PascalCase
+ * @example
+ * ```typescript
+ * const clientData = { userId: 1, userName: 'John', profile: { firstName: 'John' } };
+ * const serverData = capitalizeDeep(clientData);
+ * // Result: { UserId: 1, UserName: 'John', Profile: { FirstName: 'John' } }
+ * ```
+ */ function capitalizeDeep(value) {
     return transformDeep(value, "capitalize");
 }
 
-function assertDefined(value, message) {
+/**
+ * Asserts that a value is not undefined. Throws an error if the value is undefined.
+ * This is a type assertion function that narrows the type to exclude undefined.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to check for undefined
+ * @param message - Optional error message to use if assertion fails
+ * @throws {Error} When the value is undefined
+ * @example
+ * ```typescript
+ * function processUser(user?: User) {
+ *   assertDefined(user);
+ *   return user.name; // TypeScript knows user is defined
+ * }
+ * ```
+ */ function assertDefined(value, message) {
     invariant(value !== undefined, message);
 }
 
-function assertNotNull(value, message) {
+/**
+ * Asserts that a value is not null. Throws an error if the value is null.
+ * This is a type assertion function that narrows the type to exclude null.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to check for null
+ * @param message - Optional error message to use if assertion fails
+ * @throws {Error} When the value is null
+ * @example
+ * ```typescript
+ * function processData(data: string | null) {
+ *   assertNotNull(data);
+ *   return data.toUpperCase(); // TypeScript knows data is not null
+ * }
+ * ```
+ */ function assertNotNull(value, message) {
     invariant(value !== null, message);
 }
 
-function assertNotEmpty(value, message) {
+/**
+ * Asserts that a value is not null or undefined. Throws an error if the value is null or undefined.
+ * This is a type assertion function that narrows the type to exclude null and undefined.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to check for null or undefined
+ * @param message - Optional error message to use if assertion fails
+ * @throws {Error} When the value is null or undefined
+ * @example
+ * ```typescript
+ * function processOptionalData(data?: string | null) {
+ *   assertNotEmpty(data);
+ *   return data.toUpperCase(); // TypeScript knows data is not null/undefined
+ * }
+ * ```
+ */ function assertNotEmpty(value, message) {
     invariant(value !== null && value !== undefined, message);
 }
 
-function ensureDefined(value, message) {
+/**
+ * Ensures that a value is defined, returning it if defined or throwing an error if undefined.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to ensure is defined
+ * @param message - Optional error message to use if the value is undefined
+ * @returns The value if it is defined
+ * @throws {Error} When the value is undefined
+ * @example
+ * ```typescript
+ * function processUser(user?: User) {
+ *   const definedUser = ensureDefined(user);
+ *   return definedUser.name; // definedUser is guaranteed to be defined
+ * }
+ * ```
+ */ function ensureDefined(value, message) {
     assertDefined(value, message);
     return value;
 }
 
-function ensureNotNull(value, message) {
+/**
+ * Ensures that a value is not null, returning it if not null or throwing an error if null.
+ * Unlike assertNotNull, this function returns the value for use in expressions.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to ensure is not null
+ * @param message - Optional error message to use if the value is null
+ * @returns The value if it is not null
+ * @throws {Error} When the value is null
+ * @example
+ * ```typescript
+ * function processData(data: string | null) {
+ *   const nonNullData = ensureNotNull(data);
+ *   return nonNullData.toUpperCase(); // nonNullData is guaranteed to be not null
+ * }
+ * ```
+ */ function ensureNotNull(value, message) {
     assertNotNull(value, message);
     return value;
 }
 
-function ensureNotEmpty(value, message) {
+/**
+ * Ensures that a value is not null or undefined, returning it if valid or throwing an error if empty.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to ensure is not null or undefined
+ * @param message - Optional error message to use if the value is null or undefined
+ * @returns The value if it is not null or undefined
+ * @throws {Error} When the value is null or undefined
+ * @example
+ * ```typescript
+ * function processOptionalData(data?: string | null) {
+ *   const validData = ensureNotEmpty(data);
+ *   return validData.toUpperCase(); // validData is guaranteed to be not null/undefined
+ * }
+ * ```
+ */ function ensureNotEmpty(value, message) {
     assertNotEmpty(value, message);
     return value;
 }
@@ -98,7 +247,30 @@ function downloadFile(dataOrUrl, options = {}) {
     }
 }
 
-function useRunInTask() {
+/**
+ * React hook for tracking async task execution with loading state.
+ * Automatically manages a loading counter and provides a wrapper function for tasks.
+ * 
+ * @returns A tuple containing [isLoading: boolean, runInTask: function]
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const [isLoading, runInTask] = useRunInTask();
+ *   
+ *   const handleSave = async () => {
+ *     await runInTask(async () => {
+ *       await saveData();
+ *     });
+ *   };
+ *   
+ *   return (
+ *     <button onClick={handleSave} disabled={isLoading}>
+ *       {isLoading ? 'Saving...' : 'Save'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */ function useRunInTask() {
     const [runningTasks, setRunningTasks] = react.useState(0);
     const runInTask = react.useCallback(async (task)=>{
         setRunningTasks((runningTasks)=>runningTasks + 1);
@@ -126,7 +298,34 @@ function useBoundRunInTask(block) {
     ];
 }
 
-function useKeyByRoute(routeMatches) {
+/**
+ * React hook for generating keys based on current route matches.
+ * 
+ * @template TKey - The type of the route keys
+ * @param routeMatches - Record of route keys to match objects or arrays
+ * @returns Array of active route keys
+ * @example
+ * ```typescript
+ * function NavigationComponent() {
+ *   const routeMatches = {
+ *     home: useRouteMatch('/'),
+ *     about: useRouteMatch('/about'),
+ *     contact: useRouteMatch('/contact')
+ *   };
+ *   
+ *   const activeRoutes = useKeyByRoute(routeMatches);
+ *   // Returns ['home'] if on home page, ['about'] if on about page, etc.
+ *   
+ *   return (
+ *     <nav>
+ *       {activeRoutes.map(route => (
+ *         <span key={route}>Active: {route}</span>
+ *       ))}
+ *     </nav>
+ *   );
+ * }
+ * ```
+ */ function useKeyByRoute(routeMatches) {
     const keys = [];
     for(const key in routeMatches){
         const matches = routeMatches[key];
@@ -137,7 +336,27 @@ function useKeyByRoute(routeMatches) {
     return keys;
 }
 
-function useSetUnset(set) {
+/**
+ * React hook for boolean state management helpers.
+ * 
+ * @param set - The state setter function from useState
+ * @returns A tuple containing [setTrue: function, setFalse: function]
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const [isVisible, setIsVisible] = useState(false);
+ *   const [show, hide] = useSetUnset(setIsVisible);
+ *   
+ *   return (
+ *     <div>
+ *       <button onClick={show}>Show</button>
+ *       <button onClick={hide}>Hide</button>
+ *       {isVisible && <div>Content is visible</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */ function useSetUnset(set) {
     return [
         react.useCallback(()=>set(true), [
             set
@@ -148,7 +367,28 @@ function useSetUnset(set) {
     ];
 }
 
-function useDialog(onAfterClose) {
+/**
+ * React hook for managing dialog state with optional callback after closing.
+ * Provides convenient open/close functions and tracks the dialog's open state.
+ * 
+ * @param onAfterClose - Optional callback function to execute after the dialog closes
+ * @returns Object containing dialog state and control functions
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { isDialogOpen, openDialog, closeDialog } = useDialog(() => {
+ *     console.log('Dialog closed');
+ *   });
+ *   
+ *   return (
+ *     <div>
+ *       <button onClick={openDialog}>Open Dialog</button>
+ *       {isDialogOpen && <Dialog onClose={closeDialog} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */ function useDialog(onAfterClose) {
     const [isDialogOpen, setIsDialogOpen] = react.useState(false);
     const [openDialog, closeDialog] = useSetUnset(setIsDialogOpen);
     const close = react.useCallback(()=>{

package/index.esm.js

@@ -1,7 +1,21 @@
 import invariant from 'tiny-invariant';
 import { useState, useCallback, useMemo } from 'react';
 
-function addPrefix(object, prefix) {
+/**
+ * Adds a prefix to all keys in an object, creating a new object with prefixed keys.
+ * 
+ * @template T - The type of the input object
+ * @template TPrefix - The type of the prefix string
+ * @param object - The object whose keys will be prefixed
+ * @param prefix - The prefix string to add to each key
+ * @returns A new object with all keys prefixed
+ * @example
+ * ```typescript
+ * const apiData = { userId: 1, userName: 'John' };
+ * const prefixed = addPrefix(apiData, 'api_');
+ * // Result: { api_userId: 1, api_userName: 'John' }
+ * ```
+ */ function addPrefix(object, prefix) {
     return Object.fromEntries(Object.entries(object).map(([key, value])=>[
             `${prefix}${key}`,
             value
@@ -14,10 +28,30 @@ function transformFirst(value, transformFn) {
     }
     return transformFn(value[0]) + value.slice(1);
 }
-function toLowerFirst(value) {
+/**
+ * Converts the first character of a string to lowercase.
+ * 
+ * @param value - The string to transform
+ * @returns The string with the first character in lowercase
+ * @example
+ * ```typescript
+ * const result = toLowerFirst('UserName');
+ * // Result: 'userName'
+ * ```
+ */ function toLowerFirst(value) {
     return transformFirst(value, (value)=>value.toLowerCase());
 }
-function toUpperFirst(value) {
+/**
+ * Converts the first character of a string to uppercase.
+ * 
+ * @param value - The string to transform
+ * @returns The string with the first character in uppercase
+ * @example
+ * ```typescript
+ * const result = toUpperFirst('userName');
+ * // Result: 'UserName'
+ * ```
+ */ function toUpperFirst(value) {
     return transformFirst(value, (value)=>value.toUpperCase());
 }
 
@@ -47,36 +81,151 @@ function transformDeep(value, mode) {
     }
     return value;
 }
-function uncapitalizeDeep(value) {
+/**
+ * Recursively transforms all object keys to use uncapitalized (camelCase) format.
+ * 
+ * @template T - The type of the input value
+ * @param value - The value to transform (can be object, array, or primitive)
+ * @returns A new object with all keys converted to camelCase
+ * @example
+ * ```typescript
+ * const serverData = { UserId: 1, UserName: 'John', Profile: { FirstName: 'John' } };
+ * const clientData = uncapitalizeDeep(serverData);
+ * // Result: { userId: 1, userName: 'John', profile: { firstName: 'John' } }
+ * ```
+ */ function uncapitalizeDeep(value) {
     return transformDeep(value, "uncapitalize");
 }
-function capitalizeDeep(value) {
+/**
+ * Recursively transforms all object keys to use capitalized (PascalCase) format.
+ * 
+ * @template T - The type of the input value
+ * @param value - The value to transform (can be object, array, or primitive)
+ * @returns A new object with all keys converted to PascalCase
+ * @example
+ * ```typescript
+ * const clientData = { userId: 1, userName: 'John', profile: { firstName: 'John' } };
+ * const serverData = capitalizeDeep(clientData);
+ * // Result: { UserId: 1, UserName: 'John', Profile: { FirstName: 'John' } }
+ * ```
+ */ function capitalizeDeep(value) {
     return transformDeep(value, "capitalize");
 }
 
-function assertDefined(value, message) {
+/**
+ * Asserts that a value is not undefined. Throws an error if the value is undefined.
+ * This is a type assertion function that narrows the type to exclude undefined.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to check for undefined
+ * @param message - Optional error message to use if assertion fails
+ * @throws {Error} When the value is undefined
+ * @example
+ * ```typescript
+ * function processUser(user?: User) {
+ *   assertDefined(user);
+ *   return user.name; // TypeScript knows user is defined
+ * }
+ * ```
+ */ function assertDefined(value, message) {
     invariant(value !== undefined, message);
 }
 
-function assertNotNull(value, message) {
+/**
+ * Asserts that a value is not null. Throws an error if the value is null.
+ * This is a type assertion function that narrows the type to exclude null.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to check for null
+ * @param message - Optional error message to use if assertion fails
+ * @throws {Error} When the value is null
+ * @example
+ * ```typescript
+ * function processData(data: string | null) {
+ *   assertNotNull(data);
+ *   return data.toUpperCase(); // TypeScript knows data is not null
+ * }
+ * ```
+ */ function assertNotNull(value, message) {
     invariant(value !== null, message);
 }
 
-function assertNotEmpty(value, message) {
+/**
+ * Asserts that a value is not null or undefined. Throws an error if the value is null or undefined.
+ * This is a type assertion function that narrows the type to exclude null and undefined.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to check for null or undefined
+ * @param message - Optional error message to use if assertion fails
+ * @throws {Error} When the value is null or undefined
+ * @example
+ * ```typescript
+ * function processOptionalData(data?: string | null) {
+ *   assertNotEmpty(data);
+ *   return data.toUpperCase(); // TypeScript knows data is not null/undefined
+ * }
+ * ```
+ */ function assertNotEmpty(value, message) {
     invariant(value !== null && value !== undefined, message);
 }
 
-function ensureDefined(value, message) {
+/**
+ * Ensures that a value is defined, returning it if defined or throwing an error if undefined.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to ensure is defined
+ * @param message - Optional error message to use if the value is undefined
+ * @returns The value if it is defined
+ * @throws {Error} When the value is undefined
+ * @example
+ * ```typescript
+ * function processUser(user?: User) {
+ *   const definedUser = ensureDefined(user);
+ *   return definedUser.name; // definedUser is guaranteed to be defined
+ * }
+ * ```
+ */ function ensureDefined(value, message) {
     assertDefined(value, message);
     return value;
 }
 
-function ensureNotNull(value, message) {
+/**
+ * Ensures that a value is not null, returning it if not null or throwing an error if null.
+ * Unlike assertNotNull, this function returns the value for use in expressions.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to ensure is not null
+ * @param message - Optional error message to use if the value is null
+ * @returns The value if it is not null
+ * @throws {Error} When the value is null
+ * @example
+ * ```typescript
+ * function processData(data: string | null) {
+ *   const nonNullData = ensureNotNull(data);
+ *   return nonNullData.toUpperCase(); // nonNullData is guaranteed to be not null
+ * }
+ * ```
+ */ function ensureNotNull(value, message) {
     assertNotNull(value, message);
     return value;
 }
 
-function ensureNotEmpty(value, message) {
+/**
+ * Ensures that a value is not null or undefined, returning it if valid or throwing an error if empty.
+ * 
+ * @template T - The type of the value being checked
+ * @param value - The value to ensure is not null or undefined
+ * @param message - Optional error message to use if the value is null or undefined
+ * @returns The value if it is not null or undefined
+ * @throws {Error} When the value is null or undefined
+ * @example
+ * ```typescript
+ * function processOptionalData(data?: string | null) {
+ *   const validData = ensureNotEmpty(data);
+ *   return validData.toUpperCase(); // validData is guaranteed to be not null/undefined
+ * }
+ * ```
+ */ function ensureNotEmpty(value, message) {
     assertNotEmpty(value, message);
     return value;
 }
@@ -96,7 +245,30 @@ function downloadFile(dataOrUrl, options = {}) {
     }
 }
 
-function useRunInTask() {
+/**
+ * React hook for tracking async task execution with loading state.
+ * Automatically manages a loading counter and provides a wrapper function for tasks.
+ * 
+ * @returns A tuple containing [isLoading: boolean, runInTask: function]
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const [isLoading, runInTask] = useRunInTask();
+ *   
+ *   const handleSave = async () => {
+ *     await runInTask(async () => {
+ *       await saveData();
+ *     });
+ *   };
+ *   
+ *   return (
+ *     <button onClick={handleSave} disabled={isLoading}>
+ *       {isLoading ? 'Saving...' : 'Save'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */ function useRunInTask() {
     const [runningTasks, setRunningTasks] = useState(0);
     const runInTask = useCallback(async (task)=>{
         setRunningTasks((runningTasks)=>runningTasks + 1);
@@ -124,7 +296,34 @@ function useBoundRunInTask(block) {
     ];
 }
 
-function useKeyByRoute(routeMatches) {
+/**
+ * React hook for generating keys based on current route matches.
+ * 
+ * @template TKey - The type of the route keys
+ * @param routeMatches - Record of route keys to match objects or arrays
+ * @returns Array of active route keys
+ * @example
+ * ```typescript
+ * function NavigationComponent() {
+ *   const routeMatches = {
+ *     home: useRouteMatch('/'),
+ *     about: useRouteMatch('/about'),
+ *     contact: useRouteMatch('/contact')
+ *   };
+ *   
+ *   const activeRoutes = useKeyByRoute(routeMatches);
+ *   // Returns ['home'] if on home page, ['about'] if on about page, etc.
+ *   
+ *   return (
+ *     <nav>
+ *       {activeRoutes.map(route => (
+ *         <span key={route}>Active: {route}</span>
+ *       ))}
+ *     </nav>
+ *   );
+ * }
+ * ```
+ */ function useKeyByRoute(routeMatches) {
     const keys = [];
     for(const key in routeMatches){
         const matches = routeMatches[key];
@@ -135,7 +334,27 @@ function useKeyByRoute(routeMatches) {
     return keys;
 }
 
-function useSetUnset(set) {
+/**
+ * React hook for boolean state management helpers.
+ * 
+ * @param set - The state setter function from useState
+ * @returns A tuple containing [setTrue: function, setFalse: function]
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const [isVisible, setIsVisible] = useState(false);
+ *   const [show, hide] = useSetUnset(setIsVisible);
+ *   
+ *   return (
+ *     <div>
+ *       <button onClick={show}>Show</button>
+ *       <button onClick={hide}>Hide</button>
+ *       {isVisible && <div>Content is visible</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */ function useSetUnset(set) {
     return [
         useCallback(()=>set(true), [
             set
@@ -146,7 +365,28 @@ function useSetUnset(set) {
     ];
 }
 
-function useDialog(onAfterClose) {
+/**
+ * React hook for managing dialog state with optional callback after closing.
+ * Provides convenient open/close functions and tracks the dialog's open state.
+ * 
+ * @param onAfterClose - Optional callback function to execute after the dialog closes
+ * @returns Object containing dialog state and control functions
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { isDialogOpen, openDialog, closeDialog } = useDialog(() => {
+ *     console.log('Dialog closed');
+ *   });
+ *   
+ *   return (
+ *     <div>
+ *       <button onClick={openDialog}>Open Dialog</button>
+ *       {isDialogOpen && <Dialog onClose={closeDialog} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */ function useDialog(onAfterClose) {
     const [isDialogOpen, setIsDialogOpen] = useState(false);
     const [openDialog, closeDialog] = useSetUnset(setIsDialogOpen);
     const close = useCallback(()=>{