danholibraryjs 1.10.0 → 2.0.0

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,15 @@
+import * as Array from './array.extension';
+import * as CRUD from './crud.extension';
+import * as Loop from './loop.extension';
+import * as Random from './random.extension';
+import * as Sort from './sort.extension';
+import * as String from './string.extension';
+
+export const ArrayExtensions = {
+  ...Array,
+  ...CRUD,
+  ...Loop,
+  ...Random,
+  ...Sort,
+  ...String,
+};

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/Document.ts

@@ -1,58 +1,58 @@
 import { IElement } from "../Types";
 
 declare global {
-    interface Document {
-        /**
-         * Creates an element like Document#createElement, however with construction options to assign values in construction instead of after construction.
-         * @param tagName HTMLElement tag name
-         * @param options Construction options, instead of assigning values after construction
-         * @param children Child elements
-         */
-        createProperElement<Tag extends keyof HTMLElementTagNameMap>(tagName: Tag, options?: Partial<HTMLElementTagNameMap[Tag]>, ...children: Array<IElement>): HTMLElementTagNameMap[Tag]
-        createProperElement<Tag extends keyof HTMLElementTagNameMap>(tagName: Tag, ...children: Array<IElement>): HTMLElementTagNameMap[Tag]
-        createElementFromString<K extends keyof HTMLElementTagNameMap>(html: string, parentTag?: K): HTMLElementTagNameMap[K]
-    }
-    interface HTMLCollection {
-        /**
-         * Converts HTMLCollection to Element[]
-         */
-        array(): Element[]
-    }
+  interface Document {
+    /**
+     * Creates an element like Document#createElement, however with construction options to assign values in construction instead of after construction.
+     * @param tagName HTMLElement tag name
+     * @param options Construction options, instead of assigning values after construction
+     * @param children Child elements
+     */
+    createProperElement<Tag extends keyof HTMLElementTagNameMap>(tagName: Tag, options?: Partial<HTMLElementTagNameMap[Tag]>, ...children: Array<IElement>): HTMLElementTagNameMap[Tag];
+    createProperElement<Tag extends keyof HTMLElementTagNameMap>(tagName: Tag, ...children: Array<IElement>): HTMLElementTagNameMap[Tag];
+    createElementFromString<K extends keyof HTMLElementTagNameMap>(html: string, parentTag?: K): HTMLElementTagNameMap[K];
+  }
+  interface HTMLCollection {
+    /**
+     * Converts HTMLCollection to Element[]
+     */
+    array(): Element[];
+  }
 }
 
 function createElement<Tag extends keyof HTMLElementTagNameMap>(
-    this: Document, tagName: Tag, 
-    options?: Partial<HTMLElementTagNameMap[Tag]> | string, 
-    ...children: Array<IElement>
+  this: Document, tagName: Tag,
+  options?: Partial<HTMLElementTagNameMap[Tag]> | string,
+  ...children: Array<IElement>
 ): HTMLElementTagNameMap[Tag] {
-    
-    const element = Object.assign(document.createElement(tagName), typeof options === 'string' ? {} : options);
-    children ??= typeof options === 'string' ? [options] as Array<IElement> : [];
-    typeof options === 'string' && children.unshift(options);
-
-    if (!children.length) return element;
-    else if (typeof children === 'string') element.innerHTML = children;
-    else if (children instanceof Array) children.forEach(child => (
-        typeof child === 'string' ? 
-            element.innerHTML += child : 
-            element.appendChild(child)
-    ));
-    else element.appendChild(children);
-    return element;
+
+  const element = Object.assign(document.createElement(tagName), typeof options === 'string' ? {} : options);
+  children ??= typeof options === 'string' ? [options] as Array<IElement> : [];
+  typeof options === 'string' && children.unshift(options);
+
+  if (!children.length) return element;
+  else if (typeof children === 'string') element.innerHTML = children;
+  else if (children instanceof Array) children.forEach(child => (
+    typeof child === 'string' ?
+      element.innerHTML += child :
+      element.appendChild(child)
+  ));
+  else element.appendChild(children);
+  return element;
 
 }
 Document.prototype.createProperElement = createElement;
 
 function createElementFromString<Tag extends keyof HTMLElementTagNameMap>(this: Document, html: string, tag?: Tag): HTMLElementTagNameMap[Tag] {
-    if (!html.startsWith(`<${tag}`)) html = `<${tag}>${html}</${tag}>`;
-    return new DOMParser().parseFromString(html, 'text/html').body.firstElementChild as HTMLElementTagNameMap[Tag];
+  if (!html.startsWith(`<${tag}`)) html = `<${tag}>${html}</${tag}>`;
+  return new DOMParser().parseFromString(html, 'text/html').body.firstElementChild as HTMLElementTagNameMap[Tag];
 }
 Document.prototype.createElementFromString = createElementFromString;
 
-HTMLCollection.prototype.array = function(this: HTMLCollection) {
-    return Array.from(this);
+HTMLCollection.prototype.array = function (this: HTMLCollection) {
+  return Array.from(this);
 };
 
 export const DocumentExtensions = {
-    createElement, createElementFromString
+  createElement, createElementFromString
 };

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
 };