npm package: @hichchi/utils
Description: A comprehensive utility library with essential helper functions for JavaScript/TypeScript applications
Author: Waruna Udayanga
Latest version: 0.0.12

<!--suppress ALL -->

<div align="center">

# 🛠️ @hichchi/utils

## Description

**A comprehensive utility library with essential helper functions for JavaScript/TypeScript applications**

[![npm version](https://img.shields.io/npm/v/@hichchi/utils?style=flat&color=blue)](https://www.npmjs.com/package/@hichchi/utils)
[![npm downloads](https://img.shields.io/npm/dm/@hichchi/utils?style=flat&color=green)](https://www.npmjs.com/package/@hichchi/utils)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/hichchidev/hichchi/blob/main/LICENSE)
[![TypeScript](https://img.shields.io/badge/typescript-5.0+-blue.svg)](https://www.typescriptlang.org/)

_Part of the [Hichchi](https://github.com/hichchidev/hichchi) ecosystem - A powerful, scalable application built with Nx workspace_

[📚 Jump to Documentation](#-api-documentation)

</div>

---

## 📋 Table Of Contents

- [📦 Installation](#-installation)
- [⚡ Quick Start](#-quick-start)
- [📋 Prerequisites](#-prerequisites)
- [🌟 Overview](#-overview)
- [✨ Features](#-features)
- [🛠️ Troubleshooting](#️-troubleshooting)
- [🔧 Development](#-development)
- [📖 API Documentation](#-api-documentation)

---

## 📦 Installation

```bash
npm install @hichchi/utils
```

## ⚡ Quick Start

Get up and running with powerful utility functions in just a few minutes:

```typescript
// 1. Install the package
npm install @hichchi/utils

// 2. Import utility functions
import { dottedPathObjectToNested } from '@hichchi/utils';

// 3. Use utility functions in your application
const nestedObject = dottedPathObjectToNested({
    "id": 123,
    "name": "John Doe",
    "profile.age": 30,
    "profile.address.city": "New York",
    "profile.address.zip": "10001"
});

Result:
// {
//   id: 123,
//   name: "John Doe",
//   profile: {
//     age: 30,
//     address: {
//       city: "New York",
//       zip: "10001"
//     }
//   }
// }

```

## 📋 Prerequisites

Before installing @hichchi/utils, ensure you have:

### Required Dependencies

- **Node.js**: ^18.0.0
- **TypeScript**: ^5.0.0 (for TypeScript projects)

## 🌟 Overview

🎯 **Your essential toolkit** for JavaScript and TypeScript development. From string manipulation to file operations, from object utilities to URL handling - everything you need to streamline your development workflow with battle-tested, performance-optimized utility functions.

## ✨ Features

### 🔤 String Utilities

- 🎨 **Case Conversion** - camelCase, PascalCase, snake_case, kebab-case transformations
- 🔍 **String Analysis** - Pattern matching, validation, and content analysis
- ✂️ **String Manipulation** - Truncation, padding, cleaning, and formatting
- 🏷️ **Slug Generation** - URL-friendly string generation with customizable options
- 📝 **Template Processing** - Advanced string templating with variable substitution

### 🗂️ Object Utilities

- 🔄 **Deep Operations** - Deep merge, clone, compare, and transformation
- 🎯 **Property Access** - Safe property getting/setting with dot notation
- 🔍 **Object Analysis** - Type checking, validation, and structure analysis
- 📊 **Data Transformation** - Object flattening, nesting, and restructuring
- 🧹 **Object Cleaning** - Remove null/undefined values, empty objects

### 📝 String Template Utilities

- 🎨 **Template Processing** - Advanced string templating with variable substitution
- 🔄 **Dynamic Content** - Apply templates with custom prefixes and transformations
- 🏷️ **Tag-based Processing** - Support for various template tags and formats

### 🌐 URL Utilities

- 🔒 **Redirect Validation** - Secure redirect URL validation against allowed domains
- 🛡️ **Security Features** - Prevent open redirect vulnerabilities

### ✅ Assertion Utilities

- 🔍 **Type Guards** - TypeScript type guards for arrays and objects
- 🎯 **Property Checking** - Check if objects have specific properties
- 🛡️ **Safe Type Narrowing** - Runtime type validation with TypeScript support

### 🎨 Developer Experience

- 📝 **Full TypeScript Support** - Complete type definitions and IntelliSense
- 🔧 **Tree Shaking** - Import only what you need for optimal bundle size
- 📚 **Comprehensive Documentation** - Detailed JSDoc comments for all functions
- 🧪 **Well Tested** - Extensive test coverage for reliability
- 🚀 **Performance Optimized** - Efficient algorithms and minimal overhead

## 🔒 Security Best Practices

Detailed security best practices will be added here

## 🛠️ Troubleshooting

### Common Issues

#### TypeScript Compilation Issues

```bash
# Ensure you have the correct TypeScript version
npm install typescript@^5.0.0 --save-dev
```

## 🔧 Development

### Building the Library

```bash
nx build utils
```

### Running Tests

```bash
nx test utils
```

### Linting

```bash
nx lint utils
```

### Performance Testing

```bash
nx run utils:benchmark
```

---

<div align="center">

**Made with ❤️ by [Hichchi Dev](https://github.com/hichchidev)**

[![Hichchi Ecosystem](https://img.shields.io/badge/🏠_Hichchi_Ecosystem-blue)](https://github.com/hichchidev/hichchi)
[![Report Bug](https://img.shields.io/badge/🐛_Report_Bug-red)](https://github.com/hichchidev/hichchi/issues)
[![Request Feature](https://img.shields.io/badge/✨_Request_Feature-green)](https://github.com/hichchidev/hichchi/issues)

_Building the future of development utilities, one commit at a time_

</div>

---

# 📖 API Documentation

Complete technical reference for all classes, interfaces, methods, and types in this library.

**Auto-generated by TypeDoc** - Browse through detailed API references, code examples, and implementation guides below.

<!-- TypeDoc generated documentation will be appended below this point -->

---

## 📋 API Table of Contents

- [Enumerations](#enumerations)
  - [TemplateTag](#templatetag)
- [Functions](#functions)
  - [applyTemplate()](#applytemplate)
  - [applyTemplates()](#applytemplates)
  - [breakToWords()](#breaktowords)
  - [countOccurrences()](#countoccurrences)
  - [createExcerpt()](#createexcerpt)
  - [deepCopy()](#deepcopy)
  - [dottedPathObjectToNested()](#dottedpathobjecttonested)
  - [escapeRegExp()](#escaperegexp)
  - [extractEmails()](#extractemails)
  - [extractUrls()](#extracturls)
  - [filterByObject()](#filterbyobject)
  - [format()](#format)
  - [getEnumValues()](#getenumvalues)
  - [getFileExt()](#getfileext)
  - [getFileSize()](#getfilesize)
  - [getMapKey()](#getmapkey)
  - [getMapKeys()](#getmapkeys)
  - [getValueByPath()](#getvaluebypath)
  - [groupBy()](#groupby)
  - [hashString()](#hashstring)
  - [hasOwnAll()](#hasownall)
  - [htmlToText()](#htmltotext)
  - [isAlphanumeric()](#isalphanumeric)
  - [isArray()](#isarray)
  - [isObject()](#isobject)
  - [isObjectWith()](#isobjectwith)
  - [isValidRedirectUrl()](#isvalidredirecturl)
  - [maskString()](#maskstring)
  - [normalizeString()](#normalizestring)
  - [objectToDottedPathValueObject()](#objecttodottedpathvalueobject)
  - [omit()](#omit)
  - [padString()](#padstring)
  - [plural()](#plural)
  - [prune()](#prune)
  - [randomString()](#randomstring)
  - [removeWhitespace()](#removewhitespace)
  - [reverse()](#reverse)
  - [searchMapValues()](#searchmapvalues)
  - [singular()](#singular)
  - [slugify()](#slugify)
  - [stringSimilarity()](#stringsimilarity)
  - [toCamelCase()](#tocamelcase)
  - [toFirstCase()](#tofirstcase)
  - [toFirstCaseBreak()](#tofirstcasebreak)
  - [toKebabCase()](#tokebabcase)
  - [toLowerCase()](#tolowercase)
  - [toLowerCaseBreak()](#tolowercasebreak)
  - [toNumber()](#tonumber)
  - [toPascalCase()](#topascalcase)
  - [toProperTitleCase()](#topropertitlecase)
  - [toSentenceCase()](#tosentencecase)
  - [toSnakeCase()](#tosnakecase)
  - [toTitleCase()](#totitlecase)
  - [toUpperCase()](#touppercase)
  - [toUpperCaseBreak()](#touppercasebreak)
  - [truncate()](#truncate)
  - [wordWrap()](#wordwrap)
- [Interfaces](#interfaces)
  - [DottedPathValueObject](#dottedpathvalueobject)
  - [InfiniteObject](#infiniteobject)
  - [InflectionRule](#inflectionrule)
  - [InflectionRuleCategories](#inflectionrulecategories)
  - [LiteralObject](#literalobject)
  - [PluralSingularRulePair](#pluralsingularrulepair)
- [Type Aliases](#type-aliases)
  - [DeepPartial](#deeppartial)
  - [IsAlreadyInPath](#isalreadyinpath)
  - [IsEmpty](#isempty)
  - [IsPrimitive](#isprimitive)
  - [LooseAutocomplete](#looseautocomplete)
  - [NonNullPrimitive](#nonnullprimitive)
  - [PartialWithNull](#partialwithnull)
  - [Prettify](#prettify)
  - [Primitive](#primitive)
  - [SimpleDeepPartial](#simpledeeppartial)
  - [Type()](#type)
- [Variables](#variables)
  - [CHARACTERS_TO_REMOVE](#characters_to_remove)
  - [CONTEXT_MULTIPLIER](#context_multiplier)
  - [DEFAULT_BREAK_CHAR](#default_break_char)
  - [DEFAULT_CONTEXT_LENGTH](#default_context_length)
  - [DEFAULT_ELLIPSIS](#default_ellipsis)
  - [DEFAULT_LINE_LENGTH](#default_line_length)
  - [EnglishInflectionRules](#englishinflectionrules)
  - [HEX_PADDING_CHAR](#hex_padding_char)
  - [HEX_PADDING_LENGTH](#hex_padding_length)
  - [HEX_RADIX](#hex_radix)
  - [mimeTypes](#mimetypes)

## Enumerations

### TemplateTag

Defined in: [enums/template-tag.enum.ts:15](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L15)

Template tags for string transformations

This enum defines all available template tags that can be used with the `applyTemplate`
and `applyTemplates` functions. Each tag corresponds to a specific string transformation
function from the string.utils module.

Template tags are represented as strings in the format `#{transformationName}`. When these
tags appear in template strings, they are replaced with the result of applying the
corresponding transformation to the provided value.

#### See

- [applyTemplate](#applytemplate) For applying a single value to a template
- [applyTemplates](#applytemplates) For applying multiple values to a template

#### Enumeration Members

<table>
<thead>
<tr>
<th>Enumeration Member</th>
<th>Value</th>
<th>Defined in</th>
</tr>
</thead>
<tbody>
<tr>
<td>

<a id="enumeration-member-camel_case"></a> `CAMEL_CASE`

</td>
<td>

`"#{camelCase}"`

</td>
<td>

[enums/template-tag.enum.ts:22](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L22)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-first_case"></a> `FIRST_CASE`

</td>
<td>

`"#{firstCase}"`

</td>
<td>

[enums/template-tag.enum.ts:21](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L21)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-first_case_break"></a> `FIRST_CASE_BREAK`

</td>
<td>

`"#{firstCaseBreak}"`

</td>
<td>

[enums/template-tag.enum.ts:29](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L29)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-html_to_text"></a> `HTML_TO_TEXT`

</td>
<td>

`"#{htmlToText}"`

</td>
<td>

[enums/template-tag.enum.ts:32](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L32)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-kebab_case"></a> `KEBAB_CASE`

</td>
<td>

`"#{kebabCase}"`

</td>
<td>

[enums/template-tag.enum.ts:24](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L24)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-lower_case"></a> `LOWER_CASE`

</td>
<td>

`"#{lowerCase}"`

</td>
<td>

[enums/template-tag.enum.ts:19](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L19)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-lower_case_break"></a> `LOWER_CASE_BREAK`

</td>
<td>

`"#{lowerCaseBreak}"`

</td>
<td>

[enums/template-tag.enum.ts:27](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L27)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-number"></a> `NUMBER`

</td>
<td>

`"#{number}"`

</td>
<td>

[enums/template-tag.enum.ts:31](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L31)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-pascal_case"></a> `PASCAL_CASE`

</td>
<td>

`"#{pascalCase}"`

</td>
<td>

[enums/template-tag.enum.ts:23](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L23)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-sentence_case"></a> `SENTENCE_CASE`

</td>
<td>

`"#{sentenceCase}"`

</td>
<td>

[enums/template-tag.enum.ts:20](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L20)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-singular"></a> `SINGULAR`

</td>
<td>

`"#{singular}"`

</td>
<td>

[enums/template-tag.enum.ts:30](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L30)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-snake_case"></a> `SNAKE_CASE`

</td>
<td>

`"#{snakeCase}"`

</td>
<td>

[enums/template-tag.enum.ts:17](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L17)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-title_case"></a> `TITLE_CASE`

</td>
<td>

`"#{titleCase}"`

</td>
<td>

[enums/template-tag.enum.ts:26](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L26)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-upper_case"></a> `UPPER_CASE`

</td>
<td>

`"#{upperCase}"`

</td>
<td>

[enums/template-tag.enum.ts:16](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L16)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-upper_case_break"></a> `UPPER_CASE_BREAK`

</td>
<td>

`"#{upperCaseBreak}"`

</td>
<td>

[enums/template-tag.enum.ts:28](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L28)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-upper_kebab_case"></a> `UPPER_KEBAB_CASE`

</td>
<td>

`"#{upperKebabCase}"`

</td>
<td>

[enums/template-tag.enum.ts:25](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L25)

</td>
</tr>
<tr>
<td>

<a id="enumeration-member-upper_snake_case"></a> `UPPER_SNAKE_CASE`

</td>
<td>

`"#{upperSnakeCase}"`

</td>
<td>

[enums/template-tag.enum.ts:18](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/enums/template-tag.enum.ts#L18)

</td>
</tr>
</tbody>
</table>

## Functions

### applyTemplate()

```ts
function applyTemplate(str, prefix): string;
```

Defined in: [utils/string-template.utils.ts:83](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string-template.utils.ts#L83)

Applies a value to a template string containing transformation tags.

This function replaces template tags in a string with transformed versions of a provided value.
It's particularly useful for creating dynamic messages, error notifications, or any text
that needs to include the same value in different formats.

Each template tag is replaced with the result of applying the corresponding transformation
function to the provided value. If a tag isn't present in the template string, that
transformation is skipped.

Available template tags:

- `#{upperCase}` - Converts to UPPERCASE ("USER")
- `#{snakeCase}` - Converts to snake_case ("user_profile")
- `#{upperSnakeCase}` - Converts to UPPER_SNAKE_CASE ("USER_PROFILE")
- `#{lowerCase}` - Converts to lowercase ("user")
- `#{sentenceCase}` - Converts to Sentence case ("User profile")
- `#{firstCase}` - Converts to First case ("User")
- `#{camelCase}` - Converts to camelCase ("userProfile")
- `#{pascalCase}` - Converts to PascalCase ("UserProfile")
- `#{kebabCase}` - Converts to kebab-case ("user-profile")
- `#{upperKebabCase}` - Converts to KEBAB-CASE ("USER-PROFILE")
- `#{titleCase}` - Converts to Title Case ("User Profile")
- `#{lowerCaseBreak}` - Breaks words and converts to lowercase ("user profile")
- `#{upperCaseBreak}` - Breaks words and converts to UPPERCASE ("USER PROFILE")
- `#{firstCaseBreak}` - Breaks words and applies First case ("User profile")
- `#{singular}` - Converts plural to singular form ("users" → "user")
- `#{number}` - Converts to a number if possible ("123" → 123)
- `#{htmlToText}` - Removes HTML tags ("<b>User</b>" → "User")
- `#{format}` - Formats a string with placeholders (used with additional parameters)

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

Template string containing transformation tags

</td>
</tr>
<tr>
<td>

`prefix`

</td>
<td>

`string`

</td>
<td>

The prefix to update with

</td>
</tr>
</tbody>
</table>

#### Returns

`string`

- The template with all tags replaced by transformed values

#### Examples

```typescript
// Error message with different versions of the same term
applyTemplate(
  "Cannot create a #{lowerCase} with this email. #{sentenceCase} already exists.",
  "User",
);
// Output: "Cannot create a user with this email. User already exists."
```

```typescript
// Using multiple transformations of the same value
applyTemplate(
  "Model: #{pascalCase}\nTable: #{snakeCase}\nAPI Path: #{kebabCase}",
  "blogPost",
);
// Output:
//     Model: BlogPost
//     Table: blog_post
//     API Path: blog-post
```

#### See

- [TemplateTag](#templatetag) For the full list of available template tags
- [applyTemplates](#applytemplates) For applying multiple different values to a template

---

### applyTemplates()

```ts
function applyTemplates(str, prefixes): string;
```

Defined in: [utils/string-template.utils.ts:211](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string-template.utils.ts#L211)

Applies multiple named template transformations to a string with different values for each prefix.

This advanced templating function allows you to use multiple different values within a single
template string, each with their own set of transformation tags. Unlike `applyTemplate` which
applies one value to all tags, this function lets you specify different values for different
prefixes, enabling complex template scenarios with multiple entities.

Each prefix in the template is identified by a namespace (e.g., `user`, `post`) followed by
a dot and the transformation tag (e.g., `#{user.lowerCase}`, `#{post.titleCase}`). This allows
for sophisticated template generation where different parts of the text need different source
values with various transformations applied.

This is particularly useful for generating complex messages, code templates, documentation,
or any text that involves multiple entities that need to be formatted differently within
the same template.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

Template string containing namespaced transformation tags in the format
`#{prefix.transformationType}` where prefix matches keys in the prefixes object

</td>
</tr>
<tr>
<td>

`prefixes`

</td>
<td>

`Record`<`string`, `string`>

</td>
<td>

Object mapping prefix names to their corresponding values.
Each key becomes a namespace in the template, and the value
is the string that will be transformed according to the tags.

</td>
</tr>
</tbody>
</table>

#### Returns

`string`

The template string with all namespaced tags replaced by their transformed values

#### Examples

```typescript
// Multi-entity message generation
const message = applyTemplates(
  'User #{user.lowerCase} created a new #{entity.sentenceCase} titled "#{title.titleCase}"',
  {
    user: "JohnDoe",
    entity: "blogPost",
    title: "my first programming tutorial",
  },
);
// Returns: "User johndoe created a new Blog post titled "My First Programming Tutorial""
```

```typescript
// Code generation with multiple entities
const codeTemplate = applyTemplates(
  `class #{model.pascalCase} {
  constructor(private #{service.camelCase}: #{service.pascalCase}Service) {}

  async create#{model.pascalCase}(data: #{model.pascalCase}Data): Promise<#{model.pascalCase}> {
    return this.#{service.camelCase}.create(data);
  }
}`,
  {
    model: "user-profile",
    service: "database",
  },
);
// Generates a complete class with proper naming conventions
```

```typescript
// API documentation generation
const apiDoc = applyTemplates(
  `## #{endpoint.titleCase}

**URL:** \`/api/#{endpoint.kebabCase}\`
**Method:** #{method.upperCase}
**Model:** #{model.pascalCase}

Creates a new #{model.lowerCaseBreak} in the system.`,
  {
    endpoint: "userProfiles",
    method: "post",
    model: "UserProfile",
  },
);
```

```typescript
// Database migration script generation
const migration = applyTemplates(
  `CREATE TABLE #{table.snakeCase} (
  id SERIAL PRIMARY KEY,
  #{field.snakeCase} VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_#{table.snakeCase}_#{field.snakeCase} ON #{table.snakeCase}(#{field.snakeCase});`,
  {
    table: "UserProfiles",
    field: "emailAddress",
  },
);
```

#### Remarks

- Each prefix in the prefixes object becomes a namespace in the template
- Template tags must follow the format `#{prefix.transformationType}`
- All transformation types available in `applyTemplate` are supported
- If a prefixed tag is not found in the template, it's simply ignored
- The function processes all prefixes and their transformations in the order they appear
- Supports the same transformation types as the TemplateTag enum
- More flexible than `applyTemplate` but with slightly more complex syntax

#### See

- [applyTemplate](#applytemplate) For applying a single value to multiple transformation tags
- [TemplateTag](#templatetag) For the complete list of available transformation types

---

### breakToWords()

#### Call Signature

```ts
function breakToWords(str): string[];
```

Defined in: [utils/string.utils.ts:47](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L47)

Breaks a string into an array of words based on common separator patterns.

This function intelligently splits strings into individual words by detecting various
word boundary patterns, including:

- Camel case boundaries ("helloWorld" → \["hello", "world"])
- Snake case boundaries ("hello_world" → \["hello", "world"])
- Kebab case boundaries ("hello-world" → \["hello", "world"])
- Space-separated words ("hello world" → \["hello", "world"])
- Uppercase acronyms ("APIClient" → \["api", "client"])

The returned words are all converted to lowercase.

##### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

The string to split into words

</td>
</tr>
</tbody>
</table>

##### Returns

`string`\[]

- An array of lowercase words

##### Example

```typescript
breakToWords("helloWorld"); // ['hello', 'world']
breakToWords("hello_world"); // ['hello', 'world']
breakToWords("hello-world"); // ['hello', 'world']
breakToWords("hello world"); // ['hello', 'world']
breakToWords("APIConfig"); // ['api', 'config']
breakToWords("123Test456"); // ['123', 'test', '456']
```

##### Remarks

- Returns an empty array for empty, null, or undefined input
- Preserves numbers as separate words
- Handles consecutive uppercase letters as acronyms (preserving them as a single word)

#### Call Signature

```ts
function breakToWords(str, format): string;
```

Defined in: [utils/string.utils.ts:76](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L76)

Breaks a string into words and formats them using a provided function.

This overload splits a string into words using the same logic as the array version,
but additionally applies a formatting function to each word and joins them with spaces.

Common use cases include:

- Converting camelCase to Title Case
- Formatting identifiers for display
- Normalizing different string formats

##### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

The string to split and format

</td>
</tr>
<tr>
<td>

`format`

</td>
<td>

(`str`) => `string`

</td>
<td>

A function to apply to each word

</td>
</tr>
</tbody>
</table>

##### Returns

`string`

- A space-joined string of formatted words

##### Example

```typescript
// Convert camelCase to Sentence case
breakToWords("helloWorld", toFirstCase); // "Hello world"

// Convert snake_case to Title Case
breakToWords("user_profile_data", toFirstCase); // "User profile data"

// Format with a custom function
breakToWords("SYSTEM_ERROR", (word) => word.toLowerCase()); // "system error"
```

---

### countOccurrences()

```ts
function countOccurrences(str, searchValue, caseSensitive?): number;
```

Defined in: [utils/string.utils.ts:1288](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L1288)

Counts the occurrences of a substring within a string.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

`undefined`

</td>
<td>

The string to search within

</td>
</tr>
<tr>
<td>

`searchValue`

</td>
<td>

`string`

</td>
<td>

`undefined`

</td>
<td>

The substring to search for

</td>
</tr>
<tr>
<td>

`caseSensitive?`

</td>
<td>

`boolean`

</td>
<td>

`true`

</td>
<td>

Whether the search should be case-sensitive

</td>
</tr>
</tbody>
</table>

#### Returns

`number`

- The number of occurrences

#### Example

```typescript
countOccurrences("hello hello world", "hello"); // 2
countOccurrences("Hello hello", "hello", false); // 2
countOccurrences("Hello hello", "hello", true); // 1
```

---

### createExcerpt()

```ts
function createExcerpt(text, searchTerm, contextLength?, ellipsis?): string;
```

Defined in: [utils/string.utils.ts:721](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L721)

Creates an excerpt from a longer text by extracting a portion around a search term.
Useful for search result highlighting or previews.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`text`

</td>
<td>

`string`

</td>
<td>

`undefined`

</td>
<td>

The full text to create an excerpt from

</td>
</tr>
<tr>
<td>

`searchTerm`

</td>
<td>

`string`

</td>
<td>

`undefined`

</td>
<td>

The search term to find in the text

</td>
</tr>
<tr>
<td>

`contextLength?`

</td>
<td>

`number`

</td>
<td>

`DEFAULT_CONTEXT_LENGTH`

</td>
<td>

Number of characters to include before and after the search term

</td>
</tr>
<tr>
<td>

`ellipsis?`

</td>
<td>

`string`

</td>
<td>

`DEFAULT_ELLIPSIS`

</td>
<td>

Characters to use for indicating truncated text

</td>
</tr>
</tbody>
</table>

#### Returns

`string`

- The excerpt with the search term in context

#### Example

```typescript
const article =
  "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam in dui mauris.";

createExcerpt(article, "dolor", 10);
// "...ipsum dolor sit amet..."

createExcerpt(article, "consectetur", 15, "[...]");
// "[...]sit amet, consectetur adipiscing[...]"
```

---

### deepCopy()

```ts
function deepCopy<T>(obj): T;
```

Defined in: [utils/object.utils.ts:23](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L23)

Deep copy an object.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`T`

</td>
<td>

Type of the object.

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`obj`

</td>
<td>

`T`

</td>
<td>

Object to copy.

</td>
</tr>
</tbody>
</table>

#### Returns

`T`

Copied object.

#### Example

```TypeScript
// Example usage
const object = {
   name: "John Doe"
}

const copiedObject = deepCopy(object);
```

---

### dottedPathObjectToNested()

```ts
function dottedPathObjectToNested<R>(pathValueSet): R;
```

Defined in: [utils/object.utils.ts:549](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L549)

Converts a flattened DottedPathValueObject back into a nested object structure.

This function is the inverse of `objectToDottedPathValueObject`. It takes a flat map of
dot-notation paths to values and reconstructs a hierarchical object structure.

Each key in the input DottedPathValueObject represents a path through the object hierarchy,
with dots separating each level. The function builds a nested object structure by
parsing these paths and placing values at the appropriate locations.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
<th>Default type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`R`

</td>
<td>

`object`

</td>
<td>

The type of the returned object (defaults to object)

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`pathValueSet`

</td>
<td>

`Record`<`string`, `any`>

</td>
<td>

A flattened object with dot-notation path keys

</td>
</tr>
</tbody>
</table>

#### Returns

`R`

- A reconstructed nested object with the original hierarchy

#### Remarks

- Paths are validated for safety to prevent injection attacks
- Invalid paths are silently skipped (not included in the result)
- Path components should contain only alphanumeric characters, underscores, hyphens, and dots

#### See

- [objectToDottedPathValueObject](#objecttodottedpathvalueobject) The inverse operation to convert an object to DottedPathValueObject
- [DottedPathValueObject](#dottedpathvalueobject) The interface for the input flattened object

#### Examples

```typescript
// Convert a flat DottedPathValueObject to a nested object
const flatData = {
  "id": 123,
  "name": "John Doe",
  "profile.age": 30,
  "profile.address.city": "New York",
  "profile.address.zip": "10001"
};

const nestedObject = dottedPathObjectToNested(flatData);

Result:
// {
//   id: 123,
//   name: "John Doe",
//   profile: {
//     age: 30,
//     address: {
//       city: "New York",
//       zip: "10001"
//     }
//   }
// }
```

```typescript
// Typed return value
interface User {
  id: number;
  name: string;
  profile: {
    age: number;
    address: {
      city: string;
      zip: string;
    };
  };
}

const userData = dottedPathObjectToNested<User>(flatData);
// Returns object with User type
```

---

### escapeRegExp()

```ts
function escapeRegExp(str): string;
```

Defined in: [utils/string.utils.ts:1134](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L1134)

Escapes special characters in a string for use in regular expressions.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

The string to escape

</td>
</tr>
</tbody>
</table>

#### Returns

`string`

- The escaped string safe for use in RegExp

#### Example

```typescript
escapeRegExp("hello.world*"); // "hello\.world\*"

// Usage in RegExp:
const userInput = "hello.world*";
const regex = new RegExp(escapeRegExp(userInput));
```

---

### extractEmails()

```ts
function extractEmails(str): string[];
```

Defined in: [utils/string.utils.ts:456](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L456)

Extracts all email addresses from a string.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

The string to extract emails from

</td>
</tr>
</tbody>
</table>

#### Returns

`string`\[]

- Array of found email addresses

#### Example

```typescript
extractEmails("Contact us at support@example.com or sales@example.com");
// ["support@example.com", "sales@example.com"]
```

---

### extractUrls()

```ts
function extractUrls(str): string[];
```

Defined in: [utils/string.utils.ts:475](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L475)

Extracts all URLs from a string.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

The string to extract URLs from

</td>
</tr>
</tbody>
</table>

#### Returns

`string`\[]

- Array of found URLs

#### Example

```typescript
extractUrls("Visit https://example.com or http://test.org/page?id=5");
// ["https://example.com", "http://test.org/page?id=5"]
```

---

### filterByObject()

```ts
function filterByObject<T>(items, filters): T[];
```

Defined in: [utils/object.utils.ts:1082](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L1082)

Filters items by recursively matching nested property values.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`T`

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`items`

</td>
<td>

`T`\[]

</td>
</tr>
<tr>
<td>

`filters`

</td>
<td>

[`SimpleDeepPartial`](#simpledeeppartial)<`T`>

</td>
</tr>
</tbody>
</table>

#### Returns

`T`\[]

---

### format()

Implementation of the format function that handles both overloads.

#### Call Signature

```ts
function format(template, ...values): string;
```

Defined in: [utils/string.utils.ts:1220](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L1220)

Formats a string by replacing indexed placeholders with provided values.

This implementation uses {n} syntax for indexed placeholders where n is the
position of the value in the arguments list (0-based).

##### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`template`

</td>
<td>

`string`

</td>
<td>

The template string with {0}, {1}, etc. placeholders

</td>
</tr>
<tr>
<td>

...`values`

</td>
<td>

(`string` | `number` | `boolean` | `null` | `undefined`)\[]

</td>
<td>

Values to insert into the template

</td>
</tr>
</tbody>
</table>

##### Returns

`string`

- The formatted string

##### Example

```typescript
format("Hello, {0}!", "World"); // "Hello, World!"

format("User {0} has {1} points", "John", 100);
// "User John has 100 points"
```

#### Call Signature

```ts
function format(template, values): string;
```

Defined in: [utils/string.utils.ts:1239](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L1239)

Formats a string by replacing named placeholders with values from an object.

This implementation uses {name} syntax for named placeholders where 'name'
corresponds to a property in the provided values object.

##### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`template`

</td>
<td>

`string`

</td>
<td>

The template string with {propertyName} placeholders

</td>
</tr>
<tr>
<td>

`values`

</td>
<td>

`Record`<`string`, `string` | `number` | `boolean` | `null` | `undefined`>

</td>
<td>

Object with values to insert

</td>
</tr>
</tbody>
</table>

##### Returns

`string`

- The formatted string

##### Example

```typescript
// Named placeholders with object
format("Hello, {name}! You have {count} messages.", {
  name: "Alice",
  count: 5,
});
// "Hello, Alice! You have 5 messages."
```

---

### getEnumValues()

```ts
function getEnumValues<T>(e): T[keyof T][];
```

Defined in: [utils/object.utils.ts:1070](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L1070)

Extracts all values from a TypeScript enum, handling both string and numeric enum types correctly.

This utility function safely retrieves the actual values from TypeScript enums, accounting for
the different internal representations of string and numeric enums. For numeric enums, TypeScript
creates reverse mappings (value → key), so this function filters out the reverse mapping entries
to return only the actual enum values. For string enums, it returns all values directly.

This is particularly useful when you need to iterate over enum values, validate input against
enum values, create dropdown options from enums, or perform any operation that requires access
to the actual enum values rather than the keys.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`T` _extends_ `object`

</td>
<td>

The enum type extending object

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`e`

</td>
<td>

`T`

</td>
<td>

The enum object to extract values from

</td>
</tr>
</tbody>
</table>

#### Returns

`T`\[keyof `T`]\[]

An array containing all the actual values of the enum

#### Examples

```typescript
// String enum example
enum Color {
  RED = "red",
  GREEN = "green",
  BLUE = "blue",
}

const colorValues = getEnumValues(Color);
// Returns: ["red", "green", "blue"]

// Use for validation
function isValidColor(value: string): value is Color {
  return getEnumValues(Color).includes(value as Color);
}
```

```typescript
// Numeric enum example
enum Status {
  PENDING, // 0
  APPROVED, // 1
  REJECTED, // 2
}

const statusValues = getEnumValues(Status);
// Returns: [0, 1, 2] (not ["PENDING", "APPROVED", "REJECTED", 0, 1, 2])

// Use for creating select options
const statusOptions = getEnumValues(Status).map((value) => ({
  value,
  label: Status[value], // Get the key name for display
}));
```

```typescript
// Mixed numeric enum example
enum HttpStatus {
  OK = 200,
  NOT_FOUND = 404,
  SERVER_ERROR = 500,
}

const httpStatusValues = getEnumValues(HttpStatus);
// Returns: [200, 404, 500]

// Use for status code validation
function isValidHttpStatus(code: number): code is HttpStatus {
  return getEnumValues(HttpStatus).includes(code as HttpStatus);
}
```

```typescript
// Creating dropdown options from enum
enum UserRole {
  ADMIN = "admin",
  USER = "user",
  MODERATOR = "moderator",
}

const roleOptions = getEnumValues(UserRole).map((role) => ({
  value: role,
  label: role.charAt(0).toUpperCase() + role.slice(1),
}));
// Returns: [
//   { value: "admin", label: "Admin" },
//   { value: "user", label: "User" },
//   { value: "moderator", label: "Moderator" }
// ]
```

#### Remarks

- Automatically detects numeric vs string enums and handles them appropriately
- For numeric enums, filters out reverse mapping entries that TypeScript automatically creates
- For string enums, returns all values as-is since there are no reverse mappings
- Works with mixed numeric enums (enums with explicit numeric values)
- The returned array maintains the order of enum declaration
- Type-safe: the return type is correctly inferred as an array of the enum's value types

#### See

Object.values The underlying method used to extract enum entries

---

### getFileExt()

```ts
function getFileExt(mimeType, allowedMimeTypes?): string | undefined;
```

Defined in: [utils/file.utils.ts:1265](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/file.utils.ts#L1265)

Get the file extension of the given mime type.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`mimeType`

</td>
<td>

`string`

</td>
<td>

Mime type.

</td>
</tr>
<tr>
<td>

`allowedMimeTypes?`

</td>
<td>

`Map`<`string`, `string`>

</td>
<td>

Allowed mime types. If not provided, the default mime types map will be used.

</td>
</tr>
</tbody>
</table>

#### Returns

`string` | `undefined`

File extension or undefined if the mime type is not found.

#### Examples

```TypeScript
// Using the default mime types map
const extension = getFileExt('application/pdf');
// Output: 'pdf'
```

```TypeScript
// Using a custom mime types map
const customMimeTypes = new Map([
  ['jpg', 'image/jpeg'],
  ['png', 'image/png']
]);
const extension = getFileExt('image/jpeg', customMimeTypes);
// Output: 'jpg'
```

---

### getFileSize()

```ts
function getFileSize(size, round?): string;
```

Defined in: [utils/file.utils.ts:1296](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/file.utils.ts#L1296)

Get file size in human-readable format.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`size`

</td>
<td>

`number`

</td>
<td>

File size in bytes.

</td>
</tr>
<tr>
<td>

`round?`

</td>
<td>

`boolean`

</td>
<td>

Whether to round the size to whole numbers. If true, decimals will be removed.

</td>
</tr>
</tbody>
</table>

#### Returns

`string`

File size in human-readable format (B, KB, MB, or GB).

#### Examples

```TypeScript
// Get file size with decimals
const readableSize = getFileSize(1536);
// Output: '1.50 KB'
```

```TypeScript
// Get rounded file size
const roundedSize = getFileSize(1536, true);
// Output: '2 KB'
```

```TypeScript
// Get size for larger files
const largeFileSize = getFileSize(1073741824);
// Output: '1.00 GB'
```

---

### getMapKey()

```ts
function getMapKey(map, value): string | undefined;
```

Defined in: [utils/object.utils.ts:53](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L53)

Get the key of a map by value.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`map`

</td>
<td>

`Map`<`string`, `unknown`>

</td>
<td>

Map to get key from.

</td>
</tr>
<tr>
<td>

`value`

</td>
<td>

`unknown`

</td>
<td>

Value to get key for.

</td>
</tr>
</tbody>
</table>

#### Returns

`string` | `undefined`

Key of the map.

#### Example

```TypeScript
// Example usage
const user = new Map<string, string>([
    ["firstName", "John"],
    ["lastName", "Doe"],
    ["preferredName", "John"],
    ["age", 30],
]);

const key = getMapKey(user, "value2");

// Example output: "firstName"
```

---

### getMapKeys()

```ts
function getMapKeys(map, partialValue): string[];
```

Defined in: [utils/object.utils.ts:122](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L122)

Retrieves all keys from a Map where the corresponding values contain a specified substring.

This utility function searches through a Map's values and returns an array of keys
whose associated values include the provided partial string. The search is case-sensitive
and uses JavaScript's native string.includes() method for matching.

This is particularly useful for implementing search functionality, filtering operations,
or finding related entries in configuration maps, user preference stores, or any
key-value data structure where you need to locate entries by partial value matching.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`map`

</td>
<td>

`Map`<`string`, `string`>

</td>
<td>

The Map to search through for matching values

</td>
</tr>
<tr>
<td>

`partialValue`

</td>
<td>

`string`

</td>
<td>

The substring to search for within the Map's values

</td>
</tr>
</tbody>
</table>

#### Returns

`string`\[]

An array of keys whose corresponding values contain the partial value

#### Examples

```typescript
// Search user preferences for entries containing "John"
const userPreferences = new Map<string, string>([
  ["displayName", "John Doe"],
  ["firstName", "John"],
  ["lastName", "Doe"],
  ["preferredName", "Johnny"],
  ["email", "john.doe@example.com"],
]);

const johnKeys = getMapKeys(userPreferences, "John");
// Returns: ["displayName", "firstName", "email"]
```

```typescript
// Find configuration keys related to database settings
const config = new Map<string, string>([
  ["db_host", "localhost"],
  ["db_port", "5432"],
  ["cache_host", "redis-server"],
  ["db_name", "myapp_database"],
  ["log_level", "debug"],
]);

const dbKeys = getMapKeys(config, "db");
// Returns: ["db_name"] (only values containing "db", not keys)
```

```typescript
// Search in a translations map
const translations = new Map<string, string>([
  ["welcome_message", "Welcome to our application"],
  ["error_message", "An error occurred"],
  ["success_message", "Operation completed successfully"],
  ["info_message", "Please check your information"],
]);

const messageKeys = getMapKeys(translations, "message");
// Returns: ["welcome_message", "error_message", "success_message", "info_message"]
```

#### Remarks

- The search is case-sensitive; "John" will not match "john"
- Returns an empty array if no matches are found
- The function iterates through all Map entries, so performance scales with Map size
- Only works with Maps that have string values; other value types will cause runtime errors

---

### getValueByPath()

```ts
function getValueByPath<T>(obj, path): T | undefined;
```

Defined in: [utils/object.utils.ts:379](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L379)

Gets a value from a nested object using a dot-notation path string.

This function safely traverses a deeply nested object structure using a string path
with dot notation. It handles both object properties and array indices within the path.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`T`

</td>
<td>

Type of the value to be returned.

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`obj`

</td>
<td>

[`InfiniteObject`](#infiniteobject)

</td>
<td>

The object to retrieve the value from.

</td>
</tr>
<tr>
<td>

`path`

</td>
<td>

`string`

</td>
<td>

The dot-notation path to the desired value.

- Use dots to navigate through nested objects: 'user.profile.address'
- Use array notation for accessing array elements: 'items\[0]' or 'users\[2].name'

</td>
</tr>
</tbody>
</table>

#### Returns

`T` | `undefined`

- The value at the specified path, or undefined if:
  - Any part of the path doesn't exist
  - An array index is out of bounds
  - The path format is invalid

#### Examples

```typescript
// Simple nested object property
const user = {
  profile: {
    name: "John Doe",
    contact: { email: "john@example.com" },
  },
};
const email = getValueByPath<string>(user, "profile.contact.email");
// Returns: "john@example.com"
```

```typescript
// Accessing array elements
const data = {
  users: [
    { id: 1, name: "Alice" },
    { id: 2, name: "Bob" },
  ],
};
const name = getValueByPath<string>(data, "users[1].name");
// Returns: "Bob"
```

---

### groupBy()

```ts
function groupBy<K, V>(list, keyGetter): Map<K, V[]>;
```

Defined in: [utils/object.utils.ts:237](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L237)

Groups an array of objects into a Map based on a key extraction function.

This utility function takes an array of objects and organizes them into groups
based on a common key or property. The grouping is performed using a key extraction
function that you provide, which determines how each object should be categorized.
The result is a Map where each key represents a group and the value is an array
of objects belonging to that group.

This is particularly useful for data analysis, reporting, organizing collections
for display purposes, or preparing data for further processing where items need
to be categorized by shared characteristics.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`K`

</td>
<td>

The type of the grouping key (can be string, number, boolean, etc.)

</td>
</tr>
<tr>
<td>

`V`

</td>
<td>

The type of the objects being grouped

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`list`

</td>
<td>

`V`\[]

</td>
<td>

The array of objects to group

</td>
</tr>
<tr>
<td>

`keyGetter`

</td>
<td>

(`input`) => `K`

</td>
<td>

A function that extracts the grouping key from each object.
This function receives an object and should return the value
to group by. If the function returns null or undefined,
the object will be grouped under a null key.

</td>
</tr>
</tbody>
</table>

#### Returns

`Map`<`K`, `V`\[]>

A Map where keys are the grouping values and values are arrays
of objects that share that grouping key

#### Examples

```typescript
// Group users by age
interface User {
  name: string;
  age: number;
  department: string;
}

const users: User[] = [
  { name: "John", age: 30, department: "Engineering" },
  { name: "Jane", age: 25, department: "Marketing" },
  { name: "Bob", age: 30, department: "Engineering" },
  { name: "Alice", age: 25, department: "Sales" },
  { name: "Charlie", age: 35, department: "Engineering" },
];

const usersByAge = groupBy(users, (user) => user.age);
// Returns:
// Map {
//   30 => [
//     { name: "John", age: 30, department: "Engineering" },
//     { name: "Bob", age: 30, department: "Engineering" }
//   ],
//   25 => [
//     { name: "Jane", age: 25, department: "Marketing" },
//     { name: "Alice", age: 25, department: "Sales" }
//   ],
//   35 => [
//     { name: "Charlie", age: 35, department: "Engineering" }
//   ]
// }
```

```typescript
// Group products by category
interface Product {
  id: number;
  name: string;
  category: string;
  price: number;
}

const products: Product[] = [
  { id: 1, name: "Laptop", category: "Electronics", price: 999 },
  { id: 2, name: "Book", category: "Education", price: 29 },
  { id: 3, name: "Phone", category: "Electronics", price: 699 },
  { id: 4, name: "Pen", category: "Office", price: 5 },
];

const productsByCategory = groupBy(products, (product) => product.category);
// Useful for creating category-based product listings
```

```typescript
// Group tasks by completion status with boolean keys
interface Task {
  id: number;
  title: string;
  completed: boolean;
}

const tasks: Task[] = [
  { id: 1, title: "Review code", completed: true },
  { id: 2, title: "Write tests", completed: false },
  { id: 3, title: "Deploy app", completed: true },
  { id: 4, title: "Update docs", completed: false },
];

const tasksByStatus = groupBy(tasks, (task) => task.completed);
// Returns Map with boolean keys: true and false
```

#### Remarks

- The function preserves the original order of objects within each group
- If the keyGetter function returns null or undefined, those objects will be grouped under a null key
- The Map structure allows for efficient lookups and iteration over groups
- Works with any type of grouping key (string, number, boolean, objects, etc.)
- Empty arrays will return an empty Map

---

### hashString()

```ts
function hashString(str): Promise<string>;
```

Defined in: [utils/string.utils.ts:499](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L499)

Converts a string to a secure hash using SHA-256.

Note: This is a browser-compatible implementation using the Web Crypto API.
For Node.js environments, you might want to use the crypto module instead.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

The string to hash

</td>
</tr>
</tbody>
</table>

#### Returns

`Promise`<`string`>

- Promise resolving to the hex hash string

#### Example

```typescript
// Browser usage
await hashString("password123");
// "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f"
```

---

### hasOwnAll()

```ts
function hasOwnAll(obj, props): boolean;
```

Defined in: [utils/object.utils.ts:965](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/object.utils.ts#L965)

Checks if an object has all specified properties as its own properties (not inherited).

This utility function verifies that an object contains all the properties listed in the
provided array as direct (own) properties, not inherited from the prototype chain.
It uses the modern Object.hasOwn() method for reliable property existence checking,
making it safer than using hasOwnProperty() directly.

This is particularly useful for validating object structures, ensuring required properties
exist before processing, implementing type guards, or verifying that objects conform to
expected interfaces. It's commonly used in data validation, API request validation,
and ensuring objects have all necessary properties before performing operations.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`obj`

</td>
<td>

`Record`<`PropertyKey`, `unknown`>

</td>
<td>

The object to check for property existence

</td>
</tr>
<tr>
<td>

`props`

</td>
<td>

`PropertyKey`\[]

</td>
<td>

Array of property keys to verify exist on the object.
PropertyKey includes string, number, and symbol types.

</td>
</tr>
</tbody>
</table>

#### Returns

`boolean`

True if the object has all specified properties as own properties, false otherwise

#### Examples

```typescript
// Validate that a user object has required properties
interface User {
  id: number;
  name: string;
  email: string;
}

const user = {
  id: 123,
  name: "John Doe",
  email: "john@example.com",
  role: "admin",
};

const hasRequiredProps = hasOwnAll(user, ["id", "name", "email"]);
// Returns: true

const hasAllProps = hasOwnAll(user, ["id", "name", "email", "phone"]);
// Returns: false (missing 'phone' property)
```

```typescript
// Validate API request payload
function processUserUpdate(payload: unknown): User | null {
  if (typeof payload === "object" && payload !== null) {
    const requiredFields = ["id", "name", "email"];

    if (hasOwnAll(payload as Record<string, unknown>, requiredFields)) {
      // Safe to process as we know all required fields exist
      return updateUser(payload as User);
    }
  }

  throw new Error("Invalid payload: missing required fields");
}
```

```typescript
// Check configuration object completeness
interface DatabaseConfig {
  host: string;
  port: number;
  database: string;
  username: string;
  password: string;
}

const config = {
  host: "localhost",
  port: 5432,
  database: "myapp",
  username: "admin",
  // password is missing
};

const requiredConfigKeys = ["host", "port", "database", "username", "password"];
const isConfigComplete = hasOwnAll(config, requiredConfigKeys);
// Returns: false

if (!isConfigComplete) {
  throw new Error("Database configuration is incomplete");
}
```

```typescript
// Work with symbol properties
const symbolKey = Symbol("secret");
const obj = {
  name: "test",
  [symbolKey]: "hidden value",
};

const hasSymbolProp = hasOwnAll(obj, ["name", symbolKey]);
// Returns: true
```

#### Remarks

- Uses Object.hasOwn() which is more reliable than hasOwnProperty()
- Only checks for own properties, not inherited properties from the prototype chain
- Returns false immediately if any property is missing (short-circuit evaluation)
- Works with string, number, and symbol property keys
- Returns true for an empty properties array (vacuous truth)
- Does not check property values, only existence

#### See

Object.hasOwn The underlying method used for property checking

---

### htmlToText()

```ts
function htmlToText(str): string;
```

Defined in: [utils/string.utils.ts:1001](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L1001)

Remove HTML tags from a string and return plain text.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

String to remove HTML tags from.

</td>
</tr>
</tbody>
</table>

#### Returns

`string`

Plain text.

#### Example

```TypeScript
htmlToText("<h1>Hello World</h1>"); // "Hello World"
```

---

### isAlphanumeric()

```ts
function isAlphanumeric(str): boolean;
```

Defined in: [utils/string.utils.ts:1325](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/string.utils.ts#L1325)

Checks if a string contains only alphanumeric characters.

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`str`

</td>
<td>

`string`

</td>
<td>

The string to check

</td>
</tr>
</tbody>
</table>

#### Returns

`boolean`

- True if the string contains only alphanumeric characters

#### Example

```typescript
isAlphanumeric("abc123"); // true
isAlphanumeric("abc-123"); // false
```

---

### isArray()

```ts
function isArray<T>(value): value is T[];
```

Defined in: [utils/assertions.utils.ts:42](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/assertions.utils.ts#L42)

Type-safe utility to check if a value is an array of a specific type.

This function acts as a type guard that not only checks if the provided value
is an array (using the native Array.isArray method), but also narrows the TypeScript
type to an array of the generic type T. This enables safer handling of potentially
array-typed values with full type inference in the conditional branches.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`T`

</td>
<td>

The expected element type of the array

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`value`

</td>
<td>

`T` | `T`\[] | `undefined`

</td>
<td>

The value to check, which could be a single item,
an array of items, or undefined

</td>
</tr>
</tbody>
</table>

#### Returns

`value is T[]`

Type predicate that narrows the type to T\[] when true

#### Remarks

While this function essentially wraps Array.isArray, its value comes from the
TypeScript type narrowing it provides, making it especially useful in code that
needs to handle both single items and collections of items with type safety.

The function properly handles undefined values by returning false, making it safe
to use with optional parameters or potentially undefined values.

#### Example

```typescript
// Function that can accept either a single user or multiple users
async function createUser(
  userOrUsers: UserDto | UserDto[] | undefined,
): Promise<User | User[]> {
  // TypeScript knows userOrUsers is UserDto[] in this branch
  if (isArray<UserDto>(userOrUsers)) {
    return Promise.all(userOrUsers.map((user) => userService.createUser(user)));
  }
  // TypeScript knows userOrUsers is UserDto or undefined in this branch
  else if (userOrUsers) {
    return userService.createUser(userOrUsers);
  } else {
    throw new BadRequestException("User data is required");
  }
}
```

---

### isObject()

```ts
function isObject<T>(value?): value is T;
```

Defined in: [utils/assertions.utils.ts:91](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/assertions.utils.ts#L91)

Type-safe utility to check if a value is a non-array object of a specific type.

This function serves as a type guard that checks if the provided value is an object
(but not an array) and narrows the TypeScript type to the generic type T. It properly
excludes null, arrays, and primitive values, focusing only on object instances.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`T`

</td>
<td>

The expected object type to narrow to when the check passes

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`value?`

</td>
<td>

`T` | `T`\[]

</td>
<td>

The value to check, which could be a single object,
an array of objects, or undefined

</td>
</tr>
</tbody>
</table>

#### Returns

`value is T`

Type predicate that narrows the type to T when true

#### Remarks

This function performs three checks to ensure the value is a proper object:

1. It's not an array (using Array.isArray)
2. It's of type "object" according to JavaScript's typeof operator
3. It's not null (which would pass the typeof check but isn't a valid object)

This is particularly useful when handling parameters that could be either an object
or a simpler identifier (like an ID), allowing for type-safe conditional logic.

#### Example

```typescript
// Function that can accept either a user ID or a user object
async function getUserInfo(
  userIdOrUser: number | User | undefined,
): Promise<UserInfo> {
  // TypeScript knows userIdOrUser is User in this branch
  if (isObject<User>(userIdOrUser)) {
    // Can safely access object properties
    return await userService.getUserInfo(userIdOrUser.id);
  }
  // TypeScript knows userIdOrUser is number or undefined in this branch
  else {
    return await userService.getUserInfo(userIdOrUser);
  }
}

// Works with optional parameters too
function formatUserName(user?: User | string): string {
  if (isObject<User>(user)) {
    return `${user.firstName} ${user.lastName}`;
  }
  return user || "Guest";
}
```

---

### isObjectWith()

```ts
function isObjectWith<T>(value, propertyName): value is T;
```

Defined in: [utils/assertions.utils.ts:158](https://github.com/hichchidev/hichchi/blob/451086b0863c82a6952d5ee0c05bf458abaaa227/libs/utils/src/utils/assertions.utils.ts#L158)

Type-safe utility to check if a value is an object with a specific property.

This function acts as a type guard that determines if an unknown value is an object
that contains a specified property, and narrows the TypeScript type to the generic
type T when true. This provides a robust way to implement duck typing in TypeScript,
allowing for safe property access in the conditional branches.

#### Type Parameters

<table>
<thead>
<tr>
<th>Type Parameter</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`T` _extends_ `object`

</td>
<td>

The expected object type that should contain the property

</td>
</tr>
</tbody>
</table>

#### Parameters

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>

`value`

</td>
<td>

`unknown`

</td>
<td>

Any value to check, with no type constraints

</td>
</tr>
<tr>
<td>

`propertyName`

</td>
<td>

keyof `T`

</td>
<td>

The name of the property that should exist on the object

</td>
</tr>
</tbody>
</table>

#### Returns

`value is T`

Type predicate that narrows the type to T when true

#### Remarks

This function uses Object.prototype.hasOwnProperty.call to safely check for property
existence, even if the object has a custom implementation of hasOwnProperty or if the
property is named 'hasOwnProperty'.

Unlike the simpler isObject utility, this function can distinguish between different
object types based on their properties, making it ideal for discriminating between
different interface implementations or handling union types.

#### Example

```typescript
// Check if an object has the properties of a User interface
interface User {
  id: number;
  name: string;
}

interface Order {
  orderNumber: string;
  items: string[];
}

// Function that can handle different object types
function processEntity(entity: unknown): void {
  // Check if entity has 'id' property, indicating it's a User
  if (isObjectWith<User>(entity, "id")) {
    // TypeScript knows entity is User in this branch
    console.log(`Processing user: ${entity.name}`);
  }
  // Check if entity has 'order