temporal

package
v2026.0.152 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 27, 2026 License: MPL-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package temporal provides exact typed nanosecond values and thin, validated effects over Go's real context and time primitives.

Index

Constants

View Source 
const (
	// NanosecondsPerMicrosecond is the exact microsecond magnitude.
	NanosecondsPerMicrosecond uint64 = 1_000
	// NanosecondsPerMillisecond is the exact millisecond magnitude.
	NanosecondsPerMillisecond uint64 = 1_000_000
	// NanosecondsPerSecond is the exact second magnitude.
	NanosecondsPerSecond uint64 = 1_000_000_000
	// NanosecondsPerMinute is the exact minute magnitude.
	NanosecondsPerMinute uint64 = 60 * NanosecondsPerSecond
	// NanosecondsPerHour is the exact hour magnitude.
	NanosecondsPerHour uint64 = 60 * NanosecondsPerMinute
	// NanosecondsPerDay is the exact 24-hour day magnitude.
	NanosecondsPerDay uint64 = 24 * NanosecondsPerHour
	// DurationMaximumNanoseconds is the largest bounded duration.
	DurationMaximumNanoseconds = int64(math.MaxInt64)
	// AggregateDurationMaximumDecimalDigits bounds an unsigned 128-bit decimal.
	AggregateDurationMaximumDecimalDigits = 39
	// InstantCanonicalJSONMaximumBytes bounds compact signed instant JSON.
	InstantCanonicalJSONMaximumBytes = 22
	// DurationCanonicalJSONMaximumBytes bounds compact duration JSON.
	DurationCanonicalJSONMaximumBytes = 21
	// AggregateDurationCanonicalJSONMaximumBytes bounds compact aggregate JSON.
	AggregateDurationCanonicalJSONMaximumBytes = 41
	// TemporalJSONDocumentSlackBytes bounds insignificant JSON whitespace.
	TemporalJSONDocumentSlackBytes = 256
	// InstantJSONMaximumBytes bounds accepted instant JSON.
	InstantJSONMaximumBytes = InstantCanonicalJSONMaximumBytes + TemporalJSONDocumentSlackBytes
	// DurationJSONMaximumBytes bounds accepted duration JSON.
	DurationJSONMaximumBytes = DurationCanonicalJSONMaximumBytes + TemporalJSONDocumentSlackBytes
	// AggregateDurationJSONMaximumBytes bounds accepted aggregate JSON.
	AggregateDurationJSONMaximumBytes = AggregateDurationCanonicalJSONMaximumBytes + TemporalJSONDocumentSlackBytes
)
View Source 
const (
	RFC3339MinimumTextBytes = 20
	RFC3339MaximumTextBytes = 35
)
View Source 
const (
	// NumericInstantCanonicalJSONMaximumBytes bounds one canonical numeric
	// instant: the sign plus the widest signed 64-bit decimal.
	NumericInstantCanonicalJSONMaximumBytes = 20
	// NumericDurationCanonicalJSONMaximumBytes bounds one canonical numeric
	// duration: the widest nonnegative signed 64-bit decimal.
	NumericDurationCanonicalJSONMaximumBytes = 19
)

Variables

This section is empty.

Functions

func Wait 

func Wait(request WaitRequest) error

Wait blocks on one real standard-library timer or the caller's context.

func WithDeadline 

func WithDeadline(request DeadlineRequest) (
	context.Context,
	context.CancelFunc,
	error,
)

WithDeadline delegates one validated deadline to context.WithDeadline.

func WithTimeout 

func WithTimeout(request TimeoutRequest) (
	context.Context,
	context.CancelFunc,
	error,
)

WithTimeout delegates one validated timeout to context.WithTimeout.

Types

type AggregateDuration 

type AggregateDuration struct {
	// contains filtered or unexported fields
}

AggregateDuration is an unsigned 128-bit nanosecond accumulator.

func AggregateDurationFromDuration 

func AggregateDurationFromDuration(d Duration) (AggregateDuration, error)

AggregateDurationFromDuration widens d without loss. Duration owns the nonnegative rule, so this reports that rule's failure rather than mapping a negative duration to zero. Silently returning the zero aggregate would turn a package-internal Duration{nanoseconds: negative} into lost time at the one boundary that is supposed to preserve it exactly.

func AggregateDurationFromNanoseconds 

func AggregateDurationFromNanoseconds(nanoseconds uint64) AggregateDuration

AggregateDurationFromNanoseconds constructs an unsigned nanosecond total.

func ParseAggregateDuration 

func ParseAggregateDuration(decimal string) (AggregateDuration, error)

ParseAggregateDuration accepts canonical unsigned base-10 nanoseconds.

func (AggregateDuration) Add 

func (a AggregateDuration) Add(other AggregateDuration) (AggregateDuration, error)

Add returns an exact aggregate sum.

func (AggregateDuration) AddDuration 

func (a AggregateDuration) AddDuration(duration Duration) (AggregateDuration, error)

AddDuration adds a bounded duration.

func (AggregateDuration) Compare 

func (a AggregateDuration) Compare(other AggregateDuration) core.Comparison

Compare orders two aggregate durations.

func (AggregateDuration) Decimal 

func (a AggregateDuration) Decimal() string

Decimal returns canonical unsigned base-10 nanoseconds.

func (AggregateDuration) Duration 

func (a AggregateDuration) Duration() (Duration, error)

Duration narrows a to a bounded duration when possible.

func (AggregateDuration) IsZero 

func (a AggregateDuration) IsZero() bool

IsZero reports whether no nanoseconds have accumulated.

func (AggregateDuration) MarshalJSON 

func (a AggregateDuration) MarshalJSON() ([]byte, error)

MarshalJSON emits canonical decimal nanoseconds as a JSON string.

func (AggregateDuration) Multiply 

func (a AggregateDuration) Multiply(multiplier uint64) (AggregateDuration, error)

Multiply scales a by multiplier.

func (*AggregateDuration) UnmarshalJSON 

func (a *AggregateDuration) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts canonical decimal nanoseconds without mutation on error.

func (AggregateDuration) Validate 

func (AggregateDuration) Validate() error

Validate accepts every bit pattern in the unsigned 128-bit domain.

type DeadlineRequest 

type DeadlineRequest struct {
	Parent   context.Context
	Deadline Instant
}

DeadlineRequest supplies one parent and exact wall deadline.

func (DeadlineRequest) Validate 

func (r DeadlineRequest) Validate() error

Validate checks the deadline ingress while admitting standard terminal parents, which context.WithDeadline accepts.

type Duration 

type Duration struct {
	// contains filtered or unexported fields
}

Duration is nonnegative elapsed time bounded by signed 64-bit nanoseconds.

func DurationFromDays 

func DurationFromDays(value uint64) (Duration, error)

DurationFromDays constructs exact 24-hour days.

func DurationFromHours 

func DurationFromHours(value uint64) (Duration, error)

DurationFromHours constructs exact hours.

func DurationFromMicroseconds 

func DurationFromMicroseconds(value uint64) (Duration, error)

DurationFromMicroseconds constructs exact microseconds.

func DurationFromMilliseconds 

func DurationFromMilliseconds(value uint64) (Duration, error)

DurationFromMilliseconds constructs exact milliseconds.

func DurationFromMinutes 

func DurationFromMinutes(value uint64) (Duration, error)

DurationFromMinutes constructs exact minutes.

func DurationFromNanoseconds 

func DurationFromNanoseconds(nanoseconds int64) (Duration, error)

DurationFromNanoseconds constructs exact nonnegative nanoseconds.

func DurationFromSeconds 

func DurationFromSeconds(value uint64) (Duration, error)

DurationFromSeconds constructs exact seconds.

func NewDuration 

func NewDuration(value time.Duration) (Duration, error)

NewDuration constructs a bounded duration from a standard-library duration.

func ParseDuration 

func ParseDuration(value string) (Duration, error)

ParseDuration raises Go's documented duration syntax into a validated, nonnegative compiler-owned duration.

func (Duration) Add 

func (d Duration) Add(other Duration) (Duration, error)

Add returns the exact sum.

func (Duration) Aggregate 

func (d Duration) Aggregate() (AggregateDuration, error)

Aggregate widens d without loss.

func (Duration) Compare 

func (d Duration) Compare(other Duration) (core.Comparison, error)

Compare orders two durations.

func (Duration) IsZero 

func (d Duration) IsZero() bool

IsZero reports whether no time elapsed.

func (Duration) MarshalJSON 

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON emits exact nanoseconds as a canonical JSON string.

func (Duration) Multiply 

func (d Duration) Multiply(multiplier uint64) (Duration, error)

Multiply scales d by multiplier.

func (Duration) Nanoseconds 

func (d Duration) Nanoseconds() int64

Nanoseconds returns exact elapsed nanoseconds.

func (Duration) Stdlib 

func (d Duration) Stdlib() (time.Duration, error)

Stdlib projects d to time.Duration.

func (Duration) Subtract 

func (d Duration) Subtract(other Duration) (Duration, error)

Subtract returns the exact nonnegative difference.

func (*Duration) UnmarshalJSON 

func (d *Duration) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts canonical nonnegative nanoseconds without mutation on error.

func (Duration) Validate 

func (d Duration) Validate() error

Validate rejects negative durations.

type Instant 

type Instant struct {
	// contains filtered or unexported fields
}

Instant is a set signed Unix instant with nanosecond precision.

func InstantFromNanoseconds 

func InstantFromNanoseconds(nanoseconds int64) Instant

InstantFromNanoseconds constructs an exact signed Unix instant.

func NewInstant 

func NewInstant(value time.Time) (Instant, error)

NewInstant projects a time.Time to exact Unix nanoseconds.

func ParseRFC3339 added in v2026.0.133 

func ParseRFC3339(value string) (Instant, error)

ParseRFC3339 raises Go's documented RFC 3339 timestamp syntax into an exact signed-nanosecond Instant. The returned value is zero on every refusal.

func (Instant) Add 

func (i Instant) Add(duration Duration) (Instant, error)

Add returns i advanced by duration.

func (Instant) Compare 

func (i Instant) Compare(other Instant) (core.Comparison, error)

Compare orders two set instants.

func (Instant) IsSet 

func (i Instant) IsSet() bool

IsSet reports whether i crossed a constructor or decode boundary.

func (Instant) MarshalJSON 

func (i Instant) MarshalJSON() ([]byte, error)

MarshalJSON emits exact nanoseconds as a canonical JSON string.

func (Instant) Nanoseconds 

func (i Instant) Nanoseconds() (int64, error)

Nanoseconds returns exact signed Unix nanoseconds.

func (Instant) RFC3339 

func (i Instant) RFC3339() (string, error)

RFC3339 returns the canonical UTC second-precision representation used by human-facing protocols that require RFC 3339 text.

func (Instant) RFC3339Nano added in v2026.0.133 

func (i Instant) RFC3339Nano() (string, error)

RFC3339Nano returns the canonical UTC representation that preserves the Instant's exact nanosecond value.

func (Instant) Since 

func (i Instant) Since(earlier Instant) (Duration, error)

Since returns the nonnegative elapsed duration since earlier.

func (Instant) Subtract 

func (i Instant) Subtract(duration Duration) (Instant, error)

Subtract returns i moved backward by duration.

func (Instant) Time 

func (i Instant) Time() (time.Time, error)

Time projects i to a UTC time.Time without a monotonic reading.

func (Instant) Truncate 

func (i Instant) Truncate(precision Precision) (Instant, error)

Truncate returns i at the preceding boundary of precision.

func (*Instant) UnmarshalJSON 

func (i *Instant) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts canonical signed nanoseconds without mutation on error.

func (Instant) Validate 

func (i Instant) Validate() error

Validate rejects the unavoidable unset Go zero value.

type Interval 

type Interval struct {
	// contains filtered or unexported fields
}

Interval is a start, derived end, and exact nonnegative elapsed duration.

func IntervalFromBounds 

func IntervalFromBounds(bounds IntervalBounds) (Interval, error)

IntervalFromBounds constructs an interval from exact wall bounds.

func NewInterval 

func NewInterval(request IntervalRequest) (Interval, error)

NewInterval constructs an interval from observations, preserving monotonic elapsed time and deriving the end from start plus elapsed.

func (Interval) Bounds 

func (i Interval) Bounds() (IntervalBounds, error)

Bounds returns exact persisted wall bounds.

func (Interval) Elapsed 

func (i Interval) Elapsed() (Duration, error)

Elapsed returns the exact nonnegative duration.

func (Interval) End 

func (i Interval) End() (Instant, error)

End returns the exact derived end instant.

func (Interval) Start 

func (i Interval) Start() (Instant, error)

Start returns the exact start instant.

func (Interval) Validate 

func (i Interval) Validate() error

Validate checks the interval's exact arithmetic invariant.

type IntervalBounds 

type IntervalBounds struct {
	Start Instant
	End   Instant
}

IntervalBounds supplies exact persisted wall bounds.

func (IntervalBounds) Validate 

func (b IntervalBounds) Validate() error

Validate checks both exact bounds and their ordering.

type IntervalRequest 

type IntervalRequest struct {
	Start  Observation
	Finish Observation
}

IntervalRequest supplies two observations for one elapsed interval.

func (IntervalRequest) Validate 

func (r IntervalRequest) Validate() error

Validate checks both observation boundaries and their ordering.

type NumericDuration 

type NumericDuration struct {
	// contains filtered or unexported fields
}

NumericDuration is a Duration whose JSON projection is a bare number rather than a string. Its value semantics, including the nonnegative bound and the meaning of a real zero duration, are Duration's.

func NewNumericDuration 

func NewNumericDuration(duration Duration) (NumericDuration, error)

NewNumericDuration admits one validated duration for numeric projection.

func (NumericDuration) Duration 

func (n NumericDuration) Duration() Duration

Duration returns the projected value for arithmetic and ordering. Unlike NumericInstant.Instant it cannot fail: the Go zero value of NumericDuration is an exact zero duration, which Duration admits.

func (NumericDuration) IsZero 

func (n NumericDuration) IsZero() bool

IsZero reports a real zero duration, which is a valid observation.

func (NumericDuration) MarshalJSON 

func (n NumericDuration) MarshalJSON() ([]byte, error)

MarshalJSON emits exact nonnegative nanoseconds as a canonical JSON number.

func (*NumericDuration) UnmarshalJSON 

func (n *NumericDuration) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts one canonical JSON number and leaves the receiver untouched on every rejection.

func (NumericDuration) Validate 

func (n NumericDuration) Validate() error

Validate rejects a negative duration, matching Duration.

type NumericInstant 

type NumericInstant struct {
	// contains filtered or unexported fields
}

NumericInstant is an Instant whose JSON projection is a bare number rather than a string.

Instant and Duration marshal exact nanoseconds as a JSON string, which keeps the value readable in protocols that route large integers through a double-precision float. A wire that has always carried those nanoseconds as a JSON integer cannot adopt the string form without rewriting bytes a signature already covers, so the numeric projection is a compiler-owned Primitive contract rather than a wrapper each consumer rewrites.

The value semantics are Instant's. Only the projection differs, so a NumericInstant is placed directly in a wire struct with a json tag.

NumericInstant owns encoding, not range policy. It admits the complete signed Unix-nanosecond domain, including pre-epoch instants. A consumer whose wire is post-epoch enforces that boundary in the type that owns the fact.

func NewNumericInstant 

func NewNumericInstant(instant Instant) (NumericInstant, error)

NewNumericInstant admits one validated instant for numeric projection.

func (NumericInstant) Instant 

func (n NumericInstant) Instant() (Instant, error)

Instant returns the projected value for arithmetic, ordering, and truncation. It returns an error rather than an unset Instant because the Go zero value of NumericInstant carries no instant at all.

func (NumericInstant) IsSet 

func (n NumericInstant) IsSet() bool

IsSet reports whether n crossed a constructor or decode boundary.

func (NumericInstant) MarshalJSON 

func (n NumericInstant) MarshalJSON() ([]byte, error)

MarshalJSON emits exact signed nanoseconds as a canonical JSON number.

func (*NumericInstant) UnmarshalJSON 

func (n *NumericInstant) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts one canonical JSON number and leaves the receiver untouched on every rejection.

func (NumericInstant) Validate 

func (n NumericInstant) Validate() error

Validate rejects the unset zero value, matching Instant.

type Observation 

type Observation struct {
	// contains filtered or unexported fields
}

Observation preserves one real time.Time, including its monotonic reading, and one exact wall projection. Observe and NewObservation derive both from the same standard-library value. WithWall can replace only the projection so callers can model a real wall correction without replacing Go's elapsed-time substrate.

func NewObservation 

func NewObservation(value time.Time) (Observation, error)

NewObservation constructs an observation from a caller-supplied time.Time.

func Observe 

func Observe() (Observation, error)

Observe captures the real standard-library clock once.

func (Observation) Instant 

func (o Observation) Instant() (Instant, error)

Instant projects the observation's wall reading to exact Unix nanoseconds.

func (Observation) Since 

func (o Observation) Since(earlier Observation) (Duration, error)

Since returns elapsed time using time.Time's monotonic reading when both observations carry one. It rejects time.Sub saturation.

func (Observation) Validate 

func (o Observation) Validate() error

Validate rejects observations whose wall instant is not representable.

func (Observation) WithWall 

func (o Observation) WithWall(wall Instant) (Observation, error)

WithWall returns the same real observation with a replacement wall projection. Its elapsed-time carrier is unchanged, so Since continues to use Go's monotonic reading when the original observations carry one.

type Precision 

type Precision uint8

Precision is the closed set of exact instant truncation boundaries. 

const (
	// PrecisionUnknown is the invalid zero precision.
	PrecisionUnknown Precision = iota
	// PrecisionNanosecond preserves every nanosecond.
	PrecisionNanosecond
	// PrecisionMicrosecond truncates to a microsecond boundary.
	PrecisionMicrosecond
	// PrecisionMillisecond truncates to a millisecond boundary.
	PrecisionMillisecond
	// PrecisionSecond truncates to a second boundary.
	PrecisionSecond
)

func (Precision) IsValid 

func (p Precision) IsValid() bool

IsValid reports whether p belongs to the closed precision domain.

func (Precision) OffWireEnum 

func (Precision) OffWireEnum()

OffWireEnum declares Precision as an off-wire enum. The declaration binds Precision to core.OffWireEnum below, so the marker is compiler-checked rather than a bare method name matched by convention.

func (Precision) String 

func (p Precision) String() string

String returns a diagnostic projection of p.

func (Precision) Validate 

func (p Precision) Validate() error

Validate rejects values outside the closed precision domain.

type Ticker 

type Ticker struct {
	// contains filtered or unexported fields
}

Ticker is one caller-owned standard-library ticker capability. Its channel remains the Go time data plane while construction and ownership stay typed.

func OpenTicker 

func OpenTicker(request TickerRequest) (*Ticker, error)

OpenTicker returns a caller-owned real standard-library ticker capability.

func (*Ticker) Stop 

func (t *Ticker) Stop()

Stop releases the underlying standard-library ticker resource.

func (*Ticker) Ticks 

func (t *Ticker) Ticks() <-chan time.Time

Ticks returns the real standard-library tick channel.

func (*Ticker) Validate 

func (t *Ticker) Validate() error

Validate rejects an unset ticker capability.

type TickerRequest 

type TickerRequest struct {
	Interval Duration
}

TickerRequest supplies one positive ticker interval.

func (TickerRequest) Validate 

func (r TickerRequest) Validate() error

Validate rejects zero because time.NewTicker requires a positive interval.

type TimeoutRequest 

type TimeoutRequest struct {
	Parent   context.Context
	Duration Duration
}

TimeoutRequest supplies one parent and exact relative timeout.

func (TimeoutRequest) Validate 

func (r TimeoutRequest) Validate() error

Validate checks the timeout ingress while admitting standard terminal parents, which context.WithTimeout accepts.

type WaitRequest 

type WaitRequest struct {
	Context  context.Context
	Duration Duration
}

WaitRequest supplies one context-owned wait.

func (WaitRequest) Validate 

func (r WaitRequest) Validate() error

Validate requires a currently usable context and valid duration.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.