proposal: encoding/json/v2: exported read-write aggregate Options type

[neild]

The current JSONv2 design contains three packages (encoding/json, encoding/jsontext, and encoding/json/v2), all of which define an Options type for customizing marshal and unmarshal behavior. These three Options types are each an alias to the same type, encoding/json/internal/jsonopts.Options. For example:
https://pkg.go.dev/encoding/json/v2#Options

An Options is either a single option, such as "enable deterministic marshalling" or an aggregate of multiple options created by json.JoinOptions. Options are passed as variadic parameters, and options defined in one package may be used in another.

I do not propose substantial changes to any of the above.

---

The json.GetOption function allows retrieving the value of an option from an Options. This function takes two parameters: An Options and a setter function. It returns the value of the option that is set by the setter. For example:

opts := json.JoinOptions(
	json.Deterministic(true),
	json.StringifyNumbers(true),
)

// Note that json.Deterministic is a function!
deterministic := json.GetOption(opts, json.Deterministic) // true

I believe that json.GetOption is very clever, but also confusing and unidiomatic. Its implementation is subtle. It is not a conventional design.

---

JSONv2 includes an internal type which represents a collection of options: encoding/json/internal/jsonopts.Struct. This type can represent all options defined by packages under encoding/json/…, offers efficient read and write access, and is used by most of the JSON internals to pass options around the call stack.

The fact that jsonopts.Struct exists is an indication that there is a need for a simple, compact, mutable, mostly-allocation-free representation of a collection of options. This is the type that the JSON internals use by preference.

---

I propose replacing json.GetOption with an exported version of jsonopts.Struct.

Specifically:

We rename Options to Option in all JSONv2 packages. A json.Option is now a single option.

We add an encoding/json/jsonopts package with a jsonopts.Options type representing a collection of options:

package jsonopts

// Option is identical in use to the current Options,
// although the definition may be different.
type Option interface {
	JSONOptions(internal.NotForPublicUse)
}

// Options is a collection of options.
//
// Options implements the Option interface,
// and may be passed to functions that take ...Option parameters.
//
// Unlike the current internal/jsonopts.Struct,
// Options is an opaque type with accessors for each option.
type Options struct{}

// Join returns an Options describing the provided options.
func Join(options ...Option) Options

// Join updates opts with the provided options.
func (opts *Options) Join(options ...Option)

// Options has accessor methods for all options.

func (opts Options) AllowDuplicateNames() bool
func (opts Options) SetAllowDuplicateNames(v bool)

func (opts Options) AllowInvalidUTF8() bool
func (opts Options) SetAllowInvalidUTF8(v bool)

// etc., for all options.

That's the proposal. We retain all the convenience of the existing variadic options, but offer a conventional options value type as well.

Converting the above GetOption example to the new API:

var opts jsonopts.Options
opts.SetDeterministic(true)
opts.SetStringifyNumbers(true)

deterministic := opts.Deterministic() // true

Or:

opts := jsonopts.Join(
	json.Deterministic(true),
	json.StringifyNumbers(true),
)

deterministic := opts.Deterministic() // true

[gopherbot]

Change https://go.dev/cl/736840 mentions this issue: encoding/json: experimental options rewrite

[mateusz834]

Wouldn't it be possible to make:

type Option interface {
	JSONOptions(internal.NotForPublicUse)
}

into

package jsonopts

type Option interface {
	jsonOptions(notForPublicUse)
}

or

package jsonopts

type Option interface {
	internalopts.Option
}

package internalopts

type Option interface {
	jsonOptions(notForPublicUse)
}

Where internalopts exposes all the stuff that other packages need from this?

[mateusz834]

@neild FYI #77703 (comment) CL 747440, uses a tiny hack with struct embedding, but can be done not that hard.

[neild]

@mateusz834 I'm sorry, but I'm not certain what you're suggesting.

This proposal is about adding a new encoding/json/jsonopts package, and a concrete jsonopts.Options type.

[mateusz834]

I wonder whether the method here:

type Option interface {
-	JSONOptions(internal.NotForPublicUse)
_	jsonOptions(internal.NotForPublicUse)
}

can be made unexported. And i think it is possible (see the CL above).

So that this is not in the public API surface. (I am aware that it refers to a internal struct, but it would be better not to expose such methods). For example: #12854 (comment) (users could call this if at some point accepted), at status-quo users could pass a nil there or hack this with generics to get a zero value of that struct (internal.NotForPublicUs).