KKsort

A TypeScript library for sorting and searching algorithms.

Demo / Playground

Try it live at https://kksort-web.vercel.app/

Demo features:

• Choose the algorithm you want to test
• Enter custom input data and target values
• See results from each method instantly

Installation

npm install @kktestdev/kksort

or

pnpm add @kktestdev/kksort

Usage

1) Sort

import { quickSort } from '@kktestdev/kksort/quick-sort';

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

2) Search

import { binarySearch } from '@kktestdev/kksort/binary';

const sortedNumbers = [1, 3, 5, 7, 9];
const index = binarySearch(sortedNumbers, 7);
console.log(index); // 3

Function Signatures

// Pseudo type signatures used by functions in this library.
// The default comparator (when no compareFn is provided) supports only:
// number | string | bigint | boolean | Date
//
// In practice, T can also be an object when you supply your own compareFn.

type DefaultComparable = number | string | bigint | boolean | Date;
type Comparable = DefaultComparable | object;

// Sort
// When using a type supported by the default comparator: compareFn is optional
declare function sortFn<T extends Comparable>(
  arr: T[],
  // If arr is object[], provide compareFn to specify how elements are compared
  compareFn?: (a: T, b: T) => number
): T[];

// For other types: compareFn is always required
declare function sortFn<T>(
  arr: T[],
  compareFn: (a: T, b: T) => number
): T[];

// Search
// When using a type supported by the default comparator: compareFn is optional
declare function searchFn<T extends Comparable>(
  arr: T[],
  target: T,
  // If arr is object[], provide compareFn to specify how elements are compared
  compareFn?: (a: T, b: T) => number
): number;

// For other types: compareFn is always required
declare function searchFn<T>(
  arr: T[],
  target: T,
  compareFn: (a: T, b: T) => number
): number;

Notes:

• Search functions return the found index, or -1 if not found.
• The default comparator (when no compareFn is provided) supports only number, string, bigint, boolean, and Date.
  • NaN is not supported for number — a TypeError will be thrown if encountered.
  • Invalid Date values (where getTime() returns NaN) are not supported and will throw a TypeError.
• When no compareFn is provided, all values in arr and target must be the same type and one of the supported types above. Mixed types (e.g. number and string together) will cause defaultCompare to throw a TypeError.
• For object types or any other unsupported types, you must supply your own compareFn.
• Search functions that require a pre-sorted array: binarySearch and jumpSearch only — linearSearch and quickSearch work on unsorted arrays.

Function Details & Trade-offs

Sorting Functions

| Function | Import | Pros | Cons | Notes | |---|---|---|---|---| | bubbleSort | @kktestdev/kksort/bubble | Easy to understand, stable, great for teaching | Slow O(n²) on large inputs | Does not mutate original array | | insertionSort | @kktestdev/kksort/insertion | Excellent on nearly-sorted data, stable | Poor on large inputs (O(n²)) | Does not mutate original array | | selectionSort | @kktestdev/kksort/selection | Simple code, minimal swaps | O(n²) in all cases, not stable | Mutates original array | | mergeSort | @kktestdev/kksort/merge | Guaranteed O(n log n), stable | Extra memory O(n) | Does not mutate original array | | quickSort | @kktestdev/kksort/quick-sort | Fast in practice, good general-purpose choice | Worst case O(n²) | Does not mutate original array | | heapSort | @kktestdev/kksort/heap | Guaranteed O(n log n), low extra memory | Not stable, often slower than quicksort in practice | Mutates original array |

Search Functions

| Function | Import | Pros | Cons | Notes | |---|---|---|---|---| | binarySearch | @kktestdev/kksort/binary | Very fast O(log n) | Requires a sorted array | Does not mutate original array | | linearSearch | @kktestdev/kksort/linear | Works on unsorted arrays | Slow on large inputs (O(n)) | Does not mutate original array | | jumpSearch | @kktestdev/kksort/jump | Faster than linear on sorted data | Still slower than binary search | Requires a sorted array, does not mutate original array | | quickSearch | @kktestdev/kksort/quick-search | Fast on average for unsorted data | Worst case O(n²), rearranges elements | Mutates original array |