tiles

type ArtifactInfo struct {
	APIVersion           int               `json:"api_version"`
	FormatVersion        int               `json:"format_version"`
	TinySQLVersion       string            `json:"tinysql_version"`
	Schema               Schema            `json:"schema"`
	CoordinateSystem     CoordinateSystem  `json:"coordinate_system"`
	CreatedAt            time.Time         `json:"created_at"`
	Source               string            `json:"source"`
	SourceBytes          int64             `json:"source_bytes"`
	Resources            ResourceEstimate  `json:"resources"`
	Provenance           map[string]any    `json:"provenance,omitempty"`
	Tables               []Table           `json:"tables"`
	PhysicalIndexes      map[string]string `json:"physical_indexes,omitempty"`
	Checksums            map[string]string `json:"checksums"`
	TileDigestSHA256     string            `json:"tile_digest_sha256"`
	MetadataDigestSHA256 string            `json:"metadata_digest_sha256"`
}

type CoordinateSystem string

type ImportOptions struct {
	Schema          Schema
	BatchSize       int
	MaxMemoryBytes  int64
	MinFreeBytes    int64
	Provenance      map[string]any
	Progress        func(Progress)
	ProgressEvery   time.Duration
	ReplaceExisting bool
}

type ImportResult struct {
	ArtifactPath string           `json:"artifact_path"`
	Info         ArtifactInfo     `json:"info"`
	Estimate     ResourceEstimate `json:"estimate"`
}

type Index struct {
	Name    string   `json:"name"`
	Columns []string `json:"columns"`
	Unique  bool     `json:"unique"`
}

type Key struct {
	Z int `json:"z"`
	X int `json:"x"`
	Y int `json:"y"`
}

type MetadataScanner interface {
	Reader

	// ScanMetadata visits all metadata name/value pairs without materializing
	// table rows. Returning an error from fn stops the scan and returns that
	// same error to the caller.
	ScanMetadata(ctx context.Context, fn func(name, value string) error) error
}

type OpenOptions struct {
	MaxMemoryBytes int64
}

type Progress struct {
	Phase        string
	RowsRead     int64
	RowsWritten  int64
	BytesRead    int64
	BytesWritten int64
	TotalRows    int64
	BatchSize    int
	Estimate     *ResourceEstimate
}

type Range struct {
	Z    int `json:"z"`
	XMin int `json:"x_min"`
	XMax int `json:"x_max"`
	YMin int `json:"y_min"`
	YMax int `json:"y_max"`
}

type Reader interface {
	io.Closer

	// Info returns an independent copy of immutable artifact information.
	Info() ArtifactInfo
	// Metadata finds a standard MBTiles metadata value by name.
	Metadata(ctx context.Context, name string) (value string, found bool, err error)
	// Lookup reads one exact TMS tile.
	Lookup(ctx context.Context, key Key) (tile Tile, found bool, err error)
	// LookupFunc avoids the result wrapper on an exact tile read. fn receives a
	// caller-owned tile payload and may retain it.
	LookupFunc(ctx context.Context, key Key, fn func(Tile) error) (found bool, err error)
	// Scan streams an inclusive TMS rectangle in stable z/x/y order. Returning
	// an error from fn stops the scan and returns that same error to the caller.
	Scan(ctx context.Context, tileRange Range, fn func(Tile) error) error
}

type ResourceEstimate struct {
	SourceBytes     int64 `json:"source_bytes"`
	TileCount       int64 `json:"tile_count"`
	MapRows         int64 `json:"map_rows,omitempty"`
	ImageRows       int64 `json:"image_rows,omitempty"`
	MetadataRows    int64 `json:"metadata_rows"`
	EstimatedMemory int64 `json:"estimated_memory"`
	EstimatedDisk   int64 `json:"estimated_disk"`
	AvailableDisk   int64 `json:"available_disk"`
	BatchSize       int   `json:"batch_size"`
}

type Schema string

type Source interface {
	Info(context.Context) (SourceInfo, error)
	ScanTiles(context.Context, func(Tile) error) error
}

type SourceInfo struct {
	Name         string
	SourceBytes  int64
	TileCount    int64
	TileBytes    int64
	MaxTileBytes int64
	Metadata     map[string]string
}

type Table struct {
	Name    string   `json:"name"`
	Columns []string `json:"columns"`
	Rows    int64    `json:"rows"`
	Indexes []Index  `json:"indexes,omitempty"`
}

type Tile struct {
	Key  Key    `json:"key"`
	Data []byte `json:"-"`
}