Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/quentinroy/santas-de-roy
A secret santa API and CLI that takes into account past iterations to avoid re-assignations as much as possible
https://github.com/quentinroy/santas-de-roy
assignations history secret-santa
Last synced: 5 days ago
JSON representation
A secret santa API and CLI that takes into account past iterations to avoid re-assignations as much as possible
- Host: GitHub
- URL: https://github.com/quentinroy/santas-de-roy
- Owner: QuentinRoy
- License: mit
- Created: 2017-12-24T16:13:11.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2024-04-23T04:28:03.000Z (7 months ago)
- Last Synced: 2024-04-23T07:13:15.842Z (7 months ago)
- Topics: assignations, history, secret-santa
- Language: JavaScript
- Homepage:
- Size: 890 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 43
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Santas-De-Roy
[](https://www.npmjs.com/package/santas-de-roy)
[](https://travis-ci.org/QuentinRoy/santas-de-roy)
[](https://codecov.io/gh/QuentinRoy/santas-de-roy)
[](https://david-dm.org/QuentinRoy/santas-de-roy)
[](https://david-dm.org/QuentinRoy/santas-de-roy?type=dev)
[](https://renovateapp.com/)
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](https://en.wikipedia.org/wiki/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](https://www.npmjs.com/package/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.
```yaml
# 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. |