A cute little implementation of the Stable Match algorithm, built by and for the New Zealand Improv Festival.

Maintainability Test Coverage


Add this line to your application's Gemfile:

gem 'matchy_matchy'

And then execute:

$ bundle

Or install it yourself as:

$ gem install matchy_matchy


The MatchMaker takes two sets of data:

  • a Hash of candidates and their preferred targets
  • a Hash of targets to tuples containing their preferred targets and the number of candidates they're allowed to select

Calling perform on a MatchMaker yields an object that can return the assignments keyed either by_candidate or by_target.

candidates = {
  'Arthur'  => %w[City],
  'Sunny'   => %w[City Mercy],
  'Joseph'  => %w[City General Mercy],
  'Latha'   => %w[Mercy City General],
  'Darrius' => %w[City Mercy General],

targets = {
  'Mercy'   => [%w[Darrius Joseph], 2],
  'City'    => [%w[Darrius Arthur Sunny Latha Joseph], 2],
  'General' => [%w[Darrius Arthur Joseph Latha], 2],

results = MatchyMatchy::MatchMaker.perform(
  targets: targets,
  candidates: candidates

# {
#  'Arthur'  => 'City',
#  'Sunny'   => nil,
#  'Joseph'  => 'General',
#  'Latha'   => 'General',
#  'Darrius' => 'City',
# }

# {
#  'Mercy'   => []
#  'City'    => ['Darrius', 'Arthur'],
#  'General' => ['Joseph', 'Latha'],
# }

The candidates and targets can be pretty much any type of object. They can even clash, which makes it safe to use things like database IDs unambiguously: equal objects that are referenced in both collections will be treated separately by the MatchMaker.

You can also specify the targets without an explicit capacity, in which case a default capacity of 1 will be assumed:

targets = {
  'Mercy'   => %w[Darrius Joseph],
  'City'    => %w[Darrius Arthur Sunny Latha Joseph],
  'General' => %w[Darrius Arthur Joseph Latha],








Code of Conduct

Everyone interacting in the MatchyMatchy project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.