@sudobility/types 1.9.53 → 1.9.55

package/dist/utils/formatting/string.cjs

@@ -1,6 +1,8 @@
 "use strict";
 /**
- * String formatting and manipulation utilities
+ * String formatting and manipulation utilities.
+ *
+ * @since 1.0.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.truncate = truncate;
@@ -20,7 +22,18 @@ exports.randomString = randomString;
 exports.pluralize = pluralize;
 exports.formatNumber = formatNumber;
 /**
- * Truncate a string to a maximum length with ellipsis
+ * Truncate a string to a maximum length with a suffix (default `...`).
+ *
+ * @param str - Input string
+ * @param maxLength - Maximum allowed length including suffix
+ * @param suffix - Truncation suffix (default: `'...'`)
+ * @returns Truncated string or original if within limit
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * truncate('Hello, World!', 8); // "Hello..."
+ * ```
  */
 function truncate(str, maxLength, suffix = '...') {
     if (!str || str.length <= maxLength) {
@@ -29,7 +42,16 @@ function truncate(str, maxLength, suffix = '...') {
     return str.slice(0, maxLength - suffix.length) + suffix;
 }
 /**
- * Capitalize the first letter of a string
+ * Capitalize the first letter of a string.
+ *
+ * @param str - Input string
+ * @returns String with first character uppercased
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * capitalize('hello'); // "Hello"
+ * ```
  */
 function capitalize(str) {
     if (!str)
@@ -37,7 +59,16 @@ function capitalize(str) {
     return str.charAt(0).toUpperCase() + str.slice(1);
 }
 /**
- * Convert a string to title case
+ * Convert a string to title case (capitalize each word).
+ *
+ * @param str - Input string
+ * @returns Title-cased string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * toTitleCase('hello world'); // "Hello World"
+ * ```
  */
 function toTitleCase(str) {
     if (!str)
@@ -49,7 +80,16 @@ function toTitleCase(str) {
         .join(' ');
 }
 /**
- * Convert a string to kebab case
+ * Convert a string to kebab-case.
+ *
+ * @param str - Input string (camelCase, PascalCase, spaces, or underscores)
+ * @returns Kebab-cased string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * toKebabCase('helloWorld'); // "hello-world"
+ * ```
  */
 function toKebabCase(str) {
     if (!str)
@@ -60,7 +100,16 @@ function toKebabCase(str) {
         .toLowerCase();
 }
 /**
- * Convert a string to camel case
+ * Convert a string to camelCase.
+ *
+ * @param str - Input string (kebab-case, snake_case, or spaces)
+ * @returns camelCased string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * toCamelCase('hello-world'); // "helloWorld"
+ * ```
  */
 function toCamelCase(str) {
     if (!str)
@@ -70,7 +119,16 @@ function toCamelCase(str) {
         .replace(/^./, (char) => char.toLowerCase());
 }
 /**
- * Convert a string to snake case
+ * Convert a string to snake_case.
+ *
+ * @param str - Input string (camelCase, kebab-case, or spaces)
+ * @returns snake_cased string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * toSnakeCase('helloWorld'); // "hello_world"
+ * ```
  */
 function toSnakeCase(str) {
     if (!str)
@@ -81,7 +139,11 @@ function toSnakeCase(str) {
         .toLowerCase();
 }
 /**
- * Remove extra whitespace from a string
+ * Collapse consecutive whitespace to a single space and trim.
+ *
+ * @param str - Input string
+ * @returns Normalized string
+ * @since 1.0.0
  */
 function normalizeWhitespace(str) {
     if (!str)
@@ -89,19 +151,36 @@ function normalizeWhitespace(str) {
     return str.replace(/\s+/g, ' ').trim();
 }
 /**
- * Check if a string is empty or only whitespace
+ * Check if a string is empty, undefined, null, or only whitespace.
+ *
+ * @param str - Input string (may be nullish)
+ * @returns True if blank
+ * @since 1.0.0
  */
 function isBlank(str) {
     return !str || str.trim().length === 0;
 }
 /**
- * Check if a string is not empty and not only whitespace
+ * Type guard: check if a string is not empty and not only whitespace.
+ *
+ * @param str - Input string (may be nullish)
+ * @returns True (and narrows to `string`) if not blank
+ * @since 1.0.0
  */
 function isNotBlank(str) {
     return !isBlank(str);
 }
 /**
- * Escape HTML special characters
+ * Escape HTML special characters (`&`, `<`, `>`, `"`, `'`).
+ *
+ * @param str - Input string
+ * @returns HTML-escaped string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<b>Hi</b>'); // "&lt;b&gt;Hi&lt;/b&gt;"
+ * ```
  */
 function escapeHtml(str) {
     if (!str)
@@ -116,7 +195,16 @@ function escapeHtml(str) {
     return str.replace(/[&<>"']/g, (char) => htmlEscapes[char]);
 }
 /**
- * Remove HTML tags from a string
+ * Remove all HTML tags from a string.
+ *
+ * @param str - Input string with HTML
+ * @returns Plain text with tags removed
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * stripHtml('<p>Hello <b>world</b></p>'); // "Hello world"
+ * ```
  */
 function stripHtml(str) {
     if (!str)
@@ -124,7 +212,12 @@ function stripHtml(str) {
     return str.replace(/<[^>]*>/g, '');
 }
 /**
- * Extract initials from a name
+ * Extract initials from a name (e.g., "John Doe" -> "JD").
+ *
+ * @param name - Full name
+ * @param maxInitials - Maximum number of initials (default: 2)
+ * @returns Uppercase initials
+ * @since 1.0.0
  */
 function getInitials(name, maxInitials = 2) {
     if (!name)
@@ -137,7 +230,18 @@ function getInitials(name, maxInitials = 2) {
     return initials;
 }
 /**
- * Format bytes to human-readable size
+ * Format bytes to a human-readable size string (e.g., "1.5 MB").
+ *
+ * @param bytes - Size in bytes
+ * @param decimals - Decimal places (default: 2)
+ * @returns Formatted string like "1.5 MB"
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatBytes(1536); // "1.5 KB"
+ * formatBytes(0);    // "0 Bytes"
+ * ```
  */
 function formatBytes(bytes, decimals = 2) {
     if (bytes === 0)
@@ -149,7 +253,13 @@ function formatBytes(bytes, decimals = 2) {
     return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
 }
 /**
- * Generate a random string
+ * Generate a random string of a given length.
+ *
+ * @param length - Desired string length
+ * @param charset - Character set: `'alpha'`, `'numeric'`,
+ *   `'alphanumeric'` (default), `'hex'`, or a custom string
+ * @returns Random string
+ * @since 1.0.0
  */
 function randomString(length, charset = 'alphanumeric') {
     let chars;
@@ -176,7 +286,21 @@ function randomString(length, charset = 'alphanumeric') {
     return result;
 }
 /**
- * Pluralize a word based on count
+ * Pluralize a word based on count.
+ * Appends `'s'` by default when count is not 1.
+ *
+ * @param count - Item count
+ * @param singular - Singular form
+ * @param plural - Optional explicit plural form
+ * @returns Singular or plural form based on count
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * pluralize(1, 'item');  // "item"
+ * pluralize(3, 'item');  // "items"
+ * pluralize(2, 'child', 'children'); // "children"
+ * ```
  */
 function pluralize(count, singular, plural) {
     if (count === 1) {
@@ -185,7 +309,16 @@ function pluralize(count, singular, plural) {
     return plural || `${singular}s`;
 }
 /**
- * Format a number with commas as thousands separators
+ * Format a number with commas as thousands separators.
+ *
+ * @param num - Number to format
+ * @returns Formatted string (e.g., "1,234,567")
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatNumber(1234567); // "1,234,567"
+ * ```
  */
 function formatNumber(num) {
     return num.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');

package/dist/utils/formatting/string.d.ts

@@ -1,69 +1,202 @@
 /**
- * String formatting and manipulation utilities
+ * String formatting and manipulation utilities.
+ *
+ * @since 1.0.0
  */
 import { Optional } from '../../types/common';
 /**
- * Truncate a string to a maximum length with ellipsis
+ * Truncate a string to a maximum length with a suffix (default `...`).
+ *
+ * @param str - Input string
+ * @param maxLength - Maximum allowed length including suffix
+ * @param suffix - Truncation suffix (default: `'...'`)
+ * @returns Truncated string or original if within limit
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * truncate('Hello, World!', 8); // "Hello..."
+ * ```
  */
 export declare function truncate(str: string, maxLength: number, suffix?: string): string;
 /**
- * Capitalize the first letter of a string
+ * Capitalize the first letter of a string.
+ *
+ * @param str - Input string
+ * @returns String with first character uppercased
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * capitalize('hello'); // "Hello"
+ * ```
  */
 export declare function capitalize(str: string): string;
 /**
- * Convert a string to title case
+ * Convert a string to title case (capitalize each word).
+ *
+ * @param str - Input string
+ * @returns Title-cased string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * toTitleCase('hello world'); // "Hello World"
+ * ```
  */
 export declare function toTitleCase(str: string): string;
 /**
- * Convert a string to kebab case
+ * Convert a string to kebab-case.
+ *
+ * @param str - Input string (camelCase, PascalCase, spaces, or underscores)
+ * @returns Kebab-cased string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * toKebabCase('helloWorld'); // "hello-world"
+ * ```
  */
 export declare function toKebabCase(str: string): string;
 /**
- * Convert a string to camel case
+ * Convert a string to camelCase.
+ *
+ * @param str - Input string (kebab-case, snake_case, or spaces)
+ * @returns camelCased string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * toCamelCase('hello-world'); // "helloWorld"
+ * ```
  */
 export declare function toCamelCase(str: string): string;
 /**
- * Convert a string to snake case
+ * Convert a string to snake_case.
+ *
+ * @param str - Input string (camelCase, kebab-case, or spaces)
+ * @returns snake_cased string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * toSnakeCase('helloWorld'); // "hello_world"
+ * ```
  */
 export declare function toSnakeCase(str: string): string;
 /**
- * Remove extra whitespace from a string
+ * Collapse consecutive whitespace to a single space and trim.
+ *
+ * @param str - Input string
+ * @returns Normalized string
+ * @since 1.0.0
  */
 export declare function normalizeWhitespace(str: string): string;
 /**
- * Check if a string is empty or only whitespace
+ * Check if a string is empty, undefined, null, or only whitespace.
+ *
+ * @param str - Input string (may be nullish)
+ * @returns True if blank
+ * @since 1.0.0
  */
 export declare function isBlank(str?: Optional<string>): boolean;
 /**
- * Check if a string is not empty and not only whitespace
+ * Type guard: check if a string is not empty and not only whitespace.
+ *
+ * @param str - Input string (may be nullish)
+ * @returns True (and narrows to `string`) if not blank
+ * @since 1.0.0
  */
 export declare function isNotBlank(str?: Optional<string>): str is string;
 /**
- * Escape HTML special characters
+ * Escape HTML special characters (`&`, `<`, `>`, `"`, `'`).
+ *
+ * @param str - Input string
+ * @returns HTML-escaped string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<b>Hi</b>'); // "&lt;b&gt;Hi&lt;/b&gt;"
+ * ```
  */
 export declare function escapeHtml(str: string): string;
 /**
- * Remove HTML tags from a string
+ * Remove all HTML tags from a string.
+ *
+ * @param str - Input string with HTML
+ * @returns Plain text with tags removed
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * stripHtml('<p>Hello <b>world</b></p>'); // "Hello world"
+ * ```
  */
 export declare function stripHtml(str: string): string;
 /**
- * Extract initials from a name
+ * Extract initials from a name (e.g., "John Doe" -> "JD").
+ *
+ * @param name - Full name
+ * @param maxInitials - Maximum number of initials (default: 2)
+ * @returns Uppercase initials
+ * @since 1.0.0
  */
 export declare function getInitials(name: string, maxInitials?: number): string;
 /**
- * Format bytes to human-readable size
+ * Format bytes to a human-readable size string (e.g., "1.5 MB").
+ *
+ * @param bytes - Size in bytes
+ * @param decimals - Decimal places (default: 2)
+ * @returns Formatted string like "1.5 MB"
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatBytes(1536); // "1.5 KB"
+ * formatBytes(0);    // "0 Bytes"
+ * ```
  */
 export declare function formatBytes(bytes: number, decimals?: number): string;
 /**
- * Generate a random string
+ * Generate a random string of a given length.
+ *
+ * @param length - Desired string length
+ * @param charset - Character set: `'alpha'`, `'numeric'`,
+ *   `'alphanumeric'` (default), `'hex'`, or a custom string
+ * @returns Random string
+ * @since 1.0.0
  */
 export declare function randomString(length: number, charset?: string): string;
 /**
- * Pluralize a word based on count
+ * Pluralize a word based on count.
+ * Appends `'s'` by default when count is not 1.
+ *
+ * @param count - Item count
+ * @param singular - Singular form
+ * @param plural - Optional explicit plural form
+ * @returns Singular or plural form based on count
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * pluralize(1, 'item');  // "item"
+ * pluralize(3, 'item');  // "items"
+ * pluralize(2, 'child', 'children'); // "children"
+ * ```
  */
 export declare function pluralize(count: number, singular: string, plural?: Optional<string>): string;
 /**
- * Format a number with commas as thousands separators
+ * Format a number with commas as thousands separators.
+ *
+ * @param num - Number to format
+ * @returns Formatted string (e.g., "1,234,567")
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatNumber(1234567); // "1,234,567"
+ * ```
  */
 export declare function formatNumber(num: number): string;
 //# sourceMappingURL=string.d.ts.map

package/dist/utils/formatting/string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting/string.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;GAEG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,MAAM,SAAQ,GACb,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,MAAM,CAEhE;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAU9C;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,SAAI,GAAG,MAAM,CAUjE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAU/D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAiB,GAAG,MAAM,CA0B7E;AAED;;GAEG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GACxB,MAAM,CAKR;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting/string.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,MAAM,EACX,SAAS,EAAE,MAAM,EACjB,MAAM,SAAQ,GACb,MAAM,CAKR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAK/C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,OAAO,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,GAAG,IAAI,MAAM,CAEhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAU9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG7C;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,SAAI,GAAG,MAAM,CAUjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,SAAI,GAAG,MAAM,CAU/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAiB,GAAG,MAAM,CA0B7E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,GACxB,MAAM,CAKR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}