feat(json): wrap streaming Encoder/Decoder + Number/Delim/Valid + iface aliases

Phase 2 v0.10.4 gap-fill — the biggest genuine gap in the sweep: json.go
buffered Marshal/Unmarshal only, but consumers reach for the streaming
codec 860+ times (json.NewEncoder 654, json.NewDecoder 207) with no core
equivalent at all:

- JSONNewEncoder/JSONNewDecoder + JSONEncoder/JSONDecoder type aliases
- JSONNumber (13 uses), JSONDelim (5) — UseNumber + token-walk support
- JSONValid (2) — well-formedness gate without a throwaway Unmarshal
- JSONMarshaler/JSONUnmarshaler interface aliases for custom codecs

Additive only. Good/Bad/Ugly per symbol (incl. JSONL multi-value streams,
large-int precision via UseNumber), runnable godoc examples, ReportAllocs
benchmarks for the streaming hot paths + Valid.

Co-Authored-By: Virgil <virgil@lethean.io>

Author: Snider

json.go

@@ -27,6 +27,82 @@ import "encoding/json"
 //	}
 type RawMessage = json.RawMessage
 
+// JSONNumber is an alias for json.Number — a JSON numeric literal kept
+// as its original string so callers choose int vs float decoding (and
+// avoid float64 precision loss on large integers). Pairs with the
+// UseNumber() option on JSONDecoder.
+//
+//	var n core.JSONNumber = "9007199254740993"
+//	r := n.Int64()  // exact, no float rounding
+type JSONNumber = json.Number
+
+// JSONDelim is an alias for json.Delim — one of the four structural
+// tokens ( [ ] { } ) returned by JSONDecoder.Token during streaming
+// token walks.
+//
+//	tok, _ := dec.Token()
+//	if d, ok := tok.(core.JSONDelim); ok && d == '[' { /* array start */ }
+type JSONDelim = json.Delim
+
+// JSONEncoder is an alias for json.Encoder — the streaming writer that
+// emits JSON values to an io.Writer one at a time. Construct via
+// JSONNewEncoder.
+//
+//	var enc *core.JSONEncoder = core.JSONNewEncoder(w)
+type JSONEncoder = json.Encoder
+
+// JSONDecoder is an alias for json.Decoder — the streaming reader that
+// pulls JSON values from an io.Reader. Construct via JSONNewDecoder.
+//
+//	var dec *core.JSONDecoder = core.JSONNewDecoder(r)
+type JSONDecoder = json.Decoder
+
+// JSONMarshaler is an alias for json.Marshaler — the interface a type
+// implements to control its own JSON encoding.
+//
+//	func (id AgentID) MarshalJSON() ([]byte, error) { ... }
+//	var _ core.JSONMarshaler = AgentID{}
+type JSONMarshaler = json.Marshaler
+
+// JSONUnmarshaler is an alias for json.Unmarshaler — the interface a
+// type implements to control its own JSON decoding.
+//
+//	func (id *AgentID) UnmarshalJSON(b []byte) error { ... }
+//	var _ core.JSONUnmarshaler = (*AgentID)(nil)
+type JSONUnmarshaler = json.Unmarshaler
+
+// JSONNewEncoder returns a streaming JSON encoder writing to w. Prefer
+// it over JSONMarshal when emitting many values to a stream (HTTP
+// response, JSONL file) — it writes incrementally without buffering
+// every value into one []byte.
+//
+//	enc := core.JSONNewEncoder(core.Stdout())
+//	for _, row := range rows { enc.Encode(row) }  // one JSON value per line
+func JSONNewEncoder(w Writer) *JSONEncoder {
+	return json.NewEncoder(w)
+}
+
+// JSONNewDecoder returns a streaming JSON decoder reading from r. Prefer
+// it over JSONUnmarshal when consuming a stream of values or a body of
+// unknown length — it decodes one value at a time and can switch to
+// JSONNumber mode via dec.UseNumber().
+//
+//	dec := core.JSONNewDecoder(resp.Body)
+//	var msg Message
+//	for dec.More() { if err := dec.Decode(&msg); err != nil { break } }
+func JSONNewDecoder(r Reader) *JSONDecoder {
+	return json.NewDecoder(r)
+}
+
+// JSONValid reports whether data is a well-formed JSON encoding. Use it
+// to gate a payload before storing or forwarding it without paying a
+// full Unmarshal into a throwaway target.
+//
+//	if !core.JSONValid(body) { return core.NewError("malformed JSON body") }
+func JSONValid(data []byte) bool {
+	return json.Valid(data)
+}
+
 // JSONMarshal serialises a value to JSON bytes.
 //
 //	r := core.JSONMarshal(myStruct)

json_bench_test.go

@@ -213,3 +213,29 @@ func BenchmarkJSONUnmarshal_IntoRawMessage(b *B) {
 		_ = JSONUnmarshal(jsonMedium, &v)
 	}
 }
+
+// --- Streaming Encoder / Decoder / Valid ---
+
+func BenchmarkJSONNewEncoder_Medium(b *B) {
+	bld := NewBuilder()
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		bld.Reset()
+		_ = JSONNewEncoder(bld).Encode(fixtureMedium)
+	}
+}
+
+func BenchmarkJSONNewDecoder_Medium(b *B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		var v benchJSONMedium
+		_ = JSONNewDecoder(NewReader(jsonMediumStr)).Decode(&v)
+	}
+}
+
+func BenchmarkJSONValid_Medium(b *B) {
+	b.ReportAllocs()
+	for i := 0; i < b.N; i++ {
+		_ = JSONValid(jsonMedium)
+	}
+}

json_example_test.go

@@ -70,3 +70,39 @@ func ExampleRawMessage() {
 	// ping
 	// {"port":8080}
 }
+
+// ExampleJSONNewEncoder streams two values straight to stdout as JSONL
+// — one JSON object per line — without buffering the whole batch. Encode
+// writes the trailing newline itself.
+func ExampleJSONNewEncoder() {
+	type row struct {
+		Name string `json:"name"`
+	}
+	enc := JSONNewEncoder(Stdout())
+	enc.Encode(row{Name: "a"})
+	enc.Encode(row{Name: "b"})
+	// Output:
+	// {"name":"a"}
+	// {"name":"b"}
+}
+
+// ExampleJSONNewDecoder pulls a single value from a reader, the
+// streaming counterpart to JSONUnmarshal.
+func ExampleJSONNewDecoder() {
+	type cfg struct {
+		Port int `json:"port"`
+	}
+	var c cfg
+	JSONNewDecoder(NewReader(`{"port":8080}`)).Decode(&c)
+	Println(c.Port)
+	// Output: 8080
+}
+
+// ExampleJSONValid gates a payload without decoding it.
+func ExampleJSONValid() {
+	Println(JSONValid([]byte(`{"ok":true}`)))
+	Println(JSONValid([]byte(`{"ok":`)))
+	// Output:
+	// true
+	// false
+}

json_test.go

@@ -164,3 +164,123 @@ func TestJson_RawMessage_Ugly(t *T) {
 	AssertTrue(t, r.OK)
 	AssertEqual(t, `{"a":1}`, string(r.Value.([]byte)))
 }
+
+func TestJson_JSONNewEncoder_Good(t *T) {
+	b := NewBuilder()
+	err := JSONNewEncoder(b).Encode(testJSON{Name: "stream", Port: 80})
+
+	AssertNoError(t, err)
+	AssertContains(t, b.String(), `"name":"stream"`)
+}
+
+func TestJson_JSONNewEncoder_Bad(t *T) {
+	b := NewBuilder()
+	err := JSONNewEncoder(b).Encode(make(chan int))
+
+	AssertError(t, err)
+}
+
+func TestJson_JSONNewEncoder_Ugly(t *T) {
+	// Encode appends a trailing newline and can be called repeatedly to
+	// stream multiple values (JSONL).
+	b := NewBuilder()
+	enc := JSONNewEncoder(b)
+	AssertNoError(t, enc.Encode(testJSON{Name: "a", Port: 1}))
+	AssertNoError(t, enc.Encode(testJSON{Name: "b", Port: 2}))
+	AssertEqual(t, 2, Count(b.String(), "\n"))
+}
+
+func TestJson_JSONNewDecoder_Good(t *T) {
+	var target testJSON
+	err := JSONNewDecoder(NewReader(`{"name":"stream","port":80}`)).Decode(&target)
+
+	AssertNoError(t, err)
+	AssertEqual(t, "stream", target.Name)
+	AssertEqual(t, 80, target.Port)
+}
+
+func TestJson_JSONNewDecoder_Bad(t *T) {
+	var target testJSON
+	err := JSONNewDecoder(NewReader(`not json`)).Decode(&target)
+
+	AssertError(t, err)
+}
+
+func TestJson_JSONNewDecoder_Ugly(t *T) {
+	// More()/Decode loop over a concatenated stream of two objects.
+	dec := JSONNewDecoder(NewReader(`{"name":"a","port":1}{"name":"b","port":2}`))
+	var names []string
+	for dec.More() {
+		var tj testJSON
+		AssertNoError(t, dec.Decode(&tj))
+		names = append(names, tj.Name)
+	}
+	AssertEqual(t, []string{"a", "b"}, names)
+}
+
+func TestJson_JSONNumber_Good(t *T) {
+	// UseNumber keeps the literal so a large int survives without float
+	// rounding.
+	dec := JSONNewDecoder(NewReader(`{"big":9007199254740993}`))
+	dec.UseNumber()
+	var m map[string]JSONNumber
+	AssertNoError(t, dec.Decode(&m))
+	v := m["big"].Int64
+	n, err := v()
+	AssertNoError(t, err)
+	AssertEqual(t, int64(9007199254740993), n)
+}
+
+func TestJson_JSONNumber_Bad(t *T) {
+	var n JSONNumber = "not-a-number"
+	_, err := n.Int64()
+	AssertError(t, err)
+}
+
+func TestJson_JSONNumber_Ugly(t *T) {
+	var n JSONNumber = "3.14"
+	AssertEqual(t, "3.14", n.String())
+}
+
+func TestJson_JSONDelim_Good(t *T) {
+	dec := JSONNewDecoder(NewReader(`["x"]`))
+	tok, err := dec.Token()
+	AssertNoError(t, err)
+	d, ok := tok.(JSONDelim)
+	AssertTrue(t, ok)
+	AssertEqual(t, "[", d.String())
+}
+
+func TestJson_JSONDelim_Bad(t *T) {
+	// A string token is not a JSONDelim.
+	dec := JSONNewDecoder(NewReader(`"plain"`))
+	tok, err := dec.Token()
+	AssertNoError(t, err)
+	_, ok := tok.(JSONDelim)
+	AssertFalse(t, ok)
+}
+
+func TestJson_JSONDelim_Ugly(t *T) {
+	AssertEqual(t, "}", JSONDelim('}').String())
+}
+
+func TestJson_JSONValid_Good(t *T) {
+	AssertTrue(t, JSONValid([]byte(`{"ok":true}`)))
+}
+
+func TestJson_JSONValid_Bad(t *T) {
+	AssertFalse(t, JSONValid([]byte(`{"ok":`)))
+}
+
+func TestJson_JSONValid_Ugly(t *T) {
+	// Empty input is not valid JSON.
+	AssertFalse(t, JSONValid(nil))
+}
+
+func TestJson_JSONUnmarshaler_Good(t *T) {
+	// The interface alias is satisfied by *testJSON's pointer receiver
+	// chain via json's default decoding path (structural smoke).
+	var _ JSONUnmarshaler = (*RawMessage)(nil)
+	var _ JSONMarshaler = RawMessage(nil)
+	AssertTrue(t, true)
+}