The Best Sort

Documentation

Complete API reference and usage guide for The Best Sort library

Installation

Prerequisites

  • Node.js 18.0.0 or higher
  • npm or yarn
  • TypeScript 4.7 or higher

Install the package

npm install the-best-sort

Quick Start

Basic Sorting

import { SortableNumber, SorterBuilder, ConcreteSortingStrategyFactory, StrategyType } from 'the-best-sort';

const numbers = [1, 100, 10];
const sortableArray = numbers.map(n => new SortableNumber(n));

const factory = new ConcreteSortingStrategyFactory<SortableNumber>();
const strategy = factory.createStrategy(StrategyType.DEFAULT);

const sorter = new SorterBuilder<SortableNumber>()
  .setArray(sortableArray)
  .setStrategy(strategy)
  .build();

const sortedArray = await sorter.execute();
console.log(sortedArray);

Core Components

SortableNumber

A comparable number wrapper implementing the ISortable interface

const nums = [1, 2, 3].map(
  n => new SortableNumber(n)
);

SortingContext

Manages state and event notifications during sorting

const context = new SortingContext(
  "Strategy Name"
);
context.attach(observer);

SorterBuilder

Fluent interface for constructing sorters with observers

new SorterBuilder()
  .setArray(array)
  .setStrategy(strategy)
  .addObserver(observer)
  .build();

StatisticsObserver

Collects performance metrics during sorting execution

const stats = 
  new StatisticsObserver();
sorter.addObserver(stats);
stats.printStatistics();

StrategyFactory

Create and register sorting strategies

const factory = 
  new ConcreteSortingStrategyFactory();
const strategy = 
  factory.createStrategy(StrategyType.DEFAULT);

ConfigurationManager

Singleton for global configuration management

ConfigurationManager.getInstance()
  .updateConfig({
    baseDelayMs: 100
  });

Advanced Usage

Command Pattern

Encapsulate sorting operations as commands

import { CommandInvoker, ExecuteSortingCommand } from 'the-best-sort';

const invoker = new CommandInvoker();
const sortingCommand = new ExecuteSortingCommand(sorter);

invoker.enqueueCommand(sortingCommand);
const results = await invoker.executeAll();

Template Method Pattern

Use abstract runners for sorting workflows

import { LoggingSortingRunner } from 'the-best-sort';

const runner = new LoggingSortingRunner<SortableNumber>();
const sortedArray = await runner.run(sortableArray, StrategyType.DEFAULT);

Configuration Management

Control sorting behavior globally

import { ConfigurationManager } from 'the-best-sort';

ConfigurationManager.getInstance().updateConfig({
  baseDelayMs: 100,
  enableLogging: true,
  showTimestamps: true,
  colorize: true
});

Event System

The library emits the following event types during sorting:

STARTED

Sorting has started

ELEMENT_SORTED

An array element was processed and added to result

COMPLETED

Sorting has completed

ERROR

An error occurred during sorting

Performance Metrics

StatisticsObserver collects the following metrics during sorting:

interface SortingStatistics {
  duration: number;           // Total duration in milliseconds
  sortedElements: number;     // Number of elements sorted
  totalDelay: number;         // Sum of all delays
  averageDelay: number;       // Average delay per element
  eventCounts: Map<EventType, number>; // Event counts by type
}

Architecture

The library follows a layered architecture:

  1. Core Domain - SortableNumber, event types, configuration
  2. Patterns Layer - Decorators, strategies, factory implementations
  3. Context Layer - SortingContext managing state and notifications
  4. Observer Layer - Multiple observer implementations (Console, Statistics, History)
  5. Application Layer - ArraySorter, CommandInvoker, runners
  6. Factory Layer - Strategy and builder creation

TypeScript Features

The library leverages advanced TypeScript features:

  • Generics for type-safe implementations
  • Decorators for cross-cutting concerns
  • Abstract classes and interfaces for contracts
  • Union types and enums for type safety
  • Method decorators with property descriptors
  • Readonly types for immutability
  • Object destructuring and spreading

Limitations

Very large arrays (10,000+ elements) may cause performance degradation due to the asynchronous nature of the sleep sort algorithm and event emission overhead.