json_file.go

package qi

import (
	"encoding/json"
	"errors"

	"github.com/iamseth/yin"
)

// JSONFile owns a yin LWW map exposed as a top-level JSON object. It is a
// lower-level, caller-synchronized API: methods must not be called concurrently.
// Its constructor replica is the runtime-local author of future writes.
type JSONFile struct {
	doc *yin.LWWMap[json.RawMessage]
}

// NewJSONFile creates an empty top-level JSON object document. replica must be
// non-empty and becomes the runtime-local yin author for the document's lifetime.
func NewJSONFile(replica yin.ReplicaID) (*JSONFile, error) {
	if err := validateReplicaID(replica); err != nil {
		return nil, err
	}
	return &JSONFile{doc: yin.NewLWWMap[json.RawMessage](replica)}, nil
}

// ParseJSONFile parses a visible top-level JSON object for a non-empty local
// replica. Parsing the projection creates local writes; it does not restore yin
// causal metadata or tombstones.
func ParseJSONFile(replica yin.ReplicaID, data []byte) (*JSONFile, error) {
	if err := validateReplicaID(replica); err != nil {
		return nil, err
	}
	doc, err := yin.ParseJSONObject(replica, data)
	if err != nil {
		return nil, err
	}
	return &JSONFile{doc: doc}, nil
}

// ParseJSONFileSnapshot parses a durable yin LWW map snapshot for a non-empty
// receiving replica. Snapshots keep causal metadata and tombstones, unlike the
// visible JSON projection parsed by ParseJSONFile. Decode retains replica as the
// local author for future writes and never adopts an identity from snapshot data.
func ParseJSONFileSnapshot(replica yin.ReplicaID, data []byte) (*JSONFile, error) {
	if err := validateReplicaID(replica); err != nil {
		return nil, err
	}
	doc, err := yin.UnmarshalLWWMapSnapshotJSON(replica, data)
	if err != nil {
		return nil, err
	}
	return &JSONFile{doc: doc}, nil
}

// Set stores value at key after validating that value is a complete JSON value.
// Pass []byte("null") explicitly to store JSON null.
func (f *JSONFile) Set(key string, value json.RawMessage) error {
	if len(value) == 0 {
		return errors.New("qi: JSON value must be non-empty; use []byte(\"null\") for JSON null")
	}
	if !json.Valid(value) {
		return errors.New("qi: invalid JSON value")
	}

	copied := append(json.RawMessage(nil), value...)
	f.doc.Set(key, copied)
	return nil
}

// Delete removes key from the visible JSON object.
func (f *JSONFile) Delete(key string) {
	f.doc.Delete(key)
}

// Marshal encodes the visible top-level JSON object.
func (f *JSONFile) Marshal() ([]byte, error) {
	return yin.MarshalJSONObject(f.doc)
}

// MarshalSnapshot encodes a durable CRDT snapshot, including metadata not
// present in the visible top-level JSON object projection.
func (f *JSONFile) MarshalSnapshot() ([]byte, error) {
	return yin.MarshalLWWMapSnapshotJSON(f.doc)
}

// Version returns the current document version vector.
func (f *JSONFile) Version() yin.VersionVector {
	return f.doc.Version()
}