danholibraryjs 1.11.0 → 2.0.1

package/src/Classes/store.ts

@@ -1,9 +1,9 @@
 import { Arrayable, TransformType } from "../Types";
 import { EventEmitter } from "./Events";
 
-export type Reducer<State, Types extends Record<string, any[]>, Action extends keyof Types> = (state: State, ...args: Types[Action]) => State
-export type Actions<State, ActionTypes extends Record<string, any[]>> = { 
-    [Action in keyof ActionTypes]?: Arrayable<Reducer<State, ActionTypes, Action>> 
+export type Reducer<State, Types extends Record<string, any[]>, Action extends keyof Types> = (state: State, ...args: Types[Action]) => State;
+export type Actions<State, ActionTypes extends Record<string, any[]>> = {
+  [Action in keyof ActionTypes]?: Arrayable<Reducer<State, ActionTypes, Action>>
 };
 
 /**
@@ -70,29 +70,29 @@ export type Actions<State, ActionTypes extends Record<string, any[]>> = {
  * ```
  */
 export class Store<
-    State extends object,
-    ActionTypes extends Record<string, any[]>,
-    StoreActions extends Actions<State, ActionTypes> = Actions<State, ActionTypes>
+  State extends object,
+  ActionTypes extends Record<string, any[]>,
+  StoreActions extends Actions<State, ActionTypes> = Actions<State, ActionTypes>
 > extends EventEmitter<
-    Record<keyof StoreActions, ActionTypes[keyof ActionTypes]> 
-    & Record<'stateChange', [previous: State, current: State]>
+  Record<keyof StoreActions, ActionTypes[keyof ActionTypes]>
+  & Record<'stateChange', [previous: State, current: State]>
 > {
-    constructor(state: State, actions: StoreActions = {} as StoreActions) {
-        super(new Map(...Object.entries(actions).map(([action, reducers]) => [action, reducers as any])));
+  constructor(state: State, actions: StoreActions = {} as StoreActions) {
+    super(new Map(...Object.entries(actions).map(([action, reducers]) => [action, reducers as any])));
 
-        this._state = state;
-    }
+    this._state = state;
+  }
 
-    private _state: State;
-    public get state(): State {
-        return this._state;
-    }
+  private _state: State;
+  public get state(): State {
+    return this._state;
+  }
 
-    public dispatch<Action extends keyof ActionTypes>(action: Action, ...args: ActionTypes[Action]): State {
-        const previous = { ...this._state };
-        this._state = super.emit<State, Action>(action, ...args as any).reduce((state, returned) => ({ ...state, ...returned }), this.state);
+  public dispatch<Action extends keyof ActionTypes>(action: Action, ...args: ActionTypes[Action]): State {
+    const previous = { ...this._state };
+    this._state = super.emit<State, Action>(action, ...args as any).reduce((state, returned) => ({ ...state, ...returned }), this.state);
 
-        super.emit<void, 'stateChange'>('stateChange', ...[previous, this.state] as any);
-        return this.state;
-    }
+    super.emit<void, 'stateChange'>('stateChange', ...[previous, this.state] as any);
+    return this.state;
+  }
 }

package/src/Extensions/Array/array.extension.ts

@@ -0,0 +1,103 @@
+import { Arrayable } from "../../Types";
+
+declare global {
+  interface Array<T> {
+    /**
+     * Returns the first `count` elements from the array.
+     * @param count Number of elements to take.
+     * @returns Array containing the first `count` elements.
+     */
+    take(count: number): Array<T>;
+
+    /**
+     * Returns a new array with only unique elements from the original array.
+     * @returns An array containing only unique elements.
+     */
+    unique(): Array<T>;
+
+    /**
+     * Splits the array into chunks of a specified size or by a splitter function.
+     * @param chunkSizeOrSplitter The size of each chunk or a function that determines where to split the array.
+     * @returns An array of arrays, where each sub-array is a chunk of the original array.
+     */
+    splitBy(chunkSizeOrSplitter: number | ((value: T, index: number, array: Array<T>) => boolean)): Array<Array<T>>;
+
+    /**
+     * Groups the elements of the array based on a key selector function.
+     * @param keySelector A function that selects a key for each element in the array.
+     * @returns A Map where each key is a group identifier and the value is an array of elements in that group.
+     */
+    groupBy<K>(keySelector: (value: T, index: number, array: Array<T>) => K): Map<K, Array<T>>;
+  }
+
+  interface ArrayConstructor {
+    /**
+     * Forces an arrayable object into an array
+     * @param arrayable The arrayable object to force into an array
+     * @returns An array containing the elements of the input or the single value.
+     */
+    forceArray<T>(arrayable: Arrayable<T>): Array<T>;
+  }
+}
+
+export function take<T>(this: Array<T>, count: number): Array<T> {
+  return this.slice(0, count);
+}
+Array.prototype.take = take;
+
+export function forceArray<T>(arrayable: Arrayable<T>): Array<T> {
+  return Array.isArray(arrayable) ? arrayable : [arrayable];
+}
+Array.forceArray = forceArray;
+
+export function unique<T>(this: Array<T>): Array<T> {
+  return [...new Set(this)];
+}
+Array.prototype.unique = unique;
+
+export function splitBy<T>(this: Array<T>, chunkSize: number): Array<Array<T>>;
+export function splitBy<T>(this: Array<T>, splitter: (value: T, index: number, array: Array<T>) => boolean): Array<Array<T>>;
+export function splitBy<T>(this: Array<T>, chunkSizeOrSplitter: number | ((value: T, index: number, array: Array<T>) => boolean)): Array<Array<T>> {
+  const chunkSize = typeof chunkSizeOrSplitter === 'number' ? chunkSizeOrSplitter : undefined;
+  const splitter = typeof chunkSizeOrSplitter === 'function' ? chunkSizeOrSplitter : undefined;
+
+  const result: Array<Array<T>> = [];
+
+  if (chunkSize !== undefined) {
+    for (let i = 0; i < this.length; i += chunkSize) {
+      result.push(this.slice(i, i + chunkSize));
+    }
+  } else if (splitter !== undefined) {
+    const chunk = new Array<T>();
+    
+    for (let i = 0; i < this.length; i++) {
+      const value = this[i];
+      if (splitter(value, i, this)) {
+        if (chunk.length) {
+          result.push(chunk.splice(0, chunk.length));
+        }
+      }
+
+      chunk.push(value);
+    }
+
+    if (chunk.length) {
+      result.push(chunk);
+    }
+  }
+
+  return result;
+}
+Array.prototype.splitBy = splitBy;
+
+export function groupBy<T, K>(this: Array<T>, keySelector: (value: T, index: number, array: Array<T>) => K): Map<K, Array<T>> {
+  return this.reduce((map, item, index, array) => {
+    const key = keySelector(item, index, array);
+    const group = map.get(key) ?? new Array<T>();
+
+    group.push(item);
+    map.set(key, group);
+    return map;
+  }, new Map<K, Array<T>>());
+}
+Array.prototype.groupBy = groupBy;

package/src/Extensions/Array/crud.extension.ts

@@ -0,0 +1,46 @@
+export type UpdateFinder<T> = (item: T, index: number, self: Array<T>) => boolean
+
+declare global {
+  interface Array<T> {
+    /**
+     * Pushes items to array and returns self with new items
+     * @param items Items to add to array
+     */
+    add(...items: Array<T>): this;
+    /**
+     * Update an item in array
+     * @param old The old value or index to update
+     * @param updated Updated value
+     */
+    update(old: T | number | UpdateFinder<T>, updated: T): T;
+    /**
+     * Removes item from array and returns self without item
+     * @param item Item or index to remove
+     */
+    remove(item: T | number): this;
+  }
+}
+
+export function add<T>(this: Array<T>, ...items: Array<T>) {
+  this.push(...items);
+  return this;
+}
+Array.prototype.add = add;
+
+export function update<T>(this: Array<T>, old: T | number | UpdateFinder<T>, updated: T) {
+  const item = typeof old === 'number' ? this[old]
+    : typeof old === 'function' ? this.find(old as UpdateFinder<T>)
+      : old;
+  if (!item) throw new Error('Old was not found in array!');
+
+  const index = this.indexOf(item);
+  return this[index] = updated;
+}
+Array.prototype.update = update;
+
+export function remove<T>(this: Array<T>, value: T | number): Array<T> {
+  const index = typeof value === 'number' ? value : this.indexOf(value);
+  if (index > -1) this.splice(index, 1);
+  return this;
+}
+Array.prototype.remove = remove;

package/src/Extensions/Array/index.ts

@@ -0,0 +1,6 @@
+export * from './array.extension';
+export * from './crud.extension';
+export * from './loop.extension';
+export * from './random.extension';
+export * from './sort.extension';
+export * from './string.extension';

package/src/Extensions/Array/loop.extension.ts

@@ -0,0 +1,38 @@
+declare global {
+  interface Array<T> {
+    /**
+     * For every x in array, execute callback
+     * @param every i.e every 2nd item in array
+     * @param callback Function to execute
+     * @returns Array of results
+     */
+    nth<U>(every: number, callback: (item: T, index: number, collection: Array<T>, self: this) => U): Array<U>;
+  }
+}
+
+/**
+ * For every x in array, execute callback
+ * @param every i.e every 2nd item in array
+ * @param callback Function to execute. This includes a collection of items prior to last callback run
+ * @returns Array of results
+ */
+export function nth<T, U>(
+  this: Array<T>, 
+  every: number, 
+  callback: (item: T, index: number, collection: Array<T>, self: Array<T>) => U
+): Array<U> {
+  const result = new Array<U>();
+  let collection = new Array<T>();
+
+  for (let i = 0; i < this.length; i++) {
+    collection.push(this[i]);
+
+    if ((i + 1) % every === 0) {
+      result.push(callback(this[i], i, collection, this));
+      collection = new Array<T>();
+    }
+  }
+
+  return result;
+}
+Array.prototype.nth = nth;

package/src/Extensions/Array/random.extension.ts

@@ -0,0 +1,56 @@
+declare global {
+  interface Array<T> {
+    /**
+     * Returns a random element from the array.
+     * @returns A random element from the array.
+     */
+    random(): T;
+
+    /**
+     * Returns a new array with the elements of the original array in random order.
+     * @returns A new array with the elements shuffled.
+     */
+    shuffle(): Array<T>;
+
+    /**
+     * Selects a random item from an array based on specified weights.
+     * @param items An array of tuples where each tuple contains an item and its corresponding weight.
+     * @returns A randomly selected item based on the provided weights.
+     */
+    randomWithPercentages(items: [item: T, weight: number][]): T;
+  }
+}
+
+export function random<T>(this: Array<T>): T {
+  const randomIndex = Math.floor(Math.random() * this.length);
+  return this[randomIndex];
+}
+Array.prototype.random = random;
+
+export function shuffle<T>(this: Array<T>): Array<T> {
+  return this.sort(() => Math.random() - 0.5);
+}
+Array.prototype.shuffle = shuffle;
+
+export function randomWithPercentages<T>(items: [item: T, weight: number][]): T {
+  if (items.length === 0) throw new Error('Items array cannot be empty');
+
+  // Calculate total weight in case weights don't sum to 100
+  const totalWeight = items.reduce((sum, [, weight]) => sum + weight, 0);
+  if (totalWeight === 0) throw new Error('Total weight must be greater than zero');
+
+  // Generate random number between 0 and totalWeight
+  const random = Math.random() * totalWeight;
+
+  // Find the item that corresponds to this random value
+  let currentWeight = 0;
+  for (const [item, weight] of items) {
+    currentWeight += weight;
+    if (random <= currentWeight) {
+      return item;
+    }
+  }
+
+  throw new Error('Unable to select an item based on weights');
+}
+Array.prototype.randomWithPercentages = randomWithPercentages;

package/src/Extensions/Array/sort.extension.ts

@@ -0,0 +1,52 @@
+type Comparator<T> = (a: T, b: T) => number;
+
+declare global {
+  interface Array<T> {
+    /**
+     * Sorts the array using multiple comparators.
+     * @param comparators Functions to compare elements.
+     * @returns Sorted array.
+     */
+    orderBy(...comparators: Array<Comparator<T>>): Array<T>;
+
+    /**
+     * Sorts the array using multiple comparators in descending order.
+     * @param comparators Functions to compare elements.
+     * @returns Sorted array in descending order.
+     */
+    orderByDescending(...comparators: Array<Comparator<T>>): Array<T>;
+
+    /**
+     * Sorts the array by specified properties.
+     * @param properties Properties to sort by.
+     * @returns Sorted array.
+     */
+    sortByProperty(...properties: Array<keyof T>): Array<T>;
+  }
+}
+
+export function orderBy<T>(this: Array<T>, ...comparators: Array<Comparator<T>>): Array<T> {
+  return this.sort((a, b) => {
+    for (const comparator of comparators) {
+      const result = comparator(a, b);
+      if (result !== 0) return result;
+    }
+
+    return 0;
+  });
+}
+Array.prototype.orderBy = orderBy;
+
+export function orderByDescending<T>(this: Array<T>, ...comparators: Array<Comparator<T>>): Array<T> {
+  return this.orderBy(...comparators).reverse();
+}
+Array.prototype.orderByDescending = orderByDescending;
+
+export function sortByProperty<T extends object>(this: Array<T>, ...properties: Array<keyof T>): Array<T> {
+  return this.orderBy(...properties.map(property => (a: T, b: T) => {
+    if (a[property] < b[property]) return -1;
+    if (a[property] > b[property]) return 1;
+    return 0;
+  }));
+}
+Array.prototype.sortByProperty = sortByProperty;

package/src/Extensions/Array/string.extension.ts

@@ -0,0 +1,22 @@
+declare global {
+  interface Array<T> {
+    /**
+     * Joins the elements of the array into a string, with optional custom separators.
+     * @param args An array of strings or undefined values to be used as separators between elements.
+     * @param separator The default separator to use between elements if args is not provided or undefined.
+     * @param endSeparator The separator to use before the last element.
+     * @returns A string with the joined elements.
+     */
+    join(args?: Array<string | undefined>, separator?: string, endSeparator?: string): string;
+  }
+}
+
+export function join<T>(this: Array<T>, separator = ',', endSeparator = '&'): string {
+  const validArgs = this.filter(arg => !Object.isNullOrUndefined(arg) && arg !== '');
+  if (!validArgs.length) return '';
+  if (validArgs.length === 1) return validArgs.shift()!.toString();
+
+  const lastArg = validArgs.pop()!;
+  const combinedArgs = validArgs.join(separator);
+  return `${combinedArgs}${endSeparator ? ` ${endSeparator} ` : ''}${lastArg}`;
+}

package/src/Extensions/Function.ts

@@ -1,18 +1,45 @@
+import { Functionable } from "../Types";
+
 declare global {
-    interface Function {
-        /**
-         * Checks if obj is a function
-         * @param obj Object to check
-         */
-        is(obj: any): obj is Function;
-    }
+  interface Function {
+    /**
+     * Checks if obj is a function
+     * @param obj Object to check
+     */
+    is(obj: any): obj is Function;
+
+    /**
+     * Resolves a Functionable<T> to T, if it's a function, it will be called with the provided arguments and its return value will be returned, otherwise the value itself will be returned.
+     * @param functionable The Functionable<T> to resolve
+     * @param args Arguments to call the function with if functionable is a function
+     */
+    resolveFunctionable<T, TArgs extends any[] = any[]>(functionable: Functionable<T, TArgs>, ...args: TArgs): T;
+
+    /**
+     * Forces a Functionable<T> to be a function, if it's already a function, it will be returned as is, otherwise a function that returns the value will be returned.
+     * @param functionable The Functionable<T> to force to be a function
+     */
+    forceFunction<T, TArgs extends any[] = any[]>(functionable: Functionable<T, TArgs>): (...args: TArgs) => T;
+  }
 }
 
-function is(obj: any): obj is Function {
-    return typeof obj === 'function';
+export function is(obj: any): obj is Function {
+  return typeof obj === 'function';
 }
 Function.is = is;
 
+export function resolveFunctionable<T, TArgs extends any[] = any[]>(functionable: Functionable<T, TArgs>, ...args: TArgs): T {
+  return is(functionable) ? functionable(...args) : functionable;
+}
+Function.resolveFunctionable = resolveFunctionable;
+
+export function forceFunction<T, TArgs extends any[] = any[]>(functionable: Functionable<T, TArgs>): (...args: TArgs) => T {
+  return is(functionable) ? functionable : () => functionable;
+}
+Function.forceFunction = forceFunction;
+
 export const FunctionExtensions = {
-    is
+  is,
+  resolveFunctionable,
+  forceFunction
 };

package/src/Extensions/Map.ts

@@ -1,88 +1,88 @@
 declare global {
-    interface Map<K, V> {
-        /**
-         * Converts into Array<[Key, Value]>
-         */
-        array(): Array<[K, V]>
-        /**
-         * Maps values into new types of generics
-         * @param callback Callbacking function to map values
-         */
-        map<EK, EV>(callback: (value: V, key: K, index: number, self: this) => [EK, EV]): Map<EK, EV>
-        /**
-         * Returns array of "accepted" values. Criteria defined in callback param
-         * @param callback Callbacking function to filter away unwanted values
-         */
-        filter(callback: (value: V, key: K, index: number, self: this) => boolean): Map<K, V>
-        /**
-         * Returns array of keys
-         */
-        keyArr(): Array<K>
-        /**
-         * Returns array of values
-         */
-        valueArr(): Array<V>
-        /**
-         * Returns first [key, value] match to callback param. Returns undefined if nothing found
-         * @param callback Callbacking function to find KeyValuePair
-         */
-        find(callback: (value: V, key: K, index: number, self: this) => boolean): [K, V] | undefined
-        /**
-         * Whether or not map includes a  value. Returns true if it does, false if not ¯\_(ツ)_/¯ 
-         * @param value Value that may be includded in map
-         * @param fromIndex Start looking for value from specific index+. Default: 0
-         */
-        includes(value: V, fromIndex?: number): boolean
-    }
+  interface Map<K, V> {
+    /**
+     * Converts into Array<[Key, Value]>
+     */
+    array(): Array<[K, V]>;
+    /**
+     * Maps values into new types of generics
+     * @param callback Callbacking function to map values
+     */
+    map<EK, EV>(callback: (value: V, key: K, index: number, self: this) => [EK, EV]): Map<EK, EV>;
+    /**
+     * Returns array of "accepted" values. Criteria defined in callback param
+     * @param callback Callbacking function to filter away unwanted values
+     */
+    filter(callback: (value: V, key: K, index: number, self: this) => boolean): Map<K, V>;
+    /**
+     * Returns array of keys
+     */
+    keyArr(): Array<K>;
+    /**
+     * Returns array of values
+     */
+    valueArr(): Array<V>;
+    /**
+     * Returns first [key, value] match to callback param. Returns undefined if nothing found
+     * @param callback Callbacking function to find KeyValuePair
+     */
+    find(callback: (value: V, key: K, index: number, self: this) => boolean): [K, V] | undefined;
+    /**
+     * Whether or not map includes a  value. Returns true if it does, false if not ¯\_(ツ)_/¯ 
+     * @param value Value that may be includded in map
+     * @param fromIndex Start looking for value from specific index+. Default: 0
+     */
+    includes(value: V, fromIndex?: number): boolean;
+  }
 }
 
 function array<K, V>(this: Map<K, V>): Array<[K, V]> {
-    let result = new Array<[K, V]>();
-    for (const kvp of this) {
-        result.push(kvp);
-    }
-    return result;
+  let result = new Array<[K, V]>();
+  for (const kvp of this) {
+    result.push(kvp);
+  }
+  return result;
 }
 Map.prototype.array = array;
 
 function map<K, V, EK, EV>(this: Map<K, V>, callback: (value: V, key: K, index: number, map: Map<K, V>) => [EK, EV]): Map<EK, EV> {
-    return this.array()
-        .map(([k, v], i) => callback(v, k, i, this))
-        .reduce((map, [key, value]) => 
-            map.set(key, value), 
-        new Map<EK, EV>())
+  return this.array()
+    .map(([k, v], i) => callback(v, k, i, this))
+    .reduce((map, [key, value]) =>
+      map.set(key, value),
+      new Map<EK, EV>());
 }
 Map.prototype.map = map;
 
 function filter<K, V>(this: Map<K, V>, callback: (value: V, key: K, index: number, map: Map<K, V>) => boolean): Map<K, V> {
-    return this.array()
-        .filter(([k, v], i) => callback(v, k, i, this))
-        .reduce((map, [key, value]) => 
-            map.set(key, value), 
-        new Map<K, V>())
+  return this.array()
+    .filter(([k, v], i) => callback(v, k, i, this))
+    .reduce((map, [key, value]) =>
+      map.set(key, value),
+      new Map<K, V>());
 }
 Map.prototype.filter = filter;
 
 function keyArr<K, V>(this: Map<K, V>): Array<K> {
-    return this.array().map(([k]) => k);
+  return this.array().map(([k]) => k);
 }
 Map.prototype.keyArr = keyArr;
 
 function valueArr<K, V>(this: Map<K, V>): Array<V> {
-    return this.array().map(([_, v]) => v);
+  return this.array().map(([_, v]) => v);
 }
 Map.prototype.valueArr = valueArr;
 
 function find<K, V>(this: Map<K, V>, callback: (value: V, key: K, index: number, map: Map<K, V>) => boolean) {
-    return this.array().find(([k, v], i) => callback(v, k, i, this));
+  return this.array().find(([k, v], i) => callback(v, k, i, this));
 }
 Map.prototype.find = find;
 
 function includes<K, V>(this: Map<K, V>, item: V, fromIndex?: number) {
-    return this.valueArr().includes(item, fromIndex);
+  return this.valueArr().includes(item, fromIndex);
 }
 Map.prototype.includes = includes;
 
 export const MapExtensions = {
-    array, map, filter, keyArr, valueArr, find, includes
-}
+  array, map, filter, keyArr, valueArr, find, includes
+};

package/src/Extensions/Number.ts

@@ -0,0 +1,50 @@
+type Separators = {
+  thousand: string;
+  decimal: string;
+}
+
+declare global {
+  interface Number {
+    toSeparationString(separators: Partial<Separators>): string;
+    toRomanNumeral(): string;
+  }
+}
+
+export function toSeparationString(this: number, separators: Partial<Separators>): string {
+  const { thousand = '.', decimal = '.' } = separators;
+  const [integerPart, decimalPart] = this.toString().split('.');
+  const formattedInteger = integerPart.replace(/\B(?=(\d{3})+(?!\d))/g, thousand);
+  return decimalPart ? `${formattedInteger}${decimal}${decimalPart}` : formattedInteger;
+}
+Number.prototype.toSeparationString = toSeparationString;
+
+export function toRomanNumeral(this: number): string {
+  if (this <= 0 || this >= 4000) throw new RangeError('Number must be between 1 and 3999 to convert to Roman numeral');
+
+  const numeralMap: [number, string][] = [
+    [1000, 'M'], 
+    [900, 'CM'], 
+    [500, 'D'], 
+    [400, 'CD'],
+    [100, 'C'], 
+    [90, 'XC'], 
+    [50, 'L'], 
+    [40, 'XL'],
+    [10, 'X'], 
+    [9, 'IX'], 
+    [5, 'V'], 
+    [4, 'IV'],
+    [1, 'I']
+  ];
+
+  let value = this;
+  return numeralMap.reduce((acc, [numeralValue, numeral]) => {
+    while (value >= numeralValue) {
+      acc += numeral;
+      value -= numeralValue;
+    }
+
+    return acc;
+  }, '');
+}
+Number.prototype.toRomanNumeral = toRomanNumeral;

package/src/Extensions/Object/arrays.extension.ts

@@ -0,0 +1,27 @@
+import { ValueOf } from "../../Types";
+
+declare global {
+  interface ObjectConstructor {
+    /**
+     * Destructures object into array of [property, value]
+     * @param from Object to destruct
+     */
+    array<From extends {} = {}>(from: From): Array<[keyof From, ValueOf<From>]>;
+
+    /**
+     * Destructures object into array of property keys
+     * @param from Object to destruct
+     */
+    keysOf<From extends {} = {}>(from: From): Array<keyof From>;
+  }
+}
+
+export function array<From extends {} = {}>(this: object, from: From): Array<[keyof From, ValueOf<From>]> {
+  return Object.entries(from) as Array<[keyof From, ValueOf<From>]>;
+}
+Object.array = array;
+
+export function keysOf<From extends {} = {}>(this: object, from: From): Array<keyof From> {
+  return Object.keys(from) as Array<keyof From>;
+}
+Object.keysOf = keysOf;