output

Documentation

Overview

Package output handles formatting and writing query results and errors.

Index

• func PrintJSON(data any, prune bool)
• func PrintYAML(w io.Writer, data any) error
• func Warn(format string, args ...any)
• func WriteError(w io.Writer, err error)
• type CSVWriter
  • func NewCSVWriter(w io.Writer, columns []string) *CSVWriter
  • func (c *CSVWriter) Flush() error
  • func (c *CSVWriter) WritePagination(_ *Pagination) error
  • func (c *CSVWriter) WriteRow(row map[string]any) error
• type CompactWriter
  • func NewCompactWriter(w io.Writer, columns []string) *CompactWriter
  • func (c *CompactWriter) Flush() error
  • func (c *CompactWriter) WritePagination(p *Pagination) error
  • func (c *CompactWriter) WriteRow(row map[string]any) error
• type Format
  • func ParseFormat(s string) (Format, error)
  • func ResolveFormat(flagFormat string) Format
• type JSONWriter
  • func NewJSONWriter(w io.Writer, columns []string) *JSONWriter
  • func (j *JSONWriter) Flush() error
  • func (j *JSONWriter) WritePagination(p *Pagination) error
  • func (j *JSONWriter) WriteRow(row map[string]any) error
• type NDJSONWriter
  • func NewNDJSONWriter(w io.Writer) *NDJSONWriter
  • func (n *NDJSONWriter) Flush() error
  • func (n *NDJSONWriter) WritePagination(p *Pagination) error
  • func (n *NDJSONWriter) WriteRow(row map[string]any) error
• type Pagination
• type ResultWriter
  • func NewWriter(w io.Writer, format Format, columns []string) ResultWriter
• type YAMLWriter
  • func NewYAMLWriter(w io.Writer, columns []string) *YAMLWriter
  • func (y *YAMLWriter) Flush() error
  • func (y *YAMLWriter) WritePagination(p *Pagination) error
  • func (y *YAMLWriter) WriteRow(row map[string]any) error

Functions

func PrintJSON

func PrintJSON(data any, prune bool)

PrintJSON writes a JSON object to stdout (for admin/schema output).

func PrintYAML

func PrintYAML(w io.Writer, data any) error

PrintYAML writes arbitrary data as YAML to the given writer.

func Warn

func Warn(format string, args ...any)

Warn writes a non-error advisory to stderr with a consistent "warning: " prefix and trailing newline. Used for cases where an operation succeeds but the user should know something happened (credentials stripped, fallback used, etc.). For errors, use WriteError, which produces structured JSON; Warn is plain text.

func WriteError

func WriteError(w io.Writer, err error)

WriteError writes an error to stderr as JSON.

Types

type CSVWriter

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

CSVWriter streams rows as CSV. Column order is fixed at construction.

func NewCSVWriter

func NewCSVWriter(w io.Writer, columns []string) *CSVWriter

NewCSVWriter creates a new CSV writer with the given column order.

func (*CSVWriter) Flush

func (c *CSVWriter) Flush() error

func (*CSVWriter) WritePagination

func (c *CSVWriter) WritePagination(_ *Pagination) error

WritePagination is a no-op for CSV — no metadata support.

func (*CSVWriter) WriteRow

func (c *CSVWriter) WriteRow(row map[string]any) error

type CompactWriter

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

CompactWriter writes query results as typed NDJSON messages:

{"type":"columns","values":["id","name"]}
{"type":"row","values":[1,"Alice"]}
{"type":"row","values":[2,"Bob"]}
{"type":"pagination","values":{"hasMore":true,"rowCount":2}}

Each line is self-describing and independently parseable. Saves tokens by not repeating column names in every row.

func NewCompactWriter

func NewCompactWriter(w io.Writer, columns []string) *CompactWriter

NewCompactWriter creates a compact result writer.

func (*CompactWriter) Flush

func (c *CompactWriter) Flush() error

func (*CompactWriter) WritePagination

func (c *CompactWriter) WritePagination(p *Pagination) error

func (*CompactWriter) WriteRow

func (c *CompactWriter) WriteRow(row map[string]any) error

type Format

type Format string

Format identifies an output format.

const (
	FormatNDJSON Format = "jsonl"
	FormatJSON   Format = "json"
	FormatYAML   Format = "yaml"
	FormatCSV    Format = "csv"
)

func ParseFormat

func ParseFormat(s string) (Format, error)

ParseFormat parses a format string, returning an error for unknown formats.

func ResolveFormat

func ResolveFormat(flagFormat string) Format

ResolveFormat resolves the output format from flag > config > default.

type JSONWriter

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

JSONWriter buffers all rows and writes a single JSON envelope on Flush.

func NewJSONWriter

func NewJSONWriter(w io.Writer, columns []string) *JSONWriter

NewJSONWriter creates a new JSON envelope writer. If columns is non-nil, it defines the column order; otherwise columns are extracted from the first row.

func (*JSONWriter) Flush

func (j *JSONWriter) Flush() error

func (*JSONWriter) WritePagination

func (j *JSONWriter) WritePagination(p *Pagination) error

func (*JSONWriter) WriteRow

func (j *JSONWriter) WriteRow(row map[string]any) error

type NDJSONWriter

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

NDJSONWriter writes query results as NDJSON (one JSON object per line).

func NewNDJSONWriter

func NewNDJSONWriter(w io.Writer) *NDJSONWriter

NewNDJSONWriter creates a new NDJSON result writer.

func (*NDJSONWriter) Flush

func (n *NDJSONWriter) Flush() error

func (*NDJSONWriter) WritePagination

func (n *NDJSONWriter) WritePagination(p *Pagination) error

func (*NDJSONWriter) WriteRow

func (n *NDJSONWriter) WriteRow(row map[string]any) error

type Pagination

type Pagination struct {
	HasMore  bool `json:"hasMore"`
	RowCount int  `json:"rowCount"`
}

Pagination holds pagination metadata for result sets.

type ResultWriter

type ResultWriter interface {
	WriteRow(row map[string]any) error
	WritePagination(p *Pagination) error
	Flush() error
}

ResultWriter writes query results in a streaming fashion.

func NewWriter

func NewWriter(w io.Writer, format Format, columns []string) ResultWriter

NewWriter creates a ResultWriter for the given format.

type YAMLWriter

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

YAMLWriter buffers all rows and writes YAML on Flush.

func NewYAMLWriter

func NewYAMLWriter(w io.Writer, columns []string) *YAMLWriter

NewYAMLWriter creates a new YAML writer. If columns is non-nil, it defines the column order; otherwise columns are extracted from the first row.

func (*YAMLWriter) Flush

func (y *YAMLWriter) Flush() error

func (*YAMLWriter) WritePagination

func (y *YAMLWriter) WritePagination(p *Pagination) error

func (*YAMLWriter) WriteRow

func (y *YAMLWriter) WriteRow(row map[string]any) error