@leancodepl/utils 8.4.0 → 8.5.1

package/package.json

@@ -1,24 +1,55 @@
 {
   "name": "@leancodepl/utils",
-  "version": "8.4.0",
+  "version": "8.5.1",
   "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {
-    "@leancodepl/api-date": "8.4.0",
+    "@leancodepl/api-date": "8.5.1",
     "tiny-invariant": ">=1.3.1"
   },
   "peerDependencies": {
     "react": "*"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leancodepl/js_corelibrary.git",
+    "directory": "packages/utils"
+  },
+  "homepage": "https://github.com/leancodepl/js_corelibrary",
+  "bugs": {
+    "url": "https://github.com/leancodepl/js_corelibrary/issues"
+  },
+  "description": "Common utility functions and React hooks for web applications",
+  "keywords": [
+    "utilities",
+    "react",
+    "hooks",
+    "helpers",
+    "typescript",
+    "javascript",
+    "leancode"
+  ],
+  "author": {
+    "name": "LeanCode",
+    "url": "https://leancode.co"
+  },
+  "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": {
       "module": "./index.esm.js",
-      "types": "./index.esm.d.ts",
+      "types": "./index.d.ts",
       "import": "./index.cjs.mjs",
       "default": "./index.cjs.js"
     }
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",
-  "types": "./index.esm.d.ts"
+  "types": "./index.d.ts"
 }

package/src/lib/addPrefix.d.ts

@@ -1,5 +1,20 @@
 type PrefixWith<T, TPrefix extends string> = {
     [K in keyof T as K extends string ? `${TPrefix}${K}` : never]: T[K];
 };
+/**
+ * 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' }
+ * ```
+ */
 export declare function addPrefix<T extends object, TPrefix extends string>(object: T, prefix: TPrefix): PrefixWith<T, TPrefix>;
 export {};

package/src/lib/assertDefined.d.ts

@@ -1 +1,17 @@
+/**
+ * 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
+ * }
+ * ```
+ */
 export declare function assertDefined<T>(value: T | undefined, message?: string): asserts value is T;

package/src/lib/assertNotEmpty.d.ts

@@ -1 +1,17 @@
+/**
+ * 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
+ * }
+ * ```
+ */
 export declare function assertNotEmpty<T>(value: T | null | undefined, message?: string): asserts value is T;

package/src/lib/assertNotNull.d.ts

@@ -1 +1,17 @@
+/**
+ * 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
+ * }
+ * ```
+ */
 export declare function assertNotNull<T>(value: T | null, message?: string): asserts value is T;

package/src/lib/downloadFile.d.ts

@@ -1,6 +1,29 @@
 type DownloadFileOptions = {
     name?: string;
 };
+/**
+ * Downloads a file from a URL by creating a temporary download link.
+ *
+ * @param url - The URL to download from
+ * @param options - Optional download options including filename
+ * @example
+ * ```typescript
+ * // Download from URL
+ * downloadFile('https://example.com/file.pdf', { name: 'document.pdf' });
+ * ```
+ */
 export declare function downloadFile(url: string, options?: DownloadFileOptions): void;
+/**
+ * Downloads a file from a Blob or MediaSource object by creating a temporary object URL.
+ *
+ * @param obj - The Blob or MediaSource object to download
+ * @param options - Optional download options including filename
+ * @example
+ * ```typescript
+ * // Download from Blob
+ * const blob = new Blob(['Hello World'], { type: 'text/plain' });
+ * downloadFile(blob, { name: 'hello.txt' });
+ * ```
+ */
 export declare function downloadFile(obj: Blob | MediaSource, options?: DownloadFileOptions): void;
 export {};

package/src/lib/ensureDefined.d.ts

@@ -1 +1,17 @@
+/**
+ * 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
+ * }
+ * ```
+ */
 export declare function ensureDefined<T>(value: T | undefined, message?: string): T;

package/src/lib/ensureNotEmpty.d.ts

@@ -1 +1,17 @@
+/**
+ * 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
+ * }
+ * ```
+ */
 export declare function ensureNotEmpty<T>(value: T | null | undefined, message?: string): T;

package/src/lib/ensureNotNull.d.ts

@@ -1 +1,18 @@
+/**
+ * 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
+ * }
+ * ```
+ */
 export declare function ensureNotNull<T>(value: T | null, message?: string): T;

package/src/lib/hooks/useBoundRunInTask.d.ts

@@ -1,4 +1,30 @@
 type AnyFunction = (...args: any[]) => any;
+/**
+ * React hook for bound task execution with loading state.
+ * Creates a wrapped version of a function that automatically tracks loading state.
+ *
+ * @template T - The type of the function being wrapped
+ * @param block - The function to wrap with task tracking
+ * @returns A tuple containing [isLoading: boolean, wrappedFunction: T]
+ * @example
+ * ```typescript
+ * function UserProfile({ userId }: { userId: string }) {
+ *   const [user, setUser] = useState<User | null>(null);
+ *
+ *   const [isLoading, loadUser] = useBoundRunInTask(async () => {
+ *     const userData = await fetchUser(userId);
+ *     setUser(userData);
+ *   });
+ *
+ *   useEffect(() => {
+ *     loadUser();
+ *   }, [userId, loadUser]);
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *   return <div>{user?.name}</div>;
+ * }
+ * ```
+ */
 export declare function useBoundRunInTask<T extends AnyFunction>(block: T): [boolean, T];
 export declare function useBoundRunInTask<T extends AnyFunction>(block: T | undefined): [boolean, T | undefined];
 export {};

package/src/lib/hooks/useDialog.d.ts

@@ -1,3 +1,25 @@
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
 export declare function useDialog(onAfterClose?: () => void): {
     isDialogOpen: boolean;
     openDialog: () => void;

package/src/lib/hooks/useKeyByRoute.d.ts

@@ -1 +1,29 @@
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
 export declare function useKeyByRoute<TKey extends string>(routeMatches: Record<TKey, (object | null)[] | never | object | null>): TKey[];

package/src/lib/hooks/useRunInTask.d.ts

@@ -1 +1,25 @@
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
 export declare function useRunInTask(): readonly [boolean, <T>(task: () => Promise<T> | T) => Promise<T>];

package/src/lib/hooks/useSetUnset.d.ts

@@ -1,2 +1,23 @@
 import { Dispatch, SetStateAction } from "react";
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
 export declare function useSetUnset(set: Dispatch<SetStateAction<boolean>>): readonly [() => void, () => void];

package/src/lib/transformDeep.d.ts

@@ -1,3 +1,29 @@
 import { CapitalizeDeep, UncapitalizeDeep } from "./types";
+/**
+ * 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' } }
+ * ```
+ */
 export declare function uncapitalizeDeep<T>(value: T): UncapitalizeDeep<T>;
+/**
+ * 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' } }
+ * ```
+ */
 export declare function capitalizeDeep<T>(value: T): CapitalizeDeep<T>;

package/src/lib/transformFirst.d.ts

@@ -1,2 +1,24 @@
+/**
+ * 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'
+ * ```
+ */
 export declare function toLowerFirst(value: string): string;
+/**
+ * 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'
+ * ```
+ */
 export declare function toUpperFirst(value: string): string;

package/index.esm.d.ts

@@ -1 +0,0 @@
-export * from "./src/index";