defs.kit

A lightweight and performant collection of essential JavaScript utility functions.

defs.kit aims to provide commonly used utility functions in a small and efficient package, avoiding unnecessary bloat and dependencies. It's designed to be a drop-in replacement or supplement to larger utility libraries like Lodash or Underscore when you only need a subset of their functionality.

Installation

npm install defs.kit@latest

Usage

const fn = require('defs.kit');
// import fn from 'defs.kit'; // If using esm

// Array functions
console.log(fn.compact([0, 1, false, 2, '', 3])); // Output: [1, 2, 3]
console.log(fn.first([1, 2, 3])); // Output: 1
console.log(fn.last([1, 2, 3], 2)); // Output: [2, 3]
console.log(fn.flatten([1, [2, [3, 4]], 5])); // Output: [1, 2, 3, 4, 5]
console.log(fn.chunk([1, 2, 3, 4, 5], 2)); // Output: [[1, 2], [3, 4], [5]]
console.log(fn.uniq([1, 2, 2, 3, 1])); // Output: [1, 2, 3]
console.log(fn.filter([1, 2, 3, 4], (x) => x % 2 === 0)); // Output: [2, 4]
console.log(fn.reduce([1, 2, 3], (sum, n) => sum + n, 0)); // Output: 6

// Object functions
const obj1 = { a: 1, b: { c: 2 } };
const obj2 = { a: 1, b: { c: 2 } };
console.log(fn.isEqual(obj1, obj2)); // Output: true
console.log(fn.keys({ a: 1, b: 2 })); // Output: ['a', 'b']
console.log(fn.values({ a: 1, b: 2 })); // Output: [1, 2]
console.log(fn.assign({ a: 1 }, { b: 2 }, { c: 3 })); // Output: { a: 1, b: 2, c: 3 }

// Collection functions
fn.each([1, 2, 3], (num) => console.log(num * 2)); // Output: 2, 4, 6
console.log(fn.map([1, 2, 3], (num) => num * 2)); // Output: [2, 4, 6]
console.log(fn.find([1, 2, 3, 4], (x) => x > 2)); // Output: 3
console.log(fn.some([1, 2, 3, 4], (x) => x > 3)); // Output: true
console.log(fn.every([2, 4, 6], (x) => x % 2 === 0)); // Output: true

// String functions
console.log(fn.trim("  hello  ")); // Output: "hello"
console.log(fn.capitalize("hello")); // Output: "Hello"
console.log(fn.kebabCase("ConvertStringToKebabCase")); // Output: convert-string-to-kebab-case

// Object/Collection functions (path access)
const myObj = { a: { b: { c: 'value' } } };
console.log(fn.get(myObj, 'a.b.c')); // Output: "value"
console.log(fn.get(myObj, 'a.d.e', 'default')); // Output: "default"
console.log(fn.has(myObj, 'a.b.c')); // Output: true

// Number functions
console.log(fn.random(5, 10)); // Output: A random number between 5 and 10
console.log(fn.range(4)); // Output: [0, 1, 2, 3]

// Function functions
const debouncedLog = fn.debounce(() => console.log("Debounced!"), 1000);
debouncedLog(); debouncedLog(); // Only the last call will execute after 1000ms

let throttledCount = 0;
const throttledIncrement = fn.throttle(() => throttledCount++, 1000);
throttledIncrement(); throttledIncrement();
setTimeout(throttledIncrement, 500);
setTimeout(() => console.log("Throttled Count:", throttledCount), 1500); // Output: Throttled Count: 1 (after 1.5 seconds)

API

Array

• compact(array): Creates an array with all falsey values removed (false, null, 0, "", undefined, and NaN).

  fn.compact([0, 1, false, 2, '', 3]); // Output: [1, 2, 3]

• first(array, n = 1): Gets the first element of array. If n is provided, gets the first n elements.

  fn.first([1, 2, 3]); // Output: 1
  fn.first([1, 2, 3], 2); // Output: [1, 2]
  fn.first([], 2); // Output: []
  fn.first([1], 0); // Output: []

• last(array, n = 1): Gets the last element of array. If n is provided, gets the last n elements.

  fn.last([1, 2, 3]); // Output: 3
  fn.last([1, 2, 3], 2); // Output: [2, 3]
  fn.last([], 2); // Output: []
  fn.last([1], 0); // Output: []

• flatten(array): Recursively flattens array a single level.

  fn.flatten([1, [2, [3, 4]], 5]); // Output: [1, 2, 3, 4, 5]

• chunk(array, size = 1): Splits array into chunks of size size.

  fn.chunk([1, 2, 3, 4, 5], 2); // Output: [[1, 2], [3, 4], [5]]
  fn.chunk([1, 2, 3], 0); // Output: []
  fn.chunk([1, 2, 3], -1); // Output: []
  fn.chunk([], 2); // Output: []

• uniq(array): Creates a duplicate-free version of array.

  fn.uniq([1, 2, 2, 3, 1]); // Output: [1, 2, 3]

• filter(array, predicate): Creates a new array with all elements that pass the test implemented by the provided function.

  fn.filter([1, 2, 3, 4], (x) => x % 2 === 0); // Output: [2, 4]

• reduce(array, iteratee, accumulator): Applies a function against an accumulator and each element in the array (from left to right) to reduce it to a single value.

  fn.reduce([1, 2, 3], (sum, n) => sum + n, 0); // Output: 6
  fn.reduce([1, 2, 3], (sum, n) => sum + n); // Output: 6

Object

• isEqual(a, b): Performs a deep comparison between two values to determine if they are equivalent.

  const obj1 = { a: 1, b: { c: 2 } };
  const obj2 = { a: 1, b: { c: 2 } };
  fn.isEqual(obj1, obj2); // Output: true
  fn.isEqual(1, "1"); // Output: false

• keys(object): Creates an array of the own enumerable property names of object.

  fn.keys({ a: 1, b: 2 }); // Output: ['a', 'b']
  fn.keys(null); // Output: []

• values(object): Creates an array of the own enumerable property values of object.

  fn.values({ a: 1, b: 2 }); // Output: [1, 2]
  fn.values(null); // Output: []

• assign(...objects): Assigns own enumerable properties of source objects to the destination object.

  fn.assign({ a: 1 }, { b: 2 }, { c: 3 }); // Output: { a: 1, b: 2, c: 3 }

Collection

• each(collection, iteratee): Iterates over elements of collection, invoking iteratee for each element.

  fn.each([1, 2, 3], (num) => console.log(num * 2)); // Output: 2, 4, 6
  fn.each({a:1, b:2}, (val, key) => console.log(key, val * 2)); // Output: a 2, b 4

• map(collection, iteratee): Creates an array of values by running each element in collection through iteratee.

  fn.map([1, 2, 3], (num) => num * 2); // Output: [2, 4, 6]
  fn.map({a:1, b:2}, (val, key) => val * 2); // Output: [2, 4]

• find(collection, predicate): Returns the first element in collection that passes the truth test predicate.

  fn.find([1, 2, 3, 4], (x) => x > 2); // Output: 3
  fn.find({a:1, b:2, c:3}, (val, key) => val === 2); // Output: 2
  fn.find([1, 2, 3, 4], (x) => x > 5); // Output: undefined

• some(collection, predicate): Checks if predicate returns truthy for any element of collection.

  fn.some([1, 2, 3, 4], (x) => x > 3); // Output: true
  fn.some([1, 2, 3, 4], (x) => x > 5); // Output: false

• every(collection, predicate): Checks if predicate returns truthy for all elements of collection.

  fn.every([2, 4, 6], (x) => x % 2 === 0); // Output: true
  fn.every([2, 3, 6], (x) => x % 2 === 0); // Output: false

String

• trim(string): Removes whitespace from both ends of string.

  fn.trim("  hello  "); // Output: "hello"
  fn.trim(null); // Output: ""

• capitalize(string): Converts the first character of string to upper case and the remaining to lower case.

  fn.capitalize("hello"); // Output: "Hello"
  fn.capitalize(null); // Output: ""

• kebabCase(string): Converts string to kebab case.

  fn.kebabCase("ConvertStringToKebabCase"); // Output: convert-string-to-kebab-case
  fn.kebabCase("ABCDef"); // Output: a-b-c-def
  fn.kebabCase(null); // Output: ""

Number

• random(min = 0, max = 1): Generates a random integer between min (inclusive) and max (inclusive).

  fn.random(5, 10); // Output: A random number between 5 and 10 (inclusive)

• range(start, end, step = 1): Creates an array of integers from start (inclusive) to end (exclusive), incrementing by step. If end is omitted, it defaults to start, and start defaults to 0.

  fn.range(4); // Output: [0, 1, 2, 3]
  fn.range(2, 7); // Output: [2, 3, 4, 5, 6]
  fn.range(0, 10, 2); // Output: [0, 2, 4, 6, 8]

Function

• debounce(func, wait): Creates a debounced function that delays invoking func until after wait milliseconds have elapsed since the last time the debounced function was invoked. Useful for handling events like resizing or scrolling.

  const debouncedLog = fn.debounce(() => console.log("Debounced!"), 1000);
  debouncedLog(); // This call will be delayed
  debouncedLog(); // This call will cancel the previous one and be delayed
  // Only the last call will execute after 1000ms

• throttle(func, wait): Creates a throttled function that invokes func at most once per wait milliseconds. Useful for limiting the rate of execution of a function, such as during rapid events.

  let throttledCount = 0;
  const throttledIncrement = fn.throttle(() => throttledCount++, 1000);
  throttledIncrement(); // This call will execute immediately
  throttledIncrement(); // This call will be ignored
  setTimeout(throttledIncrement, 500); // This call will be ignored
  setTimeout(() => console.log("Throttled Count:", throttledCount), 1500); // Output: Throttled Count: 1 (after ~1.5 seconds)

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

Apache-2.0

Support

For help or support, join our community on Discord.