npm package: @qpjoy/utils
Description: A comprehensive TypeScript utility library with algorithms, data structures, and common utilities
Author: qpjoy
Latest version: 0.1.0

# @qpjoy/utils

A comprehensive TypeScript utility library from JavaScript fundamentals to deep algorithms and data structures, designed for convenience and type safety.

[![npm version](https://img.shields.io/npm/v/@qpjoy/utils.svg)](https://www.npmjs.com/package/@qpjoy/utils)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🎯 **Type-safe**: Written in TypeScript with full type definitions
- 📦 **Tree-shakeable**: Use only what you need
- 🚀 **Modern**: ESM and CommonJS support
- 🧪 **Well-tested**: Comprehensive test coverage
- 📚 **Documented**: Full JSDoc documentation with examples
- 🌐 **Universal**: Works in Node.js and browsers

## 📦 Installation

```bash
# Using pnpm (recommended)
pnpm add @qpjoy/utils

# Using npm
npm install @qpjoy/utils

# Using yarn
yarn add @qpjoy/utils
```

## 🚀 Quick Start

```typescript
import { bubbleSort } from '@qpjoy/utils';

const numbers = [64, 34, 25, 12, 22, 11, 90];
bubbleSort(numbers);
console.log(numbers); // [11, 12, 22, 25, 34, 64, 90]
```

## 📖 Usage Examples

### Sorting Algorithms

#### Basic Number Sorting

```typescript
import { bubbleSort, bubbleSortCopy } from '@qpjoy/utils';

// In-place sorting (modifies original array)
const numbers = [5, 2, 8, 1, 9];
bubbleSort(numbers);
console.log(numbers); // [1, 2, 5, 8, 9]

// Non-mutating sort (returns new array)
const original = [5, 2, 8, 1, 9];
const sorted = bubbleSortCopy(original);
console.log(original); // [5, 2, 8, 1, 9] - unchanged
console.log(sorted); // [1, 2, 8, 9]
```

#### Custom Comparison Functions

```typescript
import { bubbleSort, type CompareFn } from '@qpjoy/utils';

// Descending order
const numbers = [5, 2, 8, 1, 9];
bubbleSort(numbers, (a, b) => b - a);
console.log(numbers); // [9, 8, 5, 2, 1]

// Sorting objects by property
interface Person {
  name: string;
  age: number;
}

const people: Person[] = [
  { name: 'Alice', age: 30 },
  { name: 'Bob', age: 25 },
  { name: 'Charlie', age: 35 }
];

bubbleSort(people, (a, b) => a.age - b.age);
// People sorted by age: Bob (25), Alice (30), Charlie (35)
```

#### String Sorting

```typescript
import { bubbleSort } from '@qpjoy/utils';

// Alphabetical sorting
const words = ['banana', 'apple', 'cherry'];
bubbleSort(words);
console.log(words); // ['apple', 'banana', 'cherry']

// Sort by length
const phrases = ['hello', 'hi', 'goodbye', 'hey'];
bubbleSort(phrases, (a, b) => a.length - b.length);
console.log(phrases); // ['hi', 'hey', 'hello', 'goodbye']
```

### TypeScript Usage

The library is fully typed and works seamlessly with TypeScript:

```typescript
import { bubbleSort, type CompareFn } from '@qpjoy/utils';

// Type inference works automatically
const numbers = [3, 1, 4, 1, 5];
bubbleSort(numbers); // TypeScript knows this is number[]

// Custom types
interface Product {
  name: string;
  price: number;
  rating: number;
}

const products: Product[] = [
  { name: 'Laptop', price: 999, rating: 4.5 },
  { name: 'Mouse', price: 29, rating: 4.8 },
  { name: 'Keyboard', price: 79, rating: 4.3 }
];

// Type-safe comparison function
const byPrice: CompareFn<Product> = (a, b) => a.price - b.price;
bubbleSort(products, byPrice);
```

## 🏗️ Project Structure

```
@qpjoy/utils/
├── src/
│   └── methodology/
│       ├── algorithms/
│       │   └── sorting/
│       │       └── bubbleSort.ts
│       └── data-structures/
│           ├── linear/
│           └── tree/
├── tests/
├── dist/           # Built files (ESM + CJS)
└── docs/           # Generated documentation
```

## 🧪 Development

### Setup

```bash
# Install dependencies
pnpm install

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Generate coverage report
pnpm test:coverage

# Build the library
pnpm build

# Generate documentation
pnpm docs

# Type checking
pnpm type-check
```

### Building

```bash
# Build for production
pnpm build

# Build in watch mode (for development)
pnpm dev
```

The build output includes:

- `dist/index.js` - ESM bundle
- `dist/index.cjs` - CommonJS bundle
- `dist/index.d.ts` - TypeScript declarations
- Source maps for debugging

### Testing

```bash
# Run all tests
pnpm test

# Watch mode for TDD
pnpm test:watch

# Coverage report
pnpm test:coverage
```

### Documentation

```bash
# Generate documentation
pnpm docs

# Generate and watch documentation
pnpm docs:serve
```

Documentation is automatically generated from JSDoc comments using TypeDoc and will be available in the `docs/` directory.

## 📚 API Documentation

Full API documentation is available at [your-docs-url] (generated from JSDoc comments).

### Currently Available

#### Algorithms

- **Sorting**
  - `bubbleSort<T>(arr: T[], compareFn?: CompareFn<T>): T[]`
  - `bubbleSortCopy<T>(arr: T[], compareFn?: CompareFn<T>): T[]`

#### Types

- `CompareFn<T>` - Comparison function type for custom sorting

### Coming Soon

- More sorting algorithms (quicksort, mergesort, heapsort, etc.)
- Searching algorithms (binary search, etc.)
- Data structures (Stack, Queue, LinkedList, Tree, Graph, etc.)
- Graph algorithms
- String algorithms
- Math utilities
- And more!

## 📝 Publishing

### Prerequisites

1. Ensure you're logged into npm:

```bash
npm login
```

2. Update version in `package.json` following [semantic versioning](https://semver.org/):
   - Patch: `0.1.0` → `0.1.1` (bug fixes)
   - Minor: `0.1.0` → `0.2.0` (new features, backward compatible)
   - Major: `0.1.0` → `1.0.0` (breaking changes)

### Publishing Steps

```bash
# Build and test before publishing (done automatically by prepublishOnly)
pnpm run build
pnpm test

# Publish to npm
pnpm publish:npm

# Or publish manually
npm publish --access public
```

The `prepublishOnly` script ensures tests pass and the build is fresh before publishing.

## 🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes and add tests
4. Ensure tests pass: `pnpm test`
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Guidelines

- Write comprehensive JSDoc comments
- Add unit tests for new features
- Follow existing code style
- Update README if needed

## 📄 License

MIT © qpjoy

## 🔗 Links

- [npm Package](https://www.npmjs.com/package/@qpjoy/utils)
- [Documentation](your-docs-url)
- [GitHub Repository](https://github.com/qpjoy/utils)
- [Issue Tracker](https://github.com/qpjoy/utils/issues)

## 📮 Support

- 🐛 [Report a bug](https://github.com/qpjoy/utils/issues)
- 💡 [Request a feature](https://github.com/qpjoy/utils/issues)
- 📖 [Read the docs](your-docs-url)

---

Made with ❤️ by qpjoy