@sudobility/types 1.9.52 → 1.9.54

package/dist/utils/formatting/currency.js

@@ -1,13 +1,16 @@
 "use strict";
 /**
- * Currency formatting utilities for USDC and other tokens
+ * Currency formatting utilities for USDC and other tokens.
+ *
+ * @since 1.0.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLAIM_PERIOD_DAYS = exports.USDC_DECIMALS = void 0;
 exports.formatUSDC = formatUSDC;
 exports.parseUSDC = parseUSDC;
-// USDC configuration constants
+/** Number of decimal places for USDC token amounts. */
 exports.USDC_DECIMALS = 6;
+/** Revenue claim expiration period in days. */
 exports.CLAIM_PERIOD_DAYS = 60;
 /**
  * Format USDC amount from smallest unit to human-readable string

package/dist/utils/formatting/currency.js.map

@@ -1 +1 @@
-{"version":3,"file":"currency.js","sourceRoot":"","sources":["../../../src/utils/formatting/currency.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAeH,gCAEC;AAWD,8BAEC;AA5BD,+BAA+B;AAClB,QAAA,aAAa,GAAG,CAAC,CAAC;AAClB,QAAA,iBAAiB,GAAG,EAAE,CAAC;AAEpC;;;;;;;;GAQG;AACH,SAAgB,UAAU,CAAC,MAAc;IACvC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,qBAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,SAAS,CAAC,MAAc;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,qBAAa,CAAC,CAAC,CAAC;AACtE,CAAC"}
+{"version":3,"file":"currency.js","sourceRoot":"","sources":["../../../src/utils/formatting/currency.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAiBH,gCAEC;AAWD,8BAEC;AA9BD,uDAAuD;AAC1C,QAAA,aAAa,GAAG,CAAC,CAAC;AAE/B,+CAA+C;AAClC,QAAA,iBAAiB,GAAG,EAAE,CAAC;AAEpC;;;;;;;;GAQG;AACH,SAAgB,UAAU,CAAC,MAAc;IACvC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,qBAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,SAAS,CAAC,MAAc;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,qBAAa,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/utils/formatting/date.cjs

@@ -1,6 +1,8 @@
 "use strict";
 /**
- * Date formatting utilities
+ * Date formatting utilities.
+ *
+ * @since 1.0.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatEmailDate = formatEmailDate;
@@ -11,7 +13,19 @@ exports.isDateInRange = isDateInRange;
 exports.addDays = addDays;
 exports.addHours = addHours;
 /**
- * Format a date for display in email list
+ * Format a date for display in email list.
+ * Returns time for today, "Yesterday", day name for the past week,
+ * or a short date for older messages.
+ *
+ * @param date - Date object or ISO date string
+ * @returns Formatted date string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatEmailDate(new Date()); // "3:45 PM"
+ * formatEmailDate('2024-01-15'); // "Jan 15"
+ * ```
  */
 function formatEmailDate(date) {
     const dateObj = typeof date === 'string' ? new Date(date) : date;
@@ -54,13 +68,32 @@ function formatEmailDate(date) {
     });
 }
 /**
- * Format a timestamp to ISO string
+ * Format a Unix timestamp (ms) to an ISO 8601 string.
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @returns ISO 8601 date string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatTimestamp(1700000000000); // "2023-11-14T22:13:20.000Z"
+ * ```
  */
 function formatTimestamp(timestamp) {
     return new Date(timestamp).toISOString();
 }
 /**
- * Format a date to a relative time string (e.g., "2 hours ago")
+ * Format a date to a relative time string (e.g., "2 hours ago").
+ *
+ * @param date - Date object, ISO string, or Unix timestamp (ms)
+ * @returns Human-readable relative time string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatRelativeTime(Date.now() - 3600000); // "1 hour ago"
+ * formatRelativeTime('2024-01-01'); // "1 year ago"
+ * ```
  */
 function formatRelativeTime(date) {
     const dateObj = typeof date === 'string' || typeof date === 'number'
@@ -99,7 +132,17 @@ function formatRelativeTime(date) {
     return diffYears === 1 ? '1 year ago' : `${diffYears} years ago`;
 }
 /**
- * Parse a date string safely
+ * Parse a date string safely, returning null on invalid input.
+ *
+ * @param dateString - Date string to parse
+ * @returns Parsed Date or null if invalid
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * parseDate('2024-01-15'); // Date object
+ * parseDate('not-a-date'); // null
+ * ```
  */
 function parseDate(dateString) {
     try {
@@ -114,13 +157,24 @@ function parseDate(dateString) {
     }
 }
 /**
- * Check if a date is within a range
+ * Check if a date falls within an inclusive range.
+ *
+ * @param date - Date to check
+ * @param startDate - Range start (inclusive)
+ * @param endDate - Range end (inclusive)
+ * @returns True if date is within the range
+ * @since 1.0.0
  */
 function isDateInRange(date, startDate, endDate) {
     return date >= startDate && date <= endDate;
 }
 /**
- * Add days to a date
+ * Add (or subtract) days from a date. Returns a new Date instance.
+ *
+ * @param date - Starting date
+ * @param days - Number of days to add (negative to subtract)
+ * @returns New Date with days added
+ * @since 1.0.0
  */
 function addDays(date, days) {
     const result = new Date(date);
@@ -128,7 +182,12 @@ function addDays(date, days) {
     return result;
 }
 /**
- * Add hours to a date
+ * Add (or subtract) hours from a date. Returns a new Date instance.
+ *
+ * @param date - Starting date
+ * @param hours - Number of hours to add (negative to subtract)
+ * @returns New Date with hours added
+ * @since 1.0.0
  */
 function addHours(date, hours) {
     const result = new Date(date);

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

@@ -1,33 +1,92 @@
 /**
- * Date formatting utilities
+ * Date formatting utilities.
+ *
+ * @since 1.0.0
  */
 import { Optional } from '../../types/common';
 /**
- * Format a date for display in email list
+ * Format a date for display in email list.
+ * Returns time for today, "Yesterday", day name for the past week,
+ * or a short date for older messages.
+ *
+ * @param date - Date object or ISO date string
+ * @returns Formatted date string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatEmailDate(new Date()); // "3:45 PM"
+ * formatEmailDate('2024-01-15'); // "Jan 15"
+ * ```
  */
 export declare function formatEmailDate(date: Date | string): string;
 /**
- * Format a timestamp to ISO string
+ * Format a Unix timestamp (ms) to an ISO 8601 string.
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @returns ISO 8601 date string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatTimestamp(1700000000000); // "2023-11-14T22:13:20.000Z"
+ * ```
  */
 export declare function formatTimestamp(timestamp: number): string;
 /**
- * Format a date to a relative time string (e.g., "2 hours ago")
+ * Format a date to a relative time string (e.g., "2 hours ago").
+ *
+ * @param date - Date object, ISO string, or Unix timestamp (ms)
+ * @returns Human-readable relative time string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatRelativeTime(Date.now() - 3600000); // "1 hour ago"
+ * formatRelativeTime('2024-01-01'); // "1 year ago"
+ * ```
  */
 export declare function formatRelativeTime(date: Date | string | number): string;
 /**
- * Parse a date string safely
+ * Parse a date string safely, returning null on invalid input.
+ *
+ * @param dateString - Date string to parse
+ * @returns Parsed Date or null if invalid
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * parseDate('2024-01-15'); // Date object
+ * parseDate('not-a-date'); // null
+ * ```
  */
 export declare function parseDate(dateString: string): Optional<Date>;
 /**
- * Check if a date is within a range
+ * Check if a date falls within an inclusive range.
+ *
+ * @param date - Date to check
+ * @param startDate - Range start (inclusive)
+ * @param endDate - Range end (inclusive)
+ * @returns True if date is within the range
+ * @since 1.0.0
  */
 export declare function isDateInRange(date: Date, startDate: Date, endDate: Date): boolean;
 /**
- * Add days to a date
+ * Add (or subtract) days from a date. Returns a new Date instance.
+ *
+ * @param date - Starting date
+ * @param days - Number of days to add (negative to subtract)
+ * @returns New Date with days added
+ * @since 1.0.0
  */
 export declare function addDays(date: Date, days: number): Date;
 /**
- * Add hours to a date
+ * Add (or subtract) hours from a date. Returns a new Date instance.
+ *
+ * @param date - Starting date
+ * @param hours - Number of hours to add (negative to subtract)
+ * @returns New Date with hours added
+ * @since 1.0.0
  */
 export declare function addHours(date: Date, hours: number): Date;
 //# sourceMappingURL=date.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting/date.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CA8C3D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CA6CvE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAU5D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,IAAI,GACZ,OAAO,CAET;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAItD;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIxD"}
+{"version":3,"file":"date.d.ts","sourceRoot":"","sources":["../../../src/utils/formatting/date.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CA8C3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CA6CvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAU5D;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,IAAI,EACf,OAAO,EAAE,IAAI,GACZ,OAAO,CAET;AAED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAItD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIxD"}

package/dist/utils/formatting/date.js

@@ -1,6 +1,8 @@
 "use strict";
 /**
- * Date formatting utilities
+ * Date formatting utilities.
+ *
+ * @since 1.0.0
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatEmailDate = formatEmailDate;
@@ -11,7 +13,19 @@ exports.isDateInRange = isDateInRange;
 exports.addDays = addDays;
 exports.addHours = addHours;
 /**
- * Format a date for display in email list
+ * Format a date for display in email list.
+ * Returns time for today, "Yesterday", day name for the past week,
+ * or a short date for older messages.
+ *
+ * @param date - Date object or ISO date string
+ * @returns Formatted date string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatEmailDate(new Date()); // "3:45 PM"
+ * formatEmailDate('2024-01-15'); // "Jan 15"
+ * ```
  */
 function formatEmailDate(date) {
     const dateObj = typeof date === 'string' ? new Date(date) : date;
@@ -54,13 +68,32 @@ function formatEmailDate(date) {
     });
 }
 /**
- * Format a timestamp to ISO string
+ * Format a Unix timestamp (ms) to an ISO 8601 string.
+ *
+ * @param timestamp - Unix timestamp in milliseconds
+ * @returns ISO 8601 date string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatTimestamp(1700000000000); // "2023-11-14T22:13:20.000Z"
+ * ```
  */
 function formatTimestamp(timestamp) {
     return new Date(timestamp).toISOString();
 }
 /**
- * Format a date to a relative time string (e.g., "2 hours ago")
+ * Format a date to a relative time string (e.g., "2 hours ago").
+ *
+ * @param date - Date object, ISO string, or Unix timestamp (ms)
+ * @returns Human-readable relative time string
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * formatRelativeTime(Date.now() - 3600000); // "1 hour ago"
+ * formatRelativeTime('2024-01-01'); // "1 year ago"
+ * ```
  */
 function formatRelativeTime(date) {
     const dateObj = typeof date === 'string' || typeof date === 'number'
@@ -99,7 +132,17 @@ function formatRelativeTime(date) {
     return diffYears === 1 ? '1 year ago' : `${diffYears} years ago`;
 }
 /**
- * Parse a date string safely
+ * Parse a date string safely, returning null on invalid input.
+ *
+ * @param dateString - Date string to parse
+ * @returns Parsed Date or null if invalid
+ * @since 1.0.0
+ *
+ * @example
+ * ```typescript
+ * parseDate('2024-01-15'); // Date object
+ * parseDate('not-a-date'); // null
+ * ```
  */
 function parseDate(dateString) {
     try {
@@ -114,13 +157,24 @@ function parseDate(dateString) {
     }
 }
 /**
- * Check if a date is within a range
+ * Check if a date falls within an inclusive range.
+ *
+ * @param date - Date to check
+ * @param startDate - Range start (inclusive)
+ * @param endDate - Range end (inclusive)
+ * @returns True if date is within the range
+ * @since 1.0.0
  */
 function isDateInRange(date, startDate, endDate) {
     return date >= startDate && date <= endDate;
 }
 /**
- * Add days to a date
+ * Add (or subtract) days from a date. Returns a new Date instance.
+ *
+ * @param date - Starting date
+ * @param days - Number of days to add (negative to subtract)
+ * @returns New Date with days added
+ * @since 1.0.0
  */
 function addDays(date, days) {
     const result = new Date(date);
@@ -128,7 +182,12 @@ function addDays(date, days) {
     return result;
 }
 /**
- * Add hours to a date
+ * Add (or subtract) hours from a date. Returns a new Date instance.
+ *
+ * @param date - Starting date
+ * @param hours - Number of hours to add (negative to subtract)
+ * @returns New Date with hours added
+ * @since 1.0.0
  */
 function addHours(date, hours) {
     const result = new Date(date);

package/dist/utils/formatting/date.js.map

@@ -1 +1 @@
-{"version":3,"file":"date.js","sourceRoot":"","sources":["../../../src/utils/formatting/date.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"date.js","sourceRoot":"","sources":["../../../src/utils/formatting/date.ts"],"names":[],"mappings":"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"}

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, ',');