# cup-tool

> Outcomes, tiebreakers and other useful tools when working with FIFA and UEFA cups and torunaments

Latest version **1.4.0** (published 2026-04-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install cup-tool
pnpm add cup-tool
yarn add cup-tool
bun add cup-tool
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.4.0 |
| Published | 2026-04-01 |
| First published | 2021-09-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 70.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Magnus Engdal |
| Maintainers | magnusengdal |

## Links

- npm: https://www.npmjs.com/package/cup-tool
- npm.io page: https://npm.io/package/cup-tool

## Recent versions

- 1.4.0 (latest) — 2026-04-01
- 1.3.4 — 2024-08-04
- 1.3.3 — 2024-08-04
- 1.3.2 — 2024-07-11
- 1.3.1 — 2024-02-28
- 1.3.0 — 2024-02-28
- 1.2.1 — 2022-10-25
- 1.2.0 — 2022-10-25
- 1.1.13 — 2022-06-16
- 1.1.12 — 2022-06-16
- 1.1.11 — 2022-06-06
- 1.1.9 — 2022-06-02
- 1.1.8 — 2022-06-02
- 1.1.7 — 2022-04-06
- 1.1.6 — 2022-04-06
- … 11 more at https://npm.io/package/cup-tool/versions

## README

# Cup Tool

> Cup Tool makes it easy to calculate groups, outcomes and tiebreakers of tournaments like the UEFA Euros och FIFA World Cup.

## Getting Started

Start by initializing a cup.

```
const cup = cupTools();
```

Feed it some matches:

```
cup.matches = [
  {
    id: "a1",
    homeTeamId: "turkey",
    awayTeamId: "italy",
    group: "A",
  },
  ...
];
```

Set outcomes of those matches:

```
cup.setOutcome("a1", {
  homeScoreFT: 0,
  awayScoreFT: 3,
});
```

Now you can look at the resulting groups given those outcomes.

```
console.log(cup.groups.A);

[
  {
    teamId: "italy",
    pld: 3,
    w: 3,
    d: 0,
    l: 0,
    gf: 7,
    ga: 1,
    gd: 6,
    pts: 9,
  },
  ...
]
```

## Knockout stage

You can add the knockout matches with qualification criteria in the following format.

```
"1-A" // Winner group A
"2-A" // Runner-up group A
"1-39" // Winner KO match 39
"2-39" // Loser KO match 39
```

Always provide a `number` for knockout stage matches. Full match example:

```
cup.matches = [
  {
    id: "zb3s1",
    homeTeamQualify: "1-A",
    awayTeamQualify: "2-E",
    number: 39,
  },
  ...
  {
    id: "zb3s1",
    homeTeamQualify: "1-39",
    awayTeamQualify: "1-40",
    number: 56,
  },
  ...
];
```

After setting the outcomes, figure out which team qualified for a specific position like so:

```
cup.qualified("2-E")
```

In this case, it will return the `id` for the runnerup of group E.

## UEFA Euros

For UEFA Euros, the best thirds of each group also proceed to KO. You need to specify which Euro ruleset to use in order for it to know what teams to match up in the KO stage. Right now, `euro2016`, `euro2020`, `euro2024`, `olympics2024women` and `olympics2020women` are available.

```
const cup = cupTools("euro2024");
```

Then when the outcomes are set, you can figure out which third qualified like so:

```
cup.qualified("3-ADEF")
```

---
_Source: https://npm.io/package/cup-tool · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._