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"`
    Time     time.Time   `json:"time"`
    Country  string      `json:"country"`
    Actual   *float64    `json:"actual"`
    Estimate *float64    `json:"estimate"`
    Previous *float64    `json:"previous"`
    Unit     string      `json:"unit"`
    Impact   ImpactLevel `json:"impact"`
    Source   string      `json:"source"`
}

Key methods:

• String() string – returns a formatted table string; handles nil receiver gracefully.
• NearEqual(other *Event) bool – compares two events for near‑equality (excluding the ID field) using a configurable floating‑point tolerance.
• 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 event.

type ImpactLevel int

const (
    ImpactLow    ImpactLevel = iota
    ImpactMedium
    ImpactHigh
)

ImpactLevel implements the fmt.Stringer interface, returning "low", "medium", "high", or "unknown" for any invalid value.

Dependencies

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

License

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

Documentation

Overview

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"
	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
	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"
	Impact   ImpactLevel `json:"impact"`   // Impact level of the event
	Source   string      `json:"source"`   // Source of the data, e.g., "Bloomberg", "Reuters", "Official Government Website"
}

EconomicEvent represents a single calendar event with its details. Thought: Implement a separate package for country codes 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 (
	ImpactLow    ImpactLevel = iota // iota starts at 0, so ImpactLow = 0
	ImpactMedium                    // ImpactMedium = 1
	ImpactHigh                      // ImpactHigh = 2
)

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.