transform

Documentation

Overview

Package transform is the mechanical transform runtime. It is a pure, codec-agnostic unit: a closed set of four hardcoded verbs over the top-level fields of a JSON object, applied in listed order, strict. It imports only wireerror + encoding/json (never bundle/adapter — the server passes ops + bytes), so it has no transport or codec knowledge and a future GraphQL/gRPC adapter reuses it untouched.

Index

• func ApplyRequest(ops []Op, body []byte) ([]byte, *wireerror.Error)
• func ApplyResponse(ops []Op, body []byte) ([]byte, *wireerror.Error)
• type DefaultValue
  • func NewDefaultValue(v any) (DefaultValue, error)
  • func (d DefaultValue) JSON() any
• type Kind
• type Op
• type Path
  • func ParsePath(s string) (Path, error)
  • func (p Path) Equal(q Path) bool
  • func (p Path) HasPrefixByName(prefix Path) bool
  • func (p Path) String() string
• type Segment

Functions

func ApplyRequest

func ApplyRequest(ops []Op, body []byte) ([]byte, *wireerror.Error)

ApplyRequest runs request ops (external→internal); failures are 422.

func ApplyResponse

func ApplyResponse(ops []Op, body []byte) ([]byte, *wireerror.Error)

ApplyResponse runs response ops (internal→external); failures are 502.

Types

type DefaultValue

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

DefaultValue is the literal a `default` verb injects when the target field is absent. Construct it via NewDefaultValue, which admits only JSON scalars and preserves the original value losslessly (notably, it does not narrow integers to float64). Non-scalar defaults are rejected at construction (bundle load), so an illegal default is unrepresentable rather than a runtime surprise.

func NewDefaultValue

func NewDefaultValue(v any) (DefaultValue, error)

NewDefaultValue wraps a bundle-authored scalar (string, bool, null, or a number as decoded by the YAML loader). A map/slice/other non-scalar is rejected; the caller surfaces that as a load-time ValidationError.

func (DefaultValue) JSON

func (d DefaultValue) JSON() any

JSON returns the wrapped scalar for verbatim injection into the body.

type Kind

type Kind string

Kind is a mechanical transform verb. The set is closed and shared by the bundle loader and this interpreter as the single source of truth.

const (
	KindRename      Kind = "rename"
	KindDefault     Kind = "default"
	KindOptionalize Kind = "optionalize"
	KindCoerce      Kind = "coerce"
)

type Op

type Op struct {
	Kind     Kind         // the verb
	From     Path         // rename
	To       Path         // rename
	Field    Path         // default | optionalize | coerce
	Value    DefaultValue // default: the scalar to inject
	CoerceTo string       // coerce: string | number | bool
}

Op is one parsed, statically-validated transform stanza. Exactly one verb is represented by Kind; bundle.Load validates shape before constructing it, so the runtime only ever meets data-dependent failures.

type Path

type Path []Segment

Path is a parsed reference into a JSON value tree, used by every verb's addressing. A bare-name slice-1 path parses to a one-segment Path with Array=false; the parser rejects any other shape that lacks a Name leaf.

func ParsePath

func ParsePath(s string) (Path, error)

ParsePath parses a path string. Grammar:

path    = segment ( "." segment )*
segment = name | name "[]"
name    = one or more UTF-8 bytes excluding ".", "[", and "]"

The LAST segment must NOT be an array segment — paths must end on a Name leaf (otherwise no verb has a leaf to act on). Returns an error for any grammar violation; bundle.toOps surfaces these as ValidationError.

func (Path) Equal

func (p Path) Equal(q Path) bool

Equal reports whether p and q are the same path (both Name and Array equal at every segment).

func (Path) HasPrefixByName

func (p Path) HasPrefixByName(prefix Path) bool

HasPrefixByName reports whether p starts with prefix's segments compared by Name only (Array flag ignored). Used by optionalize's prefix coverage: "optionalize {data}" covers "data.x" AND "data[].y" — the "absent" thing's children are absent regardless of how the missing thing would have been read (object vs array).

func (Path) String

func (p Path) String() string

String returns the canonical text form of p (the inverse of ParsePath).

type Segment

type Segment struct {
	Name  string
	Array bool
}

Segment is one component of a Path. Name is the object key; when Array is true the value at Name must be a []any and the path iterates over its elements (subsequent segments apply to each element).