Money, dates, and the types that prevent bugs

There is a class of bug you cannot test your way out of, because the test and the code share the same wrong assumption. A total that is a cent off. A birthday that is a day early for half your users. A currency conversion that is a hundred times too large and looks plausible.

The defence is not care. It is a type that cannot hold the wrong thing. This chapter is the two the framework ships, and the general move behind both.

Why a float is the wrong type for money

fmt.Println(0.1 + 0.2)        // 0.30000000000000004
fmt.Println(1.1 * 3)          // 3.3000000000000003

This is not a Go problem. It is binary floating point, and JavaScript does the same thing, which is why you have seen toFixed(2) sprinkled through every invoice page you have ever worked on.

Money: an integer and a currency

type Money struct {
    Amount   int64  `json:"amount"`
    Currency string `json:"currency" gorm:"size:3"`
}

Amount is in minor units: 2800 is twenty eight dollars. The currency rides with it, because an amount without one is not a quantity of anything.

A money field embeds this as two columns with the field name as prefix:

grit generate resource Invoice --fields "total:money"

gives total_amount and total_currency.

The operations, and which ones can fail

money.New(2800, "USD")          // from minor units
money.FromMajor(28.00, "USD")   // from a figure a person typed

m.Major()                       // 28.00, for display only
m.String()                      // "$28.00"

sum, err := a.Add(b)            // errors on mixed currencies
diff, err := a.Sub(b)
line := unit.MulInt(qty)        // a line total
tax := line.MulFloat(0.2)       // a percentage
parts := total.Allocate(3)      // a split that loses nothing
eur, err := usd.Convert("EUR", "0.9213")

Three of these are worth stopping on.

*FromMajor is the one place a float is allowed near money*, because a person typed 28.00 into a form. It is converted immediately rather than carried, andMajor() goes the other way for display. Feeding Major() back into arithmetic is how the cent you were protecting gets lost.

*Add returns an error*, and the error is a currency mismatch.

*Allocate is the one people write by hand and get wrong.* Splitting 10.00 three ways gives 3.34, 3.33, 3.33. Three lots of 3.33 loses a cent, and in accounting a lost cent is not a rounding detail, it is a reconciliation that fails. The remainder goes to the earliest parts, which is the convention accounting systems expect.

Not every currency has two decimal places

var exponents = map[string]int{
    "BIF": 0, "CLP": 0, "DJF": 0, "GNF": 0, "ISK": 0, "JPY": 0,
    "KMF": 0, "KRW": 0, "PYG": 0, "RWF": 0, "UGX": 0, "VND": 0,
    "XAF": 0, "XOF": 0, "XPF": 0,
    "BHD": 3, "IQD": 3, "JOD": 3, "KWD": 3, "LYD": 3, "OMR": 3,
    "TND": 3,
}

Yen and Ugandan shillings have no minor unit. Kuwaiti dinars have three. Every other currency is assumed to have two, which is true of most of ISO 4217.

Conversion handles it too, which is the subtle part:

usd := money.New(1000, "USD")        // 10.00
jpy, _ := usd.Convert("JPY", "148.2") // 1482 JPY

Multiplying the amount by the rate and relabelling the currency would give 148200: a hundred times too much, silently, because USD has two decimals and JPY has none.

The rate is a decimal string rather than a float, and that is deliberate: 1.005 is 1.00499999999999989 in binary, and an exchange rate multiplies the largest amounts in the system, which is exactly where that error stops being invisible. The string is parsed as an exact fraction, multiplied once, and rounded once.

Dates: the type that exists because of one error message

A date field used to be a *time.Time, and time.Time accepts RFC 3339 and nothing else. The admin's date picker sends "2001-08-06". So every date field failed to save with this:

parsing time "2001-08-06" as "2006-01-02T15:04:05Z07:00":
cannot parse "" as "T"

The fix was not to make the browser send a timezone it does not have. It was two wire types that accept what a browser actually sends:

type Date struct{ time.Time }      // "2001-08-06"
type DateTime struct{ time.Time }  // and the browser's variants

The accepted layouts, widest first:

time.RFC3339Nano
time.RFC3339
"2006-01-02T15:04:05"   // datetime-local, with seconds
"2006-01-02T15:04"      // datetime-local, without
"2006-01-02"            // a date picker

The middle two are what <input type="datetime-local"> produces: no zone, and often no seconds. Neither is RFC 3339, and both are what you get from a real browser.

date against datetime, and how to choose

• date
• A day that is the same day everywhere: a birthday, an invoice date, a public holiday, a due date
• datetime
• A moment on the clock: a login, an appointment, a reading from a sensor

The test: *would two people in different countries disagree about what day it is?* A birthday is the sixth of August in Kampala and in Lima. A meeting at 14:00 is not the same moment in both.

Store timestamps in UTC and render them local. Store dates as dates, with no zone at all, because a zone on a birthday is a question nobody asked.

The same move, in smaller places

Money and time are the big two. The field type list has several more of the same idea, where choosing the right one closes a bug rather than saving typing:

• email, url, tel
• Validated on write, so the column holds something sendable
• percent
• Stored as a number with a known meaning, not "0.2 or 20?"
• slug
• Lowercased, dashed, unique. A URL is a key
• select
• A closed set, in the database and in the type
• uint
• A count that cannot be negative, enforced by the type

grit new billing && cd billing
  grit generate resource Invoice \
    --fields "number:string, issued:date, due:date, \
client:belongs_to:Client, status:select:draft=Draft|sent=Sent|paid=Paid" \
    --items "InvoiceItem:description:string,qty:int,unit:money"
  grit generate resource Client --fields "name:string, email:email"
  grit migrate

Assignment

Commit your work with the message Money and Time - Assignment One, exactly as written, so the leaderboard can score it.