moderndash 3.9.2 → 3.11.0

package/dist/index.d.cts

@@ -128,6 +128,7 @@ declare function dropWhile<TElem>(array: readonly TElem[], predicate: (value: TE
 
 /**
  * Creates an object with grouped items in the array.
+ * @deprecated Use the javascript "Object.groupBy()" version instead.
  *
  * @example
  * group([6.1, 4.2, 6.3], Math.floor)
@@ -827,19 +828,7 @@ declare function round(number: number, precision?: number): number;
 declare function sum(numbers: number[]): number;
 declare function sum<TNum extends readonly number[]>(numbers: TNum): Call<Tuples.Sum, TNum>;
 
-/**
- * The type of a plain object.
- *
- * This is a more strict type than the `object` type which also includes functions and arrays.
- *
- * You can validate if a value is a plain object with {@link isPlainObject}.
- * @example
- * let obj: PlainObject = { a: 1, b: 2 };
- *
- * obj = [1, 2, 3];
- * // => Type 'number[]' is not assignable to type 'PlainObject'.
- */
-type PlainObject = Record<PropertyKey, unknown>;
+type GenericObject = Record<PropertyKey, any>;
 
 type StringIfNever<Type> = [Type] extends [never] ? string : Type;
 type Paths$1<TObj> = StringIfNever<Call<Objects.AllPaths, TObj>>;
@@ -855,7 +844,21 @@ type Paths$1<TObj> = StringIfNever<Call<Objects.AllPaths, TObj>>;
  * @template TObj The type of the object to flatten.
  * @returns A new object with flattened keys.
  */
-declare function flatKeys<TObj extends PlainObject>(obj: TObj): Record<Paths$1<TObj>, unknown>;
+declare function flatKeys<TObj extends GenericObject>(obj: TObj): Record<Paths$1<TObj>, unknown>;
+
+/**
+ * The type of a plain object.
+ *
+ * This is a more strict type than the `object` type which also includes functions and arrays.
+ *
+ * You can validate if a value is a plain object with {@link isPlainObject}.
+ * @example
+ * let obj: PlainObject = { a: 1, b: 2 };
+ *
+ * obj = [1, 2, 3];
+ * // => Type 'number[]' is not assignable to type 'PlainObject'.
+ */
+type PlainObject = Record<PropertyKey, unknown>;
 
 /**
  * This function combines two or more objects into a single new object. Arrays and other types are overwritten.
@@ -877,7 +880,7 @@ declare function flatKeys<TObj extends PlainObject>(obj: TObj): Record<Paths$1<T
  * @template TSources The type of the source objects
  * @returns A new merged object
  */
-declare function merge<TTarget extends PlainObject, TSources extends ArrayMinLength<PlainObject, 1>>(target: TTarget, ...sources: TSources): MergeDeepObjects<[TTarget, ...TSources]>;
+declare function merge<TTarget extends GenericObject, TSources extends ArrayMinLength<GenericObject, 1>>(target: TTarget, ...sources: TSources): MergeDeepObjects<[TTarget, ...TSources]>;
 type OptionalPropertyNames<T> = {
     [K in keyof T]-?: (PlainObject extends {
         [P in K]: T[K];
@@ -905,7 +908,7 @@ type MergeDeepObjects<A extends readonly [...unknown[]]> = A extends [infer L, .
  * @template TObj The type of the object
  * @returns - An object without the specified keys
  */
-declare function omit<TObj extends PlainObject, Key extends keyof TObj>(object: TObj, keysToOmit: Key[]): Omit<TObj, Key>;
+declare function omit<TObj extends GenericObject, Key extends keyof TObj>(object: TObj, keysToOmit: Key[]): Omit<TObj, Key>;
 
 /**
  * Creates an object composed of the picked `object` properties.
@@ -920,7 +923,7 @@ declare function omit<TObj extends PlainObject, Key extends keyof TObj>(object:
  * @template TObj The type of the object.
  * @returns Returns the new object.
  */
-declare function pick<TObj extends PlainObject, Key extends keyof TObj>(object: TObj, keysToPick: Key[]): Pick<TObj, Key>;
+declare function pick<TObj extends GenericObject, Key extends keyof TObj>(object: TObj, keysToPick: Key[]): Pick<TObj, Key>;
 
 type Paths<TObj> = Call<Objects.AllPaths, TObj> | string & {};
 type UpdateObj<TObj extends PlainObject, TPath extends string, TVal> = Call<Objects.Update<TPath, TVal>, TObj>;
@@ -952,7 +955,7 @@ type UpdateObj<TObj extends PlainObject, TPath extends string, TVal> = Call<Obje
  * @template TVal The type of the value to set.
  * @returns The modified object.
  */
-declare function set<TObj extends PlainObject, TPath extends Paths<TObj>, TVal>(obj: TObj, path: TPath, value: TVal): UpdateObj<TObj, TPath, TVal>;
+declare function set<TObj extends GenericObject, TPath extends Paths<TObj>, TVal>(obj: TObj, path: TPath, value: TVal): UpdateObj<TObj, TPath, TVal>;
 
 /**
  * A class managing an async function queue with limited concurrency (e.g., 10 functions with 3 running at a time).
@@ -1350,6 +1353,34 @@ declare function trimStart(str: string, chars: string): string;
  */
 declare function unescapeHtml(str: string): string;
 
+/**
+ * Truncates a string if it's longer than the given maximum length.
+ * The last characters of the truncated string are replaced with the ellipsis
+ * string which defaults to "...".
+ *
+ * @example
+ * truncate("Hello, world!", { length: 5 })
+ * // => "Hello..."
+ *
+ * truncate("Hello, world!", { length: 5, ellipsis: " [...]" })
+ * // => "Hello [...]"
+ *
+ * truncate("Hello, world!", { length: 5, separator: " " })
+ * // => "Hello, ..."
+ *
+ * @param str The string to truncate
+ * @param options The options object
+ * @param options.length The maximum string length (default: 30)
+ * @param options.ellipsis The string to indicate text is omitted (default: "...")
+ * @param options.separator The separator pattern to truncate to (default: none)
+ * @returns The truncated string
+ */
+declare function truncate(str: string, options?: {
+    length?: number;
+    ellipsis?: string;
+    separator?: string;
+}): string;
+
 /**
  * Checks if a value is empty.
  *
@@ -1428,4 +1459,4 @@ declare function isPlainObject(value: unknown): value is PlainObject;
  */
 declare function isUrl(str: string): boolean;
 
-export { type ArrayMinLength, type GenericFunction, type Jsonifiable, type PlainObject, Queue, average, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, flatKeys, group, hash, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, median, memoize, merge, minCalls, move, omit, pascalCase, pick, races, randomElem, randomFloat, randomInt, randomString, range, replaceLast, retry, round, set, shuffle, sleep, snakeCase, sort, splitWords, sum, takeRightWhile, takeWhile, throttle, timeout, times, titleCase, toDecorator, trim, trimEnd, trimStart, tryCatch, unescapeHtml, unique };
+export { type ArrayMinLength, type GenericFunction, type GenericObject, type Jsonifiable, type PlainObject, Queue, average, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, flatKeys, group, hash, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, median, memoize, merge, minCalls, move, omit, pascalCase, pick, races, randomElem, randomFloat, randomInt, randomString, range, replaceLast, retry, round, set, shuffle, sleep, snakeCase, sort, splitWords, sum, takeRightWhile, takeWhile, throttle, timeout, times, titleCase, toDecorator, trim, trimEnd, trimStart, truncate, tryCatch, unescapeHtml, unique };

package/dist/index.d.ts

@@ -128,6 +128,7 @@ declare function dropWhile<TElem>(array: readonly TElem[], predicate: (value: TE
 
 /**
  * Creates an object with grouped items in the array.
+ * @deprecated Use the javascript "Object.groupBy()" version instead.
  *
  * @example
  * group([6.1, 4.2, 6.3], Math.floor)
@@ -827,19 +828,7 @@ declare function round(number: number, precision?: number): number;
 declare function sum(numbers: number[]): number;
 declare function sum<TNum extends readonly number[]>(numbers: TNum): Call<Tuples.Sum, TNum>;
 
-/**
- * The type of a plain object.
- *
- * This is a more strict type than the `object` type which also includes functions and arrays.
- *
- * You can validate if a value is a plain object with {@link isPlainObject}.
- * @example
- * let obj: PlainObject = { a: 1, b: 2 };
- *
- * obj = [1, 2, 3];
- * // => Type 'number[]' is not assignable to type 'PlainObject'.
- */
-type PlainObject = Record<PropertyKey, unknown>;
+type GenericObject = Record<PropertyKey, any>;
 
 type StringIfNever<Type> = [Type] extends [never] ? string : Type;
 type Paths$1<TObj> = StringIfNever<Call<Objects.AllPaths, TObj>>;
@@ -855,7 +844,21 @@ type Paths$1<TObj> = StringIfNever<Call<Objects.AllPaths, TObj>>;
  * @template TObj The type of the object to flatten.
  * @returns A new object with flattened keys.
  */
-declare function flatKeys<TObj extends PlainObject>(obj: TObj): Record<Paths$1<TObj>, unknown>;
+declare function flatKeys<TObj extends GenericObject>(obj: TObj): Record<Paths$1<TObj>, unknown>;
+
+/**
+ * The type of a plain object.
+ *
+ * This is a more strict type than the `object` type which also includes functions and arrays.
+ *
+ * You can validate if a value is a plain object with {@link isPlainObject}.
+ * @example
+ * let obj: PlainObject = { a: 1, b: 2 };
+ *
+ * obj = [1, 2, 3];
+ * // => Type 'number[]' is not assignable to type 'PlainObject'.
+ */
+type PlainObject = Record<PropertyKey, unknown>;
 
 /**
  * This function combines two or more objects into a single new object. Arrays and other types are overwritten.
@@ -877,7 +880,7 @@ declare function flatKeys<TObj extends PlainObject>(obj: TObj): Record<Paths$1<T
  * @template TSources The type of the source objects
  * @returns A new merged object
  */
-declare function merge<TTarget extends PlainObject, TSources extends ArrayMinLength<PlainObject, 1>>(target: TTarget, ...sources: TSources): MergeDeepObjects<[TTarget, ...TSources]>;
+declare function merge<TTarget extends GenericObject, TSources extends ArrayMinLength<GenericObject, 1>>(target: TTarget, ...sources: TSources): MergeDeepObjects<[TTarget, ...TSources]>;
 type OptionalPropertyNames<T> = {
     [K in keyof T]-?: (PlainObject extends {
         [P in K]: T[K];
@@ -905,7 +908,7 @@ type MergeDeepObjects<A extends readonly [...unknown[]]> = A extends [infer L, .
  * @template TObj The type of the object
  * @returns - An object without the specified keys
  */
-declare function omit<TObj extends PlainObject, Key extends keyof TObj>(object: TObj, keysToOmit: Key[]): Omit<TObj, Key>;
+declare function omit<TObj extends GenericObject, Key extends keyof TObj>(object: TObj, keysToOmit: Key[]): Omit<TObj, Key>;
 
 /**
  * Creates an object composed of the picked `object` properties.
@@ -920,7 +923,7 @@ declare function omit<TObj extends PlainObject, Key extends keyof TObj>(object:
  * @template TObj The type of the object.
  * @returns Returns the new object.
  */
-declare function pick<TObj extends PlainObject, Key extends keyof TObj>(object: TObj, keysToPick: Key[]): Pick<TObj, Key>;
+declare function pick<TObj extends GenericObject, Key extends keyof TObj>(object: TObj, keysToPick: Key[]): Pick<TObj, Key>;
 
 type Paths<TObj> = Call<Objects.AllPaths, TObj> | string & {};
 type UpdateObj<TObj extends PlainObject, TPath extends string, TVal> = Call<Objects.Update<TPath, TVal>, TObj>;
@@ -952,7 +955,7 @@ type UpdateObj<TObj extends PlainObject, TPath extends string, TVal> = Call<Obje
  * @template TVal The type of the value to set.
  * @returns The modified object.
  */
-declare function set<TObj extends PlainObject, TPath extends Paths<TObj>, TVal>(obj: TObj, path: TPath, value: TVal): UpdateObj<TObj, TPath, TVal>;
+declare function set<TObj extends GenericObject, TPath extends Paths<TObj>, TVal>(obj: TObj, path: TPath, value: TVal): UpdateObj<TObj, TPath, TVal>;
 
 /**
  * A class managing an async function queue with limited concurrency (e.g., 10 functions with 3 running at a time).
@@ -1350,6 +1353,34 @@ declare function trimStart(str: string, chars: string): string;
  */
 declare function unescapeHtml(str: string): string;
 
+/**
+ * Truncates a string if it's longer than the given maximum length.
+ * The last characters of the truncated string are replaced with the ellipsis
+ * string which defaults to "...".
+ *
+ * @example
+ * truncate("Hello, world!", { length: 5 })
+ * // => "Hello..."
+ *
+ * truncate("Hello, world!", { length: 5, ellipsis: " [...]" })
+ * // => "Hello [...]"
+ *
+ * truncate("Hello, world!", { length: 5, separator: " " })
+ * // => "Hello, ..."
+ *
+ * @param str The string to truncate
+ * @param options The options object
+ * @param options.length The maximum string length (default: 30)
+ * @param options.ellipsis The string to indicate text is omitted (default: "...")
+ * @param options.separator The separator pattern to truncate to (default: none)
+ * @returns The truncated string
+ */
+declare function truncate(str: string, options?: {
+    length?: number;
+    ellipsis?: string;
+    separator?: string;
+}): string;
+
 /**
  * Checks if a value is empty.
  *
@@ -1428,4 +1459,4 @@ declare function isPlainObject(value: unknown): value is PlainObject;
  */
 declare function isUrl(str: string): boolean;
 
-export { type ArrayMinLength, type GenericFunction, type Jsonifiable, type PlainObject, Queue, average, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, flatKeys, group, hash, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, median, memoize, merge, minCalls, move, omit, pascalCase, pick, races, randomElem, randomFloat, randomInt, randomString, range, replaceLast, retry, round, set, shuffle, sleep, snakeCase, sort, splitWords, sum, takeRightWhile, takeWhile, throttle, timeout, times, titleCase, toDecorator, trim, trimEnd, trimStart, tryCatch, unescapeHtml, unique };
+export { type ArrayMinLength, type GenericFunction, type GenericObject, type Jsonifiable, type PlainObject, Queue, average, camelCase, capitalize, chunk, count, debounce, deburr, decDebounce, decMaxCalls, decMemoize, decMinCalls, decThrottle, difference, dropRightWhile, dropWhile, escapeHtml, escapeRegExp, flatKeys, group, hash, intersection, isEmpty, isEqual, isPlainObject, isUrl, kebabCase, maxCalls, median, memoize, merge, minCalls, move, omit, pascalCase, pick, races, randomElem, randomFloat, randomInt, randomString, range, replaceLast, retry, round, set, shuffle, sleep, snakeCase, sort, splitWords, sum, takeRightWhile, takeWhile, throttle, timeout, times, titleCase, toDecorator, trim, trimEnd, trimStart, truncate, tryCatch, unescapeHtml, unique };

package/dist/index.js

@@ -835,6 +835,24 @@ function unescapeHtml(str) {
   return str.replace(htmlEntitiesRegex, (entity) => entityMap.get(entity));
 }
 
+// src/string/truncate.ts
+function truncate(str, options) {
+  const { length = 30, ellipsis = "...", separator } = options ?? {};
+  if (str.length <= length)
+    return str;
+  const end = length - ellipsis.length;
+  if (end < 1)
+    return ellipsis;
+  let truncated = str.slice(0, end);
+  if (separator) {
+    const sepIndex = truncated.lastIndexOf(separator);
+    if (sepIndex > -1) {
+      truncated = truncated.slice(0, sepIndex);
+    }
+  }
+  return truncated + ellipsis;
+}
+
 // src/validate/isEmpty.ts
 function isEmpty(value) {
   if (value === null || value === void 0)
@@ -976,6 +994,7 @@ export {
   trim,
   trimEnd,
   trimStart,
+  truncate,
   tryCatch,
   unescapeHtml,
   unique