example_test.go

package qi_test

import (
	"fmt"

	qi "github.com/iamseth/qi"
)

// applicationCheckpoint is an application-owned byte authority. A real
// implementation would load and atomically replace the same database row or
// object; qi supplies complete checkpoint bytes to commit.
type applicationCheckpoint struct {
	bytes []byte
}

func (a *applicationCheckpoint) load() []byte {
	return append([]byte(nil), a.bytes...)
}

func (a *applicationCheckpoint) CommitCheckpoint(checkpoint []byte) (bool, error) {
	a.bytes = append(a.bytes[:0], checkpoint...)
	return true, nil
}

// ExampleStore demonstrates the canonical, concurrency-safe embedding API and
// transport-independent delta exchange. Lower-level integrations that provide
// their own synchronization can compose JSONFile and Session directly.
func ExampleStore() {
	alice, err := qi.NewStore("alice")
	if err != nil {
		panic(err)
	}
	bob, err := qi.NewStore("bob")
	if err != nil {
		panic(err)
	}

	_, _ = alice.ImportVisibleJSON([]byte(`{"message":"hello","settings":{"theme":"dark"}}`))
	catchUp, _ := alice.CatchUp(bob.Cursor())
	_, _ = bob.ApplyCatchUp(catchUp)

	visible, _ := bob.ExportVisibleJSON()
	fmt.Println(string(visible))
	// Output:
	// {"message":"hello","settings":{"theme":"dark"}}
}

// ExampleSession_ExtractDeltaFor shows that extraction does not advance a
// peer cursor; the caller marks coverage only after its protocol establishes
// that the peer applied the delta.
func ExampleSession_ExtractDeltaFor() {
	aliceFile, _ := qi.NewJSONFile("alice")
	bobFile, _ := qi.NewJSONFile("bob")
	_ = aliceFile.Set("message", []byte(`"hello"`))

	alice := qi.NewSession(aliceFile)
	bob := qi.NewSession(bobFile)
	artifact, pendingBeforeMark, _ := alice.ExtractDeltaFor("bob")
	_, _ = bob.ApplyDeltaFrom("alice", artifact)

	_ = alice.Mark("bob", qi.Cursor{
		Identity: qi.DocumentIdentity{DocumentID: qi.DefaultDocumentID, Generation: qi.InitialGeneration},
		Version:  bobFile.Version(),
	})
	_, pendingAfterMark, _ := alice.ExtractDeltaFor("bob")

	fmt.Println(pendingBeforeMark, pendingAfterMark)
	// Output:
	// true false
}

// ExampleOpenDurableStore demonstrates application-owned checkpoint loading,
// publication, and restart. It is distinct from ExampleStore's in-memory mode.
func ExampleOpenDurableStore() {
	authority := new(applicationCheckpoint)
	identity := qi.DocumentIdentity{
		DocumentID: "preferences",
		Generation: qi.InitialGeneration,
	}

	store, err := qi.OpenDurableStore("alice", identity, authority.load(), authority)
	if err != nil {
		panic(err)
	}
	if err := store.Set("theme", []byte(`"dark"`)); err != nil {
		panic(err)
	}

	// On restart, the application replaces its Store from the same authority.
	// The runtime-local causal replica may change without changing document state.
	store, err = qi.OpenDurableStore("alice-after-restart", identity, authority.load(), authority)
	if err != nil {
		panic(err)
	}
	visible, _ := store.ExportVisibleJSON()
	fmt.Println(string(visible))
	// Output:
	// {"theme":"dark"}
}