danholibraryjs 2.0.1 → 2.0.2

package/README.md

@@ -26,3 +26,4 @@ import { ... } from 'DanhoLibraryJS';
 * [Extensions](/docs/Extensions.md)
 * [Interfaces](/docs/Interfaces.md)
 * [Types](/docs/Types.md)
+* [Utils](/docs/Utils.md)

package/dist/Extensions/Array/random.extension.d.ts

@@ -15,9 +15,8 @@ declare global {
          * @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;
+        randomWithPercentages(items: Array<[item: T, weight: number]>): T;
     }
 }
 export declare function random<T>(this: Array<T>): T;
 export declare function shuffle<T>(this: Array<T>): Array<T>;
-export declare function randomWithPercentages<T>(items: [item: T, weight: number][]): T;

package/dist/Extensions/Array/random.extension.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.randomWithPercentages = exports.shuffle = exports.random = void 0;
+exports.shuffle = exports.random = void 0;
 function random() {
     const randomIndex = Math.floor(Math.random() * this.length);
     return this[randomIndex];
@@ -12,24 +12,3 @@ function shuffle() {
 }
 exports.shuffle = shuffle;
 Array.prototype.shuffle = shuffle;
-function randomWithPercentages(items) {
-    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');
-}
-exports.randomWithPercentages = randomWithPercentages;
-Array.prototype.randomWithPercentages = randomWithPercentages;

package/dist/Extensions/Array/string.extension.d.ts

@@ -2,12 +2,11 @@ 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.
+         * @param separator The default separator to use between elements. Defaults to ','.
+         * @param endSeparator The separator to use before the last element. Default is '&'.
          * @returns A string with the joined elements.
          */
-        join(args?: Array<string | undefined>, separator?: string, endSeparator?: string): string;
+        join(separator?: string, endSeparator?: string): string;
     }
 }
 export declare function join<T>(this: Array<T>, separator?: string, endSeparator?: string): string;

package/dist/Extensions/Number.d.ts

@@ -4,10 +4,10 @@ type Separators = {
 };
 declare global {
     interface Number {
-        toSeparationString(separators: Partial<Separators>): string;
+        toSeparationString(separators?: Partial<Separators>): string;
         toRomanNumeral(): string;
     }
 }
-export declare function toSeparationString(this: number, separators: Partial<Separators>): string;
+export declare function toSeparationString(this: number, separators?: Partial<Separators>): string;
 export declare function toRomanNumeral(this: number): string;
 export {};

package/dist/Extensions/Number.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toRomanNumeral = exports.toSeparationString = void 0;
 function toSeparationString(separators) {
-    const { thousand = '.', decimal = '.' } = separators;
+    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;

package/dist/Extensions/Object/arrays.extension.d.ts

@@ -6,6 +6,18 @@ declare global {
          * @param from Object to destruct
          */
         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 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>>;
         /**
          * Destructures object into array of property keys
          * @param from Object to destruct
@@ -14,4 +26,6 @@ declare global {
     }
 }
 export declare function array<From extends {} = {}>(this: object, from: From): Array<[keyof From, ValueOf<From>]>;
+export declare function array<From extends {} = {}>(this: object, from: From, selector: 'keys'): Array<keyof From>;
+export declare function array<From extends {} = {}>(this: object, from: From, selector: 'values'): Array<ValueOf<From>>;
 export declare function keysOf<From extends {} = {}>(this: object, from: From): Array<keyof From>;

package/dist/Extensions/Object/arrays.extension.js

@@ -1,8 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.keysOf = exports.array = void 0;
-function array(from) {
-    return Object.entries(from);
+function array(from, selector) {
+    const entries = Object.entries(from);
+    switch (selector) {
+        case 'keys': return entries.map(([key]) => key);
+        case 'values': return entries.map(([, value]) => value);
+        default: return entries;
+    }
 }
 exports.array = array;
 Object.array = array;

package/dist/Extensions/Object/extracts.extension.d.ts

@@ -13,24 +13,24 @@ declare global {
          */
         pick<From extends {}, Props extends keyof From>(from: From, ...props: Array<Props | Partial<From>>): Pick<From, Props>;
         /**
-         * Receive an object with properties that are not in union of source and target objects
+         * Returns the difference between two objects (properties where values differ)
          * @param source Source object
          * @param target Target object
-         * @param exclude Properties to exclude from difference
-         * @returns Object with properties that are not in union of source and target objects, excluding specified properties
+         * @param exclude Properties to exclude from comparison
+         * @returns Object with properties where values differ between source and target, excluding specified properties
          */
-        difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Omit<T, keyof T>;
+        difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Partial<T>;
         /**
          * Deeply combines objects, with later objects in parameters taking precedence over earlier ones. Does not combine arrays.
          * @param objects Objects to combine
          * @returns Combined object
          */
-        combine<T extends Record<string, any | undefined>>(...objects: Array<Partial<T> | undefined>): T;
+        combine<T extends Record<string, any | undefined>>(...objects: Array<Combinable<T> | undefined>): T;
     }
 }
 export declare function omit<From extends {}, Props extends keyof From>(from: From, ...props: Array<Props | Partial<From>>): Omit<From, Props>;
 export declare function pick<From extends {}, Props extends keyof From>(from: From, ...props: Array<Props | Partial<From>>): Pick<From, Props>;
-export declare function difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Omit<T, keyof T>;
+export declare function difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Partial<T>;
 type Combinable<T extends Record<string, any>> = {
     [key in keyof T]?: T[key] extends Record<string, any> ? Combinable<T[key]> : T[key];
 };

package/dist/Extensions/Object/extracts.extension.js

@@ -30,13 +30,16 @@ function pick(from, ...props) {
 exports.pick = pick;
 Object.pick = pick;
 function difference(source, target, ...exclude) {
-    const diffKeys = new Set([...Object.keysOf(source), ...Object.keysOf(target)]);
-    exclude?.forEach(key => diffKeys.delete(key));
-    return [...diffKeys.values()].reduce((acc, key, i, arr) => {
-        const sourceValue = JSON.stringify(source[key]);
-        const targetValue = JSON.stringify(target[key]);
-        if (sourceValue !== targetValue)
-            acc[key] = target[key];
+    const excludeSet = new Set(exclude);
+    const allKeys = new Set([...Object.keysOf(source), ...Object.keysOf(target)]);
+    return [...allKeys].reduce((acc, key) => {
+        if (excludeSet.has(key))
+            return acc;
+        const sourceValue = source[key];
+        const targetValue = target[key];
+        if (JSON.stringify(sourceValue) !== JSON.stringify(targetValue)) {
+            acc[key] = targetValue;
+        }
         return acc;
     }, {});
 }

package/dist/Extensions/String/index.d.ts

@@ -1 +1,2 @@
 export * from './case.extension';
+export * from './string.extension';

package/dist/Extensions/String/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./case.extension"), exports);
+__exportStar(require("./string.extension"), exports);

package/dist/Extensions/String/string.extension.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface String {
+        truncate(length: number, ellipsis?: string): string;
+    }
+}
+export declare function truncate(this: string, length: number, ellipsis?: string): string;

package/dist/Extensions/String/string.extension.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.truncate = void 0;
+function truncate(length, ellipsis = "...") {
+    if (this.length <= length)
+        return this;
+    return this.slice(0, length - ellipsis.length) + ellipsis;
+}
+exports.truncate = truncate;
+String.prototype.truncate = truncate;

package/dist/Types/Able.d.ts

@@ -5,7 +5,7 @@ export type Functionable<T, Args extends any[] = []> = T | ((...args: Args) => T
 /**
  * Item is Promise<T> or T
  */
-export type Promisable<T> = T | Promise<T>;
+export type Promiseable<T> = T | Promise<T>;
 /**
  * Item is T or null
  */

package/dist/Utils/NumberUtils.d.ts

@@ -1 +1,6 @@
 export declare function between(min: number, max: number): number;
+export declare function randomWithPercentages<T>(items: [item: T, weight: number][]): T;
+export declare const NumberUtils: {
+    between: typeof between;
+    randomWithPercentages: typeof randomWithPercentages;
+};

package/dist/Utils/NumberUtils.js

@@ -1,7 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.between = void 0;
+exports.NumberUtils = exports.randomWithPercentages = exports.between = void 0;
 function between(min, max) {
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 exports.between = between;
+function randomWithPercentages(items) {
+    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');
+}
+exports.randomWithPercentages = randomWithPercentages;
+exports.NumberUtils = {
+    between,
+    randomWithPercentages,
+};

package/dist/Utils/StringUtils.d.ts

@@ -1,3 +1,8 @@
 export declare function classNames(...args: Array<any>): string;
 export declare function randomId(length?: number): string;
 export declare function pluralize(countable: number | ArrayLike<any> | Map<any, any>, singular: string, plural?: string): string;
+export declare const StringUtils: {
+    classNames: typeof classNames;
+    randomId: typeof randomId;
+    pluralize: typeof pluralize;
+};

package/dist/Utils/StringUtils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pluralize = exports.randomId = exports.classNames = void 0;
+exports.StringUtils = exports.pluralize = exports.randomId = exports.classNames = void 0;
 function classNames(...args) {
     return args.reduce((acc, arg) => {
         if (!arg)
@@ -45,3 +45,8 @@ function pluralize(countable, singular, plural) {
     return `${singular}s`;
 }
 exports.pluralize = pluralize;
+exports.StringUtils = {
+    classNames,
+    randomId,
+    pluralize
+};

package/dist/Utils/TimeUtils/index.d.ts

@@ -1,4 +1,7 @@
 export declare const TimeUtils: {
+    ensureStartZero(num: number): string;
+    get12HourFormat(hour: number): string;
+    get24HourFormat(hour: number): string;
     throttle<T>(throttleId: string, callback: () => T, cooldown: number): T;
     wrapInThrottle<T_1>(callback: (...args: T_1[]) => void, cooldown: number): (...args: T_1[]) => void;
     isThrottleOnCooldown(throttleId: string): boolean;

package/dist/Utils/TimeUtils/index.js

@@ -27,8 +27,10 @@ exports.TimeUtils = void 0;
 const Debounce = __importStar(require("./debounce.util"));
 const Functions = __importStar(require("./functions.util"));
 const Throttle = __importStar(require("./throttle.util"));
+const StringUtils = __importStar(require("./string.util"));
 exports.TimeUtils = {
     ...Functions,
     ...Debounce,
     ...Throttle,
+    ...StringUtils,
 };

package/dist/Utils/TimeUtils/string.util.d.ts

@@ -0,0 +1,3 @@
+export declare function ensureStartZero(num: number): string;
+export declare function get12HourFormat(hour: number): string;
+export declare function get24HourFormat(hour: number): string;

package/dist/Utils/TimeUtils/string.util.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.get24HourFormat = exports.get12HourFormat = exports.ensureStartZero = void 0;
+function ensureStartZero(num) {
+    return num < 10 ? `0${num}` : num.toString();
+}
+exports.ensureStartZero = ensureStartZero;
+function get12HourFormat(hour) {
+    if (hour === 0)
+        return '12am';
+    if (hour > 12)
+        return `${hour - 12}pm`;
+    return `${hour}am`;
+}
+exports.get12HourFormat = get12HourFormat;
+function get24HourFormat(hour) {
+    return ensureStartZero(hour);
+}
+exports.get24HourFormat = get24HourFormat;

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './Classes';
 export * from './Extensions';
 export * from './Interfaces';
 export * from './Types';
+export * from './Utils';

package/dist/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./Classes"), exports);
 __exportStar(require("./Extensions"), exports);
 __exportStar(require("./Interfaces"), exports);
 __exportStar(require("./Types"), exports);
+__exportStar(require("./Utils"), exports);

package/docs/Extensions.md

@@ -108,16 +108,6 @@ interface ArrayConstructor {
 }
 ```
 
-#### Standalone Functions
-
-```ts
-/**
- * Selects random item from weighted items
- * @param items Array of [item, weight] tuples where weight is probability
- */
-function randomWithPercentages<T>(items: [item: T, weight: number][]): T;
-```
-
 ### Function
 
 ```ts
@@ -192,9 +182,9 @@ interface Map<K, V> {
 interface Number {
     /**
      * Formats number with thousand and decimal separators
-     * @param separators Custom separators for thousand and decimal
+     * @param separators Custom separators for thousand and decimal (optional)
      */
-    toSeparationString(separators: Partial<{ thousand: string; decimal: string }>): string;
+    toSeparationString(separators?: Partial<{ thousand: string; decimal: string }>): string;
 
     /**
      * Converts number to Roman numeral (1-3999)
@@ -210,16 +200,52 @@ interface Number {
 ```ts
 interface ObjectConstructor {
     /**
-     * Converts object to array of [key, value] tuples
-     * @param from Object to convert
+     * 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 or values depending on selector
+     * @param from Object to destruct
+     * @param selector Selects whether to return keys or values
      */
-    array<From = {}>(from: From): Array<[keyof From, ValueOf<From>]>;
+    array<From extends {} = {}>(from: From, selector: 'keys'): Array<keyof 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: '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
+     */
+    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>;
+    };
 }
 ```
 
@@ -278,6 +304,13 @@ interface String {
      * @param to Cases to convert to, can chain multiple conversions
      */
     convertCase(from: Case, ...to: Array<Case>): string;
+
+    /**
+     * Truncates string to specified length with optional ellipsis
+     * @param length Maximum length of string
+     * @param ellipsis String to append if truncated (default: '...')
+     */
+    truncate(length: number, ellipsis?: string): string;
 }
 ```
 

package/docs/Types.md

@@ -38,7 +38,7 @@ type Functionable<T, Args extends any[] = []> = T | ((...args: Args) => T);
 /**
  * Value can be either T or a Promise that resolves to T
  */
-type Promisable<T> = T | Promise<T>;
+type Promiseable<T> = T | Promise<T>;
 
 /**
  * Value can be T or null

package/docs/Utils.md

@@ -0,0 +1,335 @@
+# [DanhoLibraryJS](../README.md)
+
+## Utils
+
+Utility functions and classes for common tasks.
+
+### ApiUtils
+
+```ts
+/**
+ * API utility class for making HTTP requests
+ */
+class ApiUtils<ApiEndpoints extends string> {
+    /**
+     * @param options Configuration options
+     * @param options.baseEndpointDev Base URL for development environment
+     * @param options.baseEndpoint Base URL for production environment (optional)
+     * @param options.log Enable request logging (default: false)
+     */
+    constructor(options: {
+        baseEndpointDev: string;
+        baseEndpoint?: string;
+        log?: boolean;
+    });
+
+    /**
+     * Make a request to the API
+     * @param path The path to the endpoint
+     * @param options Request options (method, body, headers, etc.)
+     * @returns The response from the API
+     */
+    public async request<TData>(
+        path: ApiEndpoints,
+        options?: RequestOptions
+    ): Promise<TData>;
+
+    /**
+     * Get the base endpoint URL based on environment
+     */
+    public get baseEndpoint(): string;
+}
+
+/**
+ * Request options type
+ */
+type RequestOptions<TBody = any> = Omit<RequestInit, 'method' | 'body'> & {
+    method?: HttpMethods;
+    body?: TBody;
+    params?: Record<string, string | number | boolean>;
+};
+
+/**
+ * HTTP methods
+ */
+type HttpMethods =
+    | 'GET'
+    | 'POST'
+    | 'PUT'
+    | 'PATCH'
+    | 'DELETE'
+    | 'HEAD'
+    | 'OPTIONS';
+```
+
+### ColorUtils
+
+```ts
+/**
+ * RGB color as tuple
+ */
+type RGB = [number, number, number];
+
+/**
+ * Hex color string
+ */
+type Hex = `#${string}`;
+
+/**
+ * Color type identifier
+ */
+type ColorType = 'hex' | 'rgb' | 'hsl';
+
+/**
+ * Convert colors between different formats
+ * @param value Color value to convert
+ * @param fromOrTo Source format (for strings) or target format (for RGB)
+ * @param to Target format (when converting from string)
+ */
+function convert(value: RGB, to: Exclude<ColorType, 'rgb'>): string;
+function convert(value: string, from: Exclude<ColorType, 'rgb'>, to: 'rgb'): RGB;
+function convert(value: string | RGB, fromOrTo: ColorType, to?: ColorType): string | RGB;
+
+/**
+ * Generate a random hex color
+ * @returns Random hex color string
+ */
+function generateRandomColor(): Hex;
+
+/**
+ * Color utilities object
+ */
+const ColorUtils = {
+    convert,
+    generateRandomColor
+};
+```
+
+### FormUtils
+
+```ts
+/**
+ * Serialize a form into an object
+ * @param form The form element to serialize
+ * @param log Whether to log the serialization process (default: false)
+ * @returns An object containing the form data
+ */
+function serializeForm<T extends object>(form: HTMLFormElement, log?: boolean): T;
+```
+
+### NumberUtils
+
+```ts
+/**
+ * Generate a random number between min and max (inclusive)
+ * @param min Minimum value
+ * @param max Maximum value
+ * @returns Random number between min and max
+ */
+function between(min: number, max: number): number;
+
+/**
+ * Select a random item from weighted items
+ * @param items Array of [item, weight] tuples where weight determines probability
+ * @returns Randomly selected item based on weights
+ * @throws Error if items array is empty or total weight is zero
+ */
+function randomWithPercentages<T>(items: [item: T, weight: number][]): T;
+
+/**
+ * Number utilities object
+ */
+const NumberUtils = {
+    between,
+    randomWithPercentages,
+};
+```
+
+### PatcherUtils
+
+```ts
+/**
+ * Patch event type
+ */
+type PatchEvent = 'before' | 'instead' | 'after';
+
+/**
+ * Monkey patch a property or method on an object
+ * @param target Object to patch
+ * @param property Property or method name to patch
+ * @param event When to run the patch ('before', 'instead', or 'after')
+ * @param replacement Replacement function or value handler
+ * @returns Function to unpatch
+ */
+function patch<
+    TTarget extends object,
+    TProperty extends keyof TTarget,
+    TPatchEvent extends PatchEvent,
+    TPatchReplacement extends PatcherReplacement<TTarget, TProperty, TPatchEvent>
+>(
+    target: TTarget,
+    property: TProperty,
+    event: TPatchEvent,
+    replacement: TPatchReplacement
+): (() => void) | undefined;
+
+/**
+ * Remove all patches from a specific property
+ * @param target Object with patches
+ * @param property Property to unpatch
+ */
+function unpatch<TTarget extends object, TProperty extends keyof TTarget>(
+    target: TTarget,
+    property: TProperty
+): void;
+
+/**
+ * Remove all patches from all objects
+ */
+function unpatchAll(): void;
+```
+
+### StringUtils
+
+```ts
+/**
+ * Combines class names from various input types
+ * Supports strings, objects (key-value where truthy values include the key),
+ * arrays, and nested structures
+ * @param args Class name arguments
+ * @returns Combined class name string
+ */
+function classNames(...args: Array<any>): string;
+
+/**
+ * Generate a random ID string
+ * @param length Length of the ID (default: 16)
+ * @returns Random alphanumeric string
+ */
+function randomId(length?: number): string;
+
+/**
+ * Pluralize a word based on count
+ * @param countable Number, array-like object, or Map to count
+ * @param singular Singular form of the word
+ * @param plural Optional custom plural form (default: adds 's' to singular)
+ * @returns Singular or plural form based on count
+ */
+function pluralize(
+    countable: number | ArrayLike<any> | Map<any, any>,
+    singular: string,
+    plural?: string
+): string;
+```
+
+### TimeUtils
+
+```ts
+/**
+ * Wait for a specified amount of time or execute a callback after a delay
+ * @param time Milliseconds to wait
+ */
+function wait<T>(time: number): Promise<void>;
+function wait<T>(callback: (...args: any[]) => T, time: number): Promise<T>;
+
+/**
+ * Get Unix timestamp from various date formats
+ * @param date Date object or date string
+ */
+function getUnixTime(date: Date | string): number;
+function getUnixTime(timestamp: number): number;
+
+/**
+ * Debounce a function call
+ * @param debounceId Unique identifier for this debounce
+ * @param callback Function to debounce
+ * @param delay Delay in milliseconds
+ * @param signal Optional AbortSignal to cancel the debounce
+ * @returns Promise that resolves with callback result or rejects if cancelled
+ */
+function debounce<T>(
+    debounceId: string,
+    callback: () => T,
+    delay: number,
+    signal?: AbortSignal
+): Promise<T>;
+
+/**
+ * Wrap a function in a debounce
+ * @param callback Function to wrap
+ * @param delay Delay in milliseconds
+ * @returns Debounced function
+ */
+function wrapInDebounce<T>(
+    callback: (...args: T[]) => void,
+    delay: number
+): (...args: T[]) => void;
+
+/**
+ * Throttle a function call
+ * @param throttleId Unique identifier for this throttle
+ * @param callback Function to throttle
+ * @param cooldown Cooldown period in milliseconds
+ * @returns Callback result or undefined if on cooldown
+ */
+function throttle<T>(
+    throttleId: string,
+    callback: () => T,
+    cooldown: number
+): T | undefined;
+
+/**
+ * Wrap a function in a throttle
+ * @param callback Function to wrap
+ * @param cooldown Cooldown period in milliseconds
+ * @returns Throttled function
+ */
+function wrapInThrottle<T>(
+    callback: (...args: T[]) => void,
+    cooldown: number
+): (...args: T[]) => void;
+
+/**
+ * Check if a throttle is currently on cooldown
+ * @param throttleId Throttle identifier to check
+ * @returns True if on cooldown, false otherwise
+ */
+function isThrottleOnCooldown(throttleId: string): boolean;
+
+/**
+ * Ensure a number is formatted with a leading zero if less than 10
+ * @param num Number to format
+ * @returns String with leading zero if needed
+ */
+function ensureStartZero(num: number): string;
+
+/**
+ * Convert 24-hour format to 12-hour format with am/pm
+ * @param hour Hour in 24-hour format (0-23)
+ * @returns Hour in 12-hour format with am/pm suffix
+ */
+function get12HourFormat(hour: number): string;
+
+/**
+ * Format hour in 24-hour format with leading zero
+ * @param hour Hour to format
+ * @returns Hour as two-digit string
+ */
+function get24HourFormat(hour: number): string;
+
+/**
+ * Time utilities object containing all time-related functions
+ */
+const TimeUtils = {
+    wait,
+    getUnixTime,
+    debounce,
+    wrapInDebounce,
+    throttle,
+    wrapInThrottle,
+    isThrottleOnCooldown,
+    ensureStartZero,
+    get12HourFormat,
+    get24HourFormat
+};
+```

package/docs/index.md

@@ -26,3 +26,4 @@ import { ... } from 'DanhoLibraryJS';
 * [Extensions](./Extensions.md)
 * [Interfaces](./Interfaces.md)
 * [Types](./Types.md)
+* [Utils](./Utils.md)

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Library for Javascript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

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

@@ -17,7 +17,7 @@ declare global {
      * @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;
+    randomWithPercentages(items: Array<[item: T, weight: number]>): T;
   }
 }
 
@@ -30,27 +30,4 @@ 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;
+Array.prototype.shuffle = shuffle;

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

@@ -2,12 +2,11 @@ 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.
+     * @param separator The default separator to use between elements. Defaults to ','.
+     * @param endSeparator The separator to use before the last element. Default is '&'.
      * @returns A string with the joined elements.
      */
-    join(args?: Array<string | undefined>, separator?: string, endSeparator?: string): string;
+    join(separator?: string, endSeparator?: string): string;
   }
 }
 

package/src/Extensions/Number.ts

@@ -5,13 +5,13 @@ type Separators = {
 
 declare global {
   interface Number {
-    toSeparationString(separators: Partial<Separators>): string;
+    toSeparationString(separators?: Partial<Separators>): string;
     toRomanNumeral(): string;
   }
 }
 
-export function toSeparationString(this: number, separators: Partial<Separators>): string {
-  const { thousand = '.', decimal = '.' } = separators;
+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;

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

@@ -7,6 +7,18 @@ declare global {
      * @param from Object to destruct
      */
     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 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>>;
 
     /**
      * Destructures object into array of property keys
@@ -16,8 +28,17 @@ declare global {
   }
 }
 
-export function array<From extends {} = {}>(this: object, from: From): Array<[keyof From, ValueOf<From>]> {
-  return Object.entries(from) as Array<[keyof From, ValueOf<From>]>;
+export function array<From extends {} = {}>(this: object, from: From): Array<[keyof From, ValueOf<From>]>;
+export function array<From extends {} = {}>(this: object, from: From, selector: 'keys'): Array<keyof From>;
+export function array<From extends {} = {}>(this: object, from: From, selector: 'values'): Array<ValueOf<From>>;
+export function array<From extends {} = {}>(this: object, from: From, selector?: 'keys' | 'values') {
+  const entries = Object.entries(from) as Array<[keyof From, ValueOf<From>]>;
+  
+  switch (selector) {
+    case 'keys': return entries.map(([key]) => key);
+    case 'values': return entries.map(([, value]) => value);
+    default: return entries;
+  }
 }
 Object.array = array;
 

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

@@ -15,20 +15,20 @@ declare global {
     pick<From extends {}, Props extends keyof From>(from: From, ...props: Array<Props | Partial<From>>): Pick<From, Props>;
 
     /**
-     * Receive an object with properties that are not in union of source and target objects
+     * Returns the difference between two objects (properties where values differ)
      * @param source Source object 
      * @param target Target object 
-     * @param exclude Properties to exclude from difference
-     * @returns Object with properties that are not in union of source and target objects, excluding specified properties
+     * @param exclude Properties to exclude from comparison
+     * @returns Object with properties where values differ between source and target, excluding specified properties
      */
-    difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Omit<T, keyof T>;
+    difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Partial<T>;
 
     /**
      * Deeply combines objects, with later objects in parameters taking precedence over earlier ones. Does not combine arrays.
      * @param objects Objects to combine
      * @returns Combined object
      */
-    combine<T extends Record<string, any | undefined>>(...objects: Array<Partial<T> | undefined>): T;
+    combine<T extends Record<string, any | undefined>>(...objects: Array<Combinable<T> | undefined>): T;
   }
 }
 
@@ -60,16 +60,21 @@ export function pick<From extends {}, Props extends keyof From>(from: From, ...p
 }
 Object.pick = pick;
 
-export function difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Omit<T, keyof T> {
-  const diffKeys = new Set([...Object.keysOf(source), ...Object.keysOf(target)]);
-  exclude?.forEach(key => diffKeys.delete(key));
+export function difference<T extends object>(source: T, target: T, ...exclude: Array<keyof T>): Partial<T> {
+  const excludeSet = new Set(exclude);
+  const allKeys = new Set([...Object.keysOf(source), ...Object.keysOf(target)]);
 
-  return [...diffKeys.values()].reduce((acc, key, i, arr) => {
-    const sourceValue = JSON.stringify(source[key]);
-    const targetValue = JSON.stringify(target[key]);
-    if (sourceValue !== targetValue) acc[key] = target[key];
+  return [...allKeys].reduce((acc, key) => {
+    if (excludeSet.has(key)) return acc;
+    
+    const sourceValue = (source as any)[key];
+    const targetValue = (target as any)[key];
+    
+    if (JSON.stringify(sourceValue) !== JSON.stringify(targetValue)) {
+      acc[key] = targetValue;
+    }
     return acc;
-  }, {} as T);
+  }, {} as any) as Partial<T>;
 }
 Object.difference = difference;
 

package/src/Extensions/String/index.ts

@@ -1 +1,2 @@
-export * from './case.extension';
+export * from './case.extension';
+export * from './string.extension';

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

@@ -0,0 +1,11 @@
+declare global {
+  interface String {
+    truncate(length: number, ellipsis?: string): string;
+  }
+}
+
+export function truncate(this: string, length: number, ellipsis: string = "..."): string {
+  if (this.length <= length) return this;
+  return this.slice(0, length - ellipsis.length) + ellipsis;
+}
+String.prototype.truncate = truncate;

package/src/Types/Able.ts

@@ -6,7 +6,7 @@ export type Functionable<T, Args extends any[] = []> = T | ((...args: Args) => T
 /**
  * Item is Promise<T> or T
  */
-export type Promisable<T> = T | Promise<T>;
+export type Promiseable<T> = T | Promise<T>;
 
 /**
  * Item is T or null

package/src/Utils/NumberUtils.ts

@@ -1,3 +1,30 @@
 export function between(min: number, max: number): number {
   return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+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');
+}
+
+export const NumberUtils = {
+  between,
+  randomWithPercentages,
 }

package/src/Utils/StringUtils.ts

@@ -41,4 +41,10 @@ export function pluralize(countable: number | ArrayLike<any> | Map<any, any>, si
   if (count === 1) return singular;
   if (plural) return plural;
   return `${singular}s`;
-}
+}
+
+export const StringUtils = {
+  classNames,
+  randomId,
+  pluralize
+};

package/src/Utils/TimeUtils/index.ts

@@ -1,9 +1,11 @@
 import * as Debounce from './debounce.util';
 import * as Functions from './functions.util';
 import * as Throttle from './throttle.util';
+import * as StringUtils from './string.util';
 
 export const TimeUtils = {
   ...Functions,
   ...Debounce,
   ...Throttle,
+  ...StringUtils,
 };

package/src/Utils/TimeUtils/string.util.ts

@@ -0,0 +1,13 @@
+export function ensureStartZero(num: number): string {
+  return num < 10 ? `0${num}` : num.toString();
+}
+
+export function get12HourFormat(hour: number): string {
+  if (hour === 0) return '12am';
+  if (hour > 12) return `${hour - 12}pm`;
+  return `${hour}am`;
+}
+
+export function get24HourFormat(hour: number): string {
+  return ensureStartZero(hour);
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './Classes';
 export * from './Extensions';
 export * from './Interfaces';
-export * from './Types';
+export * from './Types';
+export * from './Utils';

package/src/Extensions/Object/properties.ts

@@ -1,51 +0,0 @@
-import { PropertiesWith, If } from '../../Types';
-import { convertCase } from '../String/case.extension';
-
-type PrimitiveMap = {
-  string: string;
-  number: number;
-  boolean: boolean;
-  undefined: undefined;
-  null: null;
-  object: object;
-  function: Function;
-  any: any;
-  Date: Date;
-  RegExp: RegExp;
-  Promise: Promise<any>;
-  Array: Array<any>;
-  Map: Map<any, any>;
-  Set: Set<any>;
-};
-
-/**
- * Object with getPrimitiveTypes<Source, AllowFunctions extends boolean>(
- *  source: Source,
- *  allowFunctions: AllowFunctions = false
- * ): Object with properties from source that matches primitive type
- */
-export type Properties = {
-  [Key in keyof PrimitiveMap as `get${Capitalize<Key>}s`]:
-  <Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions?: AllowFunctions) =>
-    If<AllowFunctions,
-      PropertiesWith<PrimitiveMap[Key] | ((...args: any[]) => PrimitiveMap[Key]), Source>,
-      PropertiesWith<PrimitiveMap[Key], Source>
-    >
-};
-
-export const properties: Properties = [
-  'string', 'number', 'boolean', 'undefined', 'null',
-  'object', 'function', 'any',
-  'Date', 'RegExp', 'Promise', 'Array', 'Map', 'Set'
-].reduce((result, primitive) => {
-  result[`get${convertCase('camel', 'pascal')}s` as keyof Properties] = function <Source extends {}, AllowFunctions extends boolean = false>(source: Source, withFunctions: AllowFunctions = false as AllowFunctions) {
-    return Object.keysOf<Source>(source).reduce((result, key) => {
-      if ((source[key] as any).constructor.name === primitive ||
-        (withFunctions && typeof source[key] === 'function' && source[key] as any).constructor.name === primitive) {
-        result[key] = source[key];
-      }
-      return result;
-    }, {} as any);
-  };
-  return result;
-}, {} as Properties);