danholibraryjs 2.0.0 → 2.0.2

package/docs/Types.md

@@ -4,115 +4,244 @@
 
 ### General
 
-``` ts
+```ts
 /**
- * Type's properties are ReturnType
+ * Used for HTMLElement.append in ElementOptions, Document.createElement.
+ * IElement accepts HTML Elements or HTML-like strings.
  */
-type AllPropsAre<ReturnType> = {
-    [key: string]: ReturnType
-}
+type IElement = HTMLElement | string;
 
 /**
- * Item is single or multiple
+ * string or RegExp
  */
-type Arrayable<T> = T | Array<T>;
+type StringRegex = string | RegExp;
 
 /**
- * If Condition is true, Then, Else... pretty self-explanatory
+ * Conditional type - If Boolean is true, returns True, otherwise False
  */
-type If<Condition, Then, Else> = Condition extends true ? Then : Else;
+type If<Boolean extends boolean, True, False> = Boolean extends true ? True : False;
 
 /**
- * Used for HTMLElement.append in ElementOptions, Document.createProperElement.
- * IElement accepts HTML Elements or HTMl-like strings.
- * 
- * @see HTMLElement.append
- * @see Document.createProperElement
+ * Return types of T
  */
-type IElement = HTMLElement | string;
+type ValueOf<T> = T[keyof T];
+```
 
+### Able
+
+```ts
 /**
- * string or RegExp.. pretty self-explanatory
+ * Value can be either T or a function that returns T
  */
-type StringRegex = string | RegExp;
+type Functionable<T, Args extends any[] = []> = T | ((...args: Args) => T);
 
 /**
- * Return types of T
+ * Value can be either T or a Promise that resolves to T
  */
-type ValueOf<T> = T[keyof T];
+type Promiseable<T> = T | Promise<T>;
+
+/**
+ * Value can be T or null
+ */
+type Nullable<T> = T | null;
+
+/**
+ * Removes null and undefined from T
+ */
+type NonNullable<T> = T extends null | undefined ? never : T;
+```
+
+### Array
+
+```ts
+/**
+ * Item is single or multiple (T or Array<T>)
+ */
+type Arrayable<T> = T | Array<T>;
+
+/**
+ * Item is single or wrapped in single-element array
+ */
+type SingleArrayable<T> = T | [T];
+
+/**
+ * Extracts type from Array<T>
+ */
+type TFromArray<T> = T extends Array<infer U> ? U : never;
 ```
 
 ### BetterTypes
 
 ```ts
 /**
- * Construct a type with the properties of Type except for those in type Properties.
+ * Construct a type with the properties of Type except for those in Properties
  */
 type BetterOmit<Type, Properties extends keyof Type> = Omit<Type, Properties>;
+
 /**
  * Extract from From those types that are assignable to Properties
  */
 type BetterExtract<From, Properties extends From> = Extract<From, Properties>;
+
+/**
+ * Partial type but with required properties
+ */
+type PartialExcept<From, Properties extends keyof From> = Partial<From> & Required<Pick<From, Properties>>;
+```
+
+### C# Types
+
+```ts
+/**
+ * GUID string
+ */
+type Guid = string;
+
+/**
+ * TimeSpan string format
+ */
+type TimeSpanType = string;
+```
+
+### Date
+
+```ts
+/**
+ * Long month names
+ */
+type LongMonth = 'January' | 'February' | 'March' | 'April' | 'May' | 'June' | 'July' | 'August' | 'September' | 'October' | 'November' | 'December';
+
+/**
+ * Short month names
+ */
+type ShortMonth = 'Jan' | 'Feb' | 'Mar' | 'Apr' | 'May' | 'Jun' | 'Jul' | 'Aug' | 'Sep' | 'Oct' | 'Nov' | 'Dec';
+
+/**
+ * Month name (long or short)
+ */
+type Month = LongMonth | ShortMonth;
+
+/**
+ * Short day names
+ */
+type ShortDay = 'Mon' | 'Tue' | 'Wed' | 'Thu' | 'Fri' | 'Sat' | 'Sun';
+
+/**
+ * Long day names
+ */
+type LongDay = `${'Mon' | 'Tues' | 'Wednes' | 'Thurs' | 'Fri' | 'Satur' | 'Sun'}day`;
+
+/**
+ * Day name (long or short)
+ */
+type Day = ShortDay | LongDay;
+
+/**
+ * Constructor type for DanhoDate
+ */
+type DanhoDateConstructor = TimeProperties | string | number | Date;
+
+/**
+ * Time properties object
+ */
+type TimeProperties<Plural extends boolean = false> = Record<Plural extends true ? `${TimeKeys}s` : TimeKeys, number>;
+
+/**
+ * What properties to include when using TimeSpan.toString()
+ */
+type TimeSpanFormat = Partial<TransformType<TimeProperties<true>, number, boolean>>;
 ```
 
 ### Events
 
 ```ts
 /**
- * Default eventhandler mapper. Object with properties that are arrays
+ * Default event handler mapper. Object with properties that are arrays
  */
- type BaseEvent<Keys extends string, Types extends Array<any>> = Record<Keys, Types>;
+type BaseEvent<Keys extends string, Types extends Array<any>> = Record<Keys, Types>;
 
- /**
-  * Eventhandler type for:
-  * @see EventCollection
-  * @borrows BaseEvent
-  */
- type EventHandler<
-     Events extends BaseEvent<string, Array<any>> = BaseEvent<string, Array<any>>,
-     Event extends keyof Events = keyof Events,
-     ReturnType = any
- > = (...args: Events[Event]) => ReturnType;
+/**
+ * Event handler type
+ */
+type EventHandler<
+    Events extends BaseEvent<string, Array<any>> = BaseEvent<string, Array<any>>,
+    Event extends keyof Events = keyof Events,
+    ReturnType = any
+> = (...args: Events[Event]) => ReturnType;
 ```
 
-### PropertiesWith
+### Function
 
 ```ts
 /**
- * Filters all properties from From that has the return type of Type
+ * Changes return type of a function
  */
-type PropertiesWith<Type, From> = {
-    [Key in keyof From as From[Key] extends Type ? Key : never]: From[Key]
-}
-default PropertiesWith;
+type NewReturnType<Func extends (...args: any[]) => any, NewReturn> = 
+    Func extends (...args: infer Args) => any ? (...args: Args) => NewReturn : never;
 
 /**
- * Fitlers all properties from From that don't have the return type of Type
+ * Wraps function return type in Promise
  */
-type PropertiesWithout<Type, From> = {
-    [Key in keyof From as From[Key] extends Type ? never : Key]: From[Key]
-}
+type PromisedReturn<Func extends (...args: any[]) => any> = 
+    Func extends (...args: infer Args) => infer Return ? (...args: Args) => Promise<Return> : never;
+
+/**
+ * Removes all function properties from type
+ */
+type NoFunctions<T> = { [K in keyof T]: T[K] extends Function ? never : T[K] };
 ```
 
-### Time
+### Object
 
 ```ts
 /**
- * Type used to construct DanhoDate.
- * @Data Partial TimeProperties except years & months
- * @DateFormat string as dd/MM/yyyy
+ * Type's properties are all ReturnType
+ */
+type AllPropsAre<ReturnType> = {
+    [key: string]: ReturnType;
+};
+```
+
+### PropertiesWith
+
+```ts
+/**
+ * Filters all properties from From that have the return type of Type
+ */
+type PropertiesWith<Type, From> = {
+    [Key in keyof From as From[Key] extends Type ? Key : never]: From[Key];
+};
+
+/**
+ * Filters all properties from From that don't have the return type of Type
  */
-type DanhoDateConstructor = Data | DateFormat | number | Date;
+type PropertiesWithout<Type, From> = {
+    [Key in keyof From as From[Key] extends Type ? never : Key]: From[Key];
+};
 
 /**
- * Object interface with keys above to number values. If Plural is true, all properties ends with 's'
+ * Gets keys that appear in all types in the array
  */
-type TimeProperties<Plural extends boolean = false> = Record<Plural extends true ? `${TimeKeys}s` : TimeKeys, number>
+type GetRepeatedKeys<Types extends Array<any>> = 
+    Types extends [infer First, ...infer Rest]
+        ? Rest extends Array<any>
+            ? keyof First & GetRepeatedKeys<Rest>
+            : keyof First
+        : never;
 
 /**
- * What properties to include when using TimeSpan.toString(format: TimeSpanFormat): string
+ * Filters types that have specific properties
  */
-type TimeSpanFormat = Partial<TransformType<TimeProperties<true>, number, boolean>>
+type ModelWithProps<T, TProps extends (keyof T | string)> = T extends Record<TProps, any> ? T : never;
+```
+
+### String
+
+```ts
+/**
+ * Autocomplete type - allows string literal autocomplete while still accepting any string
+ */
+type Autocomplete<T> = T | (string & {});
 ```
 
 ### TransformTypes
@@ -122,21 +251,36 @@ type TimeSpanFormat = Partial<TransformType<TimeProperties<true>, number, boolea
  * Converts Start types to Switch types in From type
  */
 type TransformType<From, Start, Switch> = {
-    [Key in keyof From]: From[Key] extends Start ? Switch : From[Key]
-}
+    [Key in keyof From]: From[Key] extends Start ? Switch : From[Key];
+};
 
 /**
  * Returns object with properties matching BaseType with types of NewType
  */
-type TransformTypes<From, BaseType, NewType> = Record<keyof { 
-    [Key in keyof From as From[Key] extends BaseType ? Key : never]: Key 
-}, NewType>
+type TransformTypes<From, BaseType, NewType> = Record<keyof {
+    [Key in keyof From as From[Key] extends BaseType ? Key : never]: Key;
+}, NewType>;
+
+/**
+ * Converts object to JSON-serializable type (removes functions, Date -> string, etc.)
+ */
+type Json<T> = {
+    [K in keyof T]: T[K] extends Function
+        ? never
+        : T[K] extends Date
+        ? string
+        : T[K] extends object
+        ? Json<T[K]>
+        : T[K];
+};
 ```
 
 ### Store
+
 ```ts
 /**
- * Reducer function to map wanted parameters when using @see Store.on(action, reducer);
+ * Reducer function for Store state updates
  */
-type Reducer<State, Types extends Record<string, any[]>, Action extends keyof Types> = (state: State, ...args: Types[Action]) => State
+type Reducer<State, Types extends Record<string, any[]>, Action extends keyof Types> = 
+    (state: State, ...args: Types[Action]) => State;
 ```

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

@@ -24,6 +24,6 @@ import { ... } from 'DanhoLibraryJS';
 
 * [Classes](./Classes.md)
 * [Extensions](./Extensions.md)
-* [Functions](./Functions.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.0",
+  "version": "2.0.2",
   "description": "Library for Javascript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",