communitybuilds-node/README.md

Node.js API for Genshin Impact communitiy builds spreadsheet

# Genshin Community Builds node API

![logo](https://i.ibb.co/Q9M7kjd/logo.png)

[![NPM](https://nodei.co/npm/communitybuilds-node.png)](https://npmjs.org/package/communitybuilds-node)

Straightforward NodeJS wrapper / API to perform data fetching from [Genshin Impact Helper Team's spreadsheet](https://docs.google.com/spreadsheets/d/1gNxZ2xab1J6o1TuNVWMeLOZ7TPOqrsf3SshP5DLvKzI).

## Usage

```shell
npm i communitybuilds-node
```

```javascript
const { inspect } = require("util")
const { CommunityBuilds } = require("communitybuilds-node")

// you must init the package with a google-console apikey
CommunityBuilds.init("your-api-key")

// promise based example
CommunityBuilds.getCharactersByElement('pyro')
    .then(res => {
        const [amber] = res.data.filter(character => character.name === "amber")
        console.log(inspect(amber, { depth: null }))
    })

// async await example
async function cryoBuilds(){
    const {data} = await CommunityBuilds.getCharactersByElement('cryo')
    console.log(data)
}
```

First example will output
```javascript
{
  name: 'amber',
  builds: [
    {
      role: 'dps',
      equipment: [
        "Amos' Bow",
        'Thundering Pulse',
        'Aqua Simulacra',
        'Skyward Harp',
        'Prototype Crescent *',
        "Sharpshooter's Oath (3✩) [R5]",
        'Windblume Ode  [R5]',
        'Blackcliff Warbow',
        'Polar Star',
        'Hamayumi *'
      ],
      artifacts: [
        "Wanderer's Troupe (4)",
        "Shimenawa's Reminiscence (4)",
        'Crimson Witch of Flames (4)',
        "Crimson Witch of Flames (2) Wanderer's Troupe (2)",
        'Crimson Witch of Flames (2) +18% ATK set (2)',
        '+18% ATK set (2) / +18% ATK set (2)'
      ],
      artifactsSubStats: [
        'Crit DMG',
        'ATK%',
        'Elemental Mastery',
        'Energy Recharge',
        'Flat ATK'
      ],
      artifactsMainStats: {
        sands: 'ATK% / Elemental Mastery',
        goblet: 'Pyro DMG',
        circlet: 'Crit DMG'
      },
      talentPriority: [ 'Normal Attack', 'Burst', 'Skill' ],
      optimal: false,
    },
    {
      role: 'support',
      equipment: [
        'Elegy for the End',
        'Favonius Warbow',
        'Sacrificial Bow',
        'Viridescent Hunt'
      ],
      artifacts: [
        'Noblesse Oblige (4)',
        'Instructor (4) *',
        '2x +20% Energy Recharge%',
        'The Exile (4)'
      ],
      artifactsSubStats: [
        'Energy Recharge',
        'Crit Rate / DMG',
        'ATK%',
        'Elemental Mastery',
        'Flat ATK'
      ],
      artifactsMainStats: {
        sands: 'Energy Recharge / ATK%',
        goblet: 'Pyro DMG',
        circlet: 'Crit Rate / DMG'
      },
      talentPriority: [ 'Burst', 'Skill' ],
      optimal: true,
    }
  ]
}
```

## API keys

In order to properly function this package needs a google-console api key that you can obtain freely from [here](https://console.cloud.google.com/apis/credentials) and then enable the Google Sheet API. Create a new project then request a new API key. Beware of the 300 req/min limit. An LRU cache has been added to avoir reaching prematurely the limit.

## Available methods

```javascript

// NEW API
CommunityBuilds.getCharactersByElement('pyro')
CommunityBuilds.getCharactersByElement('...')

CommunityBuilds.getWeaponsByType('bows')
CommunityBuilds.getWeaponsByType('...')

CommunityBuilds.getArtifacts()

// OLD API
CommunityBuilds.init()      // init API
CommunityBuilds.pyro()      // fetch pyro builds
CommunityBuilds.hydro()     // fetch hydro builds
CommunityBuilds.anemo()     // fetch anemo builds
CommunityBuilds.electro()   // fetch electro builds
CommunityBuilds.dendro()    // fetch dendro build
CommunityBuilds.cryo()      // fetch cryo builds
CommunityBuilds.geo()       // fetch geo builds
CommunityBuilds.all()       // return iterable of all elements

// CommunityBuilds.claymores()   Deprecated
// CommunityBuilds.swords()      Deprecated
// CommunityBuilds.catalysts()   Deprecated
// CommunityBuilds.polearms()    Deprecated
// CommunityBuilds.bows()        Deprecated

// CommunityBuilds.artifacts()   Deprecated
```

## Notes
Fetching artifacts and weapons does NOT require a google API key, only fetching builds requires it.

## Technical notes
As mentioned before an LRU cache is implemented. This means that the first fetch is in the order of 300-400ms (depending on your hardware), subsequents fetches stands in the order of 0.01-1ms (depending on your hardware).  
This is extremely useful if you planning to do recurring fetches or updating DBs.  
The cache's TTL is 1 minute for both characters build and artifacts/weapons, though it might be increased in the future (after analyzing data of everyday uses).  
Apparently Google Docs bumps classnames by 1 upon every build. Let me explain: classname "s79" becomes "s80. This is an absolute mess,
especially for the scraping method.  
Any help is appriciated.

```javascript
// test taken on M1 mac mini

console.time()
await CommunityBuilds.artifacts()
console.timeEnd()

// default: 2.103s

// subsequent call ->
console.time()
await CommunityBuilds.artifacts()
console.timeEnd()

// default: 0.01ms
```


## Credits
Credits to the [original owners and contributors](https://docs.google.com/spreadsheets/d/1gNxZ2xab1J6o1TuNVWMeLOZ7TPOqrsf3SshP5DLvKzI/htmlview?pru=AAABdXYM80o*xMxXJdNbCCZ-v9FLVh6EXg#).