Array Wizard 📜

Description

Array Wizard is a utility library developed in TypeScript with support for React and Vite projects. This library provides useful methods for array manipulation, validations, string operations, among others.

Installation
Scripts
Usage
Methods
- Arrays
- Check
- Strings
- Timing
Contributing
License

Installation

To install the project dependencies, run:

npm install

Usage

To use this library, import the necessary methods into your TypeScript or JavaScript project.

import { sum, map, difference, flattering, intersection, uniqueElements, groupBy } from 'array-wizard';
import { isEmpty, isNullOrUndefined, isObject, isObjectLike, isString } from 'array-wizard';
import { capitalize, includes } from 'array-wizard';
import { throttle, debounce } from 'array-wizard';

Arrays

arraylable 🧩

Converts a value to an array if it is not already an array. If the value is null, it returns an empty array.
Example:

import { arraylable } from 'array-wizard';

console.log(arraylable(null)); // []
console.log(arraylable([1, 2, 3])); // [1, 2, 3]
console.log(arraylable('string')); // []

chunks 🍰

Splits an array into chunks of a specified size. Returns an array of arrays, each containing a subset of the original array.
Example:

import { chunks } from 'array-wizard';

console.log(chunks([1, 2, 3, 4, 5], 2)); // [[1, 2], [3, 4], [5]]
console.log(chunks([1, 2, 3], 5)); // [[1, 2, 3]]
console.log(chunks([], 2)); // []

difference ➖

Returns the elements of the first array that are not present in the second array.
Example:

import { difference } from 'array-wizard';

console.log(difference([1, 2, 3], [2, 3, 4])); // [1]
console.log(difference(['a', 'b', 'c'], ['b', 'd'])); // ['a', 'c']

flattering 🌟

Flattens an array up to a specified depth. Returns a new array with all sub-array elements concatenated into it recursively up to the specified depth.
Example:

import { flattering } from 'array-wizard';

console.log(flattering([1, [2, [3, [4]], 5]], 2)); // [1, 2, 3, [4], 5]
console.log(flattering([1, [2, [3, [4]], 5]], 1)); // [1, 2, [3, [4]], 5]

intersection ✴️

Returns an array containing the elements common to both arrays.
Exapmle:

import { intersection } from 'array-wizard';

console.log(intersection([1, 2, 3], [2, 3, 4])); // [2, 3]
console.log(intersection(['a', 'b', 'c'], ['b', 'c', 'd'])); // ['b', 'c']

group by ✴️

Groups elements of an array into an object according to a generated key, and returns said object.
Example:

import { groupBy } from 'array-wizard';

const array = [
  { category: 'fruit', name: 'apple' },
  { category: 'fruit', name: 'banana' },
  { category: 'vegetable', name: 'carrot' }
];

const result = groupBy(array, item => item.category);
console.log(result);
// {
//   fruit: [
//     { category: 'fruit', name: 'apple' },
//     { category: 'fruit', name: 'banana' }
//   ],
//   vegetable: [
//     { category: 'vegetable', name: 'carrot' }
//   ]
// }

map 🗺️

Applies a transformation function to each element of an array and returns a new array with the transformed elements.
Example:

import { map } from 'array-wizard';

const numbers = [1, 2, 3];
const doubled = map(numbers, x => x * 2);
console.log(doubled); // [2, 4, 6]

const words = ['hello', 'world'];
const lengths = map(words, x => x.length);
console.log(lengths); // [5, 5]

sum ➕

Sums all the numbers in an array and returns the total.
Example:

import { sum } from 'array-wizard';

console.log(sum([1, 2, 3, 4])); // 10
console.log(sum([10, -5, 5])); // 10

uniqueElements 🌈

Returns a new array with unique elements, removing duplicates from the original array.
Example:

import { uniqueElements } from 'array-wizard';

console.log(uniqueElements([1, 2, 2, 3, 4, 4])); // [1, 2, 3, 4]
console.log(uniqueElements(['a', 'b', 'b', 'c'])); // ['a', 'b', 'c']

Check

isEmpty 🏷️

Checks if a value is empty. For objects, it checks if the object has no own properties. For other types, it checks if the value is falsy.
Example:

import { isEmpty } from 'array-wizard';

/*
  @param value: Object | Array | string | number | boolean
  @returns boolean
*/

// Example usage
console.log(isEmpty({})); // true
console.log(isEmpty([])); // true
console.log(isEmpty('')); // true
console.log(isEmpty({ key: 'value' })); // false
console.log(isEmpty([1, 2, 3])); // false
console.log(isEmpty('string')); // false

isNullOrUndefined ❓

Checks if a value is null or undefined.
Example:

import { isNullOrUndefined } from 'array-wizard';

/*
  @param value: unknown
  @returns boolean
*/

// Example usage
console.log(isNullOrUndefined(null)); // true
console.log(isNullOrUndefined(undefined)); // true
console.log(isNullOrUndefined('string')); // false
console.log(isNullOrUndefined(123)); // false

isObject 🛠️

Checks if a value is an object. Returns false for null and non-object types.
Example:

import { isObject } from 'array-wizard';

/*
  @param value: unknown
  @returns boolean
*/

// Example usage
console.log(isObject({})); // true
console.log(isObject([])); // true
console.log(isObject(null)); // false
console.log(isObject('string')); // false
console.log(isObject(123)); // false

isObjectLike 🌐

Checks if a value is object-like. Excludes Date, RegExp, arrays, null, and other non-object types.
Example:

import { isObjectLike } from 'array-wizard';

/*
  @param value: unknown
  @returns boolean
*/

// Example usage
console.log(isObjectLike({})); // true
console.log(isObjectLike({ key: 'value' })); // true
console.log(isObjectLike([])); // false
console.log(isObjectLike(new Date())); // false
console.log(isObjectLike(/regex/)); // false

isString 🔤

Checks if a value is a string.
Example:

import { isString } from 'array-wizard';

/*
  @param value: unknown
  @returns boolean
*/

// Example usage
console.log(isString('hello')); // true
console.log(isString('')); // true
console.log(isString(123)); // false
console.log(isString({})); // false
console.log(isString([])); // false

Strings

capitalize 🔠

Capitalizes the first letter of each word in a string and converts the rest of the letters to lowercase.
Example:

import { capitalize } from 'array-wizard';

/*
  @param s: string
  @returns string
*/

// Example usage
console.log(capitalize('hello world')); // "Hello World"
console.log(capitalize('javaScript is fun')); // "Javascript Is Fun"
console.log(capitalize('capitalize this STRING')); // "Capitalize This String"
console.log(capitalize('already Capitalized')); // "Already Capitalized"
console.log(capitalize('')); // ""
console.log(capitalize('a')); // "A"
console.log(capitalize(123 as any)); // 123 (since 123 is not a string)

includes 🔍

Checks if a string contains a specified substring. Returns false if either argument is not a string.
Example:

import { includes } from 'array-wizard';

/*
  @param stringValue: string
  @param searchableValue: string
  @returns boolean
*/

// Example usage
console.log(includes('hello world', 'world')); // true
console.log(includes('hello world', 'WORLD')); // false
console.log(includes('JavaScript is fun', 'is')); // true
console.log(includes('JavaScript is fun', 'funny')); // false
console.log(includes('TypeScript', 'script')); // false
console.log(includes('TypeScript', 'Script')); // true
console.log(includes('TypeScript', 'Type')); // true
console.log(includes('TypeScript', '')); // true
console.log(includes('', '')); // true
console.log(includes('', 'empty')); // false
console.log(includes(123 as any, '23')); // false (since 123 is not a string)

Timing

throttle ⏳

Creates a throttled function that only invokes the provided function at most once per every specified delay period.
Example:

import { throttle } from 'array-wizard';

// Function to handle button click
const handleClick = (): void => {
  console.log('Button clicked');
  // Handle button click here
};

// Throttled version of the handleClick function
const throttledHandleClick = throttle(handleClick, 800);

// Simulate button clicks
throttledHandleClick();
throttledHandleClick();
throttledHandleClick();
// Only the first call will be executed immediately,
// subsequent calls will be ignored for the next 800ms

// Example usage in a React component
import React from 'react';

const MyComponent: React.FC = () => {
  return (
    <button onClick={throttledHandleClick}>
      Click me
    </button>
  );
};

export default MyComponent;

debounce ⌛

Creates a debounced function that delays the invocation of the provided function until after a specified delay period has elapsed since the last time the debounced function was invoked.
Example:

import React, { useState, useCallback } from 'react';
import { debounce } from 'array-wizard';

// Function to fetch search results
const fetchResults = (query) => {
  console.log(`Fetching results for ${query}`);
};

// Debounced version of the fetchResults function
const debouncedFetchResults = debounce(fetchResults, 300);

const SearchComponent: React.FC = () => {
  const [query, setQuery] = useState('');

  // Callback
  const handleInputChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
    const newQuery = event.target.value;
    setQuery(newQuery);
    debouncedFetchResults(newQuery);
  }, [debouncedFetchResults]);

  return (
    <input
      type="text"
      value={query}
      onChange={handleInputChange}
      placeholder="Search..."
    />
  );
};

export default SearchComponent;

Contributing

To contribute to this project, please open an issue or pull request on GitHub. All contributions are welcome.

License

This project is licensed under the MIT License.

array-wizard

Array Wizard 📜

Description

Table of Contents

Installation

Usage

Arrays

Check

Strings

Timing

Contributing

License

Dependents (0)

Package Sidebar

Install

Weekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

array-wizard

Array Wizard 📜

Description

Table of Contents

Installation

Usage

Arrays

Check

Strings

Timing

Contributing

License

Dependents (0)

Package Sidebar

Install

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads