Documentation
¶
Overview ¶
Package timerangepicker holds the value types and library code for the imzero2 time range picker (ADR-0016). The package is the umbrella for the picker's pure-Go layer: TimeRange (user-input expressions + tz), EvaluatedRange (resolved epoch-millisecond bounds for FFFI2 consumers), and the sub-packages evaluator (clickhouse-local driver), validator (in-process syntax check via boxer's dsl ANTLR parser), and presets (Grafana 7.5-derived quick-range registry).
The Phase 3 widget UI is not in this package — this layer is consumed by it.
Index ¶
- Constants
- Variables
- func IanaName(id uint16) (name string, err error)
- func LoadTzLocation(id uint16) (loc *time.Location, err error)
- func LookupTz(name string) (id uint16, err error)
- func PackRange(tz, from, to string) (packed string)
- func TzName(id uint16) (name string, ok bool)
- func UnpackRange(packed string) (tz, from, to string)
- type EvaluatedRange
- type Expression
- type TimeRange
Constants ¶
const ( // TzIDSystem is the reserved catalogue index for the host's // current local zone (resolves to time.Local at lookup time). // Stable across processes. TzIDSystem uint16 = 0 // TzIDUTC is the reserved catalogue index for UTC. Stable across // processes. Indices >= 2 are lazily allocated per-process by // LookupTz. TzIDUTC uint16 = 1 )
const PoolName = "timerangepicker"
PoolName is the chlocalbroker pool name the Phase-4 evaluator routes through (ch.local.exec.<PoolName>). Hosts that wire the picker declare a SubjectFilter against this exact subject in their AppI Manifest, then construct the evaluator with the same string. Lives here, in the widget's canonical package, so consumers don't drift on naming.
Variables ¶
var PackageProps = packageprops.Props{ WASMWASI: packageprops.WASMCompiles, WASMJS: packageprops.WASMCompiles, WASMFreestanding: packageprops.WASMCompiles, }
PackageProps records this package's curated properties (ADR-0080). Seeded by `boxer code analysis golang wasmsurvey props generate`; curate by hand. The same group's `props verify` reconciles it.
Functions ¶
func IanaName ¶
IanaName returns the IANA zone name for a TzID. System resolves to the runtime's time.Local zone name (e.g. "Europe/Berlin" on a host configured for CET) — this is the value the picker injects into ClickHouse SQL as the anchor_now timezone literal.
func LoadTzLocation ¶
LoadTzLocation returns the *time.Location for a TzID. System resolves to time.Local at call time so callers see the current host zone, even if the OS zone changed since process start.
func LookupTz ¶
LookupTz returns the stable per-process TzID for the given IANA tz name (e.g. "UTC", "Asia/Tokyo", "America/Los_Angeles"). The two reserved names "System" and "UTC" always resolve to TzIDSystem / TzIDUTC; any other name is validated via time.LoadLocation and interned on first sight. Returns a wrapped error when the name does not resolve to a known zone.
The catalogue can hold up to 2^16 - 1 distinct names. Process-local stability is enough for the picker's wire format because the TzID always travels alongside Go-side state that re-resolves the name on startup.
func PackRange ¶
PackRange packs (tz, from, to) into the canonical wire payload string used by the TimeRangePicker FFFI2 widget. tz is the IANA zone name the user selected from the in-widget dropdown — empty means "use whatever the picker was configured with via the Tz() builder." Inverse of UnpackRange.
Expressions containing the ASCII record separator (\x1e) are unsupported and may produce an incorrect unpack — \x1e has no meaning in ClickHouse SQL or IANA zone names, so this is a non-issue in practice.
func TzName ¶
TzName returns the IANA name interned under the given id. The returned ok is false when the id was never registered in this process. Reserved ids (0 "System", 1 "UTC") always resolve.
func UnpackRange ¶
UnpackRange splits the wire payload into (tz, from, to). On an empty payload (uninitialised binding pre-Apply) all three returns are empty. A 2-segment legacy payload (no tz prefix) is treated as (from, to) with empty tz so callers can interoperate with the Phase 3 wire shape. A payload with no delimiter at all returns the whole payload in `from` so a downstream evaluator surfaces a sensible error.
Types ¶
type EvaluatedRange ¶
EvaluatedRange is the resolved (concrete) form of a TimeRange after evaluation against an anchor instant. It is what FFFI2 consumers see on the wire (Phase 3 onwards).
func (EvaluatedRange) AsFromTime ¶
func (inst EvaluatedRange) AsFromTime() (t time.Time)
AsFromTime returns the from bound as time.Time in UTC.
func (EvaluatedRange) AsToTime ¶
func (inst EvaluatedRange) AsToTime() (t time.Time)
AsToTime returns the to bound as time.Time in UTC.
func (EvaluatedRange) Duration ¶
func (inst EvaluatedRange) Duration() (d time.Duration)
Duration returns ToEpochMS - FromEpochMS as a time.Duration. May be negative if the user set To earlier than From; the picker UI is expected to reject that, but the value type itself is permissive.
type Expression ¶
type Expression string
Expression is the source-of-truth string for a from or to bound. It must parse as a ClickHouse SQL expression that evaluates to a DateTime / DateTime64. The picker's evaluator injects a per-Apply `anchor_now` DateTime64(3, 'UTC') via a WITH clause; user expressions can reference it freely.
type TimeRange ¶
type TimeRange struct {
From Expression
To Expression
TzID uint16
}
TimeRange is the picker's user-input state — two ClickHouse SQL expressions plus the IANA timezone (interned index) in which to interpret them. TzID == 0 is reserved for "System" (time.Local); TzID == 1 is reserved for "UTC". Phase 4 lands the catalogue.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package evaluator runs ClickHouse SQL time-range expressions against a runtime-mediated clickhouse-local worker pool.
|
Package evaluator runs ClickHouse SQL time-range expressions against a runtime-mediated clickhouse-local worker pool. |
|
Package presets provides the time range picker's quick-range sidebar entries.
|
Package presets provides the time range picker's quick-range sidebar entries. |
|
Package validator wraps boxer's nanopass.Parse (ClickHouse Grammar1) to provide sub-millisecond in-process syntax validation for the time range picker's expression fields.
|
Package validator wraps boxer's nanopass.Parse (ClickHouse Grammar1) to provide sub-millisecond in-process syntax validation for the time range picker's expression fields. |