Santas-De-Roy

A secret Santa API and CLI that takes into account past iterations to avoid re-assignations as much as possible.

History

It is tradition in my family to run a secret Santa every Christmases. Assignations used to be purely random. Which is good. But there is an issue.

After some years, it happens that I've already got the same Santa a few times while some people never gave me any gifts. I mean, I have nothing against the hand-made sweaters of grand-aunty Josette, but you know, change doesn't hurt...

Alright, that is an assignment problem. We humans are very bad at that but clever algorithms can solve it. Grand-aunty, I love you. But from now on, let the computer magic takes care of who is my Santa!

Installation

npm install santas-de-roy

Original.

If you're only using the CLI and have internet access, you may not need to install it permanently and may want to use npx (installed by default with node >= 5.2).

CLI

Santa-De-Roy comes with a Command Line Interface: santas-de-roy.

Simple usage

If you do not care about history, you can just write down the names of all participants as arguments. For example:

> santas-de-roy Tintin Snowy Haddock Dupond Dupont
receivers:
  Tintin: Snowy
  Snowy: Dupond
  Haddock: Bianca
  Dupond: Haddock
  Dupont: Tintin
  Bianca: Dupont

They keys are the santas, and the value the receivers.

That's randomized by default, so if you run it again there is fair chance that nobody is going to have the same Santa again. But there is no guarantee it will not happen. Eventually it will.

History

But here comes the interesting part. If you provide a data path (YAML or JSON), it will be used to save the results. And next time, will be re-used to ensure that nobody will get the same santa twice (as much as possible).

> santas-de-roy --data history.yaml Tintin Snowy Haddock Dupond Dupont
2 past christmases found.
receivers:
  Tintin: Dupont
  Snowy: Bianca
  Haddock: Dupond
  Dupond: Tintin
  Dupont: Haddock
  Bianca: Snowy
New data written in history.yaml.

Blacklists and config file

Because it can be annoying and error prone to type each year the participants of you secret santa. You may use a config file using the --config argument. Here is an example of config file.

# Define the participants.
participants:
  - Tintin
  - Snowy
  - Haddock
  - Dupond
  - Dupont
  - Bianca

# Defines blacklist. In the example below, Haddock will not become Bianca's
# Santa, and Bianca will not become the Santa of Dupond or Dupont.
blackLists:
  Haddock:
    - Bianca
  Bianca:
    - Dupond
    - Dupont

# Exclusion groups are another way of defining blacklists. Participants
# part of the same exclusion group cannot be the santa of each others.
exclusionGroups:
  - - Dupond
    - Dupont

# Set up the path toward the history file.
data: history.yaml

# Set up an id for this particular santa assignations. Ids must be unique in the
# history.
id: chistmas2018

# Other available options (same as CLI options, see below).
random: true
dryRun: false
logLevel: info
ignoreHistory: false
quiet: false

Config files can be YAML or JSON.

Other CLI options

> santas-de-roy --help

Usage: cli [options] [participants ...]

An application to assign secret santas, optionally taking history into account.


Options:

  -V, --version        output the version number
  -c, --config [path]  set the config path (JSON or YAML)
  -d, --data [path]    set the history path (to be loaded and written, JSON or YAML)
  -d, --dry-run        do not write in the history file
  --ignore-history     ignore the history when computing the new assignations
  --log-level [level]  set the log level
  --no-random          do not randomize the assignations
  -q, --quiet          do not output results
  -i, --id [id]        give an identifier for this christmas to write in the data
  -h, --help           output usage information

API

santas-de-roy is also a library that exports a single function.

santasDeRoy(options) ⇒ Object.<string, string>

Returns: Object.<string, string> - The new assignations.

| Param | Type | Default | Description | | ------------------------- | ---------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- | | options | Object | Array.<string> | | Options for the generation. Alternatively, an array of participants can be directly provided. | | [options.participants] | Array.<string> | | The list of all participants. If omitted, then the participants appearing in exclusionGroups or as a blackLists key will be used. | | [options.history] | List.<Object.<string, string|List.<string>>> | | An array containing the previous attributions (dictionaries whose keys are the santas, and values their receiver). | | [options.blackLists] | Object.<string, Array.<string>> | | A dictionary whose keys are participants and values a list of participants they cannot be the santa of. | | [options.exclusionGroups] | Array.<Array.<string>> | | Exclusion groups of participants. A participant cannot be the santa of someone who is in his exclusion group. | | [options.randomize] | boolean | true | If true (default), randomizes the assignation algorithm. Makes the output non deterministic. |