{"id":19387429,"url":"https://github.com/quentinroy/santas-de-roy","last_synced_at":"2025-02-24T18:55:29.750Z","repository":{"id":29566283,"uuid":"115274250","full_name":"QuentinRoy/santas-de-roy","owner":"QuentinRoy","description":"A secret santa API and CLI that takes into account past iterations to avoid re-assignations as much as possible","archived":false,"fork":false,"pushed_at":"2024-04-23T04:28:03.000Z","size":911,"stargazers_count":0,"open_issues_count":43,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-23T07:13:15.842Z","etag":null,"topics":["assignations","history","secret-santa"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/QuentinRoy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-24T16:13:11.000Z","updated_at":"2024-08-07T13:17:45.447Z","dependencies_parsed_at":"2023-01-14T15:12:21.609Z","dependency_job_id":"bafcf2ff-23af-416f-a3b6-20bcdcf5a6b4","html_url":"https://github.com/QuentinRoy/santas-de-roy","commit_stats":null,"previous_names":["quentinroy/santa-des-roy"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuentinRoy%2Fsantas-de-roy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuentinRoy%2Fsantas-de-roy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuentinRoy%2Fsantas-de-roy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuentinRoy%2Fsantas-de-roy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QuentinRoy","download_url":"https://codeload.github.com/QuentinRoy/santas-de-roy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240540551,"owners_count":19817791,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assignations","history","secret-santa"],"created_at":"2024-11-10T10:09:13.850Z","updated_at":"2025-02-24T18:55:29.729Z","avatar_url":"https://github.com/QuentinRoy.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Santas-De-Roy\n\n[![NPM](https://img.shields.io/npm/v/santas-de-roy.svg)](https://www.npmjs.com/package/santas-de-roy)\n[![Build Status](https://travis-ci.org/QuentinRoy/santas-de-roy.svg?branch=master)](https://travis-ci.org/QuentinRoy/santas-de-roy)\n[![codecov](https://img.shields.io/codecov/c/github/QuentinRoy/santas-de-roy/master.svg?style=flat)](https://codecov.io/gh/QuentinRoy/santas-de-roy)\n[![dependencies Status](https://david-dm.org/QuentinRoy/santas-de-roy/status.svg)](https://david-dm.org/QuentinRoy/santas-de-roy)\n[![devDependencies Status](https://david-dm.org/QuentinRoy/santas-de-roy/dev-status.svg)](https://david-dm.org/QuentinRoy/santas-de-roy?type=dev)\n[![renovate badge](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovateapp.com/)\n\nA secret Santa API and CLI that takes into account past iterations to avoid re-assignations as much as possible.\n\n## History\n\nIt 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.\n\nAfter 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...\n\n![Grand aunty's sweater](https://raw.githubusercontent.com/QuentinRoy/santas-de-roy/master/colin.jpg \"Grand aunty's sweater\")\n\nAlright, 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!\n\n## Installation\n\n```\nnpm install santas-de-roy\n```\n\nOriginal.\n\nIf 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 \u003e= 5.2).\n\n## CLI\n\nSanta-De-Roy comes with a Command Line Interface: santas-de-roy.\n\n### Simple usage\n\nIf you do not care about history, you can just write down the names of all participants as arguments.\nFor example:\n\n```\n\u003e santas-de-roy Tintin Snowy Haddock Dupond Dupont\nreceivers:\n  Tintin: Snowy\n  Snowy: Dupond\n  Haddock: Bianca\n  Dupond: Haddock\n  Dupont: Tintin\n  Bianca: Dupont\n```\n\nThey keys are the santas, and the value the receivers.\n\nThat'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.\n\n### History\n\nBut 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).\n\n```\n\u003e santas-de-roy --data history.yaml Tintin Snowy Haddock Dupond Dupont\n2 past christmases found.\nreceivers:\n  Tintin: Dupont\n  Snowy: Bianca\n  Haddock: Dupond\n  Dupond: Tintin\n  Dupont: Haddock\n  Bianca: Snowy\nNew data written in history.yaml.\n```\n\n### Blacklists and config file\n\nBecause 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.\n\n```yaml\n# Define the participants.\nparticipants:\n  - Tintin\n  - Snowy\n  - Haddock\n  - Dupond\n  - Dupont\n  - Bianca\n\n# Defines blacklist. In the example below, Haddock will not become Bianca's\n# Santa, and Bianca will not become the Santa of Dupond or Dupont.\nblackLists:\n  Haddock:\n    - Bianca\n  Bianca:\n    - Dupond\n    - Dupont\n\n# Exclusion groups are another way of defining blacklists. Participants\n# part of the same exclusion group cannot be the santa of each others.\nexclusionGroups:\n  - - Dupond\n    - Dupont\n\n# Set up the path toward the history file.\ndata: history.yaml\n\n# Set up an id for this particular santa assignations. Ids must be unique in the\n# history.\nid: chistmas2018\n\n# Other available options (same as CLI options, see below).\nrandom: true\ndryRun: false\nlogLevel: info\nignoreHistory: false\nquiet: false\n```\n\nConfig files can be YAML or JSON.\n\n### Other CLI options\n\n```\n\u003e santas-de-roy --help\n\nUsage: cli [options] [participants ...]\n\nAn application to assign secret santas, optionally taking history into account.\n\n\nOptions:\n\n  -V, --version        output the version number\n  -c, --config [path]  set the config path (JSON or YAML)\n  -d, --data [path]    set the history path (to be loaded and written, JSON or YAML)\n  -d, --dry-run        do not write in the history file\n  --ignore-history     ignore the history when computing the new assignations\n  --log-level [level]  set the log level\n  --no-random          do not randomize the assignations\n  -q, --quiet          do not output results\n  -i, --id [id]        give an identifier for this christmas to write in the data\n  -h, --help           output usage information\n```\n\n## API\n\nsantas-de-roy is also a library that exports a single function.\n\n### santasDeRoy(options) ⇒ \u003ccode\u003eObject.\u0026lt;string, string\u0026gt;\u003c/code\u003e\n\n**Returns**: \u003ccode\u003eObject.\u0026lt;string, string\u0026gt;\u003c/code\u003e - The new assignations.\n\n| Param                     | Type                                                                         | Default           | Description                                                                                                                       |\n| ------------------------- | ---------------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| options                   | \u003ccode\u003eObject\u003c/code\u003e \\| \u003ccode\u003eArray.\u0026lt;string\u0026gt;\u003c/code\u003e                     |                   | Options for the generation. Alternatively, an array of participants can be directly provided.                                     |\n| [options.participants]    | \u003ccode\u003eArray.\u0026lt;string\u0026gt;\u003c/code\u003e                                            |                   | The list of all participants. If omitted, then the participants appearing in exclusionGroups or as a blackLists key will be used. |\n| [options.history]         | \u003ccode\u003eList.\u0026lt;Object.\u0026lt;string, string\\|List.\u0026lt;string\u0026gt;\u0026gt;\u0026gt;\u003c/code\u003e |                   | An array containing the previous attributions (dictionaries whose keys are the santas, and values their receiver).                |\n| [options.blackLists]      | \u003ccode\u003eObject.\u0026lt;string, Array.\u0026lt;string\u0026gt;\u0026gt;\u003c/code\u003e                     |                   | A dictionary whose keys are participants and values a list of participants they cannot be the santa of.                           |\n| [options.exclusionGroups] | \u003ccode\u003eArray.\u0026lt;Array.\u0026lt;string\u0026gt;\u0026gt;\u003c/code\u003e                              |                   | Exclusion groups of participants. A participant cannot be the santa of someone who is in his exclusion group.                     |\n| [options.randomize]       | \u003ccode\u003eboolean\u003c/code\u003e                                                         | \u003ccode\u003etrue\u003c/code\u003e | If true (default), randomizes the assignation algorithm. Makes the output non deterministic.                                      |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquentinroy%2Fsantas-de-roy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquentinroy%2Fsantas-de-roy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquentinroy%2Fsantas-de-roy/lists"}