tstrading

README

tstrading

A Go package providing domain types and data models for trading. It focuses on economic calendar events, their impact levels, and time periods, with support for formatting, comparison, and NoSQL document‑ID generation.

Types

Event

Represents a single economic calendar event.

type Event struct {
    ID          int64       `json:"id"`
    Name        string      `json:"name"`
    Description string      `json:"description"`
    Time        time.Time   `json:"time"`
    Country     string      `json:"country"`
    Currency    *string     `json:"currency"`
    Actual      *float64    `json:"actual"`
    Estimate    *float64    `json:"estimate"`
    Previous    *float64    `json:"previous"`
    Unit        *string     `json:"unit"`
    Precision   int         `json:"precision"`
    Change      *float64    `json:"change"`
    ChangePct   *float64    `json:"change_pct"`
    Surprise    *float64    `json:"surprise"`
    SurprisePct *float64    `json:"surprise_pct"`
    Impact      ImpactLevel `json:"impact"`
    Source      string      `json:"source"`
}

Key methods:

• String() string – returns a formatted table string; handles nil receiver gracefully. Rows with nil values are omitted.
• NearEqual(other *Event) bool – compares two events for near‑equality (excluding the ID field). Float comparisons use a precision‑based tolerance (half of the smallest displayable unit). Pointer fields (Unit, Currency, float pointers) are compared nil‑safely.
• GenerateDocID() (string, error) – produces a deterministic, URL‑safe document ID from Time, Country, and Name using SHA‑256.

Period

A time span defined by From and To.

type Period struct {
    From time.Time
    To   time.Time
}

Constructor:

• NewPeriodForDate(date time.Time) *Period – creates a Period covering the full day in UTC (00:00:00 – 23:59:59.999999999).

ImpactLevel

An integer‑based enum representing the expected market impact of an economic event.

type ImpactLevel int

const (
    ImpactUnknown ImpactLevel = iota // default zero value – used when impact is not set or unrecognised
    ImpactLow                        // 1
    ImpactMedium                     // 2
    ImpactHigh                       // 3
)

ImpactLevel implements the fmt.Stringer interface:

• ImpactLow → "low"
• ImpactMedium → "medium"
• ImpactHigh → "high"
• ImpactUnknown (or any invalid value) → "unknown"

Dependencies

• tstable – table formatting used by Event.String()
• tserr – error and test helpers
• lpstats – float pointer comparison, formatting, and string pointer utilities

License

GNU Affero General Public License v3.0 (see the LICENSE file).

Documentation

Overview

Package tstrading provides domain types and data models for trading. It focuses on economic calendar events, their impact levels, and time periods, with support for formatting, comparison, and NoSQL document-ID generation.

Copyright (c) 2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.

Copyright (c) 2026 thorsphere. All Rights Reserved. Use is governed with GNU Affero General Public License v3.0 that can be found in the LICENSE file.

Index

• type Event
  • func (ev *Event) GenerateDocID() (string, error)
  • func (ev *Event) NearEqual(other *Event) bool
  • func (ev *Event) String() string
• type ImpactLevel
  • func (i ImpactLevel) String() string
• type Period
  • func NewPeriodForDate(date time.Time) *Period

Types

type Event

type Event struct {
	ID          int64       `json:"id"`           // Unique identifier for the event, e.g., a database primary key or a UUID. It is expected to be set by the database.
	Name        string      `json:"name"`         // Name of the economic event, e.g., "Non-Farm Payrolls", "GDP Growth Rate"
	Description string      `json:"description"`  // Description of the economic event, e.g., "GDP growth rate is the annual percentage change in gross domestic product (GDP)."
	Time        time.Time   `json:"time"`         // Date and time of the event in UTC, when the data is released or expected to be released
	Country     string      `json:"country"`      // ISO 3166-1 alpha-2 two-letter country code
	Currency    *string     `json:"currency"`     // Currency of the values, e.g., "USD", "EUR", "JPY". Pointer because it can be nil if the value is not yet released
	Actual      *float64    `json:"actual"`       // Pointer, because it can be nil if the value is not yet released
	Estimate    *float64    `json:"estimate"`     // Pointer, because it can be nil if the value is not yet released
	Previous    *float64    `json:"previous"`     // Pointer, because it can be nil if the value is not yet released
	Unit        *string     `json:"unit"`         // Unit of measurement for the values, e.g., "%", "K", "M", "B". Pointer because it can be nil if the value is not yet released
	Precision   int         `json:"precision"`    // Number of decimal places to round the values to, e.g., 2 for USD, 0 for JPY
	Change      *float64    `json:"change"`       // Pointer, because it can be nil if the value is not yet released
	ChangePct   *float64    `json:"change_pct"`   // Pointer, because it can be nil if the value is not yet released
	Surprise    *float64    `json:"surprise"`     // Pointer, because it can be nil if the value is not yet released
	SurprisePct *float64    `json:"surprise_pct"` // Pointer, because it can be nil if the value is not yet released
	Impact      ImpactLevel `json:"impact"`       // Impact level of the event
	Source      string      `json:"source"`       // Source of the data, e.g., "Official Government Website"
}

Event represents a single calendar event with its details. Thought: Implement a definition for country codes, currency codes, and units of measurement and use it here for better type safety and validation.

func (*Event) GenerateDocID

func (ev *Event) GenerateDocID() (string, error)

GenerateDocID creates a deterministic, safe, unique document ID for NoSQL databases (like Firestore) based on the event's Time, Country, and Name.

func (*Event) NearEqual

func (ev *Event) NearEqual(other *Event) bool

NearEqual compares two Event instances for near-equality, taking into account all fields including the pointer fields for Actual, Estimate, and Previous. It does not compare the ID field, as it is expected to be set by the database and may not be the same for two events that are otherwise identical. It returns true if all fields are equal, and false otherwise.

func (*Event) String

func (ev *Event) String() string

String returns a formatted string representation of the Event.

type ImpactLevel

type ImpactLevel int

ImpactLevel represents the expected market impact of an economic event.

const (
	ImpactUnknown ImpactLevel = iota // iota starts at 0, so ImpactUnknown = 0
	ImpactLow                        // ImpactLow = 1
	ImpactMedium                     // ImpactMedium = 2
	ImpactHigh                       // ImpactHigh = 3
)

Define constants for the different impact levels.

func (ImpactLevel) String

func (i ImpactLevel) String() string

String returns a string representation of the ImpactLevel.

type Period

type Period struct {
	From time.Time // Start date and time of the period
	To   time.Time // End date and time of the period
}

Period represents a time period with a start and end date.

func NewPeriodForDate

func NewPeriodForDate(date time.Time) *Period

NewPeriodForDate creates a Period that spans the entire given date (00:00:00 to 23:59:59) in UTC.