es-toolkit 0.0.1

package/src/function/debounce.spec.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi } from 'vitest';
+import { debounce } from './debounce'; // adjust the import path as necessary
+import { delay } from '../promise';
+
+describe('debounce', () => {
+  it('should debounce function calls', async () => {
+    const func = vi.fn();
+    const waitMs = 50;
+    const debouncedFunc = debounce(func, waitMs);
+
+    debouncedFunc();
+    debouncedFunc();
+    debouncedFunc();
+
+    await delay(waitMs * 2)
+
+    expect(func).toHaveBeenCalledTimes(1);
+  });
+
+  it('should delay the function call by the specified wait time', async () => {
+    const func = vi.fn();
+    const waitMs = 50;
+    const debouncedFunc = debounce(func, waitMs);
+
+    debouncedFunc();
+    await delay(waitMs / 2);
+    expect(func).not.toHaveBeenCalled();
+
+    await delay(waitMs / 2 + 1);
+    expect(func).toHaveBeenCalledTimes(1);
+  });
+
+  it('should reset the wait time if called again before wait time ends', async () => {
+    const func = vi.fn();
+    const waitMs = 50;
+    const debouncedFunc = debounce(func, waitMs);
+
+    debouncedFunc();
+    await delay(waitMs / 2);
+    debouncedFunc();
+    await delay(waitMs / 2);
+    debouncedFunc();
+    await delay(waitMs / 2);
+    debouncedFunc();
+
+    expect(func).not.toHaveBeenCalled();
+
+    await delay(waitMs + 1);
+    expect(func).toHaveBeenCalledTimes(1);
+  });
+
+  it('should cancel the debounced function call', async () => {
+    const func = vi.fn();
+    const waitMs = 50;
+    const debouncedFunc = debounce(func, waitMs);
+
+    debouncedFunc();
+    debouncedFunc.cancel();
+    await delay(waitMs);
+
+    expect(func).not.toHaveBeenCalled();
+  });
+
+  it('should work correctly if the debounced function is called after the wait time', async () => {
+    const func = vi.fn();
+    const waitMs = 50;
+    const debouncedFunc = debounce(func, waitMs);
+
+    debouncedFunc();
+    await delay(waitMs + 1);
+    debouncedFunc();
+    await delay(waitMs + 1);
+
+    expect(func).toHaveBeenCalledTimes(2);
+  });
+});

package/src/function/debounce.ts

@@ -0,0 +1,42 @@
+/**
+ * Creates a debounced function that delays invoking the provided function until after `waitMs` milliseconds
+ * have elapsed since the last time the debounced function was invoked. The debounced function also has a `cancel`
+ * method to cancel any pending execution.
+ *
+ * @param {() => void} func - The function to debounce.
+ * @param {number} waitMs - The number of milliseconds to delay.
+ * @returns {{ (): void; cancel: () => void }} A new debounced function with a `cancel` method.
+ *
+ * @example
+ * const debouncedFunction = debounce(() => {
+ *   console.log('Function executed');
+ * }, 1000);
+ *
+ * // Will log 'Function executed' after 1 second if not called again in that time
+ * debouncedFunction();
+ * 
+ * // Will not log anything as the previous call is canceled
+ * debouncedFunction.cancel();
+ */
+export function debounce(func: () => void, waitMs: number) {
+  let timeoutId: number | NodeJS.Timeout | null = null;
+
+  const debounced = function () {
+    if (timeoutId != null) {
+      clearTimeout(timeoutId);
+    }
+    
+    
+    timeoutId = setTimeout(() => {
+      func();
+    }, waitMs);
+  };
+
+  debounced.cancel = function () {
+    if (timeoutId != null) {
+      clearTimeout(timeoutId);
+    }
+  }  
+
+  return debounced;
+}

package/src/function/index.ts

@@ -0,0 +1,3 @@
+export { debounce } from './debounce';
+export { once } from './once';
+export { throttle } from './throttle';

package/src/function/once.spec.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect, vi } from 'vitest';
+import { once } from './once'; // adjust the import path as necessary
+
+describe('once', () => {
+  it('should call the function only once', () => {
+    const func = vi.fn(() => 42);
+    const onceFunc = once(func);
+
+    expect(onceFunc()).toBe(42);
+    expect(onceFunc()).toBe(42);
+    expect(func).toHaveBeenCalledTimes(1);
+  });
+
+  it('should work with functions returning undefined', () => {
+    const func = vi.fn(() => undefined);
+    const onceFunc = once(func);
+
+    expect(onceFunc()).toBeUndefined();
+    expect(onceFunc()).toBeUndefined();
+    expect(func).toHaveBeenCalledTimes(1);
+  });
+
+  it('should handle functions with no return value', () => {
+    const func = vi.fn(() => { console.log('Side effect'); });
+    const onceFunc = once(func);
+
+    onceFunc();
+    onceFunc();
+    expect(func).toHaveBeenCalledTimes(1);
+  });
+});

package/src/function/once.ts

@@ -0,0 +1,34 @@
+/**
+ * Creates a function that is restricted to invoking the provided function `func` once.
+ * Repeated calls to the function will return the value from the first invocation.
+ *
+ * @template F - The type of the function to be invoked once.
+ * @param {F} func - The function to restrict.
+ * @returns {F} A new function that invokes `func` once and caches the result.
+ *
+ * @example
+ * const initialize = once(() => {
+ *   console.log('Initialized!');
+ *   return true;
+ * });
+ * 
+ * initialize(); // Logs: 'Initialized!' and returns true
+ * initialize(); // Returns true without logging
+ */
+export function once<F extends () => any>(func: F): F {
+  let called = false;
+  let cache: ReturnType<F> | undefined;
+
+  return function () {
+    if (called) {
+      return cache;
+    }
+
+    const result = func();
+
+    called = true;
+    cache = result;
+
+    return result;
+  } as F;
+}

package/src/function/throttle.spec.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect, vi } from 'vitest';
+import { throttle } from './throttle';
+import { delay } from '../promise';
+
+describe('throttle', () => {
+  it('should throttle function calls', async () => {
+    const func = vi.fn();
+    const throttledFunc = throttle(func, 100);
+
+    throttledFunc();
+    throttledFunc();
+    throttledFunc();
+
+    expect(func).toHaveBeenCalledTimes(1);
+  });
+
+  it('should execute the function immediately if not called within the wait time', async () => {
+    const func = vi.fn();
+    const waitMs = 50;
+    const throttledFunc = throttle(func, waitMs);
+
+    throttledFunc();
+    await delay(waitMs / 2);
+    throttledFunc();
+
+    expect(func).toHaveBeenCalledTimes(1);
+
+    await delay(waitMs / 2 + 1);
+    throttledFunc();
+    expect(func).toHaveBeenCalledTimes(2);
+  });
+});

package/src/function/throttle.ts

@@ -0,0 +1,39 @@
+/**
+ * Creates a throttled function that only invokes the provided function at most once
+ * per every `throttleMs` milliseconds. Subsequent calls to the throttled function
+ * within the wait time will not trigger the execution of the original function.
+ *
+ * @param {() => void} func - The function to throttle.
+ * @param {number} throttleMs - The number of milliseconds to throttle executions to.
+ * @returns {() => void} A new throttled function.
+ *
+ * @example
+ * const throttledFunction = throttle(() => {
+ *   console.log('Function executed');
+ * }, 1000);
+ *
+ * // Will log 'Function executed' immediately
+ * throttledFunction();
+ * 
+ * // Will not log anything as it is within the throttle time
+ * throttledFunction();
+ * 
+ * // After 1 second
+ * setTimeout(() => {
+ *   throttledFunction(); // Will log 'Function executed'
+ * }, 1000);
+ */
+export function throttle(func: () => void, throttleMs: number) {
+  let lastCallTime: number | null;
+
+  const throttledFunction = function () {
+    const now = Date.now();
+
+    if (lastCallTime == null || now - lastCallTime >= throttleMs) {
+      lastCallTime = now;
+      func();
+    }
+  }
+
+  return throttledFunction;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './array';
+export * from './function';
+export * from './math';
+export * from './object';
+export * from './predicate';
+export * from './promise';

package/src/math/clamp.spec.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { clamp } from "./clamp";
+
+describe("clamp function", () => {
+  it("works with max", () => {
+    expect(clamp(3, 5)).toBe(3);
+    expect(clamp(10, 6)).toBe(6);
+    expect(clamp(6, 10)).toBe(6);
+  });
+
+  it("works with max and min", () => {
+    expect(clamp(3, 5, 10)).toBe(5);
+    expect(clamp(10, 6, 10)).toBe(10);
+    expect(clamp(6, 10, 10)).toBe(10);
+    expect(clamp(7, 5, 10)).toBe(7);
+    expect(clamp(100, 5, 6)).toBe(6);
+  });
+});

package/src/math/clamp.ts

@@ -0,0 +1,17 @@
+/**
+ * @name clamp
+ * @description Checks if `value` is within the bounds, if not return the closest bound (bound1: min, bound2: max)
+ * function clamp(value: number, bound1: number, bound2?: number): number
+ * @example
+ * clamp(3, 1) // 3
+ * clamp(3, 1, 5) // 3
+ * clamp(3, 5) // 5
+ * clamp(7, 3, 5) // 5
+ */
+export function clamp(value: number, bound1: number, bound2?: number): number {
+  if (bound2 == null) {
+    return Math.min(value, bound1);
+  }
+
+  return Math.min(Math.max(value, bound1), bound2);
+}

package/src/math/index.ts

@@ -0,0 +1,3 @@
+export { clamp } from './clamp';
+export { round } from './round';
+export { sum } from './sum';

package/src/math/round.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { round } from "./round";
+
+describe("round function", () => {
+  it("rounds a number to zero decimal places by default", () => {
+    expect(round(1.5)).toBe(2);
+    expect(round(1.4)).toBe(1);
+    // JavaScript는 반올림 하는 부분이 정확히 음수 0.5라면 +∞방향, 즉, 정수로 반올림 한다.
+    // If the fractional portion is exactly 0.5, the argument is rounded to the next integer in the direction of +∞. (positive number)
+    expect(round(-1.5)).toBe(-1);
+  });
+
+  it("rounds a number to a specified number of decimal places", () => {
+    expect(round(1.2345, 2)).toBe(1.23);
+    expect(round(1.2365, 2)).toBe(1.24);
+    expect(round(-1.2345, 2)).toBe(-1.23);
+    expect(round(-1.2365, 2)).toBe(-1.24);
+  });
+
+  it("handles zero precision as default precision", () => {
+    expect(round(1.999)).toBe(2);
+    expect(round(-1.999)).toBe(-2);
+  });
+
+  it("handles negative numbers properly", () => {
+    // JavaScript는 반올림 하는 부분이 정확히 음수 0.5라면 +∞방향, 즉, 정수로 반올림 한다.
+    // If the fractional portion is exactly 0.5, the argument is rounded to the next integer in the direction of +∞. (positive number)
+    expect(round(-1.2345, 3)).toBe(-1.234);
+    expect(round(-1.2344, 3)).toBe(-1.234);
+  });
+
+  it("rounds correctly at high precision levels", () => {
+    expect(round(1.123456789, 5)).toBe(1.12346);
+    expect(round(-1.123456789, 5)).toBe(-1.12346);
+  });
+
+  it("rounds correctly with edge cases", () => {
+    expect(round(1.25, 1)).toBe(1.3);
+    // JavaScript는 반올림 하는 부분이 정확히 음수 0.5라면 +∞방향, 즉, 정수로 반올림 한다.
+    // If the fractional portion is exactly 0.5, the argument is rounded to the next integer in the direction of +∞. (positive number)
+    expect(round(-1.25, 1)).toBe(-1.2);
+    // JavaScript는 일반적인 다른 언어들과 다르게 Round half to even 으로 동작하지 않는다.
+    // The round function in JavaScript does not work as 'Round half to Even'
+    expect(round(-1.35, 1)).toBe(-1.3);
+  });
+  it("works with zero", () => {
+    expect(round(0)).toBe(0);
+  });
+
+  it("works with precision leading to no rounding", () => {
+    expect(round(8.88888, 5)).toBe(8.88888);
+  });
+});

package/src/math/round.ts

@@ -0,0 +1,16 @@
+/**
+ * @name round
+ * @description Rounds given number to given precision
+ * ```typescript
+ * function round(value: number, precision: number = 0): number
+ * ```
+ * 
+ * @example
+ * round(1.2) === 1
+ * round(3.9) === 4
+ * round(8.5) === 9
+ */
+export function round(value: number, precision: number = 0): number {
+  const multiplier = Math.pow(10, precision);
+  return Math.round(value * multiplier) / multiplier;
+}

package/src/math/sum.spec.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from "vitest";
+import { sum } from "./sum";
+
+describe("sum function", () => {
+  it("calculates the sum of a given numbers", () => {
+    const result = sum(1, 2, 3, 4);
+    expect(result).toBe(10);
+  });
+
+  it("calculates the sum of an array of numbers", () => {
+    const result = sum([1, 2, 3, 4]);
+    expect(result).toBe(10);
+  });
+
+  it("calculates the sum of an multiple array of numbers", () => {
+    const result = sum([1, 2], [3, 4]);
+    expect(result).toBe(10);
+  });
+
+  it("returns 0 for an empty array", () => {
+    const result = sum();
+    expect(result).toBe(0);
+  });
+
+  it("handles arrays with negative numbers", () => {
+    const result = sum([-1, -2, -3, 4]);
+    expect(result).toBe(-2);
+  });
+});

package/src/math/sum.ts

@@ -0,0 +1,17 @@
+/**
+ * @name sum
+ * @description Return the sum of given values.
+ * ```typescript
+ * function sum(...nums: number[] | number[][]): number;
+ * ```
+ *
+ * @example
+ * sum(1, 2, 3) === 6
+ * sum(...[1, 2, 3]) === 6
+ * sum([1, 2, 3]) === 6
+ */
+export function sum(...nums: number[] | number[][]) {
+  return nums.flat().reduce((acc, curr) => {
+    return acc + curr;
+  }, 0);
+}

package/src/object/index.ts

@@ -0,0 +1,4 @@
+export { omit } from './omit';
+export { omitBy } from './omitBy';
+export { pick } from './pick';
+export { pickBy } from './pickBy';

package/src/object/omit.spec.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { omit } from "./omit";
+
+describe("omit", () => {
+  it("should omit properties from an object", () => {
+    const object = { foo: 1, bar: 2, baz: 3 };
+
+    expect(omit(object, ['foo', 'bar'])).toEqual({ baz: 3 });
+  });
+});

package/src/object/omit.ts

@@ -0,0 +1,15 @@
+/**
+ * @name omit
+ * Omit properties from an object.
+ * @param obj The object to omit properties from
+ * @param keys The keys to omit from an object
+ */
+export function omit<T, K extends keyof T>(obj: T, keys: K[]): Omit<T, K> {
+  const result = { ...obj };
+
+  for (const key of keys) {
+    delete result[key];
+  }
+
+  return result as Omit<T, K>
+}

package/src/object/omitBy.ts

@@ -0,0 +1,3 @@
+export function omitBy() {
+  throw new Error('Not implemented');
+}

package/src/object/pick.spec.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from "vitest";
+import { pick } from "./pick";
+
+describe("pick", () => {
+  it("should pick properties from an object", () => {
+    const object = { foo: 1, bar: 2, baz: 3 };
+
+    expect(pick(object, ['foo', 'bar'])).toEqual({ foo: 1, bar: 2 });
+  });
+});

package/src/object/pick.ts

@@ -0,0 +1,15 @@
+/**
+ * @name pick
+ * Pick properties from an given object.
+ * @param obj The object to pick properties from
+ * @param keys The keys to pick from an object
+ */
+export function pick<T, K extends keyof T>(obj: T, keys: K[]): Pick<T, K> {
+  const result = {} as Pick<T, K>;
+
+  for (const key of keys) {
+    result[key] = obj[key];
+  }
+
+  return result;
+}

package/src/object/pickBy.ts

@@ -0,0 +1,3 @@
+export function pickBy() {
+  throw new Error('Not implemented');
+}

package/src/predicate/index.ts

@@ -0,0 +1,4 @@
+export { isNil } from './isNil';
+export { isNotNil } from './isNotNil';
+export { isNull } from './isNull';
+export { isUndefined } from './isUndefined';

package/src/predicate/isNil.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest"
+import { isNil } from "./isNil"
+
+describe('isNil', () => {
+  it('returns true if the value is null or undefined', () => {
+    expect(isNil(null)).toBe(true);
+    expect(isNil(undefined)).toBe(true);
+  });
+
+  it('returns false if the value is not null nor undefined', () => {
+    expect(isNil('')).toBe(false);
+    expect(isNil(123)).toBe(false);
+  })
+
+  it('can be used with TypeScript as a type predicate', () => {
+    const arr = [1, 2, null, 4, undefined];
+
+    const result = arr.filter(isNil);
+
+    // Here the type of result should be `null | undefined`.
+    expect(result).toStrictEqual([null, undefined]);
+  })
+})

package/src/predicate/isNil.ts

@@ -0,0 +1,8 @@
+/**
+ * @name isNil
+ * Checks if the given value is null or undefined.
+ * @param x The value to test if it is null or undefined
+ */
+export function isNil(x: unknown): x is null | undefined {
+  return x == null || x == undefined;
+}

package/src/predicate/isNotNil.spec.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest"
+import { isNotNil } from "./isNotNil"
+
+describe('isNotNil', () => {
+  it('returns false if the value is null or undefined', () => {
+    expect(isNotNil(null)).toBe(false);
+    expect(isNotNil(undefined)).toBe(false);
+  });
+
+  it('returns true if the value is not null nor undefined', () => {
+    expect(isNotNil('')).toBe(true);
+    expect(isNotNil(123)).toBe(true);
+  })
+
+  it('can be used with TypeScript as a type predicate', () => {
+    const arr1 = [1, 2, null, 4, undefined];
+    const arr2 = [1, 2, null];
+    const arr3 = [1, 2, 4, undefined];
+
+    const result1 = arr1.filter(isNotNil);
+    const result2 = arr2.filter(isNotNil);
+    const result3 = arr3.filter(isNotNil);
+
+    // Here the type of result should be `number[]`.
+    expect(result1).toStrictEqual([1, 2, 4]);
+    expect(result2).toStrictEqual([1, 2]);
+    expect(result3).toStrictEqual([1, 2, 4]);
+  })
+})

package/src/predicate/isNotNil.ts

@@ -0,0 +1,14 @@
+/**
+ * @name isNotNil
+ * Checks if the given value is not null nor undefined.
+ * The main use of this function is to used with TypeScript as a type predicate.
+ * @param x The value to test if it is not null nor undefined
+ * @example
+ * // Here the type of `arr` is (number | undefined)[]
+ * const arr = [1, undefined, 3];
+ * // Here the type of `result` is number[]
+ * const result = arr.filter(isNotNil);
+ */
+export function isNotNil<T>(x: T | null | undefined): x is T {
+  return x != null && x != undefined;
+}

package/src/predicate/isNull.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest"
+import { isNull } from "./isNull"
+
+describe('isNull', () => {
+  it('returns true if the value is null', () => {
+    expect(isNull(null)).toBe(true);
+  });
+
+  it('returns false if the value is not null', () => {
+    expect(isNull(undefined)).toBe(false);
+    expect(isNull('')).toBe(false);
+    expect(isNull(123)).toBe(false);
+  })
+
+  it('can be used with TypeScript as a type predicate', () => {
+    const arr = [1, 2, null, 4, undefined];
+
+    const result = arr.filter(isNull);
+
+    // Here the type of result should be `null[]`.
+    expect(result).toStrictEqual([null]);
+  })
+})

package/src/predicate/isNull.ts

@@ -0,0 +1,8 @@
+/**
+ * @name isNull
+ * Checks if the given value is null.
+ * @param x The value to test if it is null
+ */
+export function isNull(x: unknown): x is null {
+  return x === null;
+}

package/src/predicate/isUndefined.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest"
+import { isUndefined } from "./isUndefined"
+
+describe('isUndefined', () => {
+  it('returns true if the value is undefined', () => {
+    expect(isUndefined(undefined)).toBe(true);
+  });
+
+  it('returns false if the value is not undefined', () => {
+    expect(isUndefined(null)).toBe(false);
+    expect(isUndefined('')).toBe(false);
+    expect(isUndefined(123)).toBe(false);
+  })
+
+  it('can be used with TypeScript as a type predicate', () => {
+    const arr = [1, 2, null, 4, undefined];
+
+    const result = arr.filter(isUndefined);
+
+    // Here the type of result should be `null[]`.
+    expect(result).toStrictEqual([undefined]);
+  })
+})

package/src/predicate/isUndefined.ts

@@ -0,0 +1,8 @@
+/**
+ * @name isUndefined
+ * Checks if the given value is undefined.
+ * @param x The value to test if it is undefined
+ */
+export function isUndefined(x: unknown): x is undefined {
+  return x === undefined;
+}