types-belt/README.md

A comprehensive collection of TypeScript utility types for building robust and maintainable applications

# Types-Belt 🎯

A comprehensive collection of TypeScript utility types for building robust and maintainable applications. Types-Belt provides a wide range of utility types that help you write better TypeScript code with improved type safety and developer experience.

## ✨ Features

- **Object Utilities**: Transform object properties (Partial, Required, Readonly, Pick, Omit, etc.)
- **Function Utilities**: Extract function types, parameters, and return types
- **Array & Tuple Utilities**: Advanced array and tuple manipulation types
- **Conditional Types**: Type guards and conditional type utilities
- **Production Ready**: Well-tested and documented for production use
- **Zero Dependencies**: Pure TypeScript with no runtime dependencies

## 🚀 Installation

```bash
npm install types-belt
```

```bash
yarn add types-belt
```

```bash
pnpm add types-belt
```

## 📖 Usage

### Object Utility Types

```typescript
import type { Partial, Required, Readonly, Pick, Omit, Record } from 'types-belt';

interface User {
  id: number;
  name: string;
  email: string;
  password: string;
}

// Make all properties optional
type PartialUser = Partial<User>;
// Result: { id?: number; name?: string; email?: string; password?: string; }

// Make all properties required
type RequiredUser = Required<User>;
// Result: { id: number; name: string; email: string; password: string; }

// Make all properties readonly
type ReadonlyUser = Readonly<User>;
// Result: { readonly id: number; readonly name: string; readonly email: string; readonly password: string; }

// Pick specific properties
type UserPublic = Pick<User, 'id' | 'name' | 'email'>;
// Result: { id: number; name: string; email: string; }

// Omit specific properties
type UserWithoutPassword = Omit<User, 'password'>;
// Result: { id: number; name: string; email: string; }

// Create a record type
type UserRoles = Record<'admin' | 'user' | 'guest', boolean>;
// Result: { admin: boolean; user: boolean; guest: boolean; }
```

### Function Utility Types

```typescript
import type { ReturnType, Parameters, FirstParameter, LastParameter } from 'types-belt';

type MyFunction = (name: string, age: number) => Promise<boolean>;

// Extract return type
type ReturnType = ReturnType<MyFunction>; // Promise<boolean>

// Extract parameter types
type Params = Parameters<MyFunction>; // [string, number]

// Extract first parameter
type FirstParam = FirstParameter<MyFunction>; // string

// Extract last parameter
type LastParam = LastParameter<MyFunction>; // number
```

### Array & Tuple Utility Types

```typescript
import type { ArrayElement, Tuple, FirstElement, LastElement } from 'types-belt';

// Extract element type from array
type StringArray = string[];
type ElementType = ArrayElement<StringArray>; // string

// Create tuple with specific length
type StringTuple3 = Tuple<string, 3>; // [string, string, string]

// Extract first and last elements
type MyTuple = [string, number, boolean];
type First = FirstElement<MyTuple>; // string
type Last = LastElement<MyTuple>; // boolean
```

### Conditional Utility Types

```typescript
import type { Is, Extends, If, IsUnion, IsArray, IsFunction } from 'types-belt';

// Check if types are exactly equal
type IsString = Is<string, string>; // true
type IsNumber = Is<string, number>; // false

// Check if type extends another
type CanAssign = Extends<string, string | number>; // true

// Conditional type selection
type Result = If<true, string, number>; // string

// Type guards
type IsUnionType = IsUnion<string | number>; // true
type IsArrayType = IsArray<string[]>; // true
type IsFunctionType = IsFunction<() => void>; // true
```

## 🧪 Testing

Run the test suite to ensure all types work correctly:

```bash
# Run tests in watch mode
npm test

# Run tests once
npm run test:run

# Run tests with coverage
npm run test:coverage

# Type checking
npm run type-check
```

## 🏗️ Building

Build the package for distribution:

```bash
npm run build
```

This will create the following outputs in the `dist/` directory:
- `types-belt.es.js` - ES Module format
- `types-belt.cjs` - CommonJS format
- `index.d.ts` - TypeScript declarations
- Source maps

## 📦 Publishing

Before publishing to npm, the package will automatically:
1. Build the project
2. Run all tests
3. Ensure everything passes

```bash
npm publish
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by the TypeScript community's need for better utility types
- Built with modern TypeScript features and best practices
- Tested with Vitest for reliable type validation

---

**Made with ❤️ for the TypeScript community**