document.go

package jsonstat

import (
	"slices"
)

// Document is the top-level parsed value of a JSON-stat response. Depending
// on the source document's "class", exactly one of the fields below is
// populated:
//
//   - class "dataset":    [Document.Dataset] holds the single dataset. (Some
//     2.0 documents omit "class" entirely; [Decode] treats these as datasets
//     when they have the required dataset properties.)
//   - class "collection": [Document.Collection] holds the collection.
//   - class "dimension":  [Document.Dimension] holds the standalone dimension.
//
// The pre-2.0 bundle container is also accepted: [Document.Bundle] is a map
// of datasets keyed by id, and [Document.IsBundle] reports this case. Bundles
// are decoded for backward compatibility but never re-emitted by [Encode].
type Document struct {
	// Class is the JSON-stat response class declared on the document. It is
	// one of [ClassDataset], [ClassCollection], [ClassDimension], or
	// [ClassBundle] (the legacy pre-2.0 marker, synthesised by Decode).
	Class string

	// Version is the JSON-stat version declared on the document.
	Version string

	// Label is the document-level label, if any.
	Label string

	// Href is the document-level canonical URL, if any.
	Href string

	// Note is the document-level notes array.
	Note []string

	// Link is the document-level related-resource links.
	Link []Link

	// Extension collects provider-specific extra fields attached to the
	// document itself.
	Extension map[string]any

	// Dataset holds the parsed dataset when Class == [ClassDataset]. It is
	// nil otherwise.
	Dataset *Dataset

	// Collection holds the parsed collection when Class == [ClassCollection].
	Collection *Collection

	// Dimension holds the parsed standalone dimension when Class ==
	// [ClassDimension]. It is nil otherwise.
	Dimension *Dimension

	// Bundle holds the parsed datasets when the document is a pre-2.0 bundle
	// (a JSON object whose values are datasets, with no "class" property).
	// Keyed by dataset id. nil for 2.0 documents.
	Bundle map[string]*Dataset

	// IsBundle reports whether the document was decoded as a pre-2.0 bundle.
	IsBundle bool
}

// IsDataset reports whether the document is a single-dataset response.
func (d *Document) IsDataset() bool { return d != nil && d.Dataset != nil && !d.IsBundle }

// IsCollection reports whether the document is a collection response.
func (d *Document) IsCollection() bool { return d != nil && d.Collection != nil && !d.IsBundle }

// IsDimension reports whether the document is a standalone dimension response.
func (d *Document) IsDimension() bool { return d != nil && d.Dimension != nil && !d.IsBundle }

// Datasets returns every dataset in the document, regardless of class:
//
//   - dataset:   a one-element slice holding [Document.Dataset].
//   - collection: a slice holding each embedded dataset.
//   - bundle:    a slice holding each bundled dataset, in id-key order.
//   - otherwise: nil.
func (d *Document) Datasets() []*Dataset {
	if d == nil {
		return nil
	}
	switch {
	case d.IsBundle:
		keys := make([]string, 0, len(d.Bundle))
		for k := range d.Bundle {
			keys = append(keys, k)
		}
		slices.Sort(keys)
		out := make([]*Dataset, 0, len(keys))
		for _, k := range keys {
			out = append(out, d.Bundle[k])
		}
		return out
	case d.Dataset != nil:
		return []*Dataset{d.Dataset}
	case d.Collection != nil:
		return d.Collection.Datasets()
	}
	return nil
}

// SingleDataset is a convenience for the common case of a single-dataset
// document. It returns [Document.Dataset] when present, or
// [ErrDatasetNotFound] otherwise.
func (d *Document) SingleDataset() (*Dataset, error) {
	if d == nil || d.Dataset == nil || d.IsBundle {
		return nil, ErrDatasetNotFound
	}
	return d.Dataset, nil
}

// Item is one entry in a JSON-stat collection. JSON-stat's collection class
// uses a "link" array with rel "item" to enumerate its contents; each item
// may embed a full dataset, dimension, or another collection, or merely link
// to one via Href.
type Item struct {
	// Href is the URL of the item, when it is referenced rather than
	// embedded.
	Href string

	// Type is the MIME type of the item at Href.
	Type string

	// Label is the human-readable item title.
	Label string

	// Class is the embedded item's class (e.g. "dataset"), when the item is
	// embedded rather than only linked.
	Class string

	// ID is the optional item identifier inside the collection. Some
	// providers add an "id" extension to disambiguate items.
	ID string

	// Extension collects provider-specific extra fields attached to the
	// item's link entry.
	Extension map[string]any

	// EmbeddedDataset is non-nil when the item embeds a full dataset.
	EmbeddedDataset *Dataset

	// EmbeddedDimension is non-nil when the item embeds a standalone
	// dimension.
	EmbeddedDimension *Dimension
}

// IsEmbedded reports whether the item carries an embedded response rather
// than only a link.
func (i *Item) IsEmbedded() bool {
	return i != nil && (i.EmbeddedDataset != nil || i.EmbeddedDimension != nil)
}

// Collection is the in-memory representation of a JSON-stat collection
// response (class "collection"). A collection is an ordered list of
// [Item] values, each of which may embed or link to a dataset, dimension, or
// another collection.
type Collection struct {
	// Label is the collection's human-readable title.
	Label string

	// Href is the collection's canonical URL.
	Href string

	// Updated is the collection's last-updated timestamp in ISO 8601 format.
	Updated string

	// Source is the collection's source attribution text.
	Source string

	// Note is the collection-level notes.
	Note []string

	// Link holds the collection's links. Items appear here with rel "item".
	Link []Link

	// Extension collects provider-specific extra fields.
	Extension map[string]any

	// Items is the parsed item list, in declaration order.
	Items []Item
}

// ItemByIndex returns the i-th item, or [ErrItemNotFound] when out of range.
func (c *Collection) ItemByIndex(i int) (*Item, error) {
	if c == nil || i < 0 || i >= len(c.Items) {
		return nil, &ValueError{Op: "Collection.ItemByIndex", Flat: i, Err: ErrItemNotFound}
	}
	return &c.Items[i], nil
}

// ItemByID returns the first item whose [Item.ID] matches id, or
// [ErrItemNotFound] when absent. ID equality is exact-string.
func (c *Collection) ItemByID(id string) (*Item, error) {
	if c == nil {
		return nil, ErrItemNotFound
	}
	for i := range c.Items {
		if c.Items[i].ID == id {
			return &c.Items[i], nil
		}
	}
	return nil, &ValueError{Op: "Collection.ItemByID", Cat: id, Err: ErrItemNotFound}
}

// ItemsByClass returns the items whose embedded class matches the given
// JSON-stat class string (e.g. [ClassDataset]).
func (c *Collection) ItemsByClass(class string) []*Item {
	if c == nil {
		return nil
	}
	out := make([]*Item, 0)
	for i := range c.Items {
		if c.Items[i].Class == class {
			out = append(out, &c.Items[i])
		}
	}
	return out
}

// Datasets returns every embedded dataset in the collection, in declaration
// order. Items that only link (without embedding) are skipped.
func (c *Collection) Datasets() []*Dataset {
	if c == nil {
		return nil
	}
	out := make([]*Dataset, 0, len(c.Items))
	for i := range c.Items {
		if c.Items[i].EmbeddedDataset != nil {
			out = append(out, c.Items[i].EmbeddedDataset)
		}
	}
	return out
}