Brauhaus.js

A javascript library for homebrew beer calculations both in the browser and on the server. Features include:

• Support for multiple Javascript runtimes
  • Node.js 0.6.x, 0.8.x, 0.9.x
  • Chrome, Firefox, Internet Explorer 9+, Safari, Opera, etc
• BeerXML import / export
• Calculate estimated OG, FG, IBU, ABV, SRM color, calories, and more
• Tinseth and Rager IBU calculation formula support
  • Pellets vs. whole hops support
  • Late addition boil support
  • Dry hopping support
• Automatically generated recipe instructions and timeline
• Estimate monetary recipe cost in USD based on ingredients
• Built-in unit conversions (kg <-> lb/oz, liter <-> gallon, temps, etc)
• Color in °SRM to name, RGB conversions, CSS color support, etc

Brauhaus.js was developed with and for Malt.io, a community website for homebrewers to create recipes and share their love of homebrewing beer.

Installation

There are two ways to use Brauhaus.js - either in a web browser (client-side) or on e.g. Node.js (server-side).

Web Browser (client-side use)

To use Brauhaus.js in a web browser, simply download the following file and include it as you would any other script:

• Download the latest brauhaus.min.js

<script type="text/javascript" src="/scripts/brauhaus.min.js"></script>
<script type="text/javascript">
    // Your code goes here!
    // See below for an example...
</script>

Node.js (server-side use)

For Node.js, you can easily install Brauhaus.js using npm:

npm install brauhaus

Quick Example (CoffeeScript)

Here is an example of how to use the library from CoffeeScript:

# The following line is NOT required for web browser use
Brauhaus = Brauhaus ? require 'brauhaus'

# Create a recipe
r = new Brauhaus.Recipe
    name: 'My test brew'
    description: 'A new test beer using Brauhaus.js!'
    batchSize: 20.0
    boilSize: 10.0

# Add ingredients
r.add 'fermentable',
    name: 'Extra pale liquid extract'
    color: 2.5
    weight: 4.2
    yield: 78.0

r.add 'spice',
    name: 'Cascade hops'
    weight: 0.028
    aa: 5.0
    use: 'boil'
    form: 'pellet'

r.add 'yeast'
    name: 'Wyeast 3724 - Belgian Saison'
    type: 'ale'
    form: 'liquid'
    attenuation: 80

# Calculate values
r.calculate()

# Print out calculated values
console.log "Original Gravity: #{ r.og.toFixed 3 }"
console.log "Final Gravity: #{ r.fg.toFixed 3 }"
console.log "Color: #{ r.color.toFixed 1 }° SRM (#{ r.colorName() })"
console.log "IBU: #{ r.ibu.toFixed 1 }"
console.log "Alcohol: #{ r.abv.toFixed 1 }% by volume"
console.log "Calories: #{ Math.round r.calories } kcal"

Quick Example (Javascript)

Here is an example of how to use the library form Javascript:

// The following line is NOT required for web browser use
var Brauhaus = Brauhaus || require('brauhaus');

// Create a recipe
var r = new Brauhaus.Recipe({
    name: 'My test brew',
    description: 'A new test beer using Brauhaus.js!',
    batchSize: 20.0,
    boilSize: 10.0
});

// Add ingredients
r.add('fermentable', {
    name: 'Extra pale liquid extract',
    color: 2.5,
    weight: 4.2,
    yield: 78.0
});

r.add('spice', {
    name: 'Cascade hops',
    weight: 0.028,
    aa: 5.0,
    use: 'boil',
    form: 'pellet'
});

r.add('yeast', {
    name: 'Wyeast 3724 - Belgian Saison',
    type: 'ale',
    form: 'liquid',
    attenuation: 80
});

// Calculate values
r.calculate();

// Print out calculated values
console.log('Original Gravity: ' + r.og.toFixed(3));
console.log('Final Gravity: ' + r.fg.toFixed(3));
console.log('Color: ' + r.color.toFixed(1) + '° SRM (' + r.colorName() + ')');
console.log('IBU: ' + r.ibu.toFixed(1));
console.log('Alcohol: ' + r.abv.toFixed(1) + '% by volume');
console.log('Calories: ' + Math.round(r.calories) + ' kcal');

Conversion Functions

The following functions are available to convert between various forms:

Brauhaus.kgToLb (number)

Convert kilograms to pounds.

>>> Brauhaus.kgToLb(2.5)
5.51155

Brauhaus.lbToKg (number)

Convert pounds to kilograms.

>>> Brauhaus.lbToKg(5.51155)
2.5

Brauhaus.kgToLbOz (number)

Convert kilograms to pounds and ounces.

>>> Brauhaus.kgToLbOz(2.5)
{
    lb: 5,
    oz: 8.184799999999996
}

Brauhaus.lbOzToKg (numberLbs, numberOz)

Convert pounds and ounces to kilograms.

>>> Brauhaus.lbOzToKg(5, 8.184799999999996)
2.5

Brauhaus.litersToGallons (number)

Convert liters to gallons.

>>> Brauhaus.litersToGallons(20.0)
5.283440000000001

Brauhaus.gallonsToLiters (number)

Convert gallons to liters.

>>> Brauhaus.gallonsToLiters(5.283440000000001)
20.0

Brauhaus.cToF (number)

Convert a temperature from celcius to fahrenheit.

>>> Brauhaus.cToF(20.0)
68.0

Brauhaus.fToC (number)

Convert a temperature from fahrenheit to celcius.

>>> Brauhaus.fToC(68.0)
20.0

Color Conversions

Colors can be easily converted into various useful formats for the screen and web.

Brauhaus.srmToRgb (number)

Convert a color in °SRM to a RGB triplet.

>>> Brauhaus.srmToRgb(8)
[208, 88, 13]

Brauhaus.srmToCss (number)

Convert a color in °SRM to a form usable in a CSS color string.

>>> Brauhaus.srmToCss(8)
'rgb(208, 88, 14)'

Brauhaus.srmToName (number)

Convert a color in °SRM to a human-readable color.

>>> Brauhaus.srmToName(8)
'deep gold'

Beer Styles

Brauhaus ships with many pre-defined beer styles from BJCP.

Brauhaus.getStyleCategories ()

Get a list of BJCP style categories supported by Brauhaus.

>>> Brauhaus.getStyleCategories()
['Light Lager', 'Pilsner', 'Bock', ...]

Brauhaus.getStyles (string)

Get a list of styles for a particular category

>>> Brauhaus.getStyles('Bock')
['Maibock / Helles Bock', 'DoppelBock', ...]

Brauhaus.getStyle (category, style)

Get the various ranges for a particular style.

>>> Brauhaus.getStyle('Bock', 'Doppelbock')
{
    gu: [1.072, 1.112]
    fg: [1.016, 1.024]
    srm: [6, 25]
    ibu: [16, 26]
    abv: [7, 10]
}

Brauhaus Objects

The following list of objects are available within Brauhaus:

• Fermentable
• Spice
• Yeast
• Recipe

Brauhaus.Fermentable

A fermentable is some kind of a sugar that yeast can metabolize into CO2 and alcohol. Fermentables can be malts, malt extracts, honey, sugar, etc. Each fermentable can have the following properties:

Fermentable.prototype.addition ()

Get the addition type of fermentable, one of mash, steep, or boil.

>>> f.addition()
'steep'

Fermentable.prototype.colorRgb ()

Get the color triplet for this fermentable. Shortcut for Brauhaus.srmToRgb(f.color).

>>> f.colorRgb()
[233, 157, 63]

Fermentable.prototype.colorCss ()

Get the CSS-friendly color string for this fermentable. Shortcut for Brauhaus.srmToCss(f.color).

>>> f.colorCss()
'rgb(233, 157, 63)'

Fermentable.prototype.colorName ()

Get the human-readable name for the color of this fermentable. Shortcut for Brauhaus.srmToName(f.color).

>>> f.colorName()
'deep gold'

Fermentable.prototype.gu (number)

Get the gravity units of this fermentable for a number of liters, based on the weight and yield. These units make the original gravity when divided by 1000 and added to one.

>>> f.gu(20.0)
32

Fermentable.prototype.plato (number)

Get the gravity in degrees plato for this fermentable for a number of liters, based on the weight and yield.

>>> f.plato(20.0)
7.5301

Fermentable.prototype.ppg ()

Get the parts per gallon from the yield percentage.

>>> f.ppg()
36

Fermentable.prototype.price ()

Guess the price in USD per kilogram of this fermentable, based on the name. Prices are an approximation based on multiple online homebrew supply store prices. You should use toFixed(2) to display these.

>>> f.price()
13.5025

Fermentable.prototype.type ()

Get the type of fermentable, either extract or grain.

>>> f.type()
'grain'

Fermentable.prototype.weightLb ()

A shortcut for Brauhaus.kgToLb(f.weight) to get the weight in pounds.

>>> f.weightLb()
2.2

Fermentable.prototype.weightLbOz ()

A shortcut for Brauhaus.kgToLbOz(f.weight) to get the weight in pounds and ounces.

>>> f.weightLbOz()
{
    lb: 2,
    oz: 4.3
}

Brauhaus.Spice

A spice is some kind of substance added to flavor or protect a brew. Spices can be hops, coriander, orange peel, cinnamon, whirlfloc, Irish moss, rose hips, etc. Each spice can have the following properties:

Spice.prototype.price ()

Guess the price in USD per kilogram of this spice, based on the name. Prices are an approximation based on multiple online homebrew supply store prices. You should use toFixed(2) to display these.

>>> s.price()
2.5318

Spice.prototype.weightLb ()

A shortcut for Brauhaus.kgToLb(s.weight) to get the weight in pounds.

>>> s.weightLb()
0.0625

Spice.prototype.weightLbOz ()

A shortcut for Brauhaus.kgToLbOz(s.weight) to get the weight in pounds and ounces.

>>> s.weightLbOz()
{
    lb: 0,
    oz: 1
}

Brauhaus.Yeast

Yeast are the biological workhorse that transform sugars into alcohol. Yeast can be professional strains like Wyeast 3068, harvested from bottles, harvested from the air, or other bugs like bacteria that produce acid.

Yeast.prototype.price ()

Guess the price in USD per packet of this yeast, based on the name. Prices are an approximation based on multiple online homebrew supply store prices. You should use toFixed(2) to display these.

>>> y.price()
7

Brauhaus.Recipe

A beer recipe, containing ingredients like fermentables, spices, and yeast. Calculations can be made for bitterness, alcohol content, color, and more. Many values are unset by default and will be calculated when the Recipe.prototype.calculate() method is called.

Recipe.fromBeerXml (xml)

Get a list of recipes from BeerXML loaded as a string.

>>> xml = '<recipes><recipe><name>Test Recipe</name>...</recipe></recipes>'
>>> recipe = Brauhaus.Recipe.fromBeerXml(xml)[0]
<Brauhaus.Recipe object 'Test Recipe'>

Recipe.prototype.add (type, data)

Add a new ingredient to the recipe. type can be one of fermentable, spice, or yeast. The data is what will be sent to the constructor of the ingredient defined by type.

>>> r.add('fermentable', {
    name: 'Pale malt'
    weight: 4.0
    yield: 75
    color: 3.5
});
>>> r.fermentables
[<Brauhaus.Fermentable object 'Pale malt'>]

Recipe.prototype.batchSizeGallons ()

Get the recipe batch size in gallons. Shortcut for Brauhaus.litersToGallons(r.batchSize).

>>> r.batchSizeGallons()
5.025

Recipe.prototype.boilSizeGallons ()

Get the recipe boil size in gallons. Shortcut for Brauhaus.litersToGallons(r.boilSize).

>>> r.boilSizeGallons()
3.125

Recipe.prototype.calculate ()

Calculate alcohol, bitterness, color, gravities, etc. This method must be called before trying to access those values. See the quick examples above for a more complete example of calculate() usage.

>>> r.calculate()
>>> r.ibu
28.5

Recipe.prototype.toBeerXml ()

Convert this recipe into BeerXML for export. Returns a BeerXML string.

>>> r.toBeerXml()
'<?xml version="1.0"><recipes><recipe>...</recipe></recipes>'

Contributing

Contributions are welcome - just fork the project and submit a pull request when you are ready!

Getting Started

First, create a fork on GitHub. Then:

git clone ...
cd brauhausjs
npm install

Unit Tests

Before submitting a pull request, please add any relevant tests and run them via:

npm test

If you have PhantomJS installed and on your path then you can use:

CI=true npm test

Pull requests will automatically be tested by Travis CI both in Node.js 0.6/0.8/0.9 and in a headless webkit environment (PhantomJS). Changes that cause tests to fail will not be accepted.

New tests can be added in the test directory. If you add a new file there, please don't forget to update the test.html to include it!

Please note that all contributions will be licensed under the MIT license in the following section.

License

Copyright (c) 2013 Daniel G. Taylor

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.