datasource

type Event ¶

type Event struct {
	Line string
	Err  error
}

Event is a single update from a streaming source. v1 events carry a line (any printable text) destined for a logview's buffer. A non-empty Err signals a terminal error and ends the stream.

type ParamCache ¶

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

ParamCache is a bounded LRU with per-entry TTL, keyed on a string hash of the params tuple. Concurrent-safe. Never caches errors — a failing fetch retries on the next call so a stale error doesn't lock a user out for the rest of the TTL. Uses single-flight so N concurrent callers with the same key issue one upstream load, not N.

Not a ds.Source itself: the parameter-varying call sites (join lookup fan-out, cursor-driven detail refetch) know their params tuple at call time and drive the cache directly. Wrapping the leaf source would require plumbing the params through Fetch, which the interface doesn't carry.

func NewParamCache(spec *cfg.CacheSpec) (*ParamCache, error)

func (c *ParamCache) FetchOrLoad(params map[string]string, load func() (any, error)) (any, error)

func (c *ParamCache) Len() int

type Source ¶

type Source interface {
	Fetch(ctx context.Context) (any, error)
	// Refresh is the polling interval, or 0 for fetch-once.
	Refresh() time.Duration
}

Source fetches data on demand. Implementations are responsible for any per-fetch context (HTTP request, subprocess invocation, file read) but should be safe to call concurrently — the caller usually serializes via tea.Cmd anyway.

func BuildLeaf(s *cfg.Source, children map[string]Source) (Source, error)

func NewMerge(d *cfg.Source, children map[string]Source) (Source, error)

type StreamingSource ¶

type StreamingSource interface {
	Source
	Subscribe(ctx context.Context) (<-chan Event, error)
}

StreamingSource pushes events over time instead of polling for full snapshots. v1 binds streams into logview only — each Event carries a line that's appended to the buffer as it arrives. (Streaming into list/table needs a keyed-update protocol that's deferred until a real use-case demands it.)

Lifecycle:

• Subscribe returns immediately with a channel of events; the source's own goroutine pushes events as data arrives. The given context cancels the stream — when ctx.Done() fires the source stops, closes its goroutine, and closes the events channel.
• The screen reads events one at a time via a Bubble Tea Cmd that re-issues itself (the standard "channel-to-tea.Msg" bridge — CLAUDE rule 12 in tuilib).
• When the channel is closed (graceful end of stream) or an Event with a non-nil Err is delivered, the screen treats the stream as finished. The user may force a reconnect via the refresh key.

type WindowPage ¶ added in v0.2.1

type WindowPage struct {
	// Items are the rows in this window, already sliced by the source's
	// `root:` the same way Fetch would.
	Items []any
	// Total is the number of rows matching the query across every page,
	// or -1 when the source can't say. -1 is not an error: the table
	// then treats the end of what has loaded as the end of the set, and
	// grows as more arrives.
	Total int
}

WindowPage is what one FetchWindow returned.

type WindowQuery ¶ added in v0.2.1

type WindowQuery struct {
	// Offset is the index of the first row wanted.
	Offset int
	// Limit is how many rows are wanted.
	Limit int

	// Search is the filter text the user typed with no column scope, all
	// bare terms joined by a space. Empty when the filter is empty or
	// every term was scoped.
	Search string
	// Filters maps a column *title* to the value the user scoped it to,
	// from "title:value" terms. Titles are resolved against the bound
	// table's columns before they get here, so an implementation can
	// look them up directly.
	Filters map[string]string

	// Sort is the title of the column to order by, "" when unsorted.
	Sort string
	// Desc reverses the order.
	Desc bool
}

WindowQuery is one request's worth of parameters: which rows, matching what, in what order. It carries no transport detail — how to reach the source is the implementation's business.

type WindowedSource ¶ added in v0.2.1

type WindowedSource interface {
	Source
	FetchWindow(ctx context.Context, q WindowQuery) (WindowPage, error)
}

WindowedSource fetches a slice of a larger remote set instead of the whole thing, and lets the server answer the filter and the sort.

It is the third optional extension of Source, alongside StreamingSource, and it earns that the same way: the lifecycle is genuinely different. Source.Fetch says "give me everything"; a windowed source is one where everything is more rows than anyone wants to hold, so the question becomes "give me rows 400-499 matching author=tolkien, newest first" — and the answer changes as the user scrolls and types.

Implementations still satisfy Source: Fetch returns the first page, so `wrangl` and any non-table consumer get something sensible rather than an error. Only the bound table drives FetchWindow.

The types here deliberately mirror tuilib's pkg/source.Query and pkg/table's window setter without importing either — the data layer never imports the TUI (see AGENTS.md). internal/screen owns the translation, which is where both halves are already in scope.