Initial commit

Author: codegrapple

.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_requests:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: stable
+
+      - name: Test
+        run: go test ./...

.gitignore

@@ -0,0 +1,14 @@
+# Tests
+*.test
+*.out
+
+# IDEs
+.idea
+.vscode
+
+# Emacs
+*~
+\#*\#
+
+# OS
+.DS_Store

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+
+  - repo: local
+    hooks:
+      - id: go-fmt
+        name: go fmt
+        entry: gofmt -w
+        language: system
+        files: \.go$
+
+      - id: go-vet
+        name: go vet
+        entry: go vet ./...
+        language: system
+        pass_filenames: false
+
+      - id: go-test
+        name: go test
+        entry: go test ./...
+        language: system
+        pass_filenames: false

CHANGELOG

@@ -0,0 +1,6 @@
+2026-01-14  Arian Behvandnejad  <behvandnejad@gmail.com>
+
+	* Money: type storing values exclusively in minor units
+	* New(minor uint64): constructor using minor units
+	* Minor(): accessor for retrieving raw minor units
+	* CurrencyAdapter: for conversion to major units

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arian Behvandnejad
+
+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.

README.md

@@ -0,0 +1,107 @@
+# money
+
+A small, strict Go package for representing monetary values safely.
+
+This package stores money exclusively in *minor units* (for example
+cents). Its goal is not flexibility, but correctness.
+
+## Design goals
+
+This package takes a narrow position:
+
+* Monetary values are stored as unsigned integers in minor units.
+* Invalid states are not representable.
+* Programmer errors surface promptly.
+
+## Non-goals
+
+This is not a full financial library.
+
+* No currency metadata or exchange rates
+* No formatting or localization
+* No decimal math
+* No silent rounding
+
+## Usage
+
+Create values using minor units:
+
+```go
+m := money.New(12345) // 123.45 in a 2-decimal currency
+```
+
+Add and subtract safely:
+
+```go
+a := money.New(500)
+b := money.New(200)
+
+sum  := a.Add(b) // 700
+diff := a.Sub(b) // 300
+```
+
+Subtraction panics if it would go negative:
+
+```go
+_ = money.New(100).Sub(money.New(200)) // panic
+```
+
+Multiply using a floating-point factor. Results are always rounded down:
+
+```go
+m := money.New(100)
+
+m.Mul(1.25) // 125
+m.Mul(1.99) // 199
+```
+
+Negative multipliers are rejected:
+
+```go
+m.Mul(-0.5) // panic
+```
+
+### Split amounts
+
+Split money into N parts, distributing any remainder starting from the first part:
+
+```go
+m := money.New(123)
+parts := m.Split(5) // [25, 25, 25, 24, 24]
+```
+
+### Zero checks
+
+```go
+money.New(0).IsZero() // true
+```
+
+### Converting to major units
+
+Conversion to major units is explicit and adapter-based:
+
+```go
+type EUR struct{}
+
+func (EUR) MinorToMajor(minor uint64) float64 {
+	return float64(minor) / 100
+}
+
+m := money.New(12345)
+eur := m.ToMajorUnits(EUR{}) // 123.45
+```
+
+## When to use this package
+
+Use it when:
+
+* You need a safe internal representation for money
+* You want arithmetic that cannot silently go wrong
+* You prefer explicit failures over implicit bugs
+
+Avoid it when:
+
+* You need decimal math or arbitrary precision
+* You want permissive behavior
+* You allow negative monetary values
+* You’re modeling accounting rules directly

go.mod

@@ -0,0 +1,3 @@
+module github.com/codegrapple/money
+
+go 1.25.5

money.go

@@ -0,0 +1,88 @@
+package money
+
+import "math"
+
+// Money represents a monetary value stored in minor units
+// (for example cents) to avoid floating point errors.
+type Money struct {
+	amount uint64
+}
+
+// New creates a new Money value from minor units.
+func New(minor uint64) Money {
+	return Money{amount: minor}
+}
+
+// Minor returns the value in minor units.
+func (m Money) Minor() uint64 {
+	return m.amount
+}
+
+// Add returns a new Money with the sum of two values.
+func (m Money) Add(other Money) Money {
+	return Money{
+		amount: m.amount + other.amount,
+	}
+}
+
+// Sub subtracts the other value.
+// It panics if the result would be negative.
+func (m Money) Sub(other Money) Money {
+	if other.amount > m.amount {
+		panic("money: subtraction would result in negative value")
+	}
+	return Money{
+		amount: m.amount - other.amount,
+	}
+}
+
+// Mul multiplies the amount by a floating-point factor.
+// The result is always rounded down to the nearest minor unit.
+func (m Money) Mul(factor float64) Money {
+	if factor < 0 {
+		panic("money: negative multiplier")
+	}
+	return Money{
+		amount: uint64(math.Floor(float64(m.amount) * factor)),
+	}
+}
+
+// Split divides the money amount into n parts.
+// The split is exact: the sum of all parts equals the original amount.
+// Any remainder is distributed by adding 1 minor unit to the first parts.
+func (m Money) Split(n int) []Money {
+	if n <= 0 {
+		panic("money: split count must be positive")
+	}
+
+	base := m.amount / uint64(n)
+	rem := m.amount % uint64(n)
+
+	out := make([]Money, n)
+	for i := range n {
+		amt := base
+		if uint64(i) < rem {
+			amt++
+		}
+		out[i] = Money{amount: amt}
+	}
+
+	return out
+}
+
+// IsZero checks if the money value is zero.
+func (m Money) IsZero() bool {
+	return m.amount == 0
+}
+
+// CurrencyAdapter defines how to convert minor units
+// into major units for a specific currency.
+type CurrencyAdapter interface {
+	MinorToMajor(minor uint64) float64
+}
+
+// ToMajorUnits converts the money value to major units
+// using the provided currency adapter.
+func (m Money) ToMajorUnits(adapter CurrencyAdapter) float64 {
+	return adapter.MinorToMajor(m.amount)
+}