bs

README

go-bs

A small, dependency-free Go library for converting dates between Gregorian (AD) and Bikram Sambat (BS), the calendar used in Nepal.

✓ 122 BS years covered (1979-2100)
✓ 1,464 BS months represented
✓ Every supported BS date tested
✓ AD → BS → AD round-trip tested
✓ BS → AD → BS round-trip tested
✓ Zero runtime dependencies
✓ Zero network requests

Features

• ADToBS / BSToAD conversion
• Supports BS years 1979–2100 inclusive
• Strict date validation against real BS month lengths (not just shape)
• Zero runtime dependencies
• Timezone-safe: conversion is based on calendar date, not time-of-day
• Table-driven calendar data, verified against a live source where possible (see docs/calendar-data.md)
• Exhaustively tested: every one of the 44,562 supported days round-trips in both directions

Installation

go get github.com/suprimkhatri77/go-bs

Usage

Convert AD to BS:

package main

import (
	"fmt"
	"log"
	"time"

	bs "github.com/suprimkhatri77/go-bs"
)

func main() {
	ad := time.Date(2026, time.September, 22, 0, 0, 0, 0, time.UTC)

	d, err := bs.ADToBS(ad)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(d) // 2083-06-06
}

Convert BS to AD:

d, err := bs.NewDate(2083, 6, 6)
if err != nil {
	log.Fatal(err)
}

ad, err := bs.BSToAD(d)
if err != nil {
	log.Fatal(err)
}

fmt.Println(ad.Format("2006-01-02")) // 2026-09-22

Validate a BS date without converting it:

if !bs.IsValid(2080, 2, 32) {
	fmt.Println("not a real Bikram Sambat date")
}

Date arithmetic and comparison:

d, _ := bs.NewDate(2083, 6, 15)

next, _ := d.AddDays(10)
fmt.Println(next) // 2083-06-25

fmt.Println(d.Before(next)) // true

weekday, _ := d.DayOfWeek()
fmt.Println(weekday) // Thursday

name, _ := d.MonthName()
fmt.Println(name) // Ashwin

Parsing:

d, err := bs.Parse("2083-06-15")
if err != nil {
	log.Fatal(err)
}

API overview

const (
	MinBSYear = 1979
	MaxBSYear = 2100
)

type Date struct {
	Year, Month, Day int
}

func NewDate(year, month, day int) (Date, error)
func Parse(s string) (Date, error) // "YYYY-MM-DD"

func (d Date) Valid() bool
func (d Date) String() string // "YYYY-MM-DD"
func (d Date) MonthName() (string, error)

func (d Date) Before(other Date) bool
func (d Date) After(other Date) bool
func (d Date) Equal(other Date) bool

func (d Date) AddDays(n int) (Date, error)
func (d Date) DayOfWeek() (time.Weekday, error)

func ADToBS(t time.Time) (Date, error)
func BSToAD(d Date) (time.Time, error)

func IsValid(year, month, day int) bool
func IsSupportedBSYear(year int) bool
func DaysInMonth(year, month int) (int, error)
func DaysInYear(year int) (int, error)
func MonthName(month int) (string, error)

var (
	ErrInvalidYear   error
	ErrInvalidMonth  error
	ErrInvalidDay    error
	ErrInvalidFormat error
	ErrOutOfRange    error
)

All errors support errors.Is, e.g. errors.Is(err, bs.ErrInvalidDay).

Date.Month is 1-based: 1 is Baisakh, 12 is Chaitra.

This is the v0.1.0 surface. Formatting layouts, Nepali-digit conversion, DaysBetween, StartOfMonth/EndOfMonth, and calendar-grid helpers (month view, weeks-in-month, first-weekday-of-month) are deliberately left for a later release rather than bolted on now — see CHANGELOG.md.

Supported range

• Bikram Sambat: 1979–2100 (MinBSYear–MaxBSYear), inclusive.
• The corresponding Gregorian range is 1922-04-13 to 2044-04-13, derived from the verified calendar data rather than assumed.

Most BS calendar libraries stop around this range because that's roughly the edge of what Nepal's calendar authorities have officially published in advance. MaxBSYear is expected to move out further (realistically not before around BS 2095) once more official data exists.

Accuracy

BS month lengths are not computed from a formula — they follow the officially published Nepali calendar and are stored as a static, table-driven dataset. That dataset was cross-checked against multiple existing open-source implementations and, where possible, against a live calendar source, rather than copied from a single upstream project as-is. See docs/calendar-data.md for the sources, the verification method, and a documented known limitation (BS years 1979–1999 could not be checked against a live source and rely on two library sources agreeing with each other).

Timezone behavior

ADToBS looks only at the Year, Month and Day of the given time.Time — its time-of-day and location are ignored, and the same Gregorian calendar date always converts to the same BS date, regardless of which timezone the time.Time is expressed in.

Testing

go test ./...
go test -race ./...
go vet ./...

TestExhaustiveBSRoundTrip and TestExhaustiveADRoundTrip convert every one of the 44,562 supported days in both directions and confirm the round trip is exact, rather than relying on a sample.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.

Documentation

Overview

Code generated by tools/calendar-generator. DO NOT EDIT.

Regenerate with: go run ./tools/calendar-generator -out data.go See docs/calendar-data.md for sources and verification method.

Package bs converts calendar dates between the Gregorian (AD) calendar and the Bikram Sambat (BS) calendar used in Nepal, for BS years MinBSYear through MaxBSYear inclusive.

BS month lengths are not derived from a formula: they follow Nepal's officially published calendar and are stored as a verified, table-driven dataset (see docs/calendar-data.md for sources). The package has no runtime dependencies.

Conversion operates on calendar dates (year, month, day), not timestamps. ADToBS considers only the Year, Month and Day components of the given time.Time and ignores time-of-day and location.

Index

• Constants
• Variables
• func BSToAD(d Date) (time.Time, error)
• func DaysInMonth(year, month int) (int, error)
• func DaysInYear(year int) (int, error)
• func IsSupportedBSYear(year int) bool
• func IsValid(year, month, day int) bool
• func MonthName(month int) (string, error)
• type Date
  • func ADToBS(t time.Time) (Date, error)
  • func NewDate(year, month, day int) (Date, error)
  • func Parse(s string) (Date, error)
  • func (d Date) AddDays(n int) (Date, error)
  • func (d Date) After(other Date) bool
  • func (d Date) Before(other Date) bool
  • func (d Date) DayOfWeek() (time.Weekday, error)
  • func (d Date) Equal(other Date) bool
  • func (d Date) MonthName() (string, error)
  • func (d Date) String() string
  • func (d Date) Valid() bool

Constants

const (
	MinBSYear = 1979
	MaxBSYear = 2100
)

MinBSYear and MaxBSYear are the inclusive bounds of the BS years supported by this package.

Variables

var (
	// ErrInvalidYear is returned when a BS year is outside MinBSYear..MaxBSYear.
	ErrInvalidYear = errors.New("bs: invalid year")

	// ErrInvalidMonth is returned when a BS month is not in the range 1..12.
	ErrInvalidMonth = errors.New("bs: invalid month")

	// ErrInvalidDay is returned when a BS day is not a valid day of the given
	// month (either out of the generic 1..32 bound, or greater than the
	// actual number of days in that month/year).
	ErrInvalidDay = errors.New("bs: invalid day")

	// ErrOutOfRange is returned when an AD date falls outside the Gregorian
	// range corresponding to MinBSYear..MaxBSYear.
	ErrOutOfRange = errors.New("bs: date outside supported range")

	// ErrInvalidFormat is returned when a string passed to Parse is not
	// shaped like "YYYY-MM-DD".
	ErrInvalidFormat = errors.New("bs: invalid date format")
)

Sentinel errors returned by this package. Use errors.Is to check for them; wrapped errors include additional context via fmt.Errorf's %w verb.

Functions

func BSToAD

func BSToAD(d Date) (time.Time, error)

BSToAD converts a Bikram Sambat date to the corresponding Gregorian calendar date, returned as a time.Time at UTC midnight. It returns an error wrapping ErrInvalidYear, ErrInvalidMonth or ErrInvalidDay if d is not a real, supported Bikram Sambat date.

func DaysInMonth

func DaysInMonth(year, month int) (int, error)

DaysInMonth returns the number of days in the given Bikram Sambat month. It returns ErrInvalidYear or ErrInvalidMonth if year or month is out of range.

func DaysInYear

func DaysInYear(year int) (int, error)

DaysInYear returns the total number of days in the given Bikram Sambat year. It returns ErrInvalidYear if year is out of range.

func IsSupportedBSYear

func IsSupportedBSYear(year int) bool

IsSupportedBSYear reports whether year is within MinBSYear..MaxBSYear.

func IsValid

func IsValid(year, month, day int) bool

IsValid reports whether year, month and day form a real Bikram Sambat calendar date within the supported range (MinBSYear..MaxBSYear).

func MonthName

func MonthName(month int) (string, error)

MonthName returns the English name of the given 1-based Bikram Sambat month (1 is Baisakh, 12 is Chaitra).

Types

type Date

type Date struct {
	Year  int
	Month int
	Day   int
}

Date represents a Bikram Sambat calendar date. Month is 1-based, where 1 is Baisakh and 12 is Chaitra. A Date is not guaranteed to be valid unless it was constructed with NewDate or returned by this package.

func ADToBS

func ADToBS(t time.Time) (Date, error)

ADToBS converts a Gregorian calendar date to Bikram Sambat. Only the Year, Month and Day components of t are used; time-of-day and location are ignored. It returns an error wrapping ErrOutOfRange if t falls outside the Gregorian range corresponding to MinBSYear..MaxBSYear.

func NewDate

func NewDate(year, month, day int) (Date, error)

NewDate constructs a Date and validates it. It returns an error wrapping ErrInvalidYear, ErrInvalidMonth or ErrInvalidDay if the given components do not form a real Bikram Sambat calendar date in the supported range.

func Parse

func Parse(s string) (Date, error)

Parse parses a Bikram Sambat date in "YYYY-MM-DD" format (the same format Date.String produces). It returns an error wrapping ErrInvalidFormat if s is not shaped like a date, or ErrInvalidYear, ErrInvalidMonth or ErrInvalidDay if it's shaped correctly but not a real supported date.

func (Date) AddDays

func (d Date) AddDays(n int) (Date, error)

AddDays returns the date n calendar days after d (or before, if n is negative). It returns an error wrapping ErrInvalidYear, ErrInvalidMonth or ErrInvalidDay if d is not itself a valid date, or ErrOutOfRange if the result falls outside the supported range.

func (Date) After

func (d Date) After(other Date) bool

After reports whether d is chronologically after other. It compares fields directly and does not require either date to be valid.

func (Date) Before

func (d Date) Before(other Date) bool

Before reports whether d is chronologically before other. It compares fields directly and does not require either date to be valid.

func (Date) DayOfWeek

func (d Date) DayOfWeek() (time.Weekday, error)

DayOfWeek returns the day of the week d falls on, derived through its equivalent Gregorian date. It returns an error wrapping ErrInvalidYear, ErrInvalidMonth or ErrInvalidDay if d is not a valid date.

func (Date) Equal

func (d Date) Equal(other Date) bool

Equal reports whether d and other represent the same calendar date.

func (Date) MonthName

func (d Date) MonthName() (string, error)

MonthName returns the English name of d's month (e.g. "Baisakh").

func (Date) String

func (d Date) String() string

String returns d formatted as "YYYY-MM-DD".

func (Date) Valid

func (d Date) Valid() bool

Valid reports whether d is a real Bikram Sambat calendar date in the supported range.