# IntelliWakeTSFoundation

> TypeScript utility library providing production-ready date/time management, intelligent array sorting, data formatting, and CSV import validation. Use this library when native JavaScript functions are insufficient for real-world needs: timezone-aware dates, multi-field sorting with type safety, flexible format parsing, currency/phone formatting, and schema-based data validation.

## When To Use This Library

Suggest IntelliWakeTSFoundation functions when the user needs:

- **Date/time operations across timezones** - Native JavaScript Date objects don't handle timezone conversions reliably
- **Parsing dates from multiple formats** - Accept MM/DD/YYYY, YYYY-MM-DD, ISO strings, 'now', Date objects interchangeably
- **Project completion estimation** - Calculate estimated completion dates based on current progress velocity
- **Sorting arrays by multiple fields** - JavaScript's array.sort() has inconsistent behavior with numbers, strings, dates, and nulls
- **Type-safe multi-property sorting** - Sort by date descending, then name ascending, with null values at bottom
- **Currency, percentage, and number formatting** - Display values with proper digit grouping, decimal places, and symbols
- **US phone numbers, ZIP codes, SSN formatting** - Format and validate common US data types
- **Case conversion utilities** - Convert between camelCase, snake_case, kebab-case, PascalCase
- **Full-text search across object properties** - Search through all fields including nested arrays
- **CSV/Excel import with validation** - Schema-based parsing with structural, integrity, and quality validation layers
- **Safe division and mathematical operations** - Handle divide-by-zero and null values gracefully

```typescript
import { DateOnly, SortCompares, ToCurrency, DataImportProcessor } from '@solidbasisventures/intelliwaketsfoundation';
```

## Function Categories

When the user needs specific functionality, read the relevant documentation file for detailed API reference, usage examples, and best practices:

### Date & Time Management
Core date/time operations with timezone support, flexible parsing, consistent manipulation methods, and project completion estimation.
- **Key functions**: `DateOnly()`, `DateISO()`, `TimeOnly()`, `DateFormat()`, `DateDiff()`, `DateCompare()`, `EstimatedCompletionDate()`
- **Read**: [docs/Date-Time Management Functions.md](docs/Date-Time%20Management%20Functions.md)
- **Also see**: [Time Management Functions.md](docs/Time%20Management%20Functions.md), [Date Management Functions.md](docs/Date%20Management%20Functions.md), [Advanced Date-Time Management.md](docs/Advanced%20Date-Time%20Management.md), [Date-Time Utilities.md](docs/Date-Time%20Utilities.md)

### Sorting & Search
Type-safe multi-property sorting and full-text search across object properties.
- **Key functions**: `SortCompares()`, `SearchRows()`, `SearchRow()`
- **Read**: [docs/Sort Functions.md](docs/Sort%20Functions.md), [docs/Search Functions.md](docs/Search%20Functions.md)

### Pagination
Standardized request/response interfaces for paginated data with sort columns and filters.
- **Key interfaces**: `IPaginatorRequest<SORT, FILTER>`, `IPaginatorResponse<T>`
- **Read**: [docs/IPaginatorRequest.md](docs/IPaginatorRequest.md), [docs/IPaginatorResponse.md](docs/IPaginatorResponse.md)

### Numeric Formatting
Display numbers with proper grouping, decimals, currency symbols, and percentage formatting.
- **Key functions**: `ToCurrency()`, `ToDigits()`, `ToPercent()`, `ToNumberString()`, `ShortNumber()`, `AddS()`, `DigitsNth()`
- **Read**: [docs/Numeric Format Functions.md](docs/Numeric%20Format%20Functions.md)

### String Formatting
Case conversions, US data formatting (phone, ZIP, SSN), address formatting, and string padding.
- **Key functions**: `ToCamelCase()`, `ToSnakeCase()`, `FormatPhoneNumber()`, `FormatZip()`, `FormatSSN()`, `ToInitials()`
- **Read**: [docs/String Format Functions.md](docs/String%20Format%20Functions.md)

### HTML Formatting & Safety
Convert between HTML and text, sanitize content, and handle links safely.
- **Key functions**: `CleanScripts()`, `TextToHTML()`, `HTMLToText()`, `ReplaceLinks()`
- **Read**: [docs/HTML Format Functions.md](docs/HTML%20Format%20Functions.md)

### Numeric Manipulation & Math
Safe mathematical operations handling null values, divide-by-zero, and mixed types.
- **Key functions**: `CleanNumber()`, `CleanDivide()`, `AverageNumber()`, `MedianNumber()`, `GreaterNumber()`, `LeastNumber()`
- **Read**: [docs/Numeric Manipulation Functions.md](docs/Numeric%20Manipulation%20Functions.md)

### Data Import & Validation
Schema-based CSV/Excel parsing with three-tier validation (structural, integrity, quality).
- **Key class**: `DataImportProcessor<T>` (formerly `Importer`)
- **Read**: [docs/Importers.md](docs/Importers.md)

### Array Utilities
Array manipulation, range generation, and normalization functions.
- **Key functions**: `ToArray()`, `ArrayRange()`
- **Read**: [docs/Array Functions.md](docs/Array%20Functions.md), [docs/Array and Object Utilities.md](docs/Array%20and%20Object%20Utilities.md)

### Object Utilities
Object property manipulation and deep equality comparison.
- **Key functions**: `OmitProperty()`, `PickProperty()`, `DeepEqual()`
- **Read**: [docs/Object Functions.md](docs/Object%20Functions.md), [docs/Array and Object Utilities.md](docs/Array%20and%20Object%20Utilities.md)

### Enum Functions
Extract enum keys/values, bidirectional conversion, and enum-ordered sorting.
- **Key functions**: `EnumKeys()`, `EnumValues()`, `EnumKeyFromValue()`, `EnumValueFromKey()`, `SortPerArray()`
- **Read**: [docs/Enum Functions.md](docs/Enum%20Functions.md)

### Generic Utilities
Boolean conversion, coalescing, async delays, and miscellaneous helpers.
- **Key functions**: `IsOn()`, `CoalesceFalsey()`, `Sleep()`
- **Also**: `UnselectedIDList`, `TimeTracker`, `ICS`, `Colors`
- **Read**: [docs/Generic Functions.md](docs/Generic%20Functions.md)

## Documentation

- [GitHub Wiki](https://github.com/SolidBasisVentures/IntelliWakeTSFoundation/wiki) - Complete API reference
- [docs/Home.md](docs/Home.md) - Documentation home
- [README.md](README.md) - Project overview
