@qpjoy/utils

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

✨ 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

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

# Using npm
npm install @qpjoy/utils

# Using yarn
yarn add @qpjoy/utils

🚀 Quick Start

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

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

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

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:

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

# 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

# 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

# Run all tests
pnpm test

# Watch mode for TDD
pnpm test:watch

# Coverage report
pnpm test:coverage

Documentation

# 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:

npm login

2. Update version in package.json following semantic versioning:
   • 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

# 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
• Documentation
• GitHub Repository
• Issue Tracker

📮 Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Read the docs

Made with ❤️ by qpjoy