npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

bracket-data

v4.7.0

Published

Get some helpful data for a tournament bracket.

Downloads

180

Readme

bracket-data

Note: This package is now located in the bracketclub/bracketclub monorepo.

Get some helpful data for a tournament bracket.

NPM

What is a bracket?

From wikipedia:

A bracket is a tree diagram that represents the series of games played during a tournament, named as such because it appears to be a large number of interconnected (punctuational) brackets.

But if you're going to use this, you probably already know that :).

What does this module do?

Let's say you like writing code, and you like brackets, and then one day you want to write some code about brackets. Well, you'll probably need some data first. bracket-data aims to have this data for you separated by sport and year, as well as some helpers to make it easier to interact with that data.

API

This module can be used in Node or the browser. All of the following examples are extracting the same data.

In Node, you can require the module as normally would:

// Node usage
var ncaam2013 = require("bracket-data")({
  year: "2013",
  sport: "ncaam"
});

In a browser, the files are provided prebuilt so that you don't include the whole bundle.

// For usage in a browser without bundling data for any other sport/year
var ncaam2013 = require("bracket-data/browser/ncaam-2013");

If you don't care about including all the data for every sport/year, then you can still require it normally:

// Browser usage, although this bundles data for every sport/year
var ncaam2013 = require("bracket-data")({
  year: "2013",
  sport: "ncaam"
});

Other Scripts

This module has a few helper scripts which are used to make certain things easier.

npm run bracketology

This will take the current year's teams from the ESPN Bracketology website and write them to the current year's JSON files. These usually wont be 100% accurate but will allow you to get some of the current year's data to test and is useful when the teams wont be selected for a few weeks.

npm run names -- ncaam 2018 [URLS]

This will check the URLs for a full list of team names and reference them against the list of teams in the provided sport/year combination to make sure no teams are missing.

What data does this module give me?

Hopefully enough to display an interactive bracket. There are many other modules for doing things like explicity validating, scoring and updating a bracket.

Here are the specific properties with examples from the ncaam-2013 bracket. Keep in mind, that the data will change based on the number of teams in the bracket, the number of regions and which teams.

  • bracket: an object structured to have each region with the necessary properties. For example:
{
  "regions": {
    "MW": {
      "name": "Midwest",
      "fullname": "Midwest Region",
      "sameSideAs": "W",
      "teams": [
        "Louisville",
        "Duke",
        "Michigan State",
        "Saint Louis",
        "Oklahoma State",
        "Memphis",
        "Creighton",
        "Colorado State",
        "Missouri",
        "Cincinnati",
        "Saint Mary's",
        "Oregon",
        "New Mexico State",
        "Valparaiso",
        "Albany",
        "North Carolina A&T"
      ],
      "id": "MW"
    },
    /* other regions... */
    "FF": {
      "id": "FF",
      "name": "Final Four"
    }
}
  • regex: a regular expression that can be used to match a string representation of the bracket. These string representations of brackets make up the foundation of all the bracket modules as it is how the data is stored. Here's what the final bracket looked like as a string.
MW18124637211232121W19121361410291362929S185411371514315434E1912463721432434FFMWSMW
  • constants: an object with a number of constant values of the bracket. For example:
{
  "REGION_COUNT": 4,
  "REGION_IDS": [
    "MW",
    "W",
    "S",
    "E"
  ],
  "FINAL_ID": "FF",
  "ALL_IDS": [
    "MW",
    "W",
    "S",
    "E",
    "FF"
  ],
  "EMPTY": "MWXXXXXXXXXXXXXXXWXXXXXXXXXXXXXXXSXXXXXXXXXXXXXXXEXXXXXXXXXXXXXXXFFXXX",
  "FINAL_NAME": "Final Four",
  "UNPICKED_MATCH": "X",
  "TEAMS_PER_REGION": 16
}
  • order: an array with the first round team order. This is useful for display purposes as it is ordered how the teams should be paired from top-to-bottom for each region to start the bracket:
[1, 16, 8, 9, 5, 12, 4, 13, 6, 11, 3, 14, 7, 10, 2, 15];
  • scoring: any data from the json files about how to possibly score a bracket. There is no set format for the scoring data, and due to this fact, scoring data will vary quite a bit from sport to sport and year to year. You could even come up with your own scoring system, PR it, and then write your own module to score each bracket. It could be as simple as
{
  "scoring": {
    // Each correct pick is worth one point
    "simple": 1
  }
}

or a pretty standard scoring system like:

{
  "scoring": {
    // Each correct pick is worth as many points as the value at the index of its round
    "standard": [10, 20, 40, 80, 160, 320]
  }
}

or even as complex as the gooley scoring method which I have modeled here.

  • locks: a date string of when the bracket locks. Locking is when the first game of the bracket has begun and no more picks should be allowed.

Does this have X sport for Y year?

Probably not, but it's only a pull request away! All the data lives in JSON files under the ./data dir. To add a sport/year combination:

  1. Add a directory with the name of the sport (if it doesn't already exist)
  2. Add/edit a defaults.json file inside that sport's directory (if it doesn't already exist)
  3. Add a file YYYY.json inside that sport's directory

Right now the required properties are:

  • regions: an array of objects each with the properties id, name, and fullname. These are order dependent and the regions that play each other to get to the finalRegion should be at indexes 0,1 and 2,3 (in a 4 region bracket).
  • teams: an object where the keys are the ids from regions and the properties are arrays of team names in seed order
  • finalRegion: an object with a name and id property for the final region (could be Final Four, NBA Finals, etc)
  • order: an array of the seeds ordered by who would play each other in the first round

And the following properties are optional:

  • scoring: an object with properties that could be used to score the bracket
  • locks: a date string representing when the bracket "locks" aka when picks should no longer be allowed because the games have started

These properties are merged recursively (using lodash's merge) with the properties from defaults.json being overwritten by the properties from YYYY.json. This allows for things that don't change often (such as the order) to only be written in one place, whereas things such as teams (which change every year) to be located in the appropriate file.

Also see the above section for further explanation about these properites or go look at a complete example: defaults.json, YYYY.json.

Which sports does it have?

Currently it only has a few, but the next priority will be adding the 2014 data very quickly after it is available.

  • NCAA Mens Basketball ncaam: [2012, 2013, 2014, 2015, 2016, 2017, 2018]
  • NCAA Womens Basketball ncaaw: [2016, 2017, 2018]
  • NHL nhl: [2015, 2016, 2017]
  • NBA nba: [2015, 2016, 2017]

Anything else?

If this is interesting to you, I think you should follow @tweetthebracket on Twitter. There are also a lot of other bracket related modules on our GitHub organization page.

LICENSE

MIT