github.com/rs/xid v1.6.0: marshal unmarshal xid with JSON text SQL database driver scan value and sort IDs

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: marshal unmarshal xid with JSON text SQL database driver scan value and sort IDs
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/rs/xid@v1.6.0
Demonstrate these symbols/APIs:
  - github.com/rs/xid.ID.Compare
  - github.com/rs/xid.ID.MarshalJSON
  - github.com/rs/xid.ID.Scan
  - github.com/rs/xid.ID.UnmarshalJSON
  - github.com/rs/xid.ID.Value
  - github.com/rs/xid.Sort

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:66608b10e2d6231ca2fa232f774ea98d38babe834d68fda8a615f9d4337b2b0f","contract":["id.MarshalJSON serializes xid.ID as a 20-character base32 quoted JSON string","id.UnmarshalJSON parses a valid JSON string into xid.ID and handles null as NilID","id.Value returns the 20-character string representation implementing database/sql driver.Valuer","id.Scan unmarshals string or byte representations into xid.ID and handles nil implementing sql.Scanner","id.Compare returns -1, 0, or 1 based on lexicographical ordering of identifiers","xid.Sort sorts a slice of xid.ID identifiers in ascending order"],"goal":"marshal unmarshal xid with JSON text SQL database driver scan value and sort IDs","kind":"HOW","packages":["pkg:golang/github.com/rs/xid@v1.6.0"],"schemaVersion":1,"symbols":["github.com/rs/xid.ID.Compare","github.com/rs/xid.ID.MarshalJSON","github.com/rs/xid.ID.Scan","github.com/rs/xid.ID.UnmarshalJSON","github.com/rs/xid.ID.Value","github.com/rs/xid.Sort"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/rs/xid@v1.6.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/rs/xid@v1.6.0","symbols":["github.com/rs/xid.ID.Compare","github.com/rs/xid.ID.MarshalJSON","github.com/rs/xid.ID.Scan","github.com/rs/xid.ID.UnmarshalJSON","github.com/rs/xid.ID.Value","github.com/rs/xid.Sort"],"verifierAdapter":"golang@1"}

module example.com/xid-sample

go 1.22

require github.com/rs/xid v1.6.0

github.com/rs/xid v1.6.0 h1:fV591PaemRlL6JfRxGDEPl69wICngIQ3shQtzfy2gxU=
github.com/rs/xid v1.6.0/go.mod h1:7XoLgs4eV+QndskICGsho+ADou8ySMSjJKDIan90Nz0=

{
  "schemaVersion": 1,
  "goal": "marshal unmarshal xid with JSON text SQL database driver scan value and sort IDs",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/rs/xid@v1.6.0"
  ],
  "symbols": [
    "github.com/rs/xid.ID.Compare",
    "github.com/rs/xid.ID.MarshalJSON",
    "github.com/rs/xid.ID.Scan",
    "github.com/rs/xid.ID.UnmarshalJSON",
    "github.com/rs/xid.ID.Value",
    "github.com/rs/xid.Sort"
  ]
}

package test

import (
	"database/sql/driver"
	"encoding/json"
	"fmt"
	"testing"
	"time"

	"github.com/rs/xid"
)

func TestJSONMarshalingAndUnmarshaling(t *testing.T) {
	id := xid.New()
	expectedJSON := fmt.Sprintf("%q", id.String())

	marshaled, err := id.MarshalJSON()
	if err != nil {
		t.Fatalf("MarshalJSON failed: %v", err)
	}
	if string(marshaled) != expectedJSON {
		t.Fatalf("MarshalJSON returned %s, expected %s", string(marshaled), expectedJSON)
	}

	// Test struct with xid.ID field JSON serialization
	type Document struct {
		ID   xid.ID `json:"id"`
		Name string `json:"name"`
	}

	doc := Document{
		ID:   id,
		Name: "sample-item",
	}

	data, err := json.Marshal(doc)
	if err != nil {
		t.Fatalf("json.Marshal failed: %v", err)
	}

	var decoded Document
	if err := json.Unmarshal(data, &decoded); err != nil {
		t.Fatalf("json.Unmarshal failed: %v", err)
	}

	if decoded.ID != id {
		t.Fatalf("decoded ID %v does not match original %v", decoded.ID, id)
	}
	if decoded.Name != doc.Name {
		t.Fatalf("decoded Name %q does not match original %q", decoded.Name, doc.Name)
	}

	// Test UnmarshalJSON with invalid JSON and invalid lengths
	var invalidID xid.ID
	if err := invalidID.UnmarshalJSON([]byte(`"not-a-valid-xid-string"`)); err == nil {
		t.Fatal("expected error unmarshaling invalid xid string, got nil")
	}
	if err := invalidID.UnmarshalJSON([]byte(`12345`)); err == nil {
		t.Fatal("expected error unmarshaling non-string JSON, got nil")
	}
	if err := invalidID.UnmarshalJSON([]byte(`null`)); err != nil {
		t.Fatalf("UnmarshalJSON with null returned error: %v", err)
	}
	if !invalidID.IsNil() {
		t.Fatalf("UnmarshalJSON with null should result in NilID, got %v", invalidID)
	}
}

func TestSQLDriverValuerAndScanner(t *testing.T) {
	id := xid.New()

	// Test driver.Valuer interface
	val, err := id.Value()
	if err != nil {
		t.Fatalf("Value() failed: %v", err)
	}
	valStr, ok := val.(string)
	if !ok {
		t.Fatalf("expected Value() to return string, got %T", val)
	}
	if valStr != id.String() {
		t.Fatalf("Value() returned %q, expected %q", valStr, id.String())
	}

	// Nil ID Value
	var nilID xid.ID
	nilVal, err := nilID.Value()
	if err != nil {
		t.Fatalf("nilID.Value() failed: %v", err)
	}
	if nilVal != nil {
		t.Logf("nilID.Value() returned %v", nilVal)
	}

	// Test sql.Scanner interface
	var scannedFromString xid.ID
	if err := scannedFromString.Scan(id.String()); err != nil {
		t.Fatalf("Scan(string) failed: %v", err)
	}
	if scannedFromString != id {
		t.Fatalf("scanned from string %v does not match original %v", scannedFromString, id)
	}

	var scannedFromByteString xid.ID
	if err := scannedFromByteString.Scan([]byte(id.String())); err != nil {
		t.Fatalf("Scan([]byte string) failed: %v", err)
	}
	if scannedFromByteString != id {
		t.Fatalf("scanned from byte string %v does not match original %v", scannedFromByteString, id)
	}

	var scannedNil xid.ID
	if err := scannedNil.Scan(nil); err != nil {
		t.Fatalf("Scan(nil) failed: %v", err)
	}
	if !scannedNil.IsNil() {
		t.Fatalf("Scan(nil) expected IsNil() true, got %v", scannedNil)
	}

	// Invalid Scan inputs
	var errTarget xid.ID
	if err := errTarget.Scan(12345); err == nil {
		t.Fatal("expected error scanning integer, got nil")
	}
	if err := errTarget.Scan("invalid-length"); err == nil {
		t.Fatal("expected error scanning invalid string, got nil")
	}
	if err := errTarget.Scan([]byte("too-short")); err == nil {
		t.Fatal("expected error scanning short byte slice, got nil")
	}

	// Ensure driver.Valuer is implemented
	var _ driver.Valuer = id
}

func TestComparisonAndSorting(t *testing.T) {
	now := time.Now().Truncate(time.Second)
	t1 := now.Add(-10 * time.Second)
	t2 := now
	t3 := now.Add(10 * time.Second)

	id1 := xid.NewWithTime(t1)
	id2 := xid.NewWithTime(t2)
	id3 := xid.NewWithTime(t3)

	// Test Compare
	if cmp := id1.Compare(id2); cmp >= 0 {
		t.Fatalf("expected id1.Compare(id2) < 0, got %d", cmp)
	}
	if cmp := id2.Compare(id1); cmp <= 0 {
		t.Fatalf("expected id2.Compare(id1) > 0, got %d", cmp)
	}
	if cmp := id1.Compare(id1); cmp != 0 {
		t.Fatalf("expected id1.Compare(id1) == 0, got %d", cmp)
	}

	// Test Sort
	ids := []xid.ID{id3, id1, id2}
	xid.Sort(ids)

	if ids[0] != id1 || ids[1] != id2 || ids[2] != id3 {
		t.Fatalf("xid.Sort failed: expected [%v, %v, %v], got [%v, %v, %v]", id1, id2, id3, ids[0], ids[1], ids[2])
	}
}