@safs.io/match/README.md

Gale/Shapely deferred acceptance algorithm

# match

usage
```js
import { match, LeftEl, RightEl } from "@safs.io/match";
import { match } from "@safs.io/match/match";
import { LeftEl } from "@safs.io/match/left-element";
import { RightEl } from "@safs.io/match/right-element";
```

publish
`pnpm publish --tag next --access=public`


## API

constraints:
-  Left elements
  1.  MUST HAVE a unique id. (e.g. `new Left({ idKey: 'uuid'}))
-  Right elements
  1.  MUST HAVE a unique id. (e.g. `new Right({ idKey: 'uuid'}))
  2.  MUST HAVE a capacity set.

```
                                after rank hook can be used to build up stats(reason for exclusion, reason for rank, etc...).      
  LEFT                            |
  Object -> Rankable(Object)      |         Rankable(Object) with rankedCounterparts -> Matchable(Object)      
                            \     |       /                                                              \     
                              -> Rank ->                                                                  -> Match -> Matches
                            /             \                                                              /     |   
  Object -> Rankable(Object)                Rankable(Object) with rankedCounterparts -> Matchable(Object)      |
  RIGHT                                                                                                        |  
                                                                                                         after match hook used to build up stats (score, ???)
```

`POST /match`
REQUEST
```json
  {
    "left": [
      { "id": 1, "attrs": { "color": "blue", "fruit": "banana" } },
      { "id": 2, "attrs": { "color": "red", "fruit": "peach" } },
    ],

    "right": [
      { "id": "a23db", "capacity": 1, "attrs": { "color": "blue", "fruit": "peach" } }
    ]
  }
```

`STATUS 201`
RESPONSE
```json
  {
    "meta": {
      "maxPossibleScore": 30,
      "totalMatches": 1,
      "totalUnmatched": {
        "left": 1,
        "right": 0
      }
    },
    "matched": [
      { "left": 1, "right": "a23db", "score": 20 },
    ],
    "unmatched": {
      "left": [{"id": 2}],
      "right": []
    }
  }
```