danholibraryjs 2.0.0 → 2.0.2

package/dist/index.js

@@ -16,6 +16,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Classes"), exports);
 __exportStar(require("./Extensions"), exports);
-__exportStar(require("./Functions"), exports);
 __exportStar(require("./Interfaces"), exports);
 __exportStar(require("./Types"), exports);
+__exportStar(require("./Utils"), exports);

package/docs/Classes.md

@@ -2,11 +2,86 @@
 
 ## Classes
 
+### DanhoLogger
+
+```ts
+/**
+ * Enhanced console logger with prefixes, colors, and grouping
+ */
+class DanhoLogger {
+    /**
+     * @param options Logger configuration
+     * @param options.name Name to display in log prefix (default: 'DanhoLogger')
+     * @param options.color Color for the prefix (default: 'inherit')
+     * @param options.preferCollapsed Whether to use collapsed groups by default (default: false)
+     */
+    constructor(options?: { name?: string; color?: string; preferCollapsed?: boolean });
+
+    /**
+     * Name displayed in log prefix
+     */
+    public name: string;
+
+    /**
+     * Color for the prefix
+     */
+    public color?: string;
+
+    /**
+     * Logs a message
+     */
+    public log(...args: any[]): this;
+
+    /**
+     * Logs a warning message
+     */
+    public warn(...args: any[]): this;
+
+    /**
+     * Logs an error message
+     */
+    public error(...args: any[]): this;
+
+    /**
+     * Creates a log group
+     */
+    public group(...args: any[]): this;
+
+    /**
+     * Creates a collapsed log group
+     */
+    public groupCollapsed(...args: any[]): this;
+
+    /**
+     * Ends the current log group
+     */
+    public groupEnd(...args: any[]): this;
+
+    /**
+     * Starts a timer with a label
+     */
+    public time(label: string): this;
+
+    /**
+     * Ends a timer and logs the elapsed time
+     */
+    public timeEnd(label: string): this;
+
+    /**
+     * Logs data in a table format
+     */
+    public table(data: any, columns?: string[]): this;
+}
+```
+
+### Store
+
 ```ts
 /**
- * EventEmitter, but it stores state and handles state change with reducers
+ * EventEmitter that stores state and handles state changes with reducers
  * 
- * @Initialization Actions & initial state must be defined in type parameters. InitialState must be provided in constructor, whereas reducer is optional.
+ * @Initialization Actions & initial state must be defined in type parameters. 
+ * InitialState must be provided in constructor, whereas reducer is optional.
  * The ActionType must have properties as strings and values as arrays.
  * 
  * @HandlingActions Reducers can be added through constructor or using Store.on('action', reducer) or Store.once('action', reducer).
@@ -26,7 +101,7 @@ class Store<
     { [Action in keyof ActionTypes]: Array<Reducer<State, ActionTypes, Action>> } = 
     { [Action in keyof ActionTypes]: Array<Reducer<State, ActionTypes, Action>> }
 > extends EventEmitter<Record<keyof Actions, ActionTypes[keyof ActionTypes]> & Record<'stateChange', [previous: State, current: State]>> {
-    constructor(state: State, actions: { [Action in keyof ActionTypes]?: Arrayable<Reducer<State, ActionTypes, Action>> } = {});
+    constructor(state: State, actions?: { [Action in keyof ActionTypes]?: Arrayable<Reducer<State, ActionTypes, Action>> });
 
     private _state: State;
     public get state(): State;

package/docs/Extensions.md

@@ -2,72 +2,134 @@
 
 ## Extensions
 
-### General
-
-```ts
-interface BooleanConstructor {
-    /**
-     * Parses string to boolean. Will only return true if value === "true" otherwise false
-     */
-    parseBoolean(value: string): boolean
-}
-
-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
-     */
-    createProperElement<K extends keyof HTMLElementTagNameMap>(tagName: K, options?: ElementOptions): HTMLElementTagNameMap[K];
-}
-
-interface HTMLCollection {
-    /**
-     * Converts HTMLCollection to Element[]
-     */
-    array(): Element[];
-}
-```
+Extensions add new methods to native JavaScript types and interfaces.
 
 ### Array
 
+#### Instance Methods
+
 ```ts
 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
+    add(...items: Array<T>): this;
+
     /**
      * Update an item in array
-     * @param old The old value or index to update
+     * @param old The old value, index, or finder function to locate item to update
      * @param updated Updated value
      */
-    update(old: T | number, updated: T): T
+    update(old: T | number | ((item: T, index: number, self: Array<T>) => boolean), updated: T): T;
+
     /**
      * Removes item from array and returns self without item
      * @param item Item or index to remove
      */
-    remove(item: T | number): this
+    remove(item: T | number): Array<T>;
+
     /**
      * Returns a random element from array
      */
-    random(): T
+    random(): T;
+
     /**
-     * Returns item matching index. If negative number, subtracts number from length
-     * @param i Index of item
+     * Shuffles array in random order
      */
-    index(i: number): T
+    shuffle(): Array<T>;
+
+    /**
+     * Returns the first `count` elements from the array
+     * @param count Number of elements to take
+     */
+    take(count: number): Array<T>;
+
+    /**
+     * Returns a new array with 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
+     */
+    splitBy(chunkSizeOrSplitter: number | ((value: T, index: number, array: Array<T>) => boolean)): Array<Array<T>>;
+
+    /**
+     * Groups elements based on a key selector function
+     * @param keySelector A function that selects a key for each element
+     */
+    groupBy<K>(keySelector: (value: T, index: number, array: Array<T>) => K): Map<K, Array<T>>;
+
+    /**
+     * For every nth element in array, execute callback
+     * @param every Execute callback every nth element
+     * @param callback Function to execute
+     */
+    nth<U>(every: number, callback: (collection: Array<T>, index: number, self: this) => U): Array<U>;
+
+    /**
+     * Joins array elements with a separator, and a different separator before the last element
+     * @param separator Separator between elements (default: ',')
+     * @param endSeparator Separator before last element (default: '&')
+     */
+    join(separator?: string, endSeparator?: string): string;
+
+    /**
+     * Orders array by comparators in ascending order
+     * @param comparators Comparison functions
+     */
+    orderBy(...comparators: Array<(a: T, b: T) => number>): Array<T>;
+
+    /**
+     * Orders array by comparators in descending order
+     * @param comparators Comparison functions
+     */
+    orderByDescending(...comparators: Array<(a: T, b: T) => number>): Array<T>;
+
+    /**
+     * Sorts array by object properties
+     * @param properties Properties to sort by
+     */
+    sortByProperty(...properties: Array<keyof T>): Array<T>;
+}
+```
+
+#### Static Methods
+
+```ts
+interface ArrayConstructor {
     /**
-     * For every number in array, do callback
-     * @param every For every x in array
-     * @param callback Do this for every x in array
-     * @returns Mapped array
+     * Forces an arrayable object into an array
+     * @param arrayable The value or array to normalize
      */
-    nth<U>(every: number, callback: (collection: Array<T>, index: number, self: this) => U): Array<U>
+    forceArray<T>(arrayable: T | Array<T>): Array<T>;
 }
 ```
 
+### Function
+
+```ts
+/**
+ * Checks if a value is a function
+ */
+function is(obj: any): obj is Function;
+
+/**
+ * Resolves a functionable value (value or function that returns value)
+ * @param functionable Value or function
+ * @param args Arguments to pass if functionable is a function
+ */
+function resolveFunctionable<T, TArgs extends any[] = any[]>(functionable: T | ((...args: TArgs) => T), ...args: TArgs): T;
+
+/**
+ * Converts a functionable value into a function
+ * @param functionable Value or function
+ */
+function forceFunction<T, TArgs extends any[] = any[]>(functionable: T | ((...args: TArgs) => T)): (...args: TArgs) => T;
+```
+
 ### Map
 
 ```ts
@@ -75,79 +137,191 @@ interface Map<K, V> {
     /**
      * Converts map into Array<[Key, Value]>
      */
-    array(): Array<[K, V]>
+    array(): Array<[K, V]>;
+
     /**
-     * Maps values into new types of generics
-     * @param callback Callbacking function to map values
+     * Maps values into new types
+     * @param callback Mapping function
      */
-    map<EK, EV>(callback: (value: V, key: K, index: number, self: this) => [EK, EV]): Map<EK, EV>
+    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
+     * Filters map entries
+     * @param callback Filter function
      */
-    filter(callback: (value: V, key: K, index: number, self: this) => boolean): Map<K, V>
+    filter(callback: (value: V, key: K, index: number, self: this) => boolean): Map<K, V>;
+
     /**
      * Returns array of keys
      */
-    keyArr(): Array<K>
+    keyArr(): Array<K>;
+
     /**
      * Returns array of values
      */
-    valueArr(): Array<V>
+    valueArr(): Array<V>;
+
     /**
-     * Returns first [key, value] match to callback param. Returns undefined if nothing found
-     * @param callback Callbacking function to find KeyValuePair
+     * Finds first entry matching callback
+     * @param callback Find function
      */
-    find(callback: (value: V, key: K, index: number, self: this) => boolean): [K, V] | undefined
+    find(callback: (value: V, key: K, index: number, self: this) => boolean): [K, V] | undefined;
+
     /**
-     * Whether or not map includes a  value (value version of Map#has)
-     * @param value Value that may be includded in map
-     * @param fromIndex Start looking for value from specific index+. Default: 0
+     * Checks if map includes a value
+     * @param value Value to search for
+     * @param fromIndex Start looking from specific index
      */
     includes(value: V, fromIndex?: number): boolean;
 }
 ```
 
+### Number
+
+```ts
+interface Number {
+    /**
+     * Formats number with thousand and decimal separators
+     * @param separators Custom separators for thousand and decimal (optional)
+     */
+    toSeparationString(separators?: Partial<{ thousand: string; decimal: string }>): string;
+
+    /**
+     * Converts number to Roman numeral (1-3999)
+     */
+    toRomanNumeral(): string;
+}
+```
+
 ### Object
 
+#### Static Methods
+
 ```ts
 interface ObjectConstructor {
     /**
      * Destructures object into array of [property, value]
      * @param from Object to destruct
      */
-    array<From = {}>(from: From): Array<keyof From, ValueOf<From>>
+    array<From extends {} = {}>(from: From): Array<[keyof From, ValueOf<From>]>;
+    /**
+     * Destructures object into array of property keys or values depending on selector
+     * @param from Object to destruct
+     * @param selector Selects whether to return keys or values
+     */
+    array<From extends {} = {}>(from: From, selector: 'keys'): Array<keyof From>;
     /**
-     * Destructures object into array of property keys
+     * Destructures object into array of property keys or values depending on selector
      * @param from Object to destruct
+     * @param selector Selects whether to return keys or values
+     */
+    array<From extends {} = {}>(from: From, selector: 'values'): Array<ValueOf<From>>;
+
+    /**
+     * Returns array of object keys with proper typing
+     * @param from Object to get keys from
+     */
+    keysOf<From = {}>(from: From): Array<keyof From>;
+
+    /**
+     * Object with property filter methods by type
+     * Methods: getStrings, getNumbers, getBooleans, getUndefineds, getNulls,
+     *          getObjects, getFunctions, getAnys, getDates, getRegExps,
+     *          getPromises, getArrays, getMaps, getSets
+     * @example Object.properties.getStrings(obj) // Returns object with only string properties
      */
-    keysOf<From = {}>(from: From): Array<keyof From>
+    properties: {
+        getStrings<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getNumbers<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getBooleans<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getUndefineds<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getNulls<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getObjects<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getFunctions<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getAnys<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getDates<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getRegExps<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getPromises<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getArrays<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getMaps<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+        getSets<Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions): Partial<Source>;
+    };
 }
 ```
 
+#### Standalone Functions
+
+```ts
+/**
+ * Creates new object omitting specified properties
+ * @param from Source object
+ * @param props Properties to omit
+ */
+function omit<From extends {}, Props extends keyof From>(from: From, ...props: Array<Props | Partial<From>>): Omit<From, Props>;
+
+/**
+ * Creates new object with only specified properties
+ * @param from Source object
+ * @param props Properties to pick
+ */
+function pick<From extends {}, Props extends keyof From>(from: From, ...props: Array<Props | Partial<From>>): Pick<From, Props>;
+
+/**
+ * Returns the difference between two objects
+ * @param source Source object
+ * @param target Target object
+ * @param exclude Properties to exclude from comparison
+ */
+function difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Partial<T>;
+
+/**
+ * Deeply combines multiple objects
+ * @param objects Objects to combine
+ */
+function combine<T extends Record<string, any | undefined>>(...objects: Array<T | undefined>): T;
+
+/**
+ * Deep equality check for objects
+ * @param a First object
+ * @param b Second object
+ */
+function areEqual<T extends object | null>(a?: T, b?: T): boolean;
+
+/**
+ * Type guard for null or undefined
+ * @param obj Value to check
+ */
+function isNullOrUndefined(obj: any): obj is null | undefined;
+```
+
 ### String
 
 ```ts
 interface String {
     /**
-     * Uppercases first letter of string
-     */
-    toPascalCase(): string
-    /**
-     * Replaces "replacer" (default: ' ') with "replacement" (default: '_')
-     * @param replaceOptions This is practically your stereotypical String.replace, if you really want it to be
-     */
-    toSnakeCase(replaceOptions?: IReplacement): string
-    /**
-     * Replaces "replacer" (default: ' ') with "replacement" (default: '-')
-     * @param replaceOptions This is practically your stereotypical String.replace, if you really want it to be
+     * Converts string from one case to another
+     * @param from Case to convert from ('camel' | 'pascal' | 'snake' | 'kebab' | 'lower' | 'upper')
+     * @param to Cases to convert to, can chain multiple conversions
      */
-    toKebabCase(replaceOptions?: IReplacement): string
+    convertCase(from: Case, ...to: Array<Case>): string;
+
     /**
-     * String.substring but accepting negative numbers to cut from length
-     * @param start Start of string. 0 indexed, if negative number, subtracts number from length
-     * @param end End of string. 0 indexed, if negative number, substracts number from length
+     * Truncates string to specified length with optional ellipsis
+     * @param length Maximum length of string
+     * @param ellipsis String to append if truncated (default: '...')
      */
-    clip(start: number, end?: number): string
+    truncate(length: number, ellipsis?: string): string;
 }
 ```
+
+#### Standalone Function
+
+```ts
+/**
+ * Converts a string's case
+ * @param value String to convert
+ * @param from Source case format
+ * @param to Target case format(s)
+ */
+function convertCase(value: string, from: Case, ...to: Array<Case>): string;
+```