tinytime

TinyTime

A minimal, portable time utility for Go and TinyGo with WebAssembly support. Automatically uses JavaScript Date APIs in WASM environments to keep binaries small.

Quick Start

import "github.com/cdvelop/tinytime"

func main() {
    tp := tinytime.NewTimeProvider()

    // Get current Unix timestamp in nanoseconds
    nano := tp.UnixNano()
    println("Current time:", nano)

    // Format dates and times
    date := tp.FormatDate(nano)
    println("Date:", date) // "2024-01-15"

    timeStr := tp.FormatTime(int16(510)) // 8:30 in minutes
    println("Time:", timeStr) // "08:30"

    // Parse date and time strings
    parsedNano, err := tp.ParseDate("2024-01-15")
    if err != nil {
        panic(err)
    }
    println("Parsed Nano:", parsedNano)

    // Perform date calculations
    isToday := tp.IsToday(nano)
    println("Is Today?", isToday)
}

API Reference

NewTimeProvider() TimeProvider

Creates a time provider instance. Automatically selects the appropriate implementation:

• WASM: Uses JavaScript Date APIs (smaller binaries)
• Standard Go: Uses time package

Display Formatting

FormatDate(value any) string

Formats a value into a date string: "YYYY-MM-DD".

• int64: UnixNano timestamp.
• string: Valid date string (passthrough).

date := tp.FormatDate(1705306200000000000) // "2024-01-15"

FormatTime(value any) string

Formats a value into a time string.

• int64: UnixNano timestamp ("HH:MM:SS").
• int16: Minutes since midnight ("HH:MM").
• string: Valid time string (passthrough).

timeStr := tp.FormatTime(int16(510)) // "08:30"

FormatDateTime(value any) string

Formats a value into a date-time string: "YYYY-MM-DD HH:MM:SS".

• int64: UnixNano timestamp.
• string: Valid date-time string (passthrough).

dateTime := tp.FormatDateTime(1705307400000000000) // "2024-01-15 08:30:00"

FormatDateTimeShort(value any) string

Formats a value into a short date-time string: "YYYY-MM-DD HH:MM" (without seconds).

• int64: UnixNano timestamp.
• string: Valid short date-time string (passthrough).

dateTime := tp.FormatDateTimeShort(1705307400000000000) // "2024-01-15 08:30"

Parsing

ParseDate(dateStr string) (int64, error)

Parses a date string ("YYYY-MM-DD") into a UnixNano timestamp at midnight UTC.

nano, err := tp.ParseDate("2024-01-15")

ParseTime(timeStr string) (int16, error)

Parses a time string ("HH:MM" or "HH:MM:SS") into minutes since midnight.

minutes, err := tp.ParseTime("08:30") // 510

ParseDateTime(dateStr, timeStr string) (int64, error)

Combines date and time strings into a single UnixNano timestamp (UTC).

nano, err := tp.ParseDateTime("2024-01-15", "08:30")

Current Time

UnixNano() int64

Returns the current Unix timestamp in nanoseconds.

nano := tp.UnixNano()

Date Utilities

IsToday(nano int64) bool

Checks if the given UnixNano timestamp is today.

IsPast(nano int64) bool

Checks if the given UnixNano timestamp is in the past.

IsFuture(nano int64) bool

Checks if the given UnixNano timestamp is in the future.

DaysBetween(nano1, nano2 int64) int

Calculates the number of full days between two UnixNano timestamps.

Timers

AfterFunc(milliseconds int, f func()) Timer

Waits for the specified milliseconds then calls f. Returns a Timer that can be used to cancel the call.

Note: In WASM environments, the callback runs in the JavaScript event loop. Keep callbacks lightweight to avoid blocking the UI.

// Start a timer
timer := tp.AfterFunc(1000, func() {
    println("1 second passed!")
})

// Stop the timer before it fires
timer.Stop()

WebAssembly Usage

When compiled for WebAssembly (GOOS=js GOARCH=wasm), tinytime automatically uses JavaScript's native Date APIs instead of bundling Go's time package.

# Build for WebAssembly
GOOS=js GOARCH=wasm go build -o app.wasm .

# Run tests in browser
go test -tags=wasm

Testing

Run standard tests:

go test ./...

Run WebAssembly tests:

GOOS=js GOARCH=wasm go test ./...

For detailed browser testing instructions, see BROWSER_TEST.md.

Dependencies

• github.com/cdvelop/tinystring

Contributing

License

MIT.