algomate 0.3.1

Algorithm strategy selection with sorting, search, graph, matrix, and benchmark utilities.

AlgoMate

AlgoMate is a Dart package for selecting and executing algorithm strategies from explicit input hints. It includes sorting, searching, graph, matrix, dynamic programming, string, and data-structure implementations behind one public library:

import 'package:algomate/algomate.dart';

Selection is heuristic: AlgoMate ranks applicable strategies from their metadata and SelectorHint. It does not guarantee that the selected strategy is the fastest choice for every machine or dataset.

เอกสารภาษาไทย

Requirements

• Dart >=3.0.0 <4.0.0
• Android, iOS, Linux, macOS, web, and Windows are declared package platforms

Install

dependencies:
  algomate: ^0.3.1

Then run:

dart pub get

Quick start

import 'package:algomate/algomate.dart';

void main() {
  final selector = AlgoSelectorFacade.development();
  final input = [64, 34, 25, 12, 22, 11, 90];

  final result = selector.sort(
    input: input,
    hint: SelectorHint(n: input.length),
  );

  result.fold(
    (success) {
      print(success.output);
      print(success.selectedStrategy.name);
    },
    (failure) => print(failure.message),
  );
}

The built-in non-mutating sort strategies return a new list. Strategies that intentionally mutate input, such as InPlaceInsertionSortStrategy, document that behavior in their API.

Use a strategy directly

Choose a concrete strategy when selection overhead or policy is not needed:

import 'package:algomate/algomate.dart';

void main() {
  final strategy = MergeSortStrategy();
  final input = [4, 1, 3, 2];
  final output = strategy.execute(input);

  print(output); // [1, 2, 3, 4]
  print(input);  // [4, 1, 3, 2]
}

Register a custom strategy

Custom algorithms implement Strategy<I, O> and declare AlgoMetadata and canApply behavior. Register them with a matching StrategySignature:

import 'package:algomate/algomate.dart';

class DescendingSort extends Strategy<List<int>, List<int>> {
  @override
  AlgoMetadata get meta => const AlgoMetadata(
        name: 'descending_sort',
        timeComplexity: TimeComplexity.oNLogN,
        spaceComplexity: TimeComplexity.oN,
        description: 'Sort integers in descending order',
      );

  @override
  bool canApply(List<int> input, SelectorHint hint) => true;

  @override
  List<int> execute(List<int> input) => List<int>.from(input)
    ..sort((left, right) => right.compareTo(left));
}

void main() {
  final selector = AlgoSelectorFacade.development();
  selector.register<List<int>, List<int>>(
    strategy: DescendingSort(),
    signature: StrategySignature.sort(
      inputType: List<int>,
      tag: 'descending_int_sort',
    ),
  );
}

About the Parallel* APIs

ParallelMergeSort, ParallelQuickSort, ParallelBinarySearch, ParallelMatrixMultiplication, ParallelStrassenMultiplication, ParallelBFS, ParallelDFS, and ParallelConnectedComponents retain their historical names for compatibility. Their current execute() methods are synchronous and do not spawn isolates. The package preserves the platform-specific constructors, types, metadata names, applicability rules, and fallbacks shipped in 0.3.0; native and web contracts are intentionally different.

Use these APIs for their current chunked, blocked, or divide-and-conquer semantics—not as evidence of multi-core execution. For new graph code that must compile unchanged across native, JavaScript, and Wasm, use BreadthFirstSearchStrategy<T> and DepthFirstSearchStrategy<T>. See the compatibility contract for the platform table.

Benchmarks

The canonical runner measures strategies exported by the package. It records the commit and dirty state, Dart/OS/CPU details, seed, dataset sizes, warm-up, iterations, concurrency, raw samples, median, and P95 latency.

dart run tool/benchmark.dart \
  --iterations 80 \
  --warmup 10 \
  --seed 42 \
  --dataset random \
  --json benchmark/out/results.json \
  --csv benchmark/out/results.csv

Supported datasets are random, sorted, reverse, nearly-sorted, duplicates, and all. Results are machine-specific evidence, not fixed throughput guarantees.

See Benchmark guide.

Documentation

• Algorithm reference
• Graph algorithms
• Custom objects
• Parallel-name compatibility contract
• Web compatibility
• Contributing
• Changelog

Development

Run the required gates from the repository root:

dart format --output=none --set-exit-if-changed .
dart analyze
dart test
dart run test/compile/native_0_3_0_contract.dart
dart compile js test/compile/web_0_3_0_contract.dart -o /tmp/algomate.js
node /tmp/algomate.js
dart compile wasm test/compile/web_0_3_0_contract.dart -o /tmp/algomate.wasm
git diff --check

For package metadata, public exports, SDK constraints, or release preparation, also run:

dart pub publish --dry-run

License

AlgoMate is available under the MIT License.