A collection of essential utility functions for mathematical operations, color manipulation, performance optimization, and array processing in TypeScript/JavaScript applications.
- Mathematical Operations: Range mapping, interpolation, clamping
- Array Processing: Min/max extraction with custom selectors
- Color Manipulation: RGB/RGBA color interpolation
- Performance Utilities: Debouncing and throttling functions
- Non-linear Mapping: Advanced value mapping through custom ranges
npm install @petitkit/utilsimport {
mapRange,
mapRangeClamp,
lerp,
clamp,
nonLinearMap,
extend,
min,
max,
mergeRGB,
debounce,
throttle,
sum,
sumObject,
deepEqual,
forEach
} from '@petitkit/utils';Maps a value from one range to another without clamping.
// Map 50 from range [0, 100] to range [0, 1]
const result = mapRange(0, 100, 50, 0, 1); // 0.5
// Map mouse position to rotation angle
const angle = mapRange(0, window.innerWidth, mouseX, 0, 360);Parameters:
inMin(number): Input range minimuminMax(number): Input range maximuminput(number): Value to mapoutMin(number): Output range minimumoutMax(number): Output range maximum
Returns: Mapped value (number)
Maps a value from one range to another with automatic clamping to output bounds.
// Value gets clamped to output range
const result = mapRangeClamp(0, 100, 150, 0, 1); // 1 (clamped)
const result2 = mapRangeClamp(0, 100, -10, 0, 1); // 0 (clamped)Linear interpolation between two values.
// 50% between 0 and 100
const result = lerp(0, 100, 0.5); // 50
// Smooth animation
const currentValue = lerp(currentValue, targetValue, 0.1);Parameters:
start(number): Starting valueend(number): Ending valueamt(number): Interpolation amount (0-1)
Constrains a value between minimum and maximum bounds.
const result = clamp(0, -5, 100); // 0
const result2 = clamp(0, 150, 100); // 100
const result3 = clamp(0, 50, 100); // 50Maps a value through non-linear ranges using input/output arrays.
// Create easing curve
const input = [0, 25, 50, 75, 100];
const output = [0, 10, 60, 90, 100];
const result = nonLinearMap(30, input, output); // Interpolated value
// Volume curve mapping
const volumes = [0, 0.1, 0.3, 0.7, 1.0];
const positions = [0, 20, 40, 80, 100];
const volume = nonLinearMap(sliderValue, positions, volumes);Returns [min, max] values from an array using an optional selector function.
const numbers = [1, 5, 3, 9, 2];
const [min, max] = extend(numbers); // [1, 9]
// With objects
const items = [{ price: 10 }, { price: 25 }, { price: 5 }];
const [minPrice, maxPrice] = extend(items, item => item.price); // [5, 25]Get minimum or maximum values with optional selector functions.
const numbers = [1, 5, 3, 9, 2];
const minimum = min(numbers); // 1
const maximum = max(numbers); // 9
// With selector
const users = [{ age: 25 }, { age: 30 }, { age: 20 }];
const youngest = min(users, user => user.age); // 20
const oldest = max(users, user => user.age); // 30Interpolates between two RGB/RGBA colors based on progress (0-1).
// Basic RGB interpolation
const color = mergeRGB('rgb(255, 0, 0)', 'rgb(0, 255, 0)', 0.5);
// Result: 'rgb(128, 128, 0)'
// RGBA support
const color2 = mergeRGB('rgba(255, 0, 0, 1)', 'rgba(0, 255, 0, 0.5)', 0.3);
// Animation example
const animatedColor = mergeRGB(startColor, endColor, animationProgress);
element.style.backgroundColor = animatedColor;Converts a hex color code to RGBA format.
// Basic hex to rgba conversion
const rgba = hexToRgba('#ff0000'); // 'rgba(255, 0, 0, 1)'
// With custom alpha
const semiTransparent = hexToRgba('#00ff00', 0.5); // 'rgba(0, 255, 0, 0.5)'Parameters:
hex(string): Hex color code (e.g., '#ff0000')alpha(number, optional): Alpha value between 0 and 1 (default: 1)
Returns: RGBA color string
Creates a debounced function that delays execution until after wait milliseconds.
// Debounce search input
const debouncedSearch = debounce((query) => {
performSearch(query);
}, 300);
// Debounce window resize
const debouncedResize = debounce(() => {
handleResize();
}, 250);
window.addEventListener('resize', debouncedResize);Creates a throttled function that executes at most once per wait milliseconds.
// Throttle scroll handler
const throttledScroll = throttle(() => {
updateScrollPosition();
}, 16); // ~60fps
// Throttle mouse move
const throttledMouseMove = throttle((e) => {
updateCursor(e.clientX, e.clientY);
}, 10);
window.addEventListener('scroll', throttledScroll);Calculates the sum of all numbers in an array.
const numbers = [1, 2, 3, 4, 5];
const total = sum(numbers); // 15
// Calculate total price
const prices = [10.99, 25.50, 5.99];
const totalPrice = sum(prices); // 42.48Calculates the sum of all numeric values in an object.
const scores = { math: 85, science: 92, english: 78 };
const totalScore = sumObject(scores); // 255
// Handle undefined/null objects
const emptySum = sumObject(null); // 0Adds event listeners to an element or array of elements.
// Single event
addEvent(button, 'click', handleClick);
// Multiple events
addEvent(element, ['mouseenter', 'mouseleave'], handleHover);
// Multiple elements
addEvent([button1, button2], 'click', handleClick);Parameters:
element(HTMLElement | HTMLElement[]): Target element(s)events(string | string[]): Event name(s) to listen forcallback(function): Event handler function
Adds click and touch event listeners to an element or array of elements.
// Single element
click(button, handleClick);
// Multiple elements
click([button1, button2], handleClick);Parameters:
element(HTMLElement | HTMLElement[]): Target element(s)callback(function): Event handler function
Stops event propagation.
click(button, (e) => {
stopPropagation(e);
// Event won't bubble up
});Parameters:
event(Event): Event object
Returns the first element of an array.
const numbers = [1, 2, 3, 4, 5];
const firstNumber = first(numbers); // 1Parameters:
array(any[]): Input array
Returns: First element of the array
Returns the last element of an array.
const numbers = [1, 2, 3, 4, 5];
const lastNumber = last(numbers); // 5Parameters:
array(any[]): Input array
Returns: Last element of the array
Rounds a number to a specified number of decimal places.
const pi = 3.14159;
const rounded = numFixedX(pi, 2); // 3.14
const rounded2 = numFixedX(pi); // 3.14 (default 2 decimal places)Parameters:
num(number): Number to roundx(number, optional): Number of decimal places (default: 2)
Returns: Rounded number
Converts a JavaScript object to CSS style string.
const styles = {
backgroundColor: 'red',
fontSize: '16px',
marginTop: '10px'
};
const cssString = objectToStyle(styles);
// Result: 'background-color: red; font-size: 16px; margin-top: 10px'Parameters:
object(Record<string, any>): Object containing CSS properties
Returns: CSS style string
Performs deep equality comparison between two values, including nested objects and arrays.
// Simple values
deepEqual(5, 5); // true
deepEqual('hello', 'hello'); // true
deepEqual(5, '5'); // false
// Objects
deepEqual({ a: 1, b: 2 }, { a: 1, b: 2 }); // true
deepEqual({ a: 1, b: 2 }, { b: 2, a: 1 }); // true (order doesn't matter)
deepEqual({ a: 1, b: 2 }, { a: 1, b: 3 }); // false
// Arrays
deepEqual([1, 2, 3], [1, 2, 3]); // true
deepEqual([1, 2, 3], [1, 3, 2]); // false (order matters for arrays)
// Nested structures
deepEqual({ a: [1, 2], b: { c: 3 } }, { a: [1, 2], b: { c: 3 } }); // trueParameters:
a(any): First value to compareb(any): Second value to compare
Returns: Boolean indicating if the values are deeply equal
Iterates over arrays or objects, executing a callback function for each element.
// Array iteration
const numbers = [1, 2, 3, 4, 5];
forEach(numbers, (value, index, array) => {
console.log(`Index ${index}: ${value}`);
});
// Object iteration
const person = { name: 'John', age: 30, city: 'NYC' };
forEach(person, (value, key, object) => {
console.log(`${key}: ${value}`);
});
// Early termination (forEach doesn't support break, but you can return early)
forEach(numbers, (value, index) => {
if (value > 3) return; // Skip remaining iterations
console.log(value);
});Parameters:
collection(any[] | object): Array or object to iterate overcallback(function): Function to execute for each element- For arrays:
callback(value, index, array) - For objects:
callback(value, key, object)
- For arrays:
// Smooth value transitions
let currentValue = 0;
const targetValue = 100;
function animate() {
currentValue = lerp(currentValue, targetValue, 0.1);
element.style.transform = `translateX(\${currentValue}px)`;
if (Math.abs(currentValue - targetValue) > 0.1) {
requestAnimationFrame(animate);
}
}// Map viewport width to font size
const fontSize = mapRangeClamp(320, 1920, window.innerWidth, 14, 24);
document.body.style.fontSize = `\${fontSize}px`;
// Responsive spacing
const padding = mapRange(0, 1000, window.innerWidth, 10, 50);// Normalize data for charts
const data = [10, 25, 15, 30, 20];
const [minVal, maxVal] = extend(data);
const normalizedData = data.map(value =>
mapRange(minVal, maxVal, value, 0, 100)
);// Optimize expensive operations
const expensiveOperation = debounce(() => {
// Heavy computation here
processLargeDataset();
}, 500);
const smoothScrollHandler = throttle((e) => {
updateParallaxElements(e.scrollY);
}, 16);All functions include full TypeScript type definitions:
// Type-safe usage
const result: number = mapRange(0, 100, 50, 0, 1);
const colors: string = mergeRGB('rgb(255,0,0)', 'rgb(0,255,0)', 0.5);
// Generic array functions
interface Item { value: number; }
const items: Item[] = [{ value: 1 }, { value: 5 }];
const maxValue: number = max(items, item => item.value);
// Deep equality with type safety
const isEqual: boolean = deepEqual({ a: 1, b: 2 }, { a: 1, b: 2 });
// Type-safe iteration
interface User { name: string; age: number; }
const users: User[] = [{ name: 'John', age: 30 }, { name: 'Jane', age: 25 }];
forEach(users, (user: User, index: number) => {
console.log(`${index}: ${user.name} is ${user.age}`);
});- ES6+ environments
- Node.js 12+
- All modern browsers
- TypeScript 4.0+
MIT License