modern-ts 0.8.0

package/dist/types/Utils/Math.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Clamps a number between a minimum and maximum value.
+ * @param n The number to clamp.
+ * @param min The minimum allowed value.
+ * @param max The maximum allowed value.
+ * @returns The clamped number.
+ */
+export declare const clamp: (n: number, min: number, max: number) => number;
+/**
+ * Rounds a number to a specified number of decimal places.
+ * @param n The number to round.
+ * @param precision The number of decimal places (default: 0).
+ * @returns The rounded number.
+ */
+export declare const round: (n: number, precision?: number) => number;
+/**
+ * Normalizes a value from a given range to [0, 1].
+ * @param n The value to normalize.
+ * @param min The minimum of the original range.
+ * @param max The maximum of the original range.
+ * @returns The normalized value in [0, 1].
+ */
+export declare const normalize: (n: number, min: number, max: number) => number;
+/**
+ * Computes the greatest common divisor (GCD) of two numbers.
+ * @param a First number
+ * @param b Second number
+ * @returns The GCD (always non-negative)
+ */
+export declare const gcd: (a: number, b: number) => number;
+/**
+ * Computes the least common multiple (LCM) of two numbers.
+ * Uses safe calculation to prevent integer overflow.
+ * @param a First number
+ * @param b Second number
+ * @returns The LCM (always non-negative), 0 if either input is 0
+ */
+export declare const lcm: (a: number, b: number) => number;
+/**
+ * Checks if a number is within a specified range [min, max).
+ * @param n The number to check.
+ * @param min The inclusive lower bound.
+ * @param max The exclusive upper bound.
+ * @returns `true` if the number is in range.
+ */
+export declare const inRange: (n: number, min: number, max: number) => boolean;
+/**
+ * Generates an array of numbers from `start` to `end` (exclusive), incremented by `step`.
+ * @param start The start of the range.
+ * @param end The end of the range (exclusive).
+ * @param step The increment between numbers (default: 1).
+ * @returns An array of numbers.
+ */
+export declare const range: (start: number, end: number, step?: number) => number[];
+/**
+ * Like `range`, but returns numbers in reverse order.
+ * @param start The start of the range.
+ * @param end The end of the range (exclusive).
+ * @param step The increment between numbers (default: 1).
+ * @returns A reversed array of numbers.
+ */
+export declare const rangeRight: (start: number, end: number, step?: number) => number[];
+/**
+ * Maps a number from one range to another linearly.
+ * @param n The input value.
+ * @param inMin Minimum of the input range.
+ * @param inMax Maximum of the input range.
+ * @param outMin Minimum of the output range.
+ * @param outMax Maximum of the output range.
+ * @returns The mapped value.
+ */
+export declare const mapRange: (n: number, inMin: number, inMax: number, outMin: number, outMax: number) => number;
+/**
+ * Generates a random floating-point number between `min` (inclusive) and `max` (exclusive).
+ * @param min The minimum value (inclusive).
+ * @param max The maximum value (exclusive).
+ * @returns A random number in [min, max).
+ */
+export declare const random: (min: number, max: number) => number;
+/**
+ * Generates a random integer between `min` and `max` (both inclusive).
+ * @param min The minimum integer (inclusive).
+ * @param max The maximum integer (inclusive).
+ * @returns A random integer in [min, max].
+ */
+export declare const randomInt: (min: number, max: number) => number;
+/**
+ * Computes the sum of an array of numbers.
+ * @param nums Array of numbers.
+ * @returns The sum.
+ */
+export declare const sum: (nums: number[]) => number;
+/**
+ * Computes the sum of values extracted from an array using a selector function.
+ * @param arr The input array.
+ * @param getValue A function to extract numeric values from items.
+ * @returns The sum of extracted values.
+ */
+export declare const sumBy: <T>(arr: T[], getValue: (item: T) => number) => number;
+/**
+ * Computes the arithmetic mean (average) of an array of numbers.
+ * @param nums Array of numbers.
+ * @returns The mean, or 0 if the array is empty.
+ */
+export declare const mean: (nums: number[]) => number;
+/**
+ * Computes the arithmetic mean of values extracted from an array.
+ * @param arr The input array.
+ * @param getValue A function to extract numeric values from items.
+ * @returns The mean of extracted values, or 0 if empty.
+ */
+export declare const meanBy: <T>(arr: T[], getValue: (item: T) => number) => number;
+/**
+ * Computes the median of an array of numbers.
+ * @param nums Array of numbers.
+ * @returns The median value.
+ */
+export declare const median: (nums: number[]) => number;
+/**
+ * Computes the median of values extracted from an array.
+ * @param arr The input array.
+ * @param getValue A function to extract numeric values from items.
+ * @returns The median of extracted values.
+ */
+export declare const medianBy: <T>(arr: T[], getValue: (item: T) => number) => number;
+/**
+ * Computes the standard deviation of an array of numbers.
+ * @param nums Array of numbers.
+ * @param isSample If `true`, computes sample standard deviation (Bessel's correction).
+ * @returns The standard deviation.
+ */
+export declare const stdDev: (nums: number[], isSample?: boolean) => number;
+/**
+ * Checks if two numbers are approximately equal within a tolerance.
+ * @param n1 First number.
+ * @param n2 Second number.
+ * @param epsilon Tolerance (default: 1e-10).
+ * @returns `true` if |n1 - n2| < epsilon.
+ */
+export declare const approxEqual: (n1: number, n2: number, epsilon?: number) => boolean;
+/**
+ * Checks if a number is even.
+ * @param n The number to check.
+ * @returns `true` if even.
+ */
+export declare const isEven: (n: number) => boolean;
+/**
+ * Checks if a number is odd.
+ * @param n The number to check.
+ * @returns `true` if odd.
+ */
+export declare const isOdd: (n: number) => boolean;
+/**
+ * Converts degrees to radians.
+ * @param deg Angle in degrees.
+ * @returns Angle in radians.
+ */
+export declare const toRadians: (deg: number) => number;
+/**
+ * Converts radians to degrees.
+ * @param rad Angle in radians.
+ * @returns Angle in degrees.
+ */
+export declare const toDegrees: (rad: number) => number;
+/**
+ * Wraps an angle in degrees to [0, 360).
+ * @param deg Input angle in degrees.
+ * @returns Wrapped angle in [0, 360).
+ */
+export declare const wrapAngle: (deg: number) => number;
+/**
+ * Computes the smallest signed difference between two angles (in degrees).
+ * Result is in [-180, 180].
+ * @param a First angle in degrees.
+ * @param b Second angle in degrees.
+ * @returns The angular difference.
+ */
+export declare const angleDist: (a: number, b: number) => number;
+/**
+ * Computes the Euclidean distance between two 2D points.
+ * @param x1 X-coordinate of the first point.
+ * @param y1 Y-coordinate of the first point.
+ * @param x2 X-coordinate of the second point.
+ * @param y2 Y-coordinate of the second point.
+ * @returns The distance.
+ */
+export declare const getDistance: (x1: number, y1: number, x2: number, y2: number) => number;
+/**
+ * Computes the squared Euclidean distance between two 2D points (faster, no sqrt).
+ * @param x1 X-coordinate of the first point.
+ * @param y1 Y-coordinate of the first point.
+ * @param x2 X-coordinate of the second point.
+ * @param y2 Y-coordinate of the second point.
+ * @returns The squared distance.
+ */
+export declare const getDistanceSq: (x1: number, y1: number, x2: number, y2: number) => number;
+/**
+ * Linearly interpolates between `start` and `end` by factor `t`.
+ * @param start Start value.
+ * @param end End value.
+ * @param t Interpolation factor (0 = start, 1 = end).
+ * @returns The interpolated value.
+ */
+export declare const lerp: (start: number, end: number, t: number) => number;
+/**
+ * Computes a point on a quadratic Bezier curve.
+ * @param p0 Start point {x, y}
+ * @param p1 Control point {x, y}
+ * @param p2 End point {x, y}
+ * @param t Interpolation factor [0, 1]
+ * @returns The interpolated point {x, y}
+ */
+export declare const bezier2: (p0: {
+    x: number;
+    y: number;
+}, p1: {
+    x: number;
+    y: number;
+}, p2: {
+    x: number;
+    y: number;
+}, t: number) => {
+    x: number;
+    y: number;
+};

package/dist/types/Utils/Object/__export__.d.ts

@@ -0,0 +1,2 @@
+export * from './base';
+export * from './clone';

package/dist/types/Utils/Object/base.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Transforms object keys using a mapper function.
+ * @template T - Object type
+ * @param obj - Source object
+ * @param fn - Function that receives (value, key) and returns new key name
+ * @returns New object with transformed keys (original values preserved)
+ * @remarks If fn returns duplicate keys, later entries will overwrite earlier ones
+ */
+export declare const mapKeys: <T extends Record<string, unknown>>(obj: T, fn: (value: T[keyof T], key: keyof T) => string) => Record<string, T[keyof T]>;
+/**
+ * Transforms object values while preserving keys.
+ * @template T - Source object type
+ * @template V - Transformed value type
+ * @param obj - Source object
+ * @param fn - Function that receives (value, key) and returns new value
+ * @returns New object with same keys but transformed values
+ */
+export declare const mapValues: <T extends Record<string, unknown>, V>(obj: T, fn: (value: T[keyof T], key: keyof T) => V) => Record<keyof T, V>;
+/**
+ * Swaps object keys and values.
+ * @template T - Object with string/number values
+ * @param obj - Source object (values must be string or number)
+ * @returns New object with keys and values swapped
+ * @remarks Duplicate values in source will cause later keys to overwrite earlier ones
+ */
+export declare const invert: <T extends Record<string, string | number>>(obj: T) => Record<string, keyof T>;
+/**
+ * Creates new object with only specified keys.
+ * @template T - Source object type
+ * @template K - Selected keys
+ * @param obj - Source object
+ * @param keys - Array of keys to include
+ * @returns New object containing only specified keys
+ * @remarks Keys not present in source object are silently ignored
+ */
+export declare const pick: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;
+/**
+ * Creates new object with keys satisfying predicate.
+ * @template T - Source object type
+ * @param obj - Source object
+ * @param predicate - Function that receives (value, key) and returns boolean
+ * @returns Partial object containing only entries where predicate returns true
+ */
+export declare const pickBy: <T extends Record<PropertyKey, unknown>>(obj: T, predicate: (value: T[keyof T], key: keyof T) => boolean) => Partial<T>;
+/**
+ * Creates new object excluding specified keys.
+ * @template T - Source object type
+ * @template K - Keys to exclude
+ * @param obj - Source object
+ * @param keys - Array of keys to exclude
+ * @returns New object without specified keys
+ * @remarks Non-enumerable properties are not included in result
+ */
+export declare const omit: <T extends object, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>;
+/**
+ * Creates new object excluding keys where predicate returns true.
+ * @template T - Source object type
+ * @param obj - Source object
+ * @param predicate - Function that receives (value, key) and returns boolean
+ * @returns Partial object excluding entries where predicate returns true
+ */
+export declare const omitBy: <T extends Record<PropertyKey, unknown>>(obj: T, predicate: (value: T[keyof T], key: keyof T) => boolean) => Partial<T>;
+/**
+ * Finds first key where predicate returns true.
+ * @template T - Source object type
+ * @param obj - Source object
+ * @param fn - Function that receives (value, key) and returns boolean
+ * @returns First matching key, or undefined if none found
+ * @remarks Only checks own enumerable properties
+ */
+export declare const findKey: <T extends object>(obj: T, fn: (value: T[keyof T], key: keyof T) => boolean) => keyof T | undefined;
+/** Symbol indicating merge should skip current property */
+export declare const MERGE_SKIP: unique symbol;
+/** Symbol indicating merge should use default logic for current property */
+export declare const MERGE_DEFAULT: unique symbol;
+/**
+ * Customizer function type for mergeWith.
+ * @returns New value, MERGE_SKIP to skip, or MERGE_DEFAULT for default logic
+ */
+type MergeCustomizer = (target_value: unknown, source_value: unknown, key: string, target: unknown, source: unknown) => unknown;
+/**
+ * Internal merge implementation.
+ * @template T - Target object type
+ * @param target - Target object (will be mutated)
+ * @param customizer - Optional customizer function
+ * @param sources - Source objects to merge
+ * @returns Mutated target object
+ * @remarks Performs deep merge for plain objects, overwrites other values
+ */
+export declare const internalMerge: <T extends Record<string, unknown>>(target: T, customizer: MergeCustomizer | undefined, ...sources: Record<string, unknown>[]) => T;
+/**
+ * Deep merges source objects into target.
+ * @template T - Target object type
+ * @param target - Target object (will be cloned)
+ * @param sources - Source objects to merge
+ * @returns New deeply merged object (target is not mutated)
+ * @remarks Uses structuredClone for deep cloning target
+ */
+export declare const merge: <T extends Record<string, unknown>>(target: T, ...sources: Record<string, unknown>[]) => T;
+/**
+ * Deep merges with customizer function.
+ * @template T - Target object type
+ * @param target - Target object (will be cloned)
+ * @param customizer - Customizer function for control over merging
+ * @param sources - Source objects to merge
+ * @returns New deeply merged object (target is not mutated)
+ */
+export declare const mergeWith: <T extends Record<string, unknown>>(target: T, customizer: MergeCustomizer, ...sources: Record<string, unknown>[]) => T;
+/**
+ * Flattens nested object to single level.
+ * @param obj - Object to flatten
+ * @param separator - Separator for nested keys (default: '.')
+ * @returns New flattened object
+ * @remarks Empty objects are preserved as objects (not flattened)
+ */
+export declare const flattenObject: (obj: Record<string, unknown>, separator?: string) => Record<string, unknown>;
+/**
+ * Recursively converts object keys to camelCase.
+ * @template T - Desired return type
+ * @param obj - Input value
+ * @returns Value with keys transformed to camelCase
+ */
+export declare const toCamelCaseKeys: <T = unknown>(obj: unknown) => T;
+/**
+ * Recursively converts object keys to snake_case.
+ * @template T - Desired return type
+ * @param obj - Input value
+ * @returns Value with keys transformed to snake_case
+ */
+export declare const toSnakeCaseKeys: <T = unknown>(obj: unknown) => T;
+export {};

package/dist/types/Utils/Object/clone.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Special symbol indicating that a value should be skipped during cloning.
+ * When returned by a customizer or encountered as a cloned value, the property will be omitted.
+ * @example
+ * const obj = { a: 1, b: 2 };
+ * const cloned = cloneDeepWith(obj, (value) => value === 1 ? CLONE_FILTER : CLONE_DEFAULT);
+ * // Result: { b: 2 }
+ */
+export declare const CLONE_FILTER: unique symbol;
+/**
+ * Special symbol indicating that the default cloning logic should be used.
+ * When returned by a customizer, the cloner will continue with its standard cloning procedure.
+ */
+export declare const CLONE_DEFAULT: unique symbol;
+/**
+ * Special symbol indicating that an empty slot should be created.
+ * When returned by a customizer for array elements, the position will be kept as an empty slot.
+ * @example
+ * const arr = [1, 2, 3];
+ * const cloned = cloneDeepWith(arr, (value, index) => {
+ *   if (index === 1) return CLONE_HOLE; // Keep index 1 as empty slot
+ *   return CLONE_DEFAULT;
+ * });
+ * // Result: [1, empty, 3] (sparse array, length: 3)
+ * // cloned[1] === undefined, but 1 in cloned === false
+ */
+export declare const CLONE_HOLE: unique symbol;
+/**
+ * Creates a shallow copy of a value.
+ * @template T - Type of value to clone
+ * @param value - Value to clone
+ * @returns Shallow clone of the value
+ * @remarks
+ * - For primitive values (null, undefined, strings, numbers, booleans, symbols, bigints):
+ *   Returns the value directly (no actual cloning needed)
+ * - For arrays: Creates a new array with the same elements (reference copy)
+ * - For plain objects: Creates a new object with the same enumerable properties (reference copy)
+ * - For other object types (Dates, RegExps, etc.): Returns a shallow copy using spread operator
+ *   which may not preserve special behaviors
+ * @example
+ * const arr = [1, 2, { a: 3 }];
+ * const clonedArr = clone(arr);
+ * clonedArr[2].a = 99; // Also modifies original array's object
+ */
+export declare const clone: <T>(value: T) => T;
+/**
+ * Checks if the given key is a valid array index.
+ * @param k - The key to check (must be a string or number)
+ * @param n - Optional maximum index (defaults to 0, meaning no upper bound)
+ * @returns True if the key is a valid array index, false otherwise
+ */
+export declare const isArrayIndex: (k: PropertyKey, n?: number) => boolean;
+/**
+ * Customizer function for controlling cloning behavior.
+ * @param value - Current value being cloned
+ * @param key - Property key of the value (undefined for root)
+ * @param object - Parent object containing the value (undefined for root)
+ * @param stack - WeakMap tracking already visited objects for circular reference detection
+ * @returns
+ * - `CLONE_FILTER`: Skip this property (omit from result)
+ * - `CLONE_DEFAULT`: Use default cloning logic
+ * - Any other value: Use as the cloned result
+ */
+export type CloneCustomizer = (value: unknown, key: PropertyKey | undefined, object: object | undefined, stack: WeakMap<object, unknown>) => unknown;
+/**
+ * Creates a deep clone of a value.
+ * @template T - Type of value to clone
+ * @param value - Value to clone
+ * @param depth - Maximum cloning depth (default: Infinity)
+ * @returns Deep clone of the value
+ */
+export declare const cloneDeep: <T>(value: T, depth?: number) => T;
+/**
+ * Creates a deep clone of a value with custom transformation logic.
+ * @template T - Type of value to clone
+ * @param value - Value to clone
+ * @param customizer - Customizer function for controlling cloning behavior
+ * @param depth - Maximum cloning depth (default: Infinity)
+ * @returns Deep clone of the value with custom transformations
+ */
+export declare const cloneDeepWith: <T>(value: T, customizer: CloneCustomizer, depth?: number) => T;